@johnmorrisdotca/kazoku-ui 0.0.0-stage → 0.2.0

package/dist/view-controls/controller.js

@@ -0,0 +1,385 @@
+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 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 = {}) {
+    const limits = { ...DEFAULT_LIMITS, ...options.limits };
+    const clock = options.clock ?? browserClock();
+    let sizeOf = options.size;
+    let bound;
+    let frame = 0;
+    let last = 0;
+    let holds = 0;
+    let fitScale = positive(options.fitScale) ?? 1;
+    let start = positive(options.zoom) ?? "fit";
+    let atStart = true;
+    const startState = () => (start === "fit" ? 1 : start / fitScale);
+    const state = { yaw: 0, tilt: 0, zoom: 1, panX: 0, panY: 0, turning: false, drag: "move", ...options.initial };
+    if (start !== "fit")
+        state.zoom = clamp(startState(), limits.zoomMin, limits.zoomMax);
+    atStart = state.zoom === clamp(startState(), limits.zoomMin, limits.zoomMax);
+    const size = () => {
+        const own = sizeOf?.();
+        if (own !== undefined)
+            return own;
+        if (bound === undefined)
+            return undefined;
+        const r = bound.getBoundingClientRect();
+        return { width: r.width, height: r.height };
+    };
+    const emit = (final, reason) => {
+        if (bound !== undefined)
+            bound.style.touchAction = state.zoom > ZOOMED ? "none" : "pan-y";
+        options.onChange?.({ ...state }, { final, reason });
+    };
+    const camera = () => ({ yaw: state.yaw, tilt: state.tilt, zoom: state.zoom, panX: state.panX, panY: state.panY });
+    /** Take a camera in, held to the limits and, once the view's size is known, to the room the zoom gives. */
+    const take = (next) => {
+        const held = clampPan({ ...next, zoom: clamp(next.zoom, limits.zoomMin, limits.zoomMax), tilt: clamp(next.tilt, -limits.tiltMax, limits.tiltMax) }, size());
+        state.yaw = controller.turnable ? wrapYaw(held.yaw) : state.yaw;
+        state.tilt = controller.turnable ? held.tilt : state.tilt;
+        if (held.zoom !== state.zoom)
+            atStart = false;
+        state.zoom = held.zoom;
+        state.panX = held.panX;
+        state.panY = held.panY;
+    };
+    const centre = () => {
+        if (bound === undefined)
+            return { x: 0, y: 0 };
+        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. */
+    const fromMiddle = (at) => {
+        if (at === undefined)
+            return { x: 0, y: 0 };
+        const c = centre();
+        return { x: at.x - c.x, y: at.y - c.y };
+    };
+    const tick = (now) => {
+        if (!state.turning)
+            return;
+        frame = clock.request(tick);
+        if (holds > 0) {
+            last = 0;
+            return;
+        }
+        const dt = last === 0 ? 0 : Math.min(0.1, (now - last) / 1000);
+        last = now;
+        if (dt === 0)
+            return;
+        state.yaw = wrapYaw(state.yaw + controller.speed * dt);
+        emit(false, "auto");
+    };
+    const controller = {
+        state,
+        turnable: options.turnable ?? true,
+        speed: options.speed ?? 30,
+        limits,
+        ignore: options.ignore ?? DEFAULT_IGNORE,
+        get fitScale() {
+            return fitScale;
+        },
+        get startZoom() {
+            return clamp(startState(), limits.zoomMin, limits.zoomMax);
+        },
+        setFitScale(scale) {
+            const next = positive(scale);
+            if (next === undefined || next === fitScale)
+                return;
+            fitScale = next;
+            if (!atStart)
+                return;
+            const before = state.zoom;
+            take({ ...camera(), zoom: startState() });
+            atStart = true;
+            if (state.zoom !== before)
+                emit(true, "fit-scale");
+        },
+        setStartZoom(zoom) {
+            start = positive(zoom) ?? "fit";
+            take({ ...camera(), zoom: startState() });
+            atStart = true;
+            emit(true, "set");
+        },
+        set(next, final = true, reason = "set") {
+            const { turning, drag, ...cam } = next;
+            take({ ...camera(), ...cam });
+            if (drag !== undefined)
+                state.drag = drag;
+            if (turning !== undefined && turning !== state.turning) {
+                if (turning)
+                    controller.play();
+                else
+                    controller.pause();
+                return;
+            }
+            emit(final, reason);
+        },
+        play() {
+            if (state.turning || !controller.turnable)
+                return;
+            state.turning = true;
+            last = 0;
+            frame = clock.request(tick);
+            emit(true, "play");
+        },
+        pause() {
+            if (!state.turning)
+                return;
+            state.turning = false;
+            clock.cancel(frame);
+            emit(true, "pause");
+        },
+        toggle() {
+            if (state.turning)
+                controller.pause();
+            else
+                controller.play();
+        },
+        holdTurn() {
+            holds += 1;
+        },
+        releaseTurn() {
+            holds = Math.max(0, holds - 1);
+            last = 0;
+        },
+        front() {
+            take({ ...camera(), yaw: 0, tilt: 0 });
+            emit(true, "front");
+        },
+        fit() {
+            take({ ...camera(), zoom: 1, panX: 0, panY: 0 });
+            emit(true, "fit");
+        },
+        zoomAt(next, at, final = true) {
+            take(zoomAbout(camera(), next, fromMiddle(at), limits));
+            emit(final, "zoom");
+        },
+        zoomBy(factor, at) {
+            controller.zoomAt(state.zoom * factor, at);
+        },
+        panBy(stepsX, stepsY) {
+            const s = size();
+            take({ ...camera(), panX: state.panX + stepsX * (s?.width ?? 0) * PAN_STEP, panY: state.panY + stepsY * (s?.height ?? 0) * PAN_STEP });
+            emit(true, "pan");
+        },
+        setDrag(drag) {
+            state.drag = drag;
+            emit(true, "set");
+        },
+        bind(view) {
+            bound = view;
+            sizeOf = options.size;
+            return bindHands(view);
+        },
+        destroy() {
+            clock.cancel(frame);
+            state.turning = false;
+            unbind?.();
+        },
+    };
+    let unbind;
+    function bindHands(view) {
+        const pointers = new Map();
+        let gesture;
+        let holding = false;
+        let lastTap = 0;
+        let lastTapAt = { x: 0, y: 0 };
+        const hold = () => {
+            if (!holding)
+                controller.holdTurn();
+            holding = true;
+        };
+        const release = () => {
+            if (holding)
+                controller.releaseTurn();
+            holding = false;
+        };
+        const canTurn = () => controller.turnable;
+        const ignored = (e) => {
+            const target = e.target;
+            if (controller.ignore === "" || typeof target?.closest !== "function")
+                return false;
+            try {
+                const hit = target.closest(controller.ignore);
+                return hit !== null && hit !== view && view.contains(hit);
+            }
+            catch {
+                return false;
+            }
+        };
+        const onDown = (e) => {
+            if (e.pointerType === "mouse" && e.button > 2)
+                return;
+            if (ignored(e))
+                return;
+            pointers.set(e.pointerId, { x: e.clientX, y: e.clientY });
+            try {
+                view.setPointerCapture(e.pointerId);
+            }
+            catch {
+                /* a pointer already gone */
+            }
+            if (pointers.size === 2) {
+                const [a, b] = [...pointers.values()];
+                gesture = { kind: "pinch", start: { distance: Math.hypot(a.x - b.x, a.y - b.y) || 1, middle: { x: (a.x + b.x) / 2, y: (a.y + b.y) / 2 }, camera: camera() } };
+                release();
+            }
+            else if (pointers.size === 1) {
+                // At 1x a plain press and drag turns the piece; zoomed in it moves the view unless the Turn choice is made. Shift, the middle or the right button always move a zoomed view. A flat view cannot turn, so a drag moves it.
+                const pan = e.button === 1 || e.button === 2 || e.shiftKey || (state.zoom > ZOOMED && (!canTurn() || state.drag !== "turn"));
+                gesture = { kind: pan ? "pan" : "turn", x: e.clientX, y: e.clientY, camera: camera(), moved: false };
+                if (!pan)
+                    hold();
+            }
+            view.dataset.grab = "1";
+        };
+        const onMove = (e) => {
+            const p = pointers.get(e.pointerId);
+            if (p === undefined || gesture === undefined)
+                return;
+            p.x = e.clientX;
+            p.y = e.clientY;
+            if (gesture.kind === "pinch" && pointers.size >= 2) {
+                const [a, b] = [...pointers.values()];
+                take(pinchTo(gesture.start, a, b, centre(), limits));
+                emit(false, "pinch");
+            }
+            else if (gesture.kind === "pan") {
+                if (state.zoom > 1) {
+                    take({ ...camera(), panX: gesture.camera.panX + (e.clientX - gesture.x), panY: gesture.camera.panY + (e.clientY - gesture.y) });
+                    emit(false, "drag");
+                }
+            }
+            else if (gesture.kind === "turn") {
+                const dx = e.clientX - gesture.x;
+                const dy = e.clientY - gesture.y;
+                if (Math.abs(dx) + Math.abs(dy) > 3)
+                    gesture.moved = true;
+                if (!canTurn())
+                    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) });
+                emit(false, "drag");
+            }
+        };
+        const onUp = (e) => {
+            if (!pointers.delete(e.pointerId))
+                return;
+            const wasPinch = gesture?.kind === "pinch";
+            const moved = gesture?.kind !== "pinch" && gesture?.moved === true;
+            if (pointers.size === 1) {
+                // One finger left of a pinch carries on as a drag from where it is.
+                const [rest] = [...pointers.values()];
+                gesture = { kind: "pan", x: rest.x, y: rest.y, camera: camera(), moved: true };
+                emit(true, "pinch");
+            }
+            else if (pointers.size === 0) {
+                gesture = undefined;
+                release();
+                delete view.dataset.grab;
+                emit(true, "drag");
+                // A double press (two quick taps or clicks, hardly moved): in to 2x where it was pressed, and again back to 1x.
+                if (!wasPinch && !moved && e.type === "pointerup") {
+                    if (e.timeStamp - lastTap < 350 && Math.hypot(e.clientX - lastTapAt.x, e.clientY - lastTapAt.y) < 24) {
+                        lastTap = 0;
+                        controller.zoomAt(state.zoom > ZOOMED ? 1 : 2, { x: e.clientX, y: e.clientY });
+                    }
+                    else {
+                        lastTap = e.timeStamp;
+                        lastTapAt = { x: e.clientX, y: e.clientY };
+                    }
+                }
+            }
+        };
+        const onWheel = (e) => {
+            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();
+                controller.zoomAt(state.zoom * wheelZoomFactor(e.deltaY, e.deltaMode), { x: e.clientX, y: e.clientY });
+                return;
+            }
+            const horizontal = Math.abs(e.deltaX) > Math.abs(e.deltaY);
+            const focused = view.ownerDocument.activeElement === view;
+            // A sideways swipe turns it wherever the pointer is over it; an up and down wheel only when the view has focus, as the page's scroll comes first.
+            if (!horizontal && !focused)
+                return;
+            e.preventDefault();
+            if (!canTurn())
+                return;
+            if (horizontal || e.shiftKey)
+                controller.set({ yaw: state.yaw + (e.deltaX || e.deltaY) * 0.3 }, true, "wheel");
+            else
+                controller.set({ tilt: Math.round(state.tilt + e.deltaY * 0.15) }, true, "wheel");
+        };
+        const onKey = (e) => {
+            if (e.ctrlKey || e.metaKey || e.altKey)
+                return;
+            const big = e.shiftKey ? 45 : 15;
+            const turn = (next) => {
+                if (canTurn())
+                    controller.set(next, true, "key");
+            };
+            switch (e.key) {
+                case "ArrowLeft":
+                    turn({ yaw: state.yaw - big });
+                    break;
+                case "ArrowRight":
+                    turn({ yaw: state.yaw + big });
+                    break;
+                case "ArrowUp":
+                    turn({ tilt: state.tilt + 5 });
+                    break;
+                case "ArrowDown":
+                    turn({ tilt: state.tilt - 5 });
+                    break;
+                case "+":
+                case "=":
+                    controller.zoomBy(1.25);
+                    break;
+                case "-":
+                case "_":
+                    controller.zoomBy(1 / 1.25);
+                    break;
+                case "0":
+                case "Home":
+                    controller.front();
+                    controller.fit();
+                    break;
+                default: return;
+            }
+            e.preventDefault();
+        };
+        const onMenu = (e) => e.preventDefault();
+        view.addEventListener("pointerdown", onDown);
+        view.addEventListener("pointermove", onMove);
+        view.addEventListener("pointerup", onUp);
+        view.addEventListener("pointercancel", onUp);
+        view.addEventListener("wheel", onWheel, { passive: false });
+        view.addEventListener("keydown", onKey);
+        // A right press is a pan, not the browser's menu.
+        view.addEventListener("contextmenu", onMenu);
+        view.style.touchAction = state.zoom > ZOOMED ? "none" : "pan-y";
+        const off = () => {
+            view.removeEventListener("pointerdown", onDown);
+            view.removeEventListener("pointermove", onMove);
+            view.removeEventListener("pointerup", onUp);
+            view.removeEventListener("pointercancel", onUp);
+            view.removeEventListener("wheel", onWheel);
+            view.removeEventListener("keydown", onKey);
+            view.removeEventListener("contextmenu", onMenu);
+            view.style.touchAction = "";
+            release();
+            if (bound === view)
+                bound = undefined;
+            unbind = undefined;
+        };
+        unbind = off;
+        return off;
+    }
+    return controller;
+}

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

@@ -0,0 +1 @@
+export declare function defineViewControls(registry?: CustomElementRegistry): boolean;

package/dist/view-controls/define.js

@@ -0,0 +1,14 @@
+// Importing this registers <kazoku-view-controls>, unless the tag is already taken.
+//
+// `customElements.define` throws when a name is already registered, and a page can meet that without doing anything wrong: two copies of
+// this package (an app and a widget that each bundle one, or two versions), the script loaded twice, or a page that registered the tag itself
+// to supply its own element. A throw here would stop the importing module, and with it the page's script. So the tag is defined only when
+// nobody has, and the first definition wins; read `customElements.get("kazoku-view-controls")` to see which one that is.
+import { TAG, ViewControlsElement } from "./element.js";
+export function defineViewControls(registry = customElements) {
+    if (registry.get(TAG) !== undefined)
+        return false;
+    registry.define(TAG, ViewControlsElement);
+    return true;
+}
+defineViewControls();

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

@@ -0,0 +1,41 @@
+import { type ViewController, type ViewState } from "./controller.ts";
+import { EVENT, TAG } from "./index.ts";
+import { type ViewWords } from "./words.ts";
+export { EVENT, TAG };
+/** What the `kazoku-viewchange` event carries in `detail`. */
+export interface ViewChangeDetail extends ViewState {
+    final: boolean;
+    reason: string;
+}
+/**
+ * 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
+ * or dark), `overlay` (sit over the bottom of a positioned parent).
+ */
+export declare class ViewControlsElement extends HTMLElement {
+    #private;
+    static observedAttributes: string[];
+    constructor();
+    /** The controller behind the element: the same methods and state a page that wants no element would use. */
+    get controller(): ViewController;
+    /** The view now (a copy). */
+    get state(): ViewState;
+    get view(): HTMLElement | undefined;
+    /** The element the hands bind to, in place of `for`. */
+    set view(element: HTMLElement | undefined);
+    /** Your own labels over the language's, for example `{ front: "Home" }`. */
+    set words(words: Partial<ViewWords>);
+    play(): void;
+    pause(): void;
+    front(): void;
+    fit(): void;
+    set(next: Partial<ViewState>): void;
+    /** What zoom 1 means to the page: the scene is drawn at `state.zoom * fitScale`. */
+    get fitScale(): number;
+    setFitScale(scale: number): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+}