@softov/scena 0.1.2

package/dist/react/mount-context.js

@@ -0,0 +1,20 @@
+import { createContext, useCallback, useContext } from 'react';
+// Active mount key — used by useStore to rewrite `$/local/<rest>` paths to
+// `$/local/<mountKey>/<rest>`. Set by MountWrapper around each rendered mount.
+export const MountContext = createContext(null);
+export function useCurrentMountKey() {
+    return useContext(MountContext);
+}
+// Data context — absolute path string that anchors all `/...` relative paths
+// inside a mount or template instance. Defaults to undefined (no data context).
+export const DataContextContext = createContext(undefined);
+export function useDataContext() {
+    return useContext(DataContextContext);
+}
+export const WriteContext = createContext(null);
+export function useWriteBack(propName) {
+    const write = useContext(WriteContext);
+    return useCallback((next) => {
+        write?.(propName, next);
+    }, [write, propName]);
+}

package/dist/react/useSurfaceResize.d.ts

@@ -0,0 +1,39 @@
+import { type PointerEvent as ReactPointerEvent } from 'react';
+import type { SurfaceName } from '../types/mount-surface.js';
+import type { SurfacePresentation } from '../types/layout.js';
+/**
+ * Resizing a surface by its own edge, with no handle in the layout.
+ *
+ * The alternative to `ShellSplitter`, and a different model rather than a
+ * restyle of it. A splitter is a real element the shell has to place between two
+ * surfaces; it takes part in flex, it has to be conditionally rendered next to
+ * whichever surfaces happen to be visible, and its hit area is its width. Here
+ * the grip is a `::after` on the surface, so it costs the layout nothing, it
+ * cannot be rendered in the wrong place, and the hit zone is 10px while the line
+ * stays 1px.
+ *
+ * It also self-disables. A surface that is floating, sheeted or reduced to a bar
+ * has no dock boundary to drag, and the grip disappears with the presentation
+ * rather than the shell having to remember to stop rendering a splitter.
+ */
+export interface SurfaceResizeSpec {
+    /**
+     * Which of the surface's own edges carries the grip.
+     *
+     * The edge is the side that moves: a left sidebar is resized by its `right`
+     * edge, a right sidebar by its `left`, a bottom panel by its `top`.
+     */
+    edge: 'left' | 'right' | 'top' | 'bottom';
+    min?: number;
+    max?: number;
+    /** Hit zone in px. The visible line is 1px regardless. Default 10. */
+    grip?: number;
+}
+export interface SurfaceResizeBinding {
+    ref: (node: HTMLDivElement | null) => void;
+    'data-resize'?: string;
+    onPointerMove?: (event: ReactPointerEvent<HTMLDivElement>) => void;
+    onPointerLeave?: () => void;
+    onPointerDown?: (event: ReactPointerEvent<HTMLDivElement>) => void;
+}
+export declare function useSurfaceResize(surface: SurfaceName, presentation: SurfacePresentation, spec: SurfaceResizeSpec | undefined): SurfaceResizeBinding;

package/dist/react/useSurfaceResize.js

@@ -0,0 +1,135 @@
+import { useCallback, useRef } from 'react';
+import { useScena } from './ScenaProvider.js';
+/** Only a docked surface has a boundary worth dragging. */
+function resizableIn(presentation) {
+    return presentation === 'docked';
+}
+function withinGrip(element, edge, clientX, clientY, grip) {
+    const rect = element.getBoundingClientRect();
+    if (edge === 'right')
+        return clientX >= rect.right - grip && clientX <= rect.right;
+    if (edge === 'left')
+        return clientX <= rect.left + grip && clientX >= rect.left;
+    if (edge === 'top')
+        return clientY <= rect.top + grip && clientY >= rect.top;
+    return clientY >= rect.bottom - grip && clientY <= rect.bottom;
+}
+const clamp = (value, min, max) => Math.min(max, Math.max(min, value));
+export function useSurfaceResize(surface, presentation, spec) {
+    const scena = useScena();
+    const elementRef = useRef(null);
+    const draggingRef = useRef(false);
+    const rafRef = useRef(null);
+    // Separate from the frame handle. The handle is assigned *after*
+    // requestAnimationFrame returns, so a callback that runs before that (a
+    // synchronous or already-due frame) has its `null` overwritten by the
+    // assignment and no further frame is ever scheduled.
+    const scheduledRef = useRef(false);
+    const pendingRef = useRef(null);
+    const ref = useCallback((node) => {
+        elementRef.current = node;
+    }, []);
+    const active = spec !== undefined && resizableIn(presentation);
+    const edge = spec?.edge ?? 'right';
+    const grip = spec?.grip ?? 10;
+    const min = spec?.min ?? 100;
+    const max = spec?.max ?? 800;
+    const vertical = edge === 'left' || edge === 'right';
+    // `data-resize-state` is written straight to the node rather than held in
+    // state: it changes on every pointermove across the surface, and a re-render
+    // per mouse move is exactly the cost this whole model is avoiding.
+    const mark = useCallback((state) => {
+        elementRef.current?.setAttribute('data-resize-state', state);
+    }, []);
+    const commit = useCallback((transient) => {
+        scheduledRef.current = false;
+        if (pendingRef.current !== null) {
+            scena.layout.setSurface(surface, { size: pendingRef.current }, { transient });
+            pendingRef.current = null;
+        }
+    }, [scena, surface]);
+    const onPointerMove = useCallback((event) => {
+        const element = elementRef.current;
+        if (element === null || !active)
+            return;
+        if (draggingRef.current)
+            return;
+        mark(withinGrip(element, edge, event.clientX, event.clientY, grip) ? 'hot' : 'idle');
+    }, [active, edge, grip, mark]);
+    const onPointerLeave = useCallback(() => {
+        if (!draggingRef.current)
+            mark('idle');
+    }, [mark]);
+    const onPointerDown = useCallback((event) => {
+        const element = elementRef.current;
+        if (element === null || !active)
+            return;
+        if (!withinGrip(element, edge, event.clientX, event.clientY, grip))
+            return;
+        event.preventDefault();
+        const rect = element.getBoundingClientRect();
+        // Measured, not read from layout state: a surface whose size has never
+        // been set still has a real width, and the drag should start from it
+        // rather than from a default that would make it jump on the first pixel.
+        const startSize = vertical ? rect.width : rect.height;
+        const startPos = vertical ? event.clientX : event.clientY;
+        // The edge that moves toward the surface's origin grows it as the pointer
+        // travels backwards, so the delta is inverted for `left` and `top`.
+        const sign = edge === 'right' || edge === 'bottom' ? 1 : -1;
+        draggingRef.current = true;
+        mark('active');
+        document.documentElement.classList.add('oo-resizing');
+        document.documentElement.style.cursor = vertical ? 'ew-resize' : 'ns-resize';
+        element.setPointerCapture(event.pointerId);
+        const move = (moveEvent) => {
+            const pos = vertical ? moveEvent.clientX : moveEvent.clientY;
+            pendingRef.current = clamp(startSize + sign * (pos - startPos), min, max);
+            if (!scheduledRef.current) {
+                scheduledRef.current = true;
+                rafRef.current = requestAnimationFrame(() => commit(true));
+            }
+        };
+        const end = (endEvent) => {
+            element.removeEventListener('pointermove', move);
+            element.removeEventListener('pointerup', end);
+            element.removeEventListener('pointercancel', end);
+            if (rafRef.current !== null) {
+                cancelAnimationFrame(rafRef.current);
+                rafRef.current = null;
+            }
+            scheduledRef.current = false;
+            // The settled write. Everything during the drag was transient, so
+            // without this the size never reaches the store or storage.
+            //
+            // The fallback is the *live* size, not the size the drag started from:
+            // by here the last transient frame has usually already been applied and
+            // cleared `pending`, so starting over from `startSize` would end the
+            // gesture by committing the width the user just spent it changing.
+            pendingRef.current ??=
+                scena.layout.get().surfaces[surface]?.size ?? startSize;
+            commit(false);
+            draggingRef.current = false;
+            mark('idle');
+            document.documentElement.classList.remove('oo-resizing');
+            document.documentElement.style.cursor = '';
+            if (element.hasPointerCapture(endEvent.pointerId)) {
+                element.releasePointerCapture(endEvent.pointerId);
+            }
+        };
+        // Listened on the element, not the document: the pointer is captured, so
+        // every move is delivered here until release, and nothing else on the page
+        // has to be told a drag is in progress.
+        element.addEventListener('pointermove', move);
+        element.addEventListener('pointerup', end);
+        element.addEventListener('pointercancel', end);
+    }, [active, edge, grip, vertical, min, max, mark, commit, scena, surface]);
+    if (!active)
+        return { ref };
+    return {
+        ref,
+        'data-resize': edge,
+        onPointerMove,
+        onPointerLeave,
+        onPointerDown,
+    };
+}

package/dist/runtime/args-schema.d.ts

@@ -0,0 +1,11 @@
+import type { ArgsSchema, ArgType } from '../types/command.js';
+export type ValidateArgsResult = {
+    ok: true;
+    value: Record<string, unknown>;
+} | {
+    ok: false;
+    errors: string[];
+};
+export declare function validateArgs(schema: ArgsSchema | undefined, input: unknown): ValidateArgsResult;
+export declare function isPermissionPath(path: string): boolean;
+export type { ArgsSchema, ArgType };

package/dist/runtime/args-schema.js

@@ -0,0 +1,45 @@
+export function validateArgs(schema, input) {
+    if (!schema) {
+        return {
+            ok: true,
+            value: input ?? {},
+        };
+    }
+    const obj = (input ?? {});
+    const value = {};
+    const errors = [];
+    for (const [key, type] of Object.entries(schema)) {
+        const v = obj[key];
+        if (Array.isArray(type)) {
+            if (v === undefined) {
+                errors.push(`${key}: required (enum: ${type.join(' | ')})`);
+                continue;
+            }
+            if (typeof v !== 'string' || !type.includes(v)) {
+                errors.push(`${key}: expected one of ${type.join(' | ')}`);
+                continue;
+            }
+            value[key] = v;
+            continue;
+        }
+        const typeStr = type;
+        const optional = typeStr.endsWith('?');
+        const base = (optional ? typeStr.slice(0, -1) : typeStr);
+        if (v === undefined || v === null) {
+            if (!optional)
+                errors.push(`${key}: required (${base})`);
+            continue;
+        }
+        if (typeof v !== base) {
+            errors.push(`${key}: expected ${base}, got ${typeof v}`);
+            continue;
+        }
+        value[key] = v;
+    }
+    return errors.length > 0 ? { ok: false, errors } : { ok: true, value };
+}
+// `$/scope/seg/seg`-style absolute path. Trailing `/*` allowed for prefix
+// permissions; segments may contain alphanumerics, `_`, `-`, `.`, `:`.
+export function isPermissionPath(path) {
+    return /^\$\/[A-Za-z][\w:.-]*(\/[\w:.*-]+)*$/.test(path);
+}

package/dist/runtime/builtins.d.ts

@@ -0,0 +1,3 @@
+import type { Disposable } from '../types/disposable.js';
+import type { Scena } from '../types/scena.js';
+export declare function registerBuiltinFunctions(scena: Scena): Disposable;

package/dist/runtime/builtins.js

@@ -0,0 +1,193 @@
+import { combineDisposables } from '../core/disposable.js';
+// The 14 a2ui v0.10 basic-catalog functions, registered as commands at
+// createScena() time. All declare callableFrom: 'clientOnly' semantics
+// (dispatch: 'client' here — they don't round-trip through the socket).
+function arg(args, key) {
+    if (!args || typeof args !== 'object')
+        return undefined;
+    return args[key];
+}
+function toStr(v) {
+    return v === null || v === undefined ? '' : String(v);
+}
+function toNum(v) {
+    if (typeof v === 'number')
+        return v;
+    if (typeof v === 'string' && v.trim() !== '') {
+        const n = Number(v);
+        if (!Number.isNaN(n))
+            return n;
+    }
+    return Number.NaN;
+}
+const validation = (scena) => {
+    return combineDisposables(scena.commands.register({
+        id: 'required',
+        title: 'required',
+        dispatch: 'client',
+        run: (_ctx, a) => {
+            const v = arg(a, 'value');
+            return v !== undefined && v !== null && v !== '';
+        },
+    }), scena.commands.register({
+        id: 'regex',
+        title: 'regex',
+        dispatch: 'client',
+        run: (_ctx, a) => {
+            const value = toStr(arg(a, 'value'));
+            const pattern = toStr(arg(a, 'pattern'));
+            const flags = toStr(arg(a, 'flags'));
+            if (!pattern)
+                return true;
+            try {
+                return new RegExp(pattern, flags || undefined).test(value);
+            }
+            catch {
+                return false;
+            }
+        },
+    }), scena.commands.register({
+        id: 'length',
+        title: 'length',
+        dispatch: 'client',
+        run: (_ctx, a) => {
+            const value = toStr(arg(a, 'value'));
+            const min = arg(a, 'min');
+            const max = arg(a, 'max');
+            if (min !== undefined && value.length < min)
+                return false;
+            if (max !== undefined && value.length > max)
+                return false;
+            return true;
+        },
+    }), scena.commands.register({
+        id: 'numeric',
+        title: 'numeric',
+        dispatch: 'client',
+        run: (_ctx, a) => {
+            const n = toNum(arg(a, 'value'));
+            return !Number.isNaN(n);
+        },
+    }), scena.commands.register({
+        id: 'email',
+        title: 'email',
+        dispatch: 'client',
+        run: (_ctx, a) => {
+            const v = toStr(arg(a, 'value'));
+            return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(v);
+        },
+    }));
+};
+const format = (scena) => {
+    return combineDisposables(scena.commands.register({
+        id: 'formatString',
+        title: 'formatString',
+        dispatch: 'client',
+        run: (_ctx, a) => {
+            const template = toStr(arg(a, 'template'));
+            const values = (arg(a, 'values') ?? {});
+            return template.replace(/\{([^}]+)\}/g, (_, k) => toStr(values[k]));
+        },
+    }), scena.commands.register({
+        id: 'formatNumber',
+        title: 'formatNumber',
+        dispatch: 'client',
+        run: (_ctx, a) => {
+            const n = toNum(arg(a, 'value'));
+            if (Number.isNaN(n))
+                return '';
+            const locale = arg(a, 'locale');
+            const minimumFractionDigits = arg(a, 'minimumFractionDigits');
+            const maximumFractionDigits = arg(a, 'maximumFractionDigits');
+            return new Intl.NumberFormat(locale, {
+                minimumFractionDigits,
+                maximumFractionDigits,
+            }).format(n);
+        },
+    }), scena.commands.register({
+        id: 'formatCurrency',
+        title: 'formatCurrency',
+        dispatch: 'client',
+        run: (_ctx, a) => {
+            const n = toNum(arg(a, 'value'));
+            if (Number.isNaN(n))
+                return '';
+            const currency = toStr(arg(a, 'currency')) || 'USD';
+            const locale = arg(a, 'locale');
+            return new Intl.NumberFormat(locale, {
+                style: 'currency',
+                currency,
+            }).format(n);
+        },
+    }), scena.commands.register({
+        id: 'formatDate',
+        title: 'formatDate',
+        dispatch: 'client',
+        run: (_ctx, a) => {
+            const v = arg(a, 'value');
+            if (v === undefined || v === null || v === '')
+                return '';
+            const d = v instanceof Date ? v : new Date(v);
+            if (Number.isNaN(d.getTime()))
+                return '';
+            const locale = arg(a, 'locale');
+            const options = arg(a, 'options');
+            return new Intl.DateTimeFormat(locale, options).format(d);
+        },
+    }), scena.commands.register({
+        id: 'pluralize',
+        title: 'pluralize',
+        dispatch: 'client',
+        run: (_ctx, a) => {
+            const count = toNum(arg(a, 'count'));
+            const one = toStr(arg(a, 'one'));
+            const other = toStr(arg(a, 'other'));
+            return count === 1 ? one : other;
+        },
+    }));
+};
+const navigation = (scena) => {
+    return scena.commands.register({
+        id: 'openUrl',
+        title: 'openUrl',
+        dispatch: 'client',
+        run: (_ctx, a) => {
+            const url = toStr(arg(a, 'url'));
+            if (!url)
+                return;
+            if (typeof window !== 'undefined') {
+                const target = toStr(arg(a, 'target')) || '_blank';
+                window.open(url, target);
+            }
+        },
+    });
+};
+const logic = (scena) => {
+    return combineDisposables(scena.commands.register({
+        id: 'and',
+        title: 'and',
+        dispatch: 'client',
+        run: (_ctx, a) => {
+            const values = arg(a, 'values') ?? [];
+            return values.every(Boolean);
+        },
+    }), scena.commands.register({
+        id: 'or',
+        title: 'or',
+        dispatch: 'client',
+        run: (_ctx, a) => {
+            const values = arg(a, 'values') ?? [];
+            return values.some(Boolean);
+        },
+    }), scena.commands.register({
+        id: 'not',
+        title: 'not',
+        dispatch: 'client',
+        run: (_ctx, a) => {
+            return !arg(a, 'value');
+        },
+    }));
+};
+export function registerBuiltinFunctions(scena) {
+    return combineDisposables(validation(scena), format(scena), navigation(scena), logic(scena));
+}

package/dist/runtime/client-handlers.d.ts

@@ -0,0 +1,3 @@
+import type { Disposable } from '../types/disposable.js';
+export declare function registerClientHandler(name: string, handler: (args: Record<string, unknown>) => unknown | Promise<unknown>): Disposable;
+export declare function getClientHandler(name: string): ((args: Record<string, unknown>) => unknown | Promise<unknown>) | undefined;

package/dist/runtime/client-handlers.js

@@ -0,0 +1,19 @@
+// Plugin-side client handlers for FunctionCall ids that need an inline JS
+// implementation (typically declared with `callableFrom: 'clientOnly'`).
+//
+// Scena itself does not consult this registry; it is a parking lot plugin
+// authors can use to expose handlers that other plugin code (or a custom
+// dynamic-resolver bridge) looks up at call time.
+const clientHandlers = new Map();
+export function registerClientHandler(name, handler) {
+    clientHandlers.set(name, handler);
+    return {
+        dispose() {
+            if (clientHandlers.get(name) === handler)
+                clientHandlers.delete(name);
+        },
+    };
+}
+export function getClientHandler(name) {
+    return clientHandlers.get(name);
+}

package/dist/runtime/in-memory-socket.d.ts

@@ -0,0 +1,7 @@
+import type { Disposable } from '../types/disposable.js';
+import type { SocketBridge } from '../types/reactive-store.js';
+export interface InMemorySocket extends SocketBridge {
+    dispatch(event: string, payload?: unknown): void;
+    onOutgoing(event: string, fn: (payload: unknown) => void): Disposable;
+}
+export declare function createInMemorySocket(): InMemorySocket;

package/dist/runtime/in-memory-socket.js

@@ -0,0 +1,53 @@
+export function createInMemorySocket() {
+    const incoming = new Map();
+    const outgoing = new Map();
+    function add(map, event, fn) {
+        let set = map.get(event);
+        if (!set) {
+            set = new Set();
+            map.set(event, set);
+        }
+        set.add(fn);
+        return {
+            dispose() {
+                set.delete(fn);
+                if (set.size === 0)
+                    map.delete(event);
+            },
+        };
+    }
+    function fire(map, event, payload) {
+        const set = map.get(event);
+        if (!set)
+            return;
+        for (const fn of [...set]) {
+            try {
+                fn(payload);
+            }
+            catch (err) {
+                console.error(`[in-memory-socket] listener for "${event}" threw:`, err);
+            }
+        }
+    }
+    return {
+        on(event, fn) {
+            return add(incoming, event, fn);
+        },
+        off(event, fn) {
+            incoming.get(event)?.delete(fn);
+        },
+        offAll(events) {
+            for (const e of events)
+                incoming.delete(e);
+        },
+        emit(event, payload) {
+            fire(outgoing, event, payload);
+        },
+        dispatch(event, payload) {
+            fire(incoming, event, payload);
+        },
+        onOutgoing(event, fn) {
+            return add(outgoing, event, fn);
+        },
+    };
+}

package/dist/runtime/index.d.ts

@@ -0,0 +1,10 @@
+export { validateArgs, isPermissionPath } from './args-schema.js';
+export type { ValidateArgsResult } from './args-schema.js';
+export { createSurfaceBridge } from './surface-bridge.js';
+export { registerClientHandler, getClientHandler, } from './client-handlers.js';
+export { createInMemorySocket } from './in-memory-socket.js';
+export type { InMemorySocket } from './in-memory-socket.js';
+export { registerBuiltinFunctions } from './builtins.js';
+export { registerLayoutCommands } from './layout-commands.js';
+export { registerOpenerCommands } from './opener-commands.js';
+export type { RegisterOpenerCommandsOptions } from './opener-commands.js';

package/dist/runtime/index.js

@@ -0,0 +1,7 @@
+export { validateArgs, isPermissionPath } from './args-schema.js';
+export { createSurfaceBridge } from './surface-bridge.js';
+export { registerClientHandler, getClientHandler, } from './client-handlers.js';
+export { createInMemorySocket } from './in-memory-socket.js';
+export { registerBuiltinFunctions } from './builtins.js';
+export { registerLayoutCommands } from './layout-commands.js';
+export { registerOpenerCommands } from './opener-commands.js';

package/dist/runtime/layout-commands.d.ts

@@ -0,0 +1,5 @@
+import type { Scena } from '../types/scena.js';
+import type { Disposable } from '../types/disposable.js';
+import type { ScenaLayout } from '../types/layout.js';
+export declare function registerLayoutCommands(scena: Scena): Disposable;
+export type { ScenaLayout };