@johnmorrisdotca/kazoku-ui 0.15.2 → 0.17.0

package/dist/view-controls/controller.js

@@ -1,5 +1,5 @@
 import { turnOnlyInSight } from "./sight.js";
-import { between, clamp, clampPan, DEFAULT_LIMITS, dragTurn, PAN_STEP, pinchTo, WHEEL_GESTURE_MS, wheelZoomFactor, wrapYaw, ZOOMED, zoomAbout } from "./math.js";
+import { between, clamp, clampPan, DEFAULT_LIMITS, dragTurn, eulerFromQuat, PAN_STEP, pendulumTilt, pinchTo, quatFromEuler, quatIdentity, spinLocal, tumbleRates, WHEEL_GESTURE_MS, 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]";
 /** How long a move to the middle takes. */
@@ -21,11 +21,15 @@ export function createViewController(options = {}) {
     let destroyed = false;
     let centring = 0;
     let stepping = false;
+    let tiltPhase = 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 };
+    const state = { yaw: 0, tilt: 0, roll: 0, orientation: quatIdentity(), zoom: 1, panX: 0, panY: 0, turning: false, drag: "move", ...options.initial };
+    if (state.orientation === undefined)
+        state.orientation = quatIdentity();
+    state.roll ??= 0;
     if (start !== "fit")
         state.zoom = clamp(startState(), limits.zoomMin, limits.zoomMax);
     atStart = state.zoom === clamp(startState(), limits.zoomMin, limits.zoomMax);
@@ -51,17 +55,25 @@ export function createViewController(options = {}) {
     };
     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 pose = () => {
+        state.orientation = quatFromEuler(state.yaw, state.tilt, state.roll ?? 0);
+    };
     const take = (next) => {
         if (!stepping)
             stopCentre();
-        const held = clampPan({ ...next, zoom: clamp(next.zoom, limits.zoomMin, limits.zoomMax), tilt: clamp(next.tilt, -limits.tiltMax, limits.tiltMax) }, size(), controller.objectSize);
+        const rollMax = limits.rollMax;
+        const roll = clamp(wrapYaw(next.roll ?? state.roll ?? 0), -rollMax, rollMax);
+        const held = clampPan({ ...next, roll, zoom: clamp(next.zoom, limits.zoomMin, limits.zoomMax), tilt: clamp(next.tilt, -limits.tiltMax, limits.tiltMax) }, size(), controller.objectSize);
         state.yaw = controller.turnable ? wrapYaw(held.yaw) : state.yaw;
         state.tilt = controller.turnable ? held.tilt : state.tilt;
+        state.roll = controller.turnable ? roll : state.roll;
         if (held.zoom !== state.zoom)
             atStart = false;
         state.zoom = held.zoom;
         state.panX = held.panX;
         state.panY = held.panY;
+        pose();
+        tiltPhase = Math.asin(clamp(state.tilt / (limits.tiltMax || 1), -1, 1));
     };
     const centre = () => {
         if (bound === undefined)
@@ -86,20 +98,71 @@ export function createViewController(options = {}) {
             last = 0;
             return;
         }
-        const dt = last === 0 ? 0 : Math.min(0.1, (now - last) / 1000);
+        const gap = last === 0 ? 0 : (now - last) / 1000;
+        // The picture moves at most a tenth of a second in one frame, so a late frame does not jump. The limit counts the time that really passed, up to a second, so a turn that stops itself does so when that time has passed.
+        const dt = Math.min(0.1, gap);
         last = now;
-        if (dt === 0)
+        if (gap === 0)
             return;
-        state.yaw = wrapYaw(state.yaw + controller.speed * dt);
-        turned += dt;
+        const rate = controller.speed;
+        if (controller.turnAxis === "tilt")
+            stepTilt(dt, rate);
+        else if (controller.turnAxis === "roll")
+            stepRoll(dt, rate);
+        else if (controller.turnAxis === "all")
+            stepAll(dt);
+        else {
+            state.yaw = wrapYaw(state.yaw + rate * dt);
+            pose();
+        }
+        turned += Math.min(gap, 1);
         emit(false, "auto");
         if (limit > 0 && turned >= limit)
             controller.pause();
     };
+    /** Tilt within the limit swings back. At 90 degrees or more it rolls over on the quaternion, so the up axis never flips. */
+    const stepTilt = (dt, rate) => {
+        if (limits.tiltMax >= 90) {
+            state.orientation = spinLocal(state.orientation, 0, rate * dt, 0);
+            const euler = eulerFromQuat(state.orientation);
+            state.yaw = euler.yaw;
+            state.tilt = euler.tilt;
+            state.roll = euler.roll;
+            return;
+        }
+        tiltPhase += (rate * dt * Math.PI) / 180;
+        state.tilt = pendulumTilt(tiltPhase, limits.tiltMax);
+        pose();
+    };
+    const stepRoll = (dt, rate) => {
+        const max = limits.rollMax;
+        state.roll = max >= 180 ? wrapYaw((state.roll ?? 0) + rate * dt) : clamp((state.roll ?? 0) + rate * dt, -max, max);
+        pose();
+    };
+    const stepAll = (dt) => {
+        const signs = { yaw: controller.speed, tilt: controller.tiltSign, roll: controller.rollSign };
+        const rates = tumbleRates(turned, Math.abs(controller.speed), signs);
+        if (limits.tiltMax >= 90) {
+            state.orientation = spinLocal(state.orientation, rates.yaw * dt, rates.tilt * dt, rates.roll * dt);
+            const euler = eulerFromQuat(state.orientation);
+            state.yaw = euler.yaw;
+            state.tilt = euler.tilt;
+            state.roll = euler.roll;
+            return;
+        }
+        state.yaw = wrapYaw(state.yaw + rates.yaw * dt);
+        state.roll = wrapYaw((state.roll ?? 0) + rates.roll * dt);
+        tiltPhase += (rates.tilt * dt * Math.PI) / 180;
+        state.tilt = pendulumTilt(tiltPhase, limits.tiltMax);
+        pose();
+    };
     const controller = {
         state,
         turnable: options.turnable ?? true,
         speed: options.speed ?? 30,
+        turnAxis: options.turnAxis ?? "angle",
+        tiltSign: 1,
+        rollSign: 1,
         limits,
         ignore: options.ignore ?? DEFAULT_IGNORE,
         anchor: options.anchor,
@@ -193,7 +256,7 @@ export function createViewController(options = {}) {
             last = 0;
         },
         front() {
-            take({ ...camera(), yaw: 0, tilt: 0 });
+            take({ ...camera(), yaw: 0, tilt: 0, roll: 0 });
             emit(true, "front");
         },
         fit() {
@@ -203,7 +266,7 @@ export function createViewController(options = {}) {
         centre(animate = true) {
             stopCentre();
             const from = camera();
-            const to = { yaw: 0, tilt: 0, zoom: 1, panX: 0, panY: 0 };
+            const to = { yaw: 0, tilt: 0, roll: 0, zoom: 1, panX: 0, panY: 0 };
             const reduced = globalThis.matchMedia?.("(prefers-reduced-motion: reduce)")?.matches === true;
             const same = from.yaw === 0 && from.tilt === 0 && from.zoom === 1 && from.panX === 0 && from.panY === 0;
             if (!animate || reduced || same || destroyed) {

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

@@ -12,7 +12,7 @@ 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), `autoplay-for` (stop that turn by itself after this many seconds of turning), `speed` (degrees a second at a pace of 1), `pace` (the auto-turn speed as a multiple of `speed`, 1 by default; the reader's choice of the buttons is written here and kept in the address as `pace`), `paces` (the speeds the buttons stand for, `0.5 1 2` by default),
+ * buttons, links and form controls by default), `autoplay` (turn by itself from the start, unless the reader prefers reduced motion), `autoplay-for` (stop a turn by itself after this many seconds of turning: the one `autoplay` starts, and one the Play button or `play()` starts), `speed` (degrees a second at a pace of 1; a negative one starts the turn to the left), `direction` (`left` or `right`: which way Auto-turn goes; the reader's choice of the Left and Right buttons is written here and kept in the address as `direction`, and the angle goes on from where it was at the same speed), `pace` (the auto-turn speed as a multiple of `speed`, 1 by default; the reader's choice of the buttons is written here and kept in the address as `pace`), `paces` (the speeds the buttons stand for, `0.5 1 2` by default),
  * `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; the wheel itself zooms),
  * `controls` (`basic`, the default, or `advanced`: which controls are shown, the zoom readout in both, and the speed in both while the view turns; the reader's own choice with the More button is remembered in localStorage, under `kazoku-view-controls` or the key `storage` names, and wins),
  * `layout` (`classic`, the default, `horizontal`, `vertical` or `compact`: where the controls sit; the horizontal, vertical and compact layouts have the zoom slider),
@@ -32,7 +32,8 @@ export declare class ViewControlsElement extends HTMLElement {
     set view(element: HTMLElement | undefined);
     /** Your own labels over the language's, for example `{ front: "Home" }`. */
     set words(words: Partial<ViewWords>);
-    play(): void;
+    /** Turn by itself. With `seconds`, stop after that many seconds of turning; else the `autoplay-for` attribute's, if there is one. */
+    play(seconds?: number): void;
     pause(): void;
     front(): void;
     /** Put the object back in the middle at Fit and the default angle, with a brief move (at once for a reader who prefers reduced motion, or with `false`). */

package/dist/view-controls/element.js

@@ -6,7 +6,7 @@ import { localStore, remember } from "../shared/store.js";
 import { DEFAULT_KEYS, formatAddress, parseAddress, parseKeys } from "./address.js";
 import { createViewController, DEFAULT_IGNORE } from "./controller.js";
 import { EVENT, TAG } from "./index.js";
-import { LEVEL_STORAGE_KEY, parseLayout, parseLevel, zoomText } from "./levels.js";
+import { LEVEL_STORAGE_KEY, parseAxis, parseDirection, parseLayout, parseLevel, zoomText } from "./levels.js";
 import { ZOOM_STEP, ZOOMED } from "./math.js";
 import { turnOnlyInSight } from "./sight.js";
 import "../speed-buttons/define.js";
@@ -35,10 +35,23 @@ const THUMB = 28;
 const HTML = `
 <div class="bar" part="bar" role="group">
   <div class="field angle" part="field angle"><label data-w="angle" for="yaw"></label><input id="yaw" type="range" min="-180" max="180" step="1" value="0" part="slider" /><output for="yaw" data-o="yaw">0°</output></div>
-  <div class="field tilt adv" part="field tilt"><label data-w="tilt" for="tilt"></label><input id="tilt" type="range" min="-30" max="30" step="1" value="0" part="slider" /><output for="tilt" data-o="tilt">0°</output></div>
+  <div class="field tilt" part="field tilt"><label data-w="tilt" for="tilt"></label><input id="tilt" type="range" min="-30" max="30" step="1" value="0" part="slider" /><output for="tilt" data-o="tilt">0°</output></div>
+  <div class="field roll" part="field roll"><label data-w="roll" for="roll"></label><input id="roll" type="range" min="-180" max="180" step="1" value="0" part="slider" /><output for="roll" data-o="roll">0°</output></div>
+  <div class="group axes" role="group" data-g="axes">
+    <button type="button" data-b="axis-angle" aria-pressed="true" part="button"><span data-w="angle"></span></button>
+    <button type="button" data-b="axis-tilt" aria-pressed="false" part="button"><span data-w="tilt"></span></button>
+    <button type="button" data-b="axis-roll" aria-pressed="false" part="button"><span data-w="roll"></span></button>
+    <button type="button" data-b="axis-all" aria-pressed="false" part="button"><span data-w="tumble"></span></button>
+  </div>
   <button type="button" class="pace-now" data-b="pace-now" part="button" hidden><span class="lbl" data-w="speed"></span><span data-o="pace"></span></button>
   <button type="button" class="play" data-b="play" aria-pressed="false" part="button">${ICON.play}${ICON.pause}<span class="text" data-w="autoTurn"></span></button>
-  <kazoku-speed-buttons class="pace adv" data-g="pace"></kazoku-speed-buttons>
+  <div class="pacing adv" data-g="pacing">
+    <kazoku-speed-buttons class="pace" data-g="pace"></kazoku-speed-buttons>
+    <div class="group dir" role="group" data-g="direction">
+      <button type="button" data-b="turn-left" aria-pressed="false" part="button">${ICON.left}<span data-w="turnLeft"></span></button>
+      <button type="button" data-b="turn-right" aria-pressed="true" part="button">${ICON.right}<span data-w="turnRight"></span></button>
+    </div>
+  </div>
   <button type="button" class="front adv" data-b="front" part="button"><span data-w="front"></span></button>
   <button type="button" class="centre" data-b="centre" part="button" hidden>${ICON.centre}<span class="text" data-w="centre"></span></button>
   <div class="group zoom" role="group" data-g="zoom">
@@ -64,7 +77,7 @@ 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), `autoplay-for` (stop that turn by itself after this many seconds of turning), `speed` (degrees a second at a pace of 1), `pace` (the auto-turn speed as a multiple of `speed`, 1 by default; the reader's choice of the buttons is written here and kept in the address as `pace`), `paces` (the speeds the buttons stand for, `0.5 1 2` by default),
+ * buttons, links and form controls by default), `autoplay` (turn by itself from the start, unless the reader prefers reduced motion), `autoplay-for` (stop a turn by itself after this many seconds of turning: the one `autoplay` starts, and one the Play button or `play()` starts), `speed` (degrees a second at a pace of 1; a negative one starts the turn to the left), `direction` (`left` or `right`: which way Auto-turn goes; the reader's choice of the Left and Right buttons is written here and kept in the address as `direction`, and the angle goes on from where it was at the same speed), `pace` (the auto-turn speed as a multiple of `speed`, 1 by default; the reader's choice of the buttons is written here and kept in the address as `pace`), `paces` (the speeds the buttons stand for, `0.5 1 2` by default),
  * `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; the wheel itself zooms),
  * `controls` (`basic`, the default, or `advanced`: which controls are shown, the zoom readout in both, and the speed in both while the view turns; the reader's own choice with the More button is remembered in localStorage, under `kazoku-view-controls` or the key `storage` names, and wins),
  * `layout` (`classic`, the default, `horizontal`, `vertical` or `compact`: where the controls sit; the horizontal, vertical and compact layouts have the zoom slider),
@@ -72,7 +85,7 @@ const HTML = `
  * 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", "anchor", "key-tilt", "stop-turn", "tilt-step", "grab-radius", "object-size", "speed", "pace", "paces", "controls", "layout", "flat", "tilt-max", "zoom-min", "zoom-max", "address-keys"];
+    static observedAttributes = ["for", "lang", "yaw", "tilt", "roll", "zoom", "fit-scale", "ignore", "anchor", "key-tilt", "stop-turn", "tilt-step", "grab-radius", "object-size", "speed", "direction", "tilt-direction", "roll-direction", "axis", "pace", "paces", "controls", "layout", "flat", "tilt-max", "roll-max", "zoom-min", "zoom-max", "address-keys"];
     #root;
     #controller;
     #view;
@@ -91,6 +104,13 @@ export class ViewControlsElement extends HTMLElement {
     /** The zoom the slider shows now; NaN until it has shown one, and again when the marks are redrawn for new limits. */
     #zoomShown = Number.NaN;
     #pace = 1;
+    /** Which way the turn goes now, and the way the page itself starts it (its `direction`, else the sign of its `speed`): the address keeps a way only when it is not the start. */
+    #direction = "right";
+    #start;
+    #axis = "angle";
+    #tiltWay = "right";
+    #rollWay = "right";
+    #writing = false;
     #labels = wordsFor("en");
     #said = "";
     #sayTimer;
@@ -118,8 +138,9 @@ export class ViewControlsElement extends HTMLElement {
         this.#words = words;
         this.#label();
     }
-    play() {
-        this.#ensure().play();
+    /** Turn by itself. With `seconds`, stop after that many seconds of turning; else the `autoplay-for` attribute's, if there is one. */
+    play(seconds) {
+        this.#ensure().play(seconds ?? this.#playLimit());
     }
     pause() {
         this.#ensure().pause();
@@ -162,16 +183,35 @@ export class ViewControlsElement extends HTMLElement {
         this.#arrange();
         this.#limits();
         const start = {};
-        for (const key of ["yaw", "tilt"]) {
+        for (const key of ["yaw", "tilt", "roll"]) {
             const value = Number(this.getAttribute(key));
             if (this.hasAttribute(key) && Number.isFinite(value))
                 start[key] = value;
         }
-        const { pace, ...chosen } = this.hasAttribute("address") ? parseAddress(globalThis.location?.search ?? "", this.#keys, c.limits) : {};
+        const { pace, direction, axis, tiltDirection, rollDirection, ...chosen } = this.hasAttribute("address") ? parseAddress(globalThis.location?.search ?? "", this.#keys, c.limits) : {};
         Object.assign(start, chosen);
+        this.#axis = axis ?? parseAxis(this.getAttribute("axis")) ?? this.#axis;
+        if (tiltDirection)
+            this.#tiltWay = tiltDirection;
+        else {
+            const tiltWay = parseDirection(this.getAttribute("tilt-direction"));
+            if (tiltWay !== undefined)
+                this.#tiltWay = tiltWay;
+        }
+        if (rollDirection)
+            this.#rollWay = rollDirection;
+        else {
+            const rollWay = parseDirection(this.getAttribute("roll-direction"));
+            if (rollWay !== undefined)
+                this.#rollWay = rollWay;
+        }
         c.turnable = !this.hasAttribute("flat");
         this.#level = parseLevel(this.#remembered()) ?? parseLevel(this.getAttribute("controls")) ?? "basic";
         this.#pace = this.#nearestPace(pace ?? parseSpeed(this.getAttribute("pace"), this.#paces()) ?? 1);
+        // Read once: put back on a page after a move, the element is still started by the page and not by the way the reader has since chosen (which is in the attribute now).
+        const first = this.#start === undefined;
+        this.#start ??= this.#startDirection();
+        this.#direction = direction ?? (first ? this.#start : this.#direction);
         this.#speed();
         c.ignore = this.getAttribute("ignore") ?? DEFAULT_IGNORE;
         for (const name of ["key-tilt", "stop-turn", "tilt-step", "grab-radius", "object-size"])
@@ -197,7 +237,7 @@ export class ViewControlsElement extends HTMLElement {
                 return;
             this.#dispatch(c.state, { final: true, reason: "init" });
             if (this.hasAttribute("autoplay") && !globalThis.matchMedia?.("(prefers-reduced-motion: reduce)").matches)
-                c.play(Number(this.getAttribute("autoplay-for")));
+                c.play(this.#playLimit());
         });
     }
     disconnectedCallback() {
@@ -223,10 +263,15 @@ export class ViewControlsElement extends HTMLElement {
             this.#resolveView();
         else if (name === "lang")
             this.#label();
-        else if (name === "yaw" || name === "tilt") {
+        else if (name === "yaw" || name === "tilt" || name === "roll") {
             if (value !== null && Number.isFinite(Number(value)))
                 c.set({ [name]: Number(value) });
         }
+        else if (name === "axis") {
+            this.#axis = parseAxis(value) ?? "angle";
+            this.#speed();
+            this.#show();
+        }
         else if (name === "zoom")
             c.setStartZoom(this.#startZoom());
         else if (name === "fit-scale")
@@ -235,8 +280,33 @@ export class ViewControlsElement extends HTMLElement {
             c.ignore = value ?? DEFAULT_IGNORE;
         else if (name === "anchor" || name === "key-tilt" || name === "stop-turn" || name === "tilt-step" || name === "grab-radius" || name === "object-size")
             this.#option(name);
-        else if (name === "speed")
+        else if (name === "speed") {
+            // The page's own start follows its speed's sign, unless the reader has chosen the other way.
+            const start = this.#startDirection();
+            if (this.#direction === (this.#start ?? start))
+                this.#direction = start;
+            this.#start = start;
+            this.#speed();
+            this.#show();
+        }
+        else if (name === "direction") {
+            if (this.#writing)
+                return;
+            this.#start = this.#direction = this.#startDirection();
             this.#speed();
+            this.#show();
+        }
+        else if (name === "tilt-direction" || name === "roll-direction") {
+            if (this.#writing)
+                return;
+            const way = parseDirection(value) ?? "right";
+            if (name === "tilt-direction")
+                this.#tiltWay = way;
+            else
+                this.#rollWay = way;
+            this.#speed();
+            this.#show();
+        }
         else if (name === "pace" || name === "paces") {
             this.#pace = this.#nearestPace(parseSpeed(this.getAttribute("pace"), this.#paces()) ?? this.#pace);
             this.#speed();
@@ -312,30 +382,38 @@ export class ViewControlsElement extends HTMLElement {
         const c = () => this.#ensure();
         const slider = (id) => {
             const input = q(`#${id}`);
-            // A hand on the angle slider holds the automatic turn still while it is down; the turn then goes on from where the hand left it.
+            // A hand on a turn slider holds the automatic turn still while it is down; the turn then goes on from where the hand left it.
             const hold = () => {
                 this.#sliderHeld += 1;
-                if (this.#sliderHeld === 1 && id === "yaw")
+                if (this.#sliderHeld === 1)
                     c().holdTurn();
             };
             const free = () => {
                 if (this.#sliderHeld === 0)
                     return;
                 this.#sliderHeld = 0;
-                if (id === "yaw")
-                    c().releaseTurn();
+                c().releaseTurn();
             };
             input.addEventListener("pointerdown", () => hold());
             input.addEventListener("pointerup", free);
             input.addEventListener("pointercancel", free);
-            input.addEventListener("input", () => c().set({ [id]: Number(input.value) }, false, "slider"));
-            input.addEventListener("change", () => c().set({ [id]: Number(input.value) }, true, "slider"));
+            input.addEventListener("input", () => c().set({ [id === "yaw" ? this.#hand() : id]: Number(input.value) }, false, "slider"));
+            input.addEventListener("change", () => c().set({ [id === "yaw" ? this.#hand() : id]: Number(input.value) }, true, "slider"));
         };
         slider("yaw");
         slider("tilt");
+        slider("roll");
+        for (const axis of ["angle", "tilt", "roll", "all"]) {
+            q(`[data-b="axis-${axis}"]`).addEventListener("click", () => this.#chooseAxis(axis));
+        }
         this.#zoomSlider(q("#zoom"), c);
         const on = (b, run) => q(`[data-b="${b}"]`).addEventListener("click", run);
-        on("play", () => c().toggle());
+        on("play", () => {
+            if (c().state.turning)
+                c().pause();
+            else
+                c().play(this.#playLimit());
+        });
         on("front", () => c().front());
         on("out", () => c().zoomBy(1 / ZOOM_STEP));
         on("in", () => c().zoomBy(ZOOM_STEP));
@@ -357,6 +435,8 @@ export class ViewControlsElement extends HTMLElement {
                 this.#choosePace(value);
         });
         on("pace-now", () => speeds.step(1));
+        on("turn-left", () => this.#chooseDirection("left"));
+        on("turn-right", () => this.#chooseDirection("right"));
         on("left", () => c().panBy(-1, 0));
         on("right", () => c().panBy(1, 0));
         on("up", () => c().panBy(0, -1));
@@ -462,9 +542,80 @@ export class ViewControlsElement extends HTMLElement {
         if (this.hasAttribute("address"))
             this.#save();
     }
-    /** The turn's degrees a second: the `speed` attribute (30) times the pace. */
+    /** The way the page itself starts the turn: its `direction`, else left for a negative `speed` and right for the rest. */
+    #startDirection() {
+        return parseDirection(this.getAttribute("direction")) ?? (Number(this.getAttribute("speed")) < 0 ? "left" : "right");
+    }
+    /** The seconds `autoplay-for` limits a turn to, or `undefined` for none. */
+    #playLimit() {
+        const seconds = Number(this.getAttribute("autoplay-for"));
+        return seconds > 0 && Number.isFinite(seconds) ? seconds : undefined;
+    }
+    /** A way was pressed. It sets the active axis's direction (all three when All is on). The angle goes on from where it was. */
+    #chooseDirection(direction) {
+        const axes = this.#axis === "all" ? ["angle", "tilt", "roll"] : [this.#axis];
+        for (const axis of axes)
+            this.#putWay(axis, direction);
+        this.#speed();
+        this.#show();
+        if (this.hasAttribute("address"))
+            this.#save();
+    }
+    #putWay(axis, direction) {
+        const name = axis === "tilt" ? "tilt-direction" : axis === "roll" ? "roll-direction" : "direction";
+        if (axis === "tilt")
+            this.#tiltWay = direction;
+        else if (axis === "roll")
+            this.#rollWay = direction;
+        else
+            this.#direction = direction;
+        if (this.getAttribute(name) !== direction) {
+            this.#writing = true;
+            this.setAttribute(name, direction);
+            this.#writing = false;
+        }
+    }
+    /** Which axis Auto-turn drives, and which slider a reader last named. Angle is the start, so it leaves the attribute. */
+    #chooseAxis(axis) {
+        this.#axis = axis;
+        const written = axis === "angle" ? null : axis;
+        if (this.getAttribute("axis") !== written) {
+            this.#writing = true;
+            if (written === null)
+                this.removeAttribute("axis");
+            else
+                this.setAttribute("axis", written);
+            this.#writing = false;
+        }
+        this.#speed();
+        this.#show();
+        if (this.hasAttribute("address"))
+            this.#save();
+    }
+    /** The slider shows this axis. All is a tumble, so the slider stays on the angle. */
+    #hand() {
+        if (this.#axis === "tilt")
+            return "tilt";
+        if (this.#axis === "roll")
+            return "roll";
+        return "yaw";
+    }
+    /** The way Left and Right show for the axis that is on. All shows the angle's way. */
+    #activeWay() {
+        if (this.#axis === "tilt")
+            return this.#tiltWay;
+        if (this.#axis === "roll")
+            return this.#rollWay;
+        return this.#direction;
+    }
+    /** The turn's degrees a second: the size of the `speed` attribute (30) times the pace, going left when the active axis says so. */
     #speed() {
-        this.#ensure().speed = (Number(this.getAttribute("speed")) || 30) * this.#pace;
+        const c = this.#ensure();
+        const size = Math.abs(Number(this.getAttribute("speed")) || 30) * this.#pace;
+        c.turnAxis = this.#axis;
+        c.tiltSign = this.#tiltWay === "left" ? -1 : 1;
+        c.rollSign = this.#rollWay === "left" ? -1 : 1;
+        c.speed = size * (this.#activeWay() === "left" ? -1 : 1);
     }
     #limits() {
         const c = this.#ensure();
@@ -473,6 +624,7 @@ export class ViewControlsElement extends HTMLElement {
             return this.hasAttribute(name) && Number.isFinite(value) && value > 0 ? value : fallback;
         };
         c.limits.tiltMax = read("tilt-max", 30);
+        c.limits.rollMax = read("roll-max", 180);
         c.limits.zoomMin = Math.min(1, read("zoom-min", 1));
         c.limits.zoomMax = Math.max(c.limits.zoomMin, read("zoom-max", 5));
         const tilt = this.#root.querySelector("#tilt");
@@ -480,6 +632,11 @@ export class ViewControlsElement extends HTMLElement {
             tilt.min = String(-c.limits.tiltMax);
             tilt.max = String(c.limits.tiltMax);
         }
+        const roll = this.#root.querySelector("#roll");
+        if (roll !== null) {
+            roll.min = String(-c.limits.rollMax);
+            roll.max = String(c.limits.rollMax);
+        }
         this.#drawMarks();
     }
     #resolveView() {
@@ -522,6 +679,8 @@ export class ViewControlsElement extends HTMLElement {
         set('[data-b="in"]', words.zoomIn);
         set('[data-g="zoom"]', words.zoom);
         set('[data-g="pan"]', words.pan);
+        set('[data-g="direction"]', words.direction);
+        set('[data-g="axes"]', words.axis);
         set('[data-g="drag"]', words.drag);
         const speeds = this.#root.querySelector("kazoku-speed-buttons");
         speeds?.setAttribute("lang", language);
@@ -540,17 +699,37 @@ export class ViewControlsElement extends HTMLElement {
         const q = (selector) => this.#root.querySelector(selector);
         const yaw = q("#yaw");
         const tilt = q("#tilt");
-        yaw.value = String(Math.round(s.yaw));
+        const roll = q("#roll");
         tilt.value = String(Math.round(s.tilt));
-        q('[data-o="yaw"]').value = `${Math.round(s.yaw)}°`;
+        roll.value = String(Math.round(s.roll ?? 0));
+        // The one slider shows the axis the chips have chosen. All keeps the angle, which is where a tumble is read from.
+        const hand = this.#hand();
+        const span = hand === "tilt" ? c.limits.tiltMax : hand === "roll" ? c.limits.rollMax : 180;
+        const value = hand === "tilt" ? s.tilt : hand === "roll" ? (s.roll ?? 0) : s.yaw;
+        const text = String(Math.round(value));
+        if (yaw.max !== String(span)) {
+            yaw.max = String(span);
+            yaw.min = String(-span);
+        }
+        if (yaw.value !== text)
+            yaw.value = text;
+        const words = this.#labels;
+        const name = hand === "tilt" ? words.tilt : hand === "roll" ? words.roll : words.angle;
+        const label = q('[data-w="angle"]');
+        if (label.textContent !== name)
+            label.textContent = name;
+        q('[data-o="yaw"]').value = `${text}°`;
         q('[data-o="tilt"]').value = `${Math.round(s.tilt)}°`;
+        q('[data-o="roll"]').value = `${Math.round(s.roll ?? 0)}°`;
+        for (const axis of ["angle", "tilt", "roll", "all"]) {
+            q(`[data-b="axis-${axis}"]`).setAttribute("aria-pressed", String(this.#axis === axis));
+        }
         q('[data-b="play"]').setAttribute("aria-pressed", String(s.turning));
         // Centre comes in once the view has been zoomed or moved, which is when the object can be lost; it puts it back in the middle at Fit and the default angle.
         q(".centre").hidden = s.zoom === 1 && s.panX === 0 && s.panY === 0;
         q('[data-b="out"]').disabled = s.zoom <= c.limits.zoomMin + 1e-6;
         q('[data-b="in"]').disabled = s.zoom >= c.limits.zoomMax - 1e-6;
         const advanced = this.#level === "advanced";
-        const words = this.#labels;
         const zoom = zoomText(s.zoom);
         // A frame of the automatic turn comes through here: what has not changed is not written.
         const write = (node, text) => {
@@ -586,6 +765,9 @@ export class ViewControlsElement extends HTMLElement {
         const pace = speedText(this.#pace);
         write(q('[data-o="pace"]'), pace);
         say(q('[data-b="pace-now"]'), `${words.speed}: ${pace}`);
+        const way = this.#activeWay();
+        q('[data-b="turn-left"]').setAttribute("aria-pressed", String(way === "left"));
+        q('[data-b="turn-right"]').setAttribute("aria-pressed", String(way === "right"));
         const more = q('[data-b="more"]');
         more.setAttribute("aria-expanded", String(advanced));
         this.dataset.level = this.#level;
@@ -596,9 +778,9 @@ export class ViewControlsElement extends HTMLElement {
         q('[data-b="turn"]').setAttribute("aria-pressed", String(s.drag === "turn"));
         // A flat view cannot turn: the angle, tilt, auto-turn and front are not shown, and a drag only moves.
         const flat = !c.turnable;
-        for (const selector of [".angle", ".play"])
+        for (const selector of [".angle", ".tilt", ".roll", ".play", '[data-g="axes"]'])
             q(selector).hidden = flat;
-        for (const selector of [".tilt", ".front", '[data-g="drag"]', '[data-g="pace"]'])
+        for (const selector of [".front", '[data-g="drag"]', '[data-g="pacing"]'])
             q(selector).hidden = flat || !advanced;
         // The speed is always in sight while the view turns: one small button in basic, which steps through the three; advanced always has the three.
         q(".pace-now").hidden = flat || advanced || !s.turning;
@@ -636,7 +818,14 @@ export class ViewControlsElement extends HTMLElement {
     #save() {
         this.#writer.write((search) => {
             const s = this.#ensure().state;
-            return formatAddress(search, { ...s, pace: this.#pace }, this.#keys, s.turning, this.#ensure().startZoom);
+            return formatAddress(search, {
+                ...s,
+                pace: this.#pace,
+                direction: this.#direction === (this.#start ?? this.#direction) ? null : this.#direction,
+                axis: this.#axis,
+                tiltDirection: this.#tiltWay === "right" ? null : this.#tiltWay,
+                rollDirection: this.#rollWay === "right" ? null : this.#rollWay,
+            }, this.#keys, s.turning, this.#ensure().startZoom);
         });
     }
 }

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

@@ -1,8 +1,8 @@
 export { DEFAULT_KEYS, formatAddress, parseAddress, parseKeys, type AddressChoices, type AddressKeys, type DragMode } from "./address.ts";
 export { createViewController, DEFAULT_IGNORE, type ChangeInfo, type Clock, type ViewController, type ViewControllerOptions, type ViewState } from "./controller.ts";
-export { between, clamp, clampPan, DEFAULT_LIMITS, degreesPerPixel, dragTurn, PAN_STEP, pinchTo, TILT_ACROSS, TURN_ACROSS, WHEEL_GESTURE_MS, wheelZoomFactor, wrapYaw, ZOOM_STEP, ZOOMED, zoomAbout, type Camera, type Limits, type PinchStart, type Point, type Size } from "./math.ts";
+export { between, clamp, clampPan, DEFAULT_LIMITS, degreesPerPixel, dragTurn, eulerFromQuat, PAN_STEP, pendulumTilt, pinchTo, quatFromEuler, quatIdentity, rateSign, spinLocal, TILT_ACROSS, tumbleRates, TURN_ACROSS, upVector, WHEEL_GESTURE_MS, wheelZoomFactor, wrapYaw, ZOOM_STEP, ZOOMED, zoomAbout, type Camera, type Limits, type PinchStart, type Point, type Quat, type Size, type TumbleSigns, type Vec3 } from "./math.ts";
 export { languageOf, WORDS, wordsFor, type Language, type ViewWords } from "./words.ts";
 export declare const EVENT = "kazoku-viewchange";
 export declare const TAG = "kazoku-view-controls";
-export { LAYOUTS, LEVEL_STORAGE_KEY, PACE_FACTOR, PACES, parseLayout, parseLevel, parsePace, zoomText, type Layout, type Level, type Pace } from "./levels.ts";
+export { LAYOUTS, LEVEL_STORAGE_KEY, PACE_FACTOR, PACES, parseAxis, parseLayout, parseLevel, parsePace, zoomText, type Layout, type Level, type Pace, type TurnAxis } from "./levels.ts";
 export { COMMON_ZOOMS, MARK_GAP, SLIDER_STEP, SNAP_PX, zoomAtPosition, zoomMarks, zoomPosition, zoomSnap, zoomStep, zoomToMark, type ZoomMark } from "./zoomScale.ts";

package/dist/view-controls/index.js

@@ -1,9 +1,9 @@
 // The view controls without the element: the controller, the arithmetic, the address and the labels. Nothing here touches the DOM until `bind` is called, so it imports on a server.
 export { DEFAULT_KEYS, formatAddress, parseAddress, parseKeys } from "./address.js";
 export { createViewController, DEFAULT_IGNORE } from "./controller.js";
-export { between, clamp, clampPan, DEFAULT_LIMITS, degreesPerPixel, dragTurn, PAN_STEP, pinchTo, TILT_ACROSS, TURN_ACROSS, WHEEL_GESTURE_MS, wheelZoomFactor, wrapYaw, ZOOM_STEP, ZOOMED, zoomAbout } from "./math.js";
+export { between, clamp, clampPan, DEFAULT_LIMITS, degreesPerPixel, dragTurn, eulerFromQuat, PAN_STEP, pendulumTilt, pinchTo, quatFromEuler, quatIdentity, rateSign, spinLocal, TILT_ACROSS, tumbleRates, TURN_ACROSS, upVector, WHEEL_GESTURE_MS, wheelZoomFactor, wrapYaw, ZOOM_STEP, ZOOMED, zoomAbout } from "./math.js";
 export { languageOf, WORDS, wordsFor } from "./words.js";
 export const EVENT = "kazoku-viewchange";
 export const TAG = "kazoku-view-controls";
-export { LAYOUTS, LEVEL_STORAGE_KEY, PACE_FACTOR, PACES, parseLayout, parseLevel, parsePace, zoomText } from "./levels.js";
+export { LAYOUTS, LEVEL_STORAGE_KEY, PACE_FACTOR, PACES, parseAxis, parseLayout, parseLevel, parsePace, zoomText } from "./levels.js";
 export { COMMON_ZOOMS, MARK_GAP, SLIDER_STEP, SNAP_PX, zoomAtPosition, zoomMarks, zoomPosition, zoomSnap, zoomStep, zoomToMark } from "./zoomScale.js";

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

@@ -8,6 +8,12 @@ export type Pace = "slow" | "medium" | "fast";
 export declare const PACES: readonly Pace[];
 export declare const PACE_FACTOR: Record<Pace, number>;
 export declare const parsePace: (text: string | null | undefined) => Pace | undefined;
+/** Which way Auto-turn goes. By the drag rule `yaw` goes up as the hand goes right, so `right` is a positive speed and `left` a negative one; the page's drawing decides what that looks like. */
+export type Direction = "left" | "right";
+export declare const parseDirection: (text: string | null | undefined) => Direction | undefined;
+/** Which axis Auto-turn drives. `angle` is yaw, the default. `all` is a tumble on yaw, tilt and roll at once. */
+export type TurnAxis = "angle" | "tilt" | "roll" | "all";
+export declare const parseAxis: (text: string | null | undefined) => TurnAxis | undefined;
 /** The zoom as the readout shows it: `1×`, `2.4×`; below 1, two figures, so a small zoom never reads `0×`. */
 export declare const zoomText: (zoom: number) => string;
 /**

package/dist/view-controls/levels.js

@@ -5,6 +5,8 @@ export const LEVEL_STORAGE_KEY = "kazoku-view-controls";
 export const PACES = ["slow", "medium", "fast"];
 export const PACE_FACTOR = { slow: 0.5, medium: 1, fast: 2 };
 export const parsePace = (text) => PACES.find((pace) => pace === text);
+export const parseDirection = (text) => (text === "left" || text === "right" ? text : undefined);
+export const parseAxis = (text) => (text === "angle" || text === "tilt" || text === "roll" || text === "all" ? text : undefined);
 /** The zoom as the readout shows it: `1×`, `2.4×`; below 1, two figures, so a small zoom never reads `0×`. */
 export const zoomText = (zoom) => `${Number(zoom < 1 ? zoom.toPrecision(2) : zoom.toFixed(1))}×`;
 export const LAYOUTS = ["classic", "horizontal", "vertical", "compact"];