@johnmorrisdotca/kazoku-ui 0.2.1 → 0.7.2

package/dist/theme-switch/element.js

@@ -0,0 +1,203 @@
+// <kazoku-theme-switch>: Light, Dark and Auto as a row of buttons. It writes the choice as `data-theme` on a target (the page's <html> by default; `auto` removes it),
+// keeps it in the address and, if asked, in localStorage, and tells the page with a `kazoku-themechange` event. It draws nothing of the page: the page's CSS reads `data-theme`.
+import { createAddressState } from "../address-state/address.js";
+import { adoptStyles } from "../shared/adopt.js";
+import { watchScheme } from "../shared/scheme.js";
+import { localStore, remember } from "../shared/store.js";
+import { resolveTarget } from "../shared/target.js";
+import { EVENT, TAG } from "./index.js";
+import { STYLES } from "./styles.js";
+import { applyTheme, parseModes, parseTheme, readTheme, resolveTheme, THEME_ADDRESS_KEY, THEME_STORAGE_KEY, themeOf } from "./theme.js";
+import { languageOf, wordsFor } from "./words.js";
+export { EVENT, TAG };
+const icon = (body) => `<svg viewBox="0 0 24 24" aria-hidden="true">${body}</svg>`;
+const ICON = {
+    light: icon('<path d="M12 7a5 5 0 1 0 0 10 5 5 0 0 0 0-10zM11 1h2v3h-2zM11 20h2v3h-2zM1 11h3v2H1zM20 11h3v2h-3zM4.2 5.6l1.4-1.4 2.1 2.1-1.4 1.4zM16.3 17.7l1.4-1.4 2.1 2.1-1.4 1.4zM5.6 19.8l-1.4-1.4 2.1-2.1 1.4 1.4zM17.7 7.7l-1.4-1.4 2.1-2.1 1.4 1.4z"/>'),
+    dark: icon('<path d="M20 14.5A8.5 8.5 0 0 1 9.5 4 8.5 8.5 0 1 0 20 14.5z"/>'),
+    auto: icon('<circle cx="12" cy="12" r="8.5" fill="none" stroke="currentColor" stroke-width="2"/><path d="M12 3.5a8.5 8.5 0 0 0 0 17z"/>'),
+};
+/**
+ * Attributes: `value` (`light`, `dark` or `auto`; the choice), `target` (a CSS selector for the element that gets `data-theme`; the page's <html> by default),
+ * `modes` (which buttons: `light dark` leaves Auto out), `address` (keep the choice in `?theme=`, or the key `address-key` names), `storage` (also remember it in
+ * localStorage under that key; a bare `storage` uses `kazoku-theme`), `lang` (`en` or `ja`), `theme` (`light` or `dark`: its own look, otherwise the page's).
+ * The choice is read, in this order, from the address, the store, `value`, then what the target already holds.
+ */
+export class ThemeSwitchElement extends HTMLElement {
+    static observedAttributes = ["value", "target", "modes", "lang"];
+    #root;
+    #choice = "auto";
+    #target;
+    #words = {};
+    #ready = false;
+    #styled = false;
+    #address = createAddressState({ delay: 0 });
+    #stop = [];
+    #watching;
+    constructor() {
+        super();
+        this.#root = this.attachShadow({ mode: "open" });
+    }
+    /** The choice now: `light`, `dark` or `auto`. Setting it applies it (event reason `set`). */
+    get value() {
+        return this.#choice;
+    }
+    set value(next) {
+        const theme = parseTheme(next);
+        if (theme !== undefined)
+            this.#choose(theme, "set");
+    }
+    /** The colours showing now: `light` or `dark`. */
+    get scheme() {
+        return resolveTheme(this.#choice, this.#prefersDark());
+    }
+    /** The element the choice is written on. */
+    get target() {
+        return this.#target;
+    }
+    set target(element) {
+        this.#aim(element);
+    }
+    /** Your own labels over the language's, for example `{ auto: "System" }`. */
+    set words(words) {
+        this.#words = words;
+        this.#render();
+    }
+    connectedCallback() {
+        if (!this.#styled) {
+            adoptStyles(this.#root, STYLES, this.nonce);
+            this.#styled = true;
+        }
+        this.#stop.push(watchScheme(this));
+        this.#resolveTarget();
+        const target = this.#target;
+        const remembered = readTheme({
+            ...(this.hasAttribute("address") ? { search: globalThis.location?.search ?? "", addressKey: this.#addressKey() } : {}),
+            ...(this.hasAttribute("storage") ? { storage: localStore(), storageKey: this.#storageKey() } : {}),
+        });
+        this.#choice = remembered ?? parseTheme(this.getAttribute("value")) ?? (target !== undefined && target.hasAttribute("data-theme") ? themeOf(target) : "auto");
+        if (target !== undefined)
+            applyTheme(target, this.#choice);
+        this.#render();
+        const media = globalThis.matchMedia?.("(prefers-color-scheme: dark)");
+        const onSystem = () => {
+            if (this.#choice === "auto")
+                this.#dispatch("system");
+        };
+        media?.addEventListener("change", onSystem);
+        this.#stop.push(() => media?.removeEventListener("change", onSystem));
+        this.#ready = true;
+        // Said once the page has had its turn to listen; `value` can be read at any time.
+        queueMicrotask(() => {
+            if (this.isConnected)
+                this.#dispatch("init");
+        });
+    }
+    disconnectedCallback() {
+        for (const stop of this.#stop.splice(0))
+            stop();
+        this.#watching?.disconnect();
+        this.#watching = undefined;
+        this.#ready = false;
+    }
+    attributeChangedCallback(name, _old, value) {
+        if (!this.#ready)
+            return;
+        if (name === "value") {
+            const theme = parseTheme(value);
+            if (theme !== undefined)
+                this.#choose(theme, "set");
+        }
+        else if (name === "target") {
+            this.#resolveTarget();
+            if (this.#target !== undefined)
+                applyTheme(this.#target, this.#choice);
+        }
+        else
+            this.#render();
+    }
+    #addressKey() {
+        return this.getAttribute("address-key") || THEME_ADDRESS_KEY;
+    }
+    #storageKey() {
+        return this.getAttribute("storage") || THEME_STORAGE_KEY;
+    }
+    #prefersDark() {
+        return globalThis.matchMedia?.("(prefers-color-scheme: dark)").matches === true;
+    }
+    #resolveTarget() {
+        this.#aim(resolveTarget(this, this.getAttribute("target")));
+    }
+    #aim(element) {
+        if (element === this.#target)
+            return;
+        this.#watching?.disconnect();
+        this.#target = element;
+        if (element === undefined)
+            return;
+        // Something else writing the target's data-theme (a page's own button, another switch) moves this one with it.
+        this.#watching = new MutationObserver(() => {
+            const held = themeOf(element);
+            if (held !== this.#choice) {
+                this.#choice = held;
+                this.#render();
+                this.#dispatch("external");
+            }
+        });
+        this.#watching.observe(element, { attributes: true, attributeFilter: ["data-theme"] });
+    }
+    #choose(theme, reason) {
+        if (this.#target !== undefined)
+            applyTheme(this.#target, theme);
+        const changed = theme !== this.#choice;
+        this.#choice = theme;
+        this.#render();
+        if (this.hasAttribute("address"))
+            this.#address.set(this.#addressKey(), theme === "auto" ? null : theme);
+        if (this.hasAttribute("storage")) {
+            remember(this.#storageKey(), theme);
+        }
+        if (changed || reason === "user")
+            this.#dispatch(reason);
+    }
+    #language() {
+        return languageOf(this.getAttribute("lang") ?? this.closest("[lang]")?.getAttribute("lang") ?? this.ownerDocument.documentElement.lang);
+    }
+    #render() {
+        const language = this.#language();
+        const words = wordsFor(language, this.#words);
+        const modes = parseModes(this.getAttribute("modes"));
+        let group = this.#root.querySelector(".group");
+        if (group === null) {
+            group = this.ownerDocument.createElement("div");
+            group.className = "group";
+            group.setAttribute("part", "group");
+            group.setAttribute("role", "group");
+            this.#root.append(group);
+        }
+        group.setAttribute("aria-label", words.group);
+        group.setAttribute("lang", language);
+        const have = [...group.querySelectorAll("button")];
+        if (have.length !== modes.length || have.some((button, index) => button.dataset.v !== modes[index])) {
+            group.replaceChildren(...modes.map((mode) => {
+                const button = this.ownerDocument.createElement("button");
+                button.type = "button";
+                button.dataset.v = mode;
+                button.setAttribute("part", "button");
+                button.innerHTML = `${ICON[mode]}<span class="t"></span>`;
+                button.addEventListener("click", () => this.#choose(mode, "user"));
+                return button;
+            }));
+        }
+        for (const button of group.querySelectorAll("button")) {
+            const mode = button.dataset.v;
+            button.querySelector(".t").textContent = words[mode];
+            button.setAttribute("aria-pressed", String(mode === this.#choice));
+        }
+    }
+    #dispatch(reason) {
+        if (this.#target === undefined)
+            return;
+        const detail = { choice: this.#choice, scheme: this.scheme, reason, target: this.#target };
+        this.dispatchEvent(new CustomEvent(EVENT, { detail, bubbles: true, composed: true }));
+    }
+}

package/dist/theme-switch/index.d.ts

@@ -0,0 +1,4 @@
+export { applyTheme, parseModes, parseTheme, readTheme, resolveTheme, THEME_ADDRESS_KEY, THEME_ATTRIBUTE, THEME_STORAGE_KEY, themeOf, THEMES, type RememberedTheme, type Scheme, type Theme } from "./theme.ts";
+export { languageOf, WORDS, wordsFor, type Language, type ThemeWords } from "./words.ts";
+export declare const EVENT = "kazoku-themechange";
+export declare const TAG = "kazoku-theme-switch";

package/dist/theme-switch/index.js

@@ -0,0 +1,5 @@
+// The theme switch without the element: the choices, how one is applied and where one is remembered. Nothing here touches the DOM until `applyTheme` is called with an element.
+export { applyTheme, parseModes, parseTheme, readTheme, resolveTheme, THEME_ADDRESS_KEY, THEME_ATTRIBUTE, THEME_STORAGE_KEY, themeOf, THEMES } from "./theme.js";
+export { languageOf, WORDS, wordsFor } from "./words.js";
+export const EVENT = "kazoku-themechange";
+export const TAG = "kazoku-theme-switch";

package/dist/theme-switch/styles.d.ts

@@ -0,0 +1 @@
+export declare const STYLES = "\n:host {\n  --_ink: var(--kazoku-ink, #1b1b1f);\n  --_surface: var(--kazoku-surface, #ffffff);\n  --_line: var(--kazoku-line, #c9ccd3);\n  --_accent: var(--kazoku-accent, #2457d6);\n  display: inline-block;\n  box-sizing: border-box;\n  color: var(--_ink);\n  font: 600 0.9rem/1.2 system-ui, -apple-system, \"Hiragino Sans\", \"Noto Sans JP\", \"Segoe UI\", sans-serif;\n  color-scheme: light dark;\n}\n@media (prefers-color-scheme: dark) {\n  :host(:not([theme=\"light\"]):not([data-scheme=\"light\"])) {\n    --_ink: var(--kazoku-ink, #f1f2f6);\n    --_surface: var(--kazoku-surface, #1c1d22);\n    --_line: var(--kazoku-line, #4a4d58);\n    --_accent: var(--kazoku-accent, #8fb0ff);\n  }\n}\n:host([theme=\"dark\"]), :host([data-scheme=\"dark\"]:not([theme=\"light\"])) {\n  --_ink: var(--kazoku-ink, #f1f2f6);\n  --_surface: var(--kazoku-surface, #1c1d22);\n  --_line: var(--kazoku-line, #4a4d58);\n  --_accent: var(--kazoku-accent, #8fb0ff);\n  color-scheme: dark;\n}\n:host([theme=\"light\"]) { color-scheme: light; }\n[hidden] { display: none !important; }\n.vh { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); white-space: nowrap; }\n.group { display: inline-flex; align-items: center; flex-wrap: wrap; gap: 4px; }\nbutton { -webkit-appearance: none; appearance: none; box-sizing: border-box; display: inline-flex; align-items: center; justify-content: center; gap: 6px; min-width: 48px; min-height: 48px; margin: 0; padding: 0 14px; border: 1px solid var(--_line); border-radius: 24px; background: var(--_surface); color: var(--_ink); font: inherit; cursor: pointer; white-space: nowrap; }\nbutton:hover:not(:disabled) { border-color: var(--_ink); }\nbutton:focus-visible { outline: 2px solid var(--_ink); outline-offset: 2px; }\nbutton[aria-pressed=\"true\"] { background: var(--_ink); color: var(--_surface); border-color: var(--_ink); }\nbutton:disabled { opacity: 0.4; cursor: default; }\nsvg { width: 18px; height: 18px; fill: currentColor; flex: none; }\n\n@media (max-width: 640px) {\n  .t { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); }\n  button { padding: 0; }\n}\n";

package/dist/theme-switch/styles.js

@@ -0,0 +1,8 @@
+import { BASE_STYLES } from "../shared/base.js";
+// Light, Dark and Auto as one row of buttons. On a phone the words are left to a screen reader and the icons stay.
+export const STYLES = `${BASE_STYLES}
+@media (max-width: 640px) {
+  .t { position: absolute; width: 1px; height: 1px; overflow: hidden; clip-path: inset(50%); }
+  button { padding: 0; }
+}
+`;

package/dist/theme-switch/theme.d.ts

@@ -0,0 +1,29 @@
+export declare const THEMES: readonly ["light", "dark", "auto"];
+export type Theme = (typeof THEMES)[number];
+export type Scheme = "light" | "dark";
+/** The attribute the choice is written to on the target. `auto` removes it, so the page's own `prefers-color-scheme` rules decide. */
+export declare const THEME_ATTRIBUTE = "data-theme";
+/** The address parameter, with `address`. */
+export declare const THEME_ADDRESS_KEY = "theme";
+/** The localStorage key, with a bare `storage`. */
+export declare const THEME_STORAGE_KEY = "kazoku-theme";
+export declare const parseTheme: (value: unknown) => Theme | undefined;
+/** The colours a choice gives: light and dark are themselves, auto is the device's. */
+export declare const resolveTheme: (choice: Theme, prefersDark: boolean) => Scheme;
+/** The choices a switch offers, from `modes="light dark"`: the known ones, once each, in the order light, dark, auto. Nothing usable gives all three. */
+export declare function parseModes(value: string | null | undefined): Theme[];
+/** What a target holds now: `light` or `dark` when forced, `auto` when it says nothing or something else. */
+export declare const themeOf: (target: Element) => Theme;
+/** Writes the choice on the target (`data-theme="light"`, `"dark"`, or no attribute for auto). */
+export declare function applyTheme(target: Element, choice: Theme): void;
+/** Where a remembered choice may be read from. A page that keeps nothing passes neither. */
+export interface RememberedTheme {
+    /** An address' search string such as `?theme=dark`, read with `addressKey`. */
+    search?: string;
+    addressKey?: string;
+    /** A localStorage-like object and the key in it. A store that throws is the same as an empty one. */
+    storage?: Pick<Storage, "getItem">;
+    storageKey?: string;
+}
+/** The remembered choice: the address first, then the store. `undefined` when neither holds a valid one. */
+export declare function readTheme(from: RememberedTheme): Theme | undefined;

package/dist/theme-switch/theme.js

@@ -0,0 +1,43 @@
+// The theme choice without the element: the three choices, what each means, and how a choice is applied to a page. Nothing here touches the DOM until a function is called with an element.
+export const THEMES = ["light", "dark", "auto"];
+/** The attribute the choice is written to on the target. `auto` removes it, so the page's own `prefers-color-scheme` rules decide. */
+export const THEME_ATTRIBUTE = "data-theme";
+/** The address parameter, with `address`. */
+export const THEME_ADDRESS_KEY = "theme";
+/** The localStorage key, with a bare `storage`. */
+export const THEME_STORAGE_KEY = "kazoku-theme";
+export const parseTheme = (value) => THEMES.includes(value) ? value : undefined;
+/** The colours a choice gives: light and dark are themselves, auto is the device's. */
+export const resolveTheme = (choice, prefersDark) => (choice === "auto" ? (prefersDark ? "dark" : "light") : choice);
+/** The choices a switch offers, from `modes="light dark"`: the known ones, once each, in the order light, dark, auto. Nothing usable gives all three. */
+export function parseModes(value) {
+    const named = new Set((value ?? "").split(/[\s,]+/).map((word) => parseTheme(word.toLowerCase())));
+    const kept = THEMES.filter((theme) => named.has(theme));
+    return kept.length > 0 ? kept : [...THEMES];
+}
+/** What a target holds now: `light` or `dark` when forced, `auto` when it says nothing or something else. */
+export const themeOf = (target) => parseTheme(target.getAttribute(THEME_ATTRIBUTE)) ?? "auto";
+/** Writes the choice on the target (`data-theme="light"`, `"dark"`, or no attribute for auto). */
+export function applyTheme(target, choice) {
+    if (choice === "auto")
+        target.removeAttribute(THEME_ATTRIBUTE);
+    else
+        target.setAttribute(THEME_ATTRIBUTE, choice);
+}
+/** The remembered choice: the address first, then the store. `undefined` when neither holds a valid one. */
+export function readTheme(from) {
+    if (from.search !== undefined) {
+        const asked = parseTheme(new URLSearchParams(from.search).get(from.addressKey ?? THEME_ADDRESS_KEY));
+        if (asked !== undefined)
+            return asked;
+    }
+    if (from.storage !== undefined) {
+        try {
+            return parseTheme(from.storage.getItem(from.storageKey ?? THEME_STORAGE_KEY));
+        }
+        catch {
+            /* a browser that keeps nothing */
+        }
+    }
+    return undefined;
+}

package/dist/theme-switch/words.d.ts

@@ -0,0 +1,11 @@
+export interface ThemeWords {
+    group: string;
+    light: string;
+    dark: string;
+    auto: string;
+}
+export type Language = "en" | "ja";
+export declare const WORDS: Record<Language, ThemeWords>;
+/** The language to use for a `lang` value such as "ja", "ja-JP" or "en-CA": Japanese for ja, English for anything else. */
+export declare const languageOf: (lang: string | null | undefined) => Language;
+export declare const wordsFor: (language: Language, overrides?: Partial<ThemeWords>) => ThemeWords;

package/dist/theme-switch/words.js

@@ -0,0 +1,7 @@
+export const WORDS = {
+    en: { group: "Colour theme", light: "Light", dark: "Dark", auto: "Auto" },
+    ja: { group: "テーマ", light: "ライト", dark: "ダーク", auto: "自動" },
+};
+/** The language to use for a `lang` value such as "ja", "ja-JP" or "en-CA": Japanese for ja, English for anything else. */
+export const languageOf = (lang) => (/^ja\b/i.test(lang ?? "") ? "ja" : "en");
+export const wordsFor = (language, overrides = {}) => ({ ...WORDS[language], ...overrides });

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

@@ -14,6 +14,8 @@ export interface ChangeInfo {
 }
 /** What `bind` leaves alone by default: the page's own controls inside the view. */
 export declare const DEFAULT_IGNORE = "button, a, input, select, textarea, label, [data-kazoku-ignore]";
+/** Which way Arrow Up tips the view: like a drag up (`"drag"`, the default) or the way the wheel turned up does (`"wheel"`, the other way). */
+export type KeyTilt = "drag" | "wheel";
 export interface Clock {
     request(callback: (now: number) => void): number;
     cancel(id: number): void;
@@ -31,6 +33,14 @@ export interface ViewControllerOptions {
     fitScale?: number;
     /** A CSS selector for what inside the view `bind` leaves alone: a press on a match is not captured, so its click goes through. An empty string leaves nothing alone. */
     ignore?: string;
+    /** The point the zoom buttons and keys zoom about, in content coordinates: CSS pixels from the view's middle when it is at Fit (zoom 1, no pan). It moves with the picture, so the point stays where it is on screen while the view zooms. Left out, they zoom about the view's middle. */
+    anchor?: Point;
+    /** Which way Arrow Up tips the view: `"drag"` (the default, as a drag up) or `"wheel"` (as a wheel turned up). */
+    keyTilt?: KeyTilt;
+    /** True to stop the automatic turn when the reader presses the view, uses the wheel on it or presses a key it handles. False (the default) lets it carry on. Buttons and sliders never stop it. */
+    stopTurn?: boolean;
+    /** Round the tilt of a drag to a multiple of this many degrees; 0 (the default) leaves it unrounded, 1 gives whole degrees. */
+    tiltStep?: number;
     /** The view's size in CSS pixels, for holding the pan; `bind` gives it from the element when this is left out. */
     size?: () => Size | undefined;
     onChange?: (state: ViewState, info: ChangeInfo) => void;
@@ -44,6 +54,11 @@ export interface ViewController {
     readonly limits: Limits;
     /** What a pointer press leaves alone inside the view (see `ViewControllerOptions.ignore`). Can be changed at any time. */
     ignore: string;
+    /** The point the buttons and keys zoom about (see `ViewControllerOptions.anchor`); `undefined` for the view's middle. Can be changed at any time. */
+    anchor: Point | undefined;
+    keyTilt: KeyTilt;
+    stopTurn: boolean;
+    tiltStep: number;
     /** What zoom 1 means to the page (see `ViewControllerOptions.fitScale`). */
     readonly fitScale: number;
     /** The `state.zoom` the view opens at: 1 for "fit", else the starting scale divided by `fitScale`. The address leaves a zoom at this value out. */
@@ -53,15 +68,20 @@ export interface ViewController {
     /** Start at "fit" or at a scale relative to natural size, and go there now. */
     setStartZoom(zoom: "fit" | number): void;
     set(next: Partial<ViewState>, final?: boolean, reason?: string): void;
-    play(): void;
+    /** Turn by itself. With `seconds`, stop by itself (as `pause`) after that many seconds of turning; time spent suspended does not count. `toggle` and a bare `play()` turn without a limit. */
+    play(seconds?: number): void;
     pause(): void;
     toggle(): void;
+    /** Stop the frame loop while nothing can see the view (it is off screen, the tab is hidden): no frames are asked for and no "auto" change is sent. `state.turning` stays true. Counts, so suspends nest. */
+    suspendTurn(): void;
+    /** Undo one `suspendTurn`; the turn goes on from where it was when the last one is undone. */
+    resumeTurn(): void;
     /** Hold the automatic turn still while a hand (a slider being dragged) has the angle; `releaseTurn` lets it carry on from where the hand left it. Counts, so holds nest. */
     holdTurn(): void;
     releaseTurn(): void;
     front(): void;
     fit(): void;
-    /** Zoom to `next` about the point `at` (client pixels; the view's middle when left out). */
+    /** Zoom to `next` about the point `at` (client pixels); left out, about the `anchor`, else the view's middle. */
     zoomAt(next: number, at?: Point, final?: boolean): void;
     zoomBy(factor: number, at?: Point): void;
     /** Move the view by whole fractions of its size: `panBy(1, 0)` is a quarter of its width to the right. */

package/dist/view-controls/controller.js

@@ -1,6 +1,7 @@
 import { clamp, clampPan, DEFAULT_LIMITS, dragTurn, PAN_STEP, pinchTo, wheelZoomFactor, wrapYaw, ZOOMED, zoomAbout } from "./math.js";
 /** What `bind` leaves alone by default: the page's own controls inside the view. */
 export const DEFAULT_IGNORE = "button, a, input, select, textarea, label, [data-kazoku-ignore]";
+const HANDLED_KEYS = ["ArrowLeft", "ArrowRight", "ArrowUp", "ArrowDown", "+", "=", "-", "_", "0", "Home"];
 const positive = (value) => (typeof value === "number" && Number.isFinite(value) && value > 0 ? value : undefined);
 const browserClock = () => ({ request: (callback) => globalThis.requestAnimationFrame(callback), cancel: (id) => globalThis.cancelAnimationFrame(id) });
 export function createViewController(options = {}) {
@@ -11,6 +12,9 @@ export function createViewController(options = {}) {
     let frame = 0;
     let last = 0;
     let holds = 0;
+    let suspends = 0;
+    let limit = 0;
+    let turned = 0;
     let fitScale = positive(options.fitScale) ?? 1;
     let start = positive(options.zoom) ?? "fit";
     let atStart = true;
@@ -51,15 +55,17 @@ export function createViewController(options = {}) {
         const r = bound.getBoundingClientRect();
         return { x: r.left + r.width / 2, y: r.top + r.height / 2 };
     };
-    /** Client pixels to pixels from the view's middle. */
+    /** Client pixels to pixels from the view's middle; with none, the anchor's place on screen now, else the middle. */
     const fromMiddle = (at) => {
-        if (at === undefined)
-            return { x: 0, y: 0 };
+        if (at === undefined) {
+            const a = controller.anchor;
+            return a === undefined ? { x: 0, y: 0 } : { x: state.panX + state.zoom * a.x, y: state.panY + state.zoom * a.y };
+        }
         const c = centre();
         return { x: at.x - c.x, y: at.y - c.y };
     };
     const tick = (now) => {
-        if (!state.turning)
+        if (!state.turning || suspends > 0)
             return;
         frame = clock.request(tick);
         if (holds > 0) {
@@ -71,7 +77,10 @@ export function createViewController(options = {}) {
         if (dt === 0)
             return;
         state.yaw = wrapYaw(state.yaw + controller.speed * dt);
+        turned += dt;
         emit(false, "auto");
+        if (limit > 0 && turned >= limit)
+            controller.pause();
     };
     const controller = {
         state,
@@ -79,6 +88,10 @@ export function createViewController(options = {}) {
         speed: options.speed ?? 30,
         limits,
         ignore: options.ignore ?? DEFAULT_IGNORE,
+        anchor: options.anchor,
+        keyTilt: options.keyTilt ?? "drag",
+        stopTurn: options.stopTurn ?? false,
+        tiltStep: options.tiltStep ?? 0,
         get fitScale() {
             return fitScale;
         },
@@ -118,12 +131,15 @@ export function createViewController(options = {}) {
             }
             emit(final, reason);
         },
-        play() {
+        play(seconds) {
             if (state.turning || !controller.turnable)
                 return;
             state.turning = true;
             last = 0;
-            frame = clock.request(tick);
+            turned = 0;
+            limit = positive(seconds) ?? 0;
+            if (suspends === 0)
+                frame = clock.request(tick);
             emit(true, "play");
         },
         pause() {
@@ -139,6 +155,20 @@ export function createViewController(options = {}) {
             else
                 controller.play();
         },
+        suspendTurn() {
+            suspends += 1;
+            if (suspends === 1)
+                clock.cancel(frame);
+        },
+        resumeTurn() {
+            if (suspends === 0)
+                return;
+            suspends -= 1;
+            if (suspends > 0 || !state.turning)
+                return;
+            last = 0;
+            frame = clock.request(tick);
+        },
         holdTurn() {
             holds += 1;
         },
@@ -199,6 +229,10 @@ export function createViewController(options = {}) {
             holding = false;
         };
         const canTurn = () => controller.turnable;
+        const grab = () => {
+            if (controller.stopTurn)
+                controller.pause();
+        };
         const ignored = (e) => {
             if (controller.ignore === "")
                 return false;
@@ -226,6 +260,7 @@ export function createViewController(options = {}) {
                 return;
             if (ignored(e))
                 return;
+            grab();
             pointers.set(e.pointerId, { x: e.clientX, y: e.clientY });
             try {
                 view.setPointerCapture(e.pointerId);
@@ -273,7 +308,7 @@ export function createViewController(options = {}) {
                     return;
                 const r = view.getBoundingClientRect();
                 // Up and down tips it for a mouse; on a finger the browser keeps the vertical drag to scroll the page, and the tilt slider tips it.
-                take({ ...camera(), ...dragTurn(gesture.camera, dx, dy, { width: r.width, height: r.height }, e.pointerType !== "touch", limits) });
+                take({ ...camera(), ...dragTurn(gesture.camera, dx, dy, { width: r.width, height: r.height }, e.pointerType !== "touch", limits, controller.tiltStep) });
                 emit(false, "drag");
             }
         };
@@ -310,6 +345,7 @@ export function createViewController(options = {}) {
             if (e.ctrlKey || e.metaKey) {
                 // A trackpad's pinch arrives as Ctrl and the wheel; Command and the wheel does the same for a mouse.
                 e.preventDefault();
+                grab();
                 controller.zoomAt(state.zoom * wheelZoomFactor(e.deltaY, e.deltaMode), { x: e.clientX, y: e.clientY });
                 return;
             }
@@ -321,6 +357,7 @@ export function createViewController(options = {}) {
             e.preventDefault();
             if (!canTurn())
                 return;
+            grab();
             if (horizontal || e.shiftKey)
                 controller.set({ yaw: state.yaw + (e.deltaX || e.deltaY) * 0.3 }, true, "wheel");
             else
@@ -329,6 +366,10 @@ export function createViewController(options = {}) {
         const onKey = (e) => {
             if (e.ctrlKey || e.metaKey || e.altKey)
                 return;
+            if (!HANDLED_KEYS.includes(e.key))
+                return;
+            grab();
+            const up = controller.keyTilt === "wheel" ? -5 : 5;
             const big = e.shiftKey ? 45 : 15;
             const turn = (next) => {
                 if (canTurn())
@@ -342,10 +383,10 @@ export function createViewController(options = {}) {
                     turn({ yaw: state.yaw + big });
                     break;
                 case "ArrowUp":
-                    turn({ tilt: state.tilt + 5 });
+                    turn({ tilt: state.tilt + up });
                     break;
                 case "ArrowDown":
-                    turn({ tilt: state.tilt - 5 });
+                    turn({ tilt: state.tilt - up });
                     break;
                 case "+":
                 case "=":

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

@@ -1,5 +1,6 @@
 import { type ViewController, type ViewState } from "./controller.ts";
 import { EVENT, TAG } from "./index.ts";
+import { type Point } from "./math.ts";
 import { type ViewWords } from "./words.ts";
 export { EVENT, TAG };
 /** What the `kazoku-viewchange` event carries in `detail`. */
@@ -10,8 +11,9 @@ export interface ViewChangeDetail extends ViewState {
 /**
  * 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 declare class ViewControlsElement extends HTMLElement {
@@ -32,6 +34,9 @@ export declare class ViewControlsElement extends HTMLElement {
     front(): void;
     fit(): void;
     set(next: Partial<ViewState>): void;
+    /** 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(): Point | undefined;
+    set anchor(point: Point | undefined | null);
     /** What zoom 1 means to the page: the scene is drawn at `state.zoom * fitScale`. */
     get fitScale(): number;
     setFitScale(scale: number): void;