blinkk/degu

A general utility library for interactive websites, with a focus on performance.

Degu

A general utility library for interactive websites, with a focus on performance.

• API docs
• Examples
• Coverage

Motivation

degu is an interactive developer toolbox. It is not the next buzzword-filled, huge component library with ready-made UI solutions (such as modals, carousels, etc.) but it aims to provide the "hammer and nails" needed to build highly-interactive, performant, kickass websites.

Installation

npm install @blinkk/degu@latest --save-dev

Getting started

• Read the API docs
• Explore the examples folder

Import the library:

import {WebWorker} from '@blinkk/degu';

const worker = new WebWorker((params)=> {
    return params.a * params.b;
})

worker.run({a: 5, b: 2}).then((result)=> {
   console.log(result); // 10
})

Import specific files:

import * as mathf from '@blinkk/degu/lib/mathf/mathf.js'
import * as is from '@blinkk/degu/lib/is/is.js'
import * as dom from '@blinkk/degu/lib/dom/dom.js';

ThreeJS deps

Classes under threef require three.js deps. Currently supports r110.

npm install --save-dev [email protected]
npm install --save-dev @types/[email protected]

Browser compatibility

degu supports only "evergreen" browsers back to the latest two versions:

• Chrome
• Edge (Chromium version)
• Firefox
• Safari

Upgrading

If you have already been using version 2.x.y and are upgrading to version 3.x.y, see our MIGRATION.md guide for details.

Contributing

Please read CONTRIBUTING.md on how to develop for degu.

License

Please read LICENSE.md

degu's Issues

Consolidate files created when porting Toolbox code

Goal is to keep file-count down by grouping exports into single files.

Created per #54 (comment)

Implement Quaternions

• implement quaternions
• redo Vector-dom-force with quaternions

directive-lottie-scroll - Refactor lottieObject as class

Separating lottieObject as a separate class will keep it cleaner and separate functionality.

Memoize is.supportingWebp

Build in scrollToFocus into cssParallax.

Create ScrollToOnFocus class

We need a way to "scroll to" specific locations on the page based on focus state of elements to help with accessibility.

This is highly useful for project that have scroll based modules that have chapter (title, body etc) content go in and out based on specific scroll points.

Roughly:

<div root>
  <div scroll-to-on-focus="0.4">xxx</div>
 </div>
 
 new ScrollToOnFocus(root);

YouTube Modal not opening (detailsDialog.toggle is not defined)

Steps to replicate:

• https://blinkk.github.io/degu/examples/components.html
• Scroll to bottom and click one of the YouTube modal buttons

To replicate on dev:

• Clone repo
• yarn install
• yarn run server
• http://localhost:5173/degu/examples/components.html

Automate releases with Release Please

https://github.com/googleapis/release-please

`func.debounce` return type is too vague

Right now the return type of debounce is Function. This is too vague for the Typescript compiler when you try to use it with addEventListener:

Error: @rollup/plugin-typescript TS2769: No overload matches this call.
  Overload 1 of 2, '(type: "resize", listener: (this: Window, ev: UIEvent) => any, options?: boolean | AddEventListenerOptions | undefined): void', gave the following error.
    Argument of type 'Function' is not assignable to parameter of type '(this: Window, ev: UIEvent) => any'.
      Type 'Function' provides no match for the signature '(this: Window, ev: UIEvent): any'.
  Overload 2 of 2, '(type: string, listener: EventListenerOrEventListenerObject, options?: boolean | AddEventListenerOptions | undefined): void', gave the following error.
    Argument of type 'Function' is not assignable to parameter of type 'EventListenerOrEventListenerObject'.

Changing the signature of debounce so that the return type is () => void might fix it (or maybe something more specific than that).

Lottie Directive Upgrades

• [] For multiple lotties (desktop / mobile etc), cull frame updates based on the visibility of the current lottie container.

Clean up horizontal-scroll-element

• break out an init function
• the resizeOnFirstEv should be an option OR possible an event
• clean up controller

Remove dependency on jQuery

https://github.com/blinkk/degu/blob/main/src/dom/scroll-points.ts

Switch to a native implementation, or if this library isn't needed, remove altogether.

ProgressWatcher sometimes fires callbacks every frame

When adding a watcher to a ProgressWatcher, if the range value is set to 0 or 1, the callback will sometimes be fired every frame, when it's supposed to only be fired once each time the threshold is crossed.

I have a workaround right now of just using 0.001 or 0.999 instead.

Move "lit" components to "components" directory

`<degu-image>`: SVG with query params results in srcset being used

When using an SVG with query params, e.g. http://localhost:3000/static/placeholder/16x9.svg?bgColor=FFEFA4 the srcset version of degu-image is still used

(Need to do the extension check by splitting on ? and checking the extension on the first part.)

`debounce` function behaving in non-standard way

It's not quite a bug, but the debounce function (https://github.com/blinkk/degu/blob/main/src/func/func.ts#L30) behaves differently than what debounce functions usually do.

Usually, the goal is to call the function once after X seconds, and all subsequent calls should restart the timer, such that the function is only invoked X seconds after the last call. The current behavior is to always call the function X seconds after the first call.

The minimal "fix" would be to change

if (!immediate && timeOutId === undefined) {
  timeOutId = +setTimeout(runLater, wait);
}

to

if (!immediate) {
  if (timeOutId) {
    clearTimeout(timeOutId);
  }
  timeOutId = +setTimeout(runLater, wait);
}

but I'm not sure what the best approach is, i.e. if this new behaviour should replace the old, or if it should be gated behind a parameter...and it also might affect the related throttle function.

Autodetect "type" in LazyVideo

LazyVideo should auto-detect the "type" from the video URL and apply the attr if it's not already set (or improperly set). Remove all type="" references in examples as well.

Support specifying `loading` attribute on `degu-image`

I should be able to specify the loading attribute on <degu-image> and have it propagate down to the img element within the shadow DOM. For example, I may want to specify loading="eager" and overwrite the default loading=lazy.

Build "pure" custom elements

We are going to build a library of custom elements to facilitate common patterns in our projects.

• Image: degu-image
• Video: degu-video
• Asset (layer of indirection atop image, video): degu-asset
• Scroll carousel: degu-scroll-carousel
• YouTube modal: degu-youtube-modal
• YouTube video (inline YouTube video player): degu-youtube-video
• Hamburger menu (potential wrapper around details-dialog with focus trap): degu-hamburger-menu
• Formatted price with localization support: degu-price

See https://github.com/github/details-dialog-element for a fantastic reference for building pure custom elements with no dependencies.

Add play(), stop() options to css parallax

Add an option for css-parallax to disable scroll tie the animation and instead manually update the progress and control playback. This will allow css-parallax to be used as triggered animations instead of scroll tie without refactoring.

CanvasImageSequence - image decoding on draw

Image decoding seems to happen on each draw call which is odd. For smaller images this isn't a huge deal but when dealing with large images this decode time will slug performance.

CssVarInterpolate should automatically set `visibility: hidden` for opacity: 0

Brainstorming ways for cssVarInterpolate to automatically set visibility: hidden when opacity is set to 0.

Key issues:

1. cssVarInterpolate is element agnostic. It ONLY creates css variables. It is up to the user to add and use the variable in css.
2. the variables names are up to the user. Therefore, there is no definitive way to know if this particular css variable is going to be used for opacity.

 {
            progress: [{ from: 0, to: 0.3, start: 0, end: 1 },],
            id: '--hohoho'
 },
         
.myvar
    opacity: var(--hohoho)

1 - assume the name opacity in the css variable.

If the word opacity is found in the css variable, cssvarinterpolate will automatically create a visibility variable for you.

 {
            progress: [{ from: 0, to: 0.3, start: 0, end: 1 },],
            id: '--my-opacity'
 },
         
.myvar
    opacity: var(--my-opacity)
    visibility: var(--my-visibility)

2 - Add a flag for visibility var.

If the word opacity is found in the css variable, cssvarinterpolate will automatically create a visibility variable for you.

 {
            progress: [{ from: 0, to: 0.3, start: 0, end: 1 },],
            id: '--my-opacity'
            generateVisibilityVarAs: '--my-visibility'
 },
         
.myvar
    opacity: var(--my-opacity)
    visibility: var(--my-visibility)

3 - Opacity mutationobserver

Since cssVarInterpolate was never designed to directly manipulate elements, we could have a new class that observes opacity and sets visibility: hidden. However, this might be an expensive operation.

YouTube modal should autoplay video when triggered

Just saw it staged on the starter:
https://blinkk.github.io/amagaki-starter/

When the video button is clicked and the modal opens, the video should autoplay.

Add continuous testing and deployment

We need to automate a few things:

1. Deploying documentation site (current site: http://yano-js.surge.sh/)
2. Deploying examples site (current site: http://yano.inverseq.com/index.html)
3. Run the tests.

Both 1 and 2 should be deployed to GitHub pages (or similar) via GitHub Actions (or similar)

`degu-image`: Disable srcset behavior when non-dynamic image is used

Currently, degu-image only supports dynamic Google images. When a Google image is not specified, it appears the dynamic srcset behavior still kicks in. I think this should be disabled when non-Google images are used:

Additionally, I think it incorrectly uses image/webp in the srcset here (the URL ends in .png).

Improve raf.read / raf.write with Promises

I'm thinking of returning promises for raf.read and raf.write so that we can avoid a nested syntax and use async / await.

Add round option to css-var-interpolate

Avoid subpixel rendering. We could just auto round when 'px' is in the string or add this as a new option.

Move /x and /pseudo-3d-canvas to /experimental

`degu-image` needs the ability to specify custom google image parameters

Sometimes we want to specify things like the quality level (e.g. v1) manually. The degu-image should support some kind of attribute for overwriting or supplanting google image parameters, e.g.

<degu-image google-params="v1-cc" src="..."></degu-image>

The v1-cc would either override or append to the default image params.

Carousel BEFORE_CHANGE fires in confusing situations

The BEFORE_CHANGE event fires when a new transitionTarget is assigned.

This is confusing when the transitionTarget matches the currently active slide.

transitionTarget can be assigned matching the currently active slide to support situations where a draggable slide has been moved a bit, but not enough to change the active slide, and it needs to transition back to center.

The naming of BEFORE_CHANGE in this circumstance is confusing. It is probably worth splitting this into two events BEFORE_CHANGE and BEFORE_TRANSITION, firing one or both as necessary. This would also apply to AFTER events.

Dependency upgrades

We need to update a few dependencies in order to get the latest versions and resolve vulnerabilities in the dependency chain

• node-sass -> sass
• babel-preset-es2015 -> babel-preset-env

Rename to blinkkcode/degu

Filing an issue to track renaming the project to Degu. Note that we won't change anything about our current release, so projects that depend on npm package Yano can continue to do so and won't break.

1. Move to blinkkcode/degu on GitHub, with package @blinkk/degu.
2. Set up GitHub Actions to publish whenever package.json's version changes (see example from https://github.com/blinkkcode/fileset/blob/main/.github/workflows/publish.yml)
3. Audit docs and change references/branding as needed
4. Update project dependencies
5. Get a mascot illustrated :)

Thoughts @uxder @angusm @stevenle ?

Canvas Video Renderer

Create a component that takes a video and renders it onto a canvas.

Why? Because the hack to acquire the pixel color of a video, doesn't work if you just apply it to a canvas in memory.
https://github.com/blinkkcode/degu/blob/main/src/dom/dom-canvas.ts#L111

So you need to:

• take the video, put in a canvas
• display the canvas instead of the video
  to avoid color issues.

A simple component that plays the video in canvas will resolve the issue.

Other references:
https://blinkkcode.github.io/degu/examples/canvas-image-sequence10.html
https://github.com/blinkkcode/degu/blob/main/examples/canvas-image-sequence10.js#L92

Review / Audit Classes to go into /Experiemental

• Lottie Button
• VectorDOM

SVG bugs with Degu Image

• Non-Google Images are treated as Google images and use srcset. Non-Google images should just use a normal <img> tag without <picture>.
• When width and height are omitted from the host element, the attributes appear anyway on the inner elements.

Using...

<degu-image src="/static/placeholder/7x3.svg" alt="Logo" class="header__logo__image"></degu-image>

...results in:

<degu-image src="/static/placeholder/7x3.svg" alt="Logo" class="header__logo__image"><!---->
      <!--?lit$05163032$-->
      <picture>
        <!--?lit$05163032$--><!---->
      <source type="image/webp" srcset="
          /static/placeholder/7x3.svg=rw-e365-w2880,
          /static/placeholder/7x3.svg=rw-e365-w5760 2x" media="(min-width: 1440px)">
    <!----><!---->
      <source type="image/webp" srcset="
          /static/placeholder/7x3.svg=rw-e365-w1440,
          /static/placeholder/7x3.svg=rw-e365-w2880 2x" media="(min-width: 1024px) and (max-width: 1399px)">
    <!----><!---->
      <source type="image/webp" srcset="
          /static/placeholder/7x3.svg=rw-e365-w1024,
          /static/placeholder/7x3.svg=rw-e365-w2048 2x" media="(min-width: 768px) and (max-width: 1023px)">
    <!----><!---->
      <source type="image/webp" srcset="
          /static/placeholder/7x3.svg=rw-e365-w768,
          /static/placeholder/7x3.svg=rw-e365-w1536 2x" media="(max-width: 767px)">
    <!---->
        <!--?lit$05163032$-->
      <img loading="lazy" src="/static/placeholder/7x3.svg" width="" height="" alt="Logo">
    
      </picture>
    
    </degu-image>