@texuli/deck 0.0.0-stage → 0.5.0

package/dist/engine/controller.js

@@ -0,0 +1,248 @@
+/**
+ * Imperative framework-free controller with typed events and ordered plugin hooks.
+ *
+ * `createDeckController(deck, options)` owns navigation, overview/blackout/pause
+ * flags, optional auto-slide, and routes `handleInput` through `decideDeckInput`.
+ * Stage chrome (help, laser, fullscreen, presenter window) stays with the host:
+ * the controller emits the action and leaves rendering to the stage.
+ */
+import { createAutoSlideScheduler } from "./auto-slide.js";
+import { decideDeckInput, } from "./controls.js";
+import { createDeckNavigator, } from "./navigation.js";
+function sameLocation(a, b) {
+    return (a.slideId === b.slideId &&
+        a.slideIndex === b.slideIndex &&
+        a.step === b.step &&
+        a.overview === b.overview &&
+        a.blackout === b.blackout &&
+        a.paused === b.paused);
+}
+export function createDeckController(deck, options = {}) {
+    const navigator = createDeckNavigator(deck, options);
+    let overview = false;
+    let blackout = false;
+    let paused = false;
+    let destroyed = false;
+    const listeners = new Map();
+    const stateListeners = new Set();
+    const cleanups = [];
+    const plugins = options.plugins ?? [];
+    const snapshot = () => ({
+        ...navigator.getLocation(),
+        overview,
+        blackout,
+        paused,
+    });
+    const emit = (event, detail) => {
+        for (const listener of listeners.get(event) ?? []) {
+            listener(detail);
+        }
+    };
+    const announceChange = (previous, source) => {
+        const state = snapshot();
+        if (sameLocation(state, previous))
+            return state;
+        const change = { state, previous, source };
+        emit('statechange', change);
+        for (const listener of stateListeners)
+            listener(state, previous);
+        if (state.slideId !== previous.slideId || state.slideIndex !== previous.slideIndex) {
+            emit('slidechange', change);
+        }
+        else if (state.step !== previous.step) {
+            emit('stepchange', change);
+        }
+        for (const plugin of plugins)
+            plugin.afterNavigate?.(state, previous);
+        return state;
+    };
+    const controller = {};
+    let navigate;
+    const autoMs = options.autoSlideMs ?? deck.navigation?.autoSlideMs ?? 0;
+    const scheduler = autoMs > 0
+        ? createAutoSlideScheduler({
+            intervalMs: autoMs,
+            clock: options.clock,
+            startPaused: options.autoSlidePaused === true || paused,
+            onAdvance: () => {
+                if (!paused && !destroyed)
+                    navigate(() => navigator.next(), 'auto');
+            },
+        })
+        : undefined;
+    navigate = (move, source = 'api', target) => {
+        if (destroyed)
+            return snapshot();
+        const previous = snapshot();
+        let action = move;
+        for (const plugin of plugins) {
+            const decision = plugin.beforeNavigate?.(target ?? previous, previous);
+            if (decision === false)
+                return previous;
+            if (decision && typeof decision === 'object') {
+                const redirected = decision;
+                action = () => navigator.goTo(redirected);
+            }
+        }
+        action();
+        return announceChange(previous, source);
+    };
+    const fireAction = (name, source) => {
+        for (const plugin of plugins)
+            plugin.onAction?.(name, source);
+        emit('action', { action: name, source });
+    };
+    const applyAction = (name, source) => {
+        fireAction(name, source);
+        switch (name) {
+            case 'next':
+                navigate(() => navigator.next(), source);
+                break;
+            case 'prev':
+                navigate(() => navigator.prev(), source);
+                break;
+            case 'first':
+                navigate(() => navigator.first(), source);
+                break;
+            case 'last':
+                navigate(() => navigator.last(), source);
+                break;
+            case 'overview':
+                controller.setOverview(!overview);
+                break;
+            case 'blackout':
+                controller.setBlackout(!blackout);
+                break;
+            default:
+                // Stage-owned chrome: help, laser, fullscreen, presenter, print, …
+                break;
+        }
+    };
+    Object.assign(controller, {
+        goTo(target, opts = {}) {
+            return navigate(() => navigator.goTo(target), opts.source ?? 'api', target);
+        },
+        next(opts = {}) {
+            return navigate(() => navigator.next(), opts.source ?? 'api');
+        },
+        prev(opts = {}) {
+            return navigate(() => navigator.prev(), opts.source ?? 'api');
+        },
+        first(opts = {}) {
+            return navigate(() => navigator.first(), opts.source ?? 'api');
+        },
+        last(opts = {}) {
+            return navigate(() => navigator.last(), opts.source ?? 'api');
+        },
+        getState: snapshot,
+        subscribe(eventOrListener, maybeListener) {
+            if (typeof eventOrListener === 'function') {
+                stateListeners.add(eventOrListener);
+                return () => {
+                    stateListeners.delete(eventOrListener);
+                };
+            }
+            const event = eventOrListener;
+            const listener = maybeListener;
+            const group = listeners.get(event) ?? new Set();
+            group.add(listener);
+            listeners.set(event, group);
+            return () => {
+                group.delete(listener);
+                if (group.size === 0)
+                    listeners.delete(event);
+            };
+        },
+        setOverview(open) {
+            if (overview === open || destroyed)
+                return;
+            overview = open;
+            emit('overview', { open, state: snapshot() });
+        },
+        setBlackout(active) {
+            if (blackout === active || destroyed)
+                return;
+            blackout = active;
+            emit('blackout', { active, state: snapshot() });
+        },
+        pause() {
+            if (paused || destroyed)
+                return;
+            paused = true;
+            scheduler?.pause();
+            emit('pause', { paused: true, state: snapshot() });
+        },
+        resume() {
+            if (!paused || destroyed)
+                return;
+            paused = false;
+            scheduler?.resume();
+            emit('pause', { paused: false, state: snapshot() });
+        },
+        handleInput(input, inputState = {}, source = input.kind === 'swipe'
+            ? 'swipe'
+            : input.kind === 'key'
+                ? 'keyboard'
+                : 'pointer') {
+            if (destroyed)
+                return null;
+            const picked = decideDeckInput(input, {
+                ...inputState,
+                overview: overview ? 'open' : inputState.overview,
+                blackout: blackout || inputState.blackout,
+                dir: inputState.dir ?? deck.meta?.dir,
+            });
+            if (!picked)
+                return null;
+            scheduler?.input();
+            applyAction(picked, source);
+            return picked;
+        },
+        beforeRender(extra = {}) {
+            if (destroyed)
+                return;
+            const state = snapshot();
+            const slide = deck.slides[state.slideIndex];
+            const context = {
+                state,
+                ...(slide ? { slide } : {}),
+                ...extra,
+            };
+            for (const plugin of plugins)
+                plugin.beforeRender?.(context);
+        },
+        afterRender(extra = {}) {
+            if (destroyed)
+                return;
+            const state = snapshot();
+            const slide = deck.slides[state.slideIndex];
+            const context = {
+                state,
+                ...(slide ? { slide } : {}),
+                ...extra,
+            };
+            for (const plugin of plugins)
+                plugin.afterRender?.(context);
+        },
+        destroy() {
+            if (destroyed)
+                return;
+            destroyed = true;
+            scheduler?.stop();
+            for (const cleanup of cleanups.splice(0).reverse())
+                cleanup();
+            for (const plugin of plugins)
+                plugin.onDestroy?.();
+            emit('destroy', { state: snapshot() });
+            listeners.clear();
+            stateListeners.clear();
+        },
+    });
+    for (const plugin of plugins) {
+        const cleanup = plugin.setup?.(controller);
+        if (typeof cleanup === 'function')
+            cleanups.push(cleanup);
+    }
+    scheduler?.start();
+    return controller;
+}

package/dist/engine/controls.d.ts

@@ -0,0 +1,128 @@
+/**
+ * Controls registry and pure input decisions.
+ *
+ * `DECK_CONTROLS` is the single source for the toolbar, help dialog and
+ * `decideDeckInput` key map. No DOM: the host describes the event target as a
+ * path of plain element facts (`inputPathFrom` builds it from a real path).
+ *
+ * Keys (Protoyard registry + Texuli Enter/Backspace):
+ * → ↓ PageDown Space Enter / ← ↑ PageUp Shift+Space Backspace, Home/End,
+ * O, F, S|P, B|., L, ?, Ctrl/⌘+P, D, Esc stack.
+ * Swipe: ≥50 px, 1.5× dominance, <800 ms.
+ */
+export declare const DECK_INPUT_ACTIONS: readonly ["next", "prev", "first", "last", "overview", "presenter", "fullscreen", "blackout", "laser", "help", "print", "fullscreen-exit", "copy-link", "jump", "debug"];
+export type DeckAction = (typeof DECK_INPUT_ACTIONS)[number];
+/** @deprecated Use {@link DeckAction}. */
+export type DeckInputAction = DeckAction;
+export declare const DECK_CONTROL_GROUPS: readonly ["navigate", "view", "present", "share", "help", "debug"];
+export type DeckControlGroup = (typeof DECK_CONTROL_GROUPS)[number];
+export declare const DECK_CONTROL_CAPABILITIES: readonly ["fullscreen", "popup", "clipboard", "print", "debug"];
+export type DeckControlCapability = (typeof DECK_CONTROL_CAPABILITIES)[number];
+export type DeckControlEnvironment = Readonly<Record<DeckControlCapability, boolean>>;
+export declare const DEFAULT_DECK_CONTROL_ENVIRONMENT: DeckControlEnvironment;
+export interface DeckControlKey {
+    /** `KeyboardEvent.key` (letters match either case). */
+    key: string;
+    /** How a person reads it: `→`, `Page Down`, `Ctrl + P`. */
+    label: string;
+    /** `required` (Shift+Space), `allowed` (`?`). Omitted: no Shift. */
+    shift?: 'required' | 'allowed';
+    modifier?: 'ctrl' | 'meta';
+    /** The key only closes this control while it is on (`Esc`). */
+    closes?: boolean;
+}
+export interface DeckControl {
+    action: DeckAction;
+    group: DeckControlGroup;
+    /** Message key for the short name (resolved through `DECK_MESSAGES`). */
+    labelKey: string;
+    /** Message key for the one-sentence description. */
+    descriptionKey: string;
+    keys: readonly DeckControlKey[];
+    toggle: boolean;
+    requires: readonly DeckControlCapability[];
+    available: (env: DeckControlEnvironment) => boolean;
+}
+/** Every deck control, in display order. */
+export declare const DECK_CONTROLS: readonly DeckControl[];
+/** Look up a control by action. Throws when the action is unknown. */
+export declare function deckControlFor(action: DeckAction): DeckControl;
+/** The controls that work in `env`, in display order. */
+export declare function availableDeckControls(env?: DeckControlEnvironment): DeckControl[];
+/** One help-dialog row: a control's keys, its action and its label key. */
+export interface DeckKeyBinding {
+    keys: readonly string[];
+    action: DeckAction;
+    labelKey: string;
+}
+/** Help-dialog rows for the controls available in `env`. */
+export declare function deckKeyBindings(env?: DeckControlEnvironment): DeckKeyBinding[];
+/** Default-environment key bindings (debug omitted). */
+export declare const DECK_KEY_BINDINGS: readonly DeckKeyBinding[];
+/** A swipe must travel this far (CSS px) along its axis. */
+export declare const DECK_SWIPE_MIN_DISTANCE = 50;
+/** …and be this much longer on its axis than across it (axis lock). */
+export declare const DECK_SWIPE_AXIS_RATIO = 1.5;
+/** Slower drags are not swipes (they are reading or selecting). */
+export declare const DECK_SWIPE_MAX_DURATION_MS = 800;
+/** Interactive blocks put this on their root so clicks/swipes never move the deck. */
+export declare const DECK_INTERACTIVE_ATTRIBUTE = "data-tx-deck-interactive";
+/** Deck chrome (progress, slide number, toolbar) carries this attribute. */
+export declare const DECK_CHROME_ATTRIBUTE = "data-tx-deck-chrome";
+export interface DeckInputTarget {
+    tag: string;
+    role?: string;
+    editable?: boolean;
+    href?: boolean;
+    attributes?: readonly string[];
+}
+export interface DeckInputState {
+    /** `closing` covers the overview's exit transition (the double-advance bug). */
+    overview?: 'closed' | 'open' | 'closing';
+    blackout?: boolean;
+    laser?: boolean;
+    help?: boolean;
+    fullscreen?: boolean;
+    /** True when the debug panel is available; only then does D act. */
+    debugAvailable?: boolean;
+    /** True while the debug panel is open: Esc closes it first. */
+    debug?: boolean;
+    /** Flips left/right navigation when `rtl`. */
+    dir?: 'ltr' | 'rtl' | 'auto';
+}
+interface Modifiers {
+    shiftKey?: boolean;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    altKey?: boolean;
+}
+export type DeckInputEvent = (Modifiers & {
+    kind: 'key';
+    key: string;
+    repeat?: boolean;
+    isComposing?: boolean;
+    path?: readonly DeckInputTarget[];
+}) | (Modifiers & {
+    kind: 'click';
+    button?: number;
+    selectionLength?: number;
+    path?: readonly DeckInputTarget[];
+}) | {
+    kind: 'swipe';
+    dx: number;
+    dy: number;
+    durationMs?: number;
+    pointerType?: 'touch' | 'pen' | 'mouse';
+    path?: readonly DeckInputTarget[];
+};
+/** The actions Esc can reach, innermost first. */
+export declare const DECK_ESCAPE_ORDER: readonly DeckAction[];
+/** The action an input event asks for, or `null` when the deck should ignore it. */
+export declare function decideDeckInput(event: DeckInputEvent, state?: DeckInputState): DeckAction | null;
+/**
+ * Turns an event path (`event.composedPath()`, innermost first) into the
+ * plain targets `decideDeckInput` reads. Non-elements are skipped; the walk
+ * stops at `stopAt` (the deck root) when given.
+ */
+export declare function inputPathFrom(nodes: readonly unknown[], stopAt?: unknown): DeckInputTarget[];
+export {};