@johnmorrisdotca/kazoku-ui 0.2.1 → 0.7.2

package/dist/view-controls/element.js

@@ -1,5 +1,7 @@
 // <kazoku-view-controls>: the view controls as a framework-free custom element. It never draws the scene. It binds the pointer, pinch, wheel and keys
 // to the element named by `for`, and tells the page what the view is now with a `kazoku-viewchange` event; the page applies it to its canvas, WebGL, SVG or CSS 3D.
+import { createAddressWriter } from "../address-state/address.js";
+import { adoptStyles } from "../shared/adopt.js";
 import { DEFAULT_KEYS, formatAddress, parseAddress, parseKeys } from "./address.js";
 import { createViewController, DEFAULT_IGNORE } from "./controller.js";
 import { EVENT, TAG } from "./index.js";
@@ -44,12 +46,13 @@ const HTML = `
 /**
  * Attributes: `for` (the id of the view to bind), `lang` (en or ja; else the page's), `yaw`, `tilt` (the starting view), `zoom` (`fit`, the default, or a scale where 1
  * is the scene's natural size), `fit-scale` (the page's scale at Fit: what zoom 1 means), `ignore` (a selector for what inside the view a pointer press leaves alone;
- * buttons, links and form controls by default), `autoplay` (turn by itself from the start, unless the reader prefers reduced motion), `speed` (degrees a second),
- * `flat` (the view cannot turn), `tilt-max`, `zoom-min`, `zoom-max`, `address` (keep the choices in the page's address), `address-keys` (`yaw:a,tilt:b`), `theme` (light
+ * buttons, links and form controls by default), `autoplay` (turn by itself from the start, unless the reader prefers reduced motion), `autoplay-for` (stop that turn by itself after this many seconds of turning), `speed` (degrees a second),
+ * `anchor` (`x,y`: the point the zoom buttons and keys zoom about, in pixels from the view's middle at Fit), `key-tilt` (`drag`, the default, or `wheel`: which way Arrow Up tips),
+ * `stop-turn` (a press, the wheel or a key on the view stops the automatic turn), `tilt-step` (round a drag's tilt to a multiple of this many degrees), `flat` (the view cannot turn), `tilt-max`, `zoom-min`, `zoom-max`, `address` (keep the choices in the page's address), `address-keys` (`yaw:a,tilt:b`), `theme` (light
  * or dark), `overlay` (sit over the bottom of a positioned parent).
  */
 export class ViewControlsElement extends HTMLElement {
-    static observedAttributes = ["for", "lang", "yaw", "tilt", "zoom", "fit-scale", "ignore", "speed", "flat", "tilt-max", "zoom-min", "zoom-max", "address-keys"];
+    static observedAttributes = ["for", "lang", "yaw", "tilt", "zoom", "fit-scale", "ignore", "anchor", "key-tilt", "stop-turn", "tilt-step", "speed", "flat", "tilt-max", "zoom-min", "zoom-max", "address-keys"];
     #root;
     #controller;
     #view;
@@ -57,8 +60,11 @@ export class ViewControlsElement extends HTMLElement {
     #words = {};
     #ready = false;
     #sliderHeld = 0;
-    #saveTimer = 0;
+    #writer = createAddressWriter({ delay: 250 });
     #keys = DEFAULT_KEYS;
+    #seen;
+    #onScreen = true;
+    #suspended = false;
     constructor() {
         super();
         this.#root = this.attachShadow({ mode: "open" });
@@ -98,6 +104,13 @@ export class ViewControlsElement extends HTMLElement {
     set(next) {
         this.#ensure().set(next);
     }
+    /** The point the zoom buttons and keys zoom about: `{ x, y }` in CSS pixels from the view's middle when it is at Fit, moving with the picture. `undefined` zooms about the view's middle. The `anchor` attribute (`"x,y"`) sets the same. */
+    get anchor() {
+        return this.#ensure().anchor;
+    }
+    set anchor(point) {
+        this.#ensure().anchor = point ?? undefined;
+    }
     /** What zoom 1 means to the page: the scene is drawn at `state.zoom * fitScale`. */
     get fitScale() {
         return this.#ensure().fitScale;
@@ -122,6 +135,10 @@ export class ViewControlsElement extends HTMLElement {
         c.turnable = !this.hasAttribute("flat");
         c.speed = Number(this.getAttribute("speed")) || 30;
         c.ignore = this.getAttribute("ignore") ?? DEFAULT_IGNORE;
+        for (const name of ["key-tilt", "stop-turn", "tilt-step"])
+            this.#option(name);
+        if (this.hasAttribute("anchor"))
+            this.#option("anchor");
         const fitScale = Number(this.getAttribute("fit-scale"));
         if (this.hasAttribute("fit-scale"))
             c.setFitScale(fitScale);
@@ -133,25 +150,30 @@ export class ViewControlsElement extends HTMLElement {
             this.ownerDocument.addEventListener("DOMContentLoaded", () => this.#resolveView(), { once: true });
         this.#ready = true;
         this.#show();
+        this.ownerDocument.addEventListener("visibilitychange", this.#sight);
+        this.#watch();
         // Said once the page has had its turn to listen; a page can also read `state` at any time.
         queueMicrotask(() => {
             if (!this.isConnected)
                 return;
             this.#dispatch(c.state, { final: true, reason: "init" });
             if (this.hasAttribute("autoplay") && !globalThis.matchMedia?.("(prefers-reduced-motion: reduce)").matches)
-                c.play();
+                c.play(Number(this.getAttribute("autoplay-for")));
         });
     }
     disconnectedCallback() {
+        this.ownerDocument.removeEventListener("visibilitychange", this.#sight);
+        this.#seen?.disconnect();
+        this.#seen = undefined;
+        this.#suspended = false;
+        this.#onScreen = true;
         this.#unbind?.();
         this.#unbind = undefined;
         this.#controller?.destroy();
         this.#controller = undefined;
         this.#view = undefined;
         this.#ready = false;
-        if (this.#saveTimer !== 0)
-            globalThis.clearTimeout(this.#saveTimer);
-        this.#saveTimer = 0;
+        this.#writer.cancel();
     }
     attributeChangedCallback(name, _old, value) {
         if (!this.#ready)
@@ -171,6 +193,8 @@ export class ViewControlsElement extends HTMLElement {
             c.setFitScale(Number(value));
         else if (name === "ignore")
             c.ignore = value ?? DEFAULT_IGNORE;
+        else if (name === "anchor" || name === "key-tilt" || name === "stop-turn" || name === "tilt-step")
+            this.#option(name);
         else if (name === "speed")
             c.speed = Number(value) || 30;
         else if (name === "flat") {
@@ -182,6 +206,20 @@ export class ViewControlsElement extends HTMLElement {
         else
             this.#limits();
     }
+    #option(name) {
+        const c = this.#ensure();
+        const value = this.getAttribute(name);
+        if (name === "anchor") {
+            const [x, y] = (value ?? "").trim().split(/[\s,]+/).map(Number);
+            c.anchor = x !== undefined && y !== undefined && Number.isFinite(x) && Number.isFinite(y) ? { x, y } : undefined;
+        }
+        else if (name === "key-tilt")
+            c.keyTilt = value === "wheel" ? "wheel" : "drag";
+        else if (name === "stop-turn")
+            c.stopTurn = value !== null;
+        else if (name === "tilt-step")
+            c.tiltStep = Number(value) > 0 && Number.isFinite(Number(value)) ? Number(value) : 0;
+    }
     #startZoom() {
         const value = Number(this.getAttribute("zoom"));
         return this.hasAttribute("zoom") && Number.isFinite(value) && value > 0 ? value : "fit";
@@ -193,7 +231,8 @@ export class ViewControlsElement extends HTMLElement {
         return this.#controller;
     }
     #build() {
-        this.#root.innerHTML = `<style>${STYLES}</style>${HTML}`;
+        this.#root.innerHTML = HTML;
+        adoptStyles(this.#root, STYLES, this.nonce);
         const q = (selector) => this.#root.querySelector(selector);
         const c = this.#ensure();
         const slider = (id) => {
@@ -263,11 +302,40 @@ export class ViewControlsElement extends HTMLElement {
         this.#unbind?.();
         this.#unbind = undefined;
         this.#view = element;
-        if (element === undefined)
-            return;
         // A view takes the keys only if it can be focused: a page that wants arrows and plus and minus on it gives it a tabindex.
-        this.#unbind = this.#ensure().bind(element);
+        if (element !== undefined)
+            this.#unbind = this.#ensure().bind(element);
+        this.#watch();
+    }
+    /** The automatic turn runs only while the view (else this element) is on screen in a visible tab; otherwise its frame loop is stopped. */
+    #watch() {
+        this.#seen?.disconnect();
+        this.#seen = undefined;
+        this.#onScreen = true;
+        if (typeof IntersectionObserver === "function" && this.isConnected) {
+            this.#seen = new IntersectionObserver((entries) => {
+                const last = entries[entries.length - 1];
+                if (last === undefined)
+                    return;
+                this.#onScreen = last.isIntersecting;
+                this.#sight();
+            });
+            this.#seen.observe(this.#view ?? this);
+        }
+        this.#sight();
     }
+    #sight = () => {
+        if (this.#controller === undefined)
+            return;
+        const idle = !this.#onScreen || this.ownerDocument.visibilityState === "hidden";
+        if (idle === this.#suspended)
+            return;
+        this.#suspended = idle;
+        if (idle)
+            this.#controller.suspendTurn();
+        else
+            this.#controller.resumeTurn();
+    };
     #label() {
         const language = languageOf(this.getAttribute("lang") ?? this.closest("[lang]")?.getAttribute("lang") ?? this.ownerDocument.documentElement.lang);
         const words = wordsFor(language, this.#words);
@@ -323,19 +391,9 @@ export class ViewControlsElement extends HTMLElement {
     }
     /** The address is written at most four times a second: Safari stops a page that changes its address more than a hundred times in thirty seconds. */
     #save() {
-        if (this.#saveTimer !== 0)
-            return;
-        this.#saveTimer = globalThis.setTimeout(() => {
-            this.#saveTimer = 0;
-            try {
-                const s = this.#ensure().state;
-                const next = formatAddress(globalThis.location.search, s, this.#keys, s.turning, this.#ensure().startZoom);
-                if (next !== globalThis.location.search)
-                    globalThis.history.replaceState(globalThis.history.state, "", `${globalThis.location.pathname}${next}${globalThis.location.hash}`);
-            }
-            catch {
-                /* an address that cannot be changed (a sandboxed frame): the view still works */
-            }
-        }, 250);
+        this.#writer.write((search) => {
+            const s = this.#ensure().state;
+            return formatAddress(search, s, this.#keys, s.turning, this.#ensure().startZoom);
+        });
     }
 }

package/dist/view-controls/math.d.ts

@@ -44,7 +44,7 @@ export interface PinchStart {
 }
 /** The camera for two fingers now at `a` and `b`: zoom by the change of distance about where the pinch began, and the middle of the fingers also drags the view. `centre` is the view's middle in client pixels. */
 export declare function pinchTo(start: PinchStart, a: Point, b: Point, centre: Point, limits?: Limits): Camera;
-/** A one-pointer drag that turns: `dx` and `dy` pixels from where it began, in a view of `size`. A finger does not tilt (the page's own scroll keeps the vertical drag). */
-export declare function dragTurn(start: Camera, dx: number, dy: number, size: Size, tips: boolean, limits?: Limits): Pick<Camera, "yaw" | "tilt">;
+/** A one-pointer drag that turns: `dx` and `dy` pixels from where it began, in a view of `size`. A finger does not tilt (the page's own scroll keeps the vertical drag). A `step` above 0 rounds the tilt to a multiple of it. */
+export declare function dragTurn(start: Camera, dx: number, dy: number, size: Size, tips: boolean, limits?: Limits, step?: number): Pick<Camera, "yaw" | "tilt">;
 /** The factor a Ctrl or Command wheel turn zooms by (a trackpad's pinch arrives that way). `deltaMode` 1 is lines. */
 export declare const wheelZoomFactor: (deltaY: number, deltaMode: number) => number;

package/dist/view-controls/math.js

@@ -38,10 +38,11 @@ export function pinchTo(start, a, b, centre, limits = DEFAULT_LIMITS) {
         return zoomed;
     return { ...zoomed, panX: zoomed.panX + (middle.x - start.middle.x), panY: zoomed.panY + (middle.y - start.middle.y) };
 }
-/** A one-pointer drag that turns: `dx` and `dy` pixels from where it began, in a view of `size`. A finger does not tilt (the page's own scroll keeps the vertical drag). */
-export function dragTurn(start, dx, dy, size, tips, limits = DEFAULT_LIMITS) {
+/** A one-pointer drag that turns: `dx` and `dy` pixels from where it began, in a view of `size`. A finger does not tilt (the page's own scroll keeps the vertical drag). A `step` above 0 rounds the tilt to a multiple of it. */
+export function dragTurn(start, dx, dy, size, tips, limits = DEFAULT_LIMITS, step = 0) {
     const yaw = wrapYaw(start.yaw + (dx / (size.width || 360)) * TURN_ACROSS);
-    const tilt = tips ? clamp(start.tilt - (dy / (size.height || 360)) * TILT_ACROSS, -limits.tiltMax, limits.tiltMax) : start.tilt;
+    const raw = start.tilt - (dy / (size.height || 360)) * TILT_ACROSS;
+    const tilt = tips ? clamp(step > 0 ? Math.round(raw / step) * step : raw, -limits.tiltMax, limits.tiltMax) : start.tilt;
     return { yaw, tilt };
 }
 /** The factor a Ctrl or Command wheel turn zooms by (a trackpad's pinch arrives that way). `deltaMode` 1 is lines. */

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@johnmorrisdotca/kazoku-ui",
-  "version": "0.2.1",
-  "description": "Kazoku UI 家族, the family's shared interface parts as their own versioned package. First part: view controls for any 3D or zoomable view (angle, tilt, auto-turn, zoom about the pointer, pan, touch, address state) as a framework-free custom element and a plain controller. Zero dependencies.",
+  "version": "0.7.2",
+  "description": "Kazoku UI 家族, the family's shared interface parts as their own versioned package: view controls for any 3D or zoomable view (angle, tilt, auto-turn, zoom about the pointer, pan, touch, address state) a light, dark and auto theme switch, a language picker, choices kept in the address and a save-as-image button, each a framework-free custom element and a plain controller. Zero dependencies.",
   "keywords": [
     "view-controls",
     "3d",
@@ -16,7 +16,17 @@
     "typescript",
     "javascript",
     "zero-dependencies",
-    "browser"
+    "browser",
+    "theme-switch",
+    "dark-mode",
+    "language-picker",
+    "i18n",
+    "address-state",
+    "url-state",
+    "save-image",
+    "png",
+    "svg",
+    "download"
   ],
   "homepage": "https://johnmorrisdotca.github.io/kazoku-ui/",
   "repository": {
@@ -30,7 +40,10 @@
   "license": "MIT",
   "type": "module",
   "sideEffects": [
-    "./dist/view-controls/define.js"
+    "./dist/view-controls/define.js",
+    "./dist/theme-switch/define.js",
+    "./dist/language-picker/define.js",
+    "./dist/save-image/define.js"
   ],
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -55,6 +68,56 @@
       "types": "./dist/view-controls/define.d.ts",
       "import": "./dist/view-controls/define.js",
       "default": "./dist/view-controls/define.js"
+    },
+    "./theme-switch": {
+      "types": "./dist/theme-switch/index.d.ts",
+      "import": "./dist/theme-switch/index.js",
+      "default": "./dist/theme-switch/index.js"
+    },
+    "./theme-switch/element": {
+      "types": "./dist/theme-switch/element.d.ts",
+      "import": "./dist/theme-switch/element.js",
+      "default": "./dist/theme-switch/element.js"
+    },
+    "./theme-switch/define": {
+      "types": "./dist/theme-switch/define.d.ts",
+      "import": "./dist/theme-switch/define.js",
+      "default": "./dist/theme-switch/define.js"
+    },
+    "./language-picker": {
+      "types": "./dist/language-picker/index.d.ts",
+      "import": "./dist/language-picker/index.js",
+      "default": "./dist/language-picker/index.js"
+    },
+    "./language-picker/element": {
+      "types": "./dist/language-picker/element.d.ts",
+      "import": "./dist/language-picker/element.js",
+      "default": "./dist/language-picker/element.js"
+    },
+    "./language-picker/define": {
+      "types": "./dist/language-picker/define.d.ts",
+      "import": "./dist/language-picker/define.js",
+      "default": "./dist/language-picker/define.js"
+    },
+    "./address-state": {
+      "types": "./dist/address-state/index.d.ts",
+      "import": "./dist/address-state/index.js",
+      "default": "./dist/address-state/index.js"
+    },
+    "./save-image": {
+      "types": "./dist/save-image/index.d.ts",
+      "import": "./dist/save-image/index.js",
+      "default": "./dist/save-image/index.js"
+    },
+    "./save-image/element": {
+      "types": "./dist/save-image/element.d.ts",
+      "import": "./dist/save-image/element.js",
+      "default": "./dist/save-image/element.js"
+    },
+    "./save-image/define": {
+      "types": "./dist/save-image/define.d.ts",
+      "import": "./dist/save-image/define.js",
+      "default": "./dist/save-image/define.js"
     }
   },
   "files": [