@gadxr/ui 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,40 @@
+import './fonts.css';
+export { default as ThemeProvider } from './ThemeProvider.svelte';
+export { default as Scene3D } from './Scene3D.svelte';
+export { default as Space3D } from './Space3D.svelte';
+export { default as Text } from './Text.svelte';
+export { default as Button } from './Button.svelte';
+export { default as ButtonGroup } from './ButtonGroup.svelte';
+export { default as Panel } from './Panel.svelte';
+export { default as Stack } from './Stack.svelte';
+export { default as Checkbox } from './Checkbox.svelte';
+export { default as Slider } from './Slider.svelte';
+export { default as Input } from './Input.svelte';
+export { default as Keyboard } from './Keyboard.svelte';
+export { default as Tag } from './Tag.svelte';
+export { default as Spinner } from './Spinner.svelte';
+export { default as ProgressBar } from './ProgressBar.svelte';
+export { default as Avatar } from './Avatar.svelte';
+export { default as Tooltip } from './Tooltip.svelte';
+export { default as Tabs } from './Tabs.svelte';
+export { default as Tab } from './Tab.svelte';
+export { default as Menu, type MenuItem } from './Menu.svelte';
+export { default as RadialMenu } from './RadialMenu.svelte';
+export { default as Modal } from './Modal.svelte';
+export { default as Toaster } from './Toaster.svelte';
+export { default as Surface, type SurfacePlacement, type SurfaceDesktopPlacement, type ScreenRegion } from './Surface.svelte';
+export { xr } from './xr.svelte';
+export { toaster, DEFAULT_TOAST_DURATION, type Toast, type ToastOptions } from './toast.svelte';
+export { defaultTheme, createTheme, toMeters } from './theme';
+export type { Theme, ButtonKind, ButtonSize, ButtonShape, Dimension, TypographyVariant, TagKind, TagVariant, TagSize, SpinnerSize, ToastKind, ProgressBarSize, AvatarSize, AvatarStatus, TooltipPlacement } from './theme';
+export { resolveButtonStyle } from './button-style';
+export { resolveCheckboxStyle, resolveTagStyle, resolveInputStyle, resolveKeyStyle, sliderFraction, sliderValueAt, nextIndex, initials, avatarColor, tooltipOffset } from './component-style';
+export { textFocus, type Editable } from './text-focus.svelte';
+export { edit, keyToAction, type EditAction, type Splice, type TextState } from './text-edit';
+export { KEYBOARD, type EnterKeyHint, type KeyboardPage, type ShiftState } from './keyboard-layout';
+export { stackLayout } from './layout-math';
+export { wedgeAt, wedgeCenter, RadialInput } from './radial-math';
+export type { ButtonProps, TextProps } from './types';
+export { ensure3d } from './aframe';
+export { everyFrame } from './aframe/frame';
+export { RAYCASTABLE, MOUSE_CURSOR, TROIKA_SCRIPT } from './aframe/scene';

package/dist/index.js

@@ -0,0 +1,40 @@
+// gadxr design system: Base UI-style components that render as HTML, or as
+// A-Frame entities inside <Scene3D> (or <Space3D>).
+import './fonts.css';
+export { default as ThemeProvider } from './ThemeProvider.svelte';
+export { default as Scene3D } from './Scene3D.svelte';
+export { default as Space3D } from './Space3D.svelte';
+export { default as Text } from './Text.svelte';
+export { default as Button } from './Button.svelte';
+export { default as ButtonGroup } from './ButtonGroup.svelte';
+export { default as Panel } from './Panel.svelte';
+export { default as Stack } from './Stack.svelte';
+export { default as Checkbox } from './Checkbox.svelte';
+export { default as Slider } from './Slider.svelte';
+export { default as Input } from './Input.svelte';
+export { default as Keyboard } from './Keyboard.svelte';
+export { default as Tag } from './Tag.svelte';
+export { default as Spinner } from './Spinner.svelte';
+export { default as ProgressBar } from './ProgressBar.svelte';
+export { default as Avatar } from './Avatar.svelte';
+export { default as Tooltip } from './Tooltip.svelte';
+export { default as Tabs } from './Tabs.svelte';
+export { default as Tab } from './Tab.svelte';
+export { default as Menu } from './Menu.svelte';
+export { default as RadialMenu } from './RadialMenu.svelte';
+export { default as Modal } from './Modal.svelte';
+export { default as Toaster } from './Toaster.svelte';
+export { default as Surface } from './Surface.svelte';
+export { xr } from './xr.svelte';
+export { toaster, DEFAULT_TOAST_DURATION } from './toast.svelte';
+export { defaultTheme, createTheme, toMeters } from './theme';
+export { resolveButtonStyle } from './button-style';
+export { resolveCheckboxStyle, resolveTagStyle, resolveInputStyle, resolveKeyStyle, sliderFraction, sliderValueAt, nextIndex, initials, avatarColor, tooltipOffset } from './component-style';
+export { textFocus } from './text-focus.svelte';
+export { edit, keyToAction } from './text-edit';
+export { KEYBOARD } from './keyboard-layout';
+export { stackLayout } from './layout-math';
+export { wedgeAt, wedgeCenter, RadialInput } from './radial-math';
+export { ensure3d } from './aframe';
+export { everyFrame } from './aframe/frame';
+export { RAYCASTABLE, MOUSE_CURSOR, TROIKA_SCRIPT } from './aframe/scene';

package/dist/keyboard-layout.d.ts

@@ -0,0 +1,28 @@
+export type KeyboardPage = 'letters' | 'numbers' | 'symbols';
+export type ShiftState = 'off' | 'once' | 'caps';
+export type EnterKeyHint = 'enter' | 'done' | 'go' | 'next' | 'search' | 'send';
+export type KeyDef = {
+    action: 'char';
+    char: string;
+    width?: number;
+} | {
+    action: 'shift' | 'backspace' | 'space' | 'enter' | 'done' | 'close';
+    width: number;
+} | {
+    action: 'page';
+    page: KeyboardPage;
+    width: number;
+} | {
+    action: 'spacer';
+    width: number;
+};
+export declare const ROW_UNITS = 11.5;
+export declare const KEYBOARD: Record<KeyboardPage, KeyDef[][]>;
+export declare const keyWidth: (key: KeyDef) => number;
+export declare function keyLabel(key: KeyDef, shift?: ShiftState, enterKeyHint?: EnterKeyHint): string;
+export declare function keyChar(key: {
+    char: string;
+}, shift: ShiftState): string;
+export declare function tapShift(shift: ShiftState, msSinceLastTap: number, doubleTapMs?: number): ShiftState;
+export declare const afterChar: (shift: ShiftState) => ShiftState;
+export declare const startPage: (inputmode: "text" | "numeric") => KeyboardPage;

package/dist/keyboard-layout.js

@@ -0,0 +1,77 @@
+// The VR keyboard's keys and shift logic. Three pages: letters (QWERTY), numbers and
+// symbols. Widths are in key units; every row adds up to ROW_UNITS, so rows line up.
+// Labels stick to glyphs the bundled Geist has (no ⌫ / ✓), so troika needn't fetch
+// a fallback font. Erasable TypeScript only (tested in Node).
+export const ROW_UNITS = 11.5;
+const chars = (s) => [...s].map((char) => ({ action: 'char', char }));
+const backspace = { action: 'backspace', width: 1.5 };
+const indent = { action: 'spacer', width: 0.5 };
+const enter = { action: 'enter', width: 2 };
+const bottom = (page) => [
+    { action: 'page', page, width: 1.5 },
+    { action: 'close', width: 1.25 },
+    { action: 'space', width: 6.25 },
+    { action: 'done', width: 2.5 },
+];
+export const KEYBOARD = {
+    letters: [
+        [...chars('qwertyuiop'), backspace],
+        [indent, ...chars('asdfghjkl'), enter],
+        [{ action: 'shift', width: 1.5 }, ...chars('zxcvbnm,.?')],
+        bottom('numbers'),
+    ],
+    numbers: [
+        [...chars('1234567890'), backspace],
+        [indent, ...chars('-/:;()$&@'), enter],
+        [{ action: 'page', page: 'symbols', width: 1.5 }, ...chars(`.,?!'"_*%+`)],
+        bottom('letters'),
+    ],
+    symbols: [
+        [...chars('[]{}#^=<>~'), backspace],
+        [indent, ...chars('\\|`€£¥•°…'), enter],
+        [{ action: 'page', page: 'numbers', width: 1.5 }, ...chars(`.,?!'"_*%+`)],
+        bottom('letters'),
+    ],
+};
+export const keyWidth = (key) => ('width' in key && key.width ? key.width : 1);
+const PAGE_LABEL = { letters: 'ABC', numbers: '123', symbols: '#+=' };
+const ENTER_LABEL = { enter: '↵', done: 'Done', go: 'Go', next: 'Next', search: 'Search', send: 'Send' };
+export function keyLabel(key, shift = 'off', enterKeyHint = 'enter') {
+    switch (key.action) {
+        case 'char':
+            return keyChar(key, shift);
+        case 'shift':
+            return shift === 'caps' ? 'CAPS' : '⇧';
+        case 'backspace':
+            return '←';
+        case 'space':
+            return 'space';
+        case 'enter':
+            return ENTER_LABEL[enterKeyHint];
+        case 'done':
+            return 'Done';
+        case 'close':
+            return '×';
+        case 'page':
+            return PAGE_LABEL[key.page];
+        case 'spacer':
+            return '';
+    }
+}
+// What a character key types.
+export function keyChar(key, shift) {
+    return shift === 'off' ? key.char : key.char.toUpperCase();
+}
+// Shift: a tap shifts the next letter; a second tap within `doubleTapMs` locks caps;
+// any tap while locked (or a slow second tap) turns it off.
+export function tapShift(shift, msSinceLastTap, doubleTapMs = 400) {
+    if (shift === 'off')
+        return 'once';
+    if (shift === 'once' && msSinceLastTap <= doubleTapMs)
+        return 'caps';
+    return 'off';
+}
+// After typing a character, a one-shot shift is used up; caps stays.
+export const afterChar = (shift) => (shift === 'once' ? 'off' : shift);
+// The page a field opens on.
+export const startPage = (inputmode) => (inputmode === 'numeric' ? 'numbers' : 'letters');

package/dist/layout-math.d.ts

@@ -0,0 +1,20 @@
+export type Size = {
+    width: number;
+    height: number;
+};
+export type Align = 'start' | 'center' | 'end';
+export type Item = Size & {
+    align?: Align;
+};
+export type StackOptions = {
+    direction: 'row' | 'column';
+    gap: number;
+    align?: Align;
+};
+export type StackLayout = Size & {
+    offsets: {
+        x: number;
+        y: number;
+    }[];
+};
+export declare function stackLayout(sizes: Item[], { direction, gap, align }: StackOptions): StackLayout;

package/dist/layout-math.js

@@ -0,0 +1,22 @@
+// 3D layout: stacks items in a row or column, centered on the stack's origin.
+// Pure math, shared by every container (ButtonGroup, Panel). Units are meters.
+// Erasable TypeScript only — tests import it with Node's type stripping.
+export function stackLayout(sizes, { direction, gap, align = 'center' }) {
+    const row = direction === 'row';
+    const main = (s) => (row ? s.width : s.height);
+    const cross = (s) => (row ? s.height : s.width);
+    const totalMain = sizes.reduce((sum, s) => sum + main(s), 0) + gap * Math.max(0, sizes.length - 1);
+    const totalCross = sizes.reduce((max, s) => Math.max(max, cross(s)), 0);
+    let cursor = -totalMain / 2;
+    const offsets = sizes.map((s) => {
+        const along = cursor + main(s) / 2;
+        cursor += main(s) + gap;
+        const a = s.align ?? align;
+        const across = a === 'start' ? -totalCross / 2 + cross(s) / 2 : a === 'end' ? totalCross / 2 - cross(s) / 2 : 0;
+        // Rows run left to right; columns run top to bottom (+y is up).
+        return row ? { x: along, y: -across } : { x: across, y: -along };
+    });
+    return row
+        ? { width: totalMain, height: totalCross, offsets }
+        : { width: totalCross, height: totalMain, offsets };
+}

package/dist/layout.svelte.d.ts

@@ -0,0 +1,17 @@
+import { type Item, type Size, type StackOptions } from './layout-math';
+export type Position = {
+    x: number;
+    y: number;
+};
+export type Stack = {
+    register(): number;
+    unregister(id: number): void;
+    setSize(id: number, size: Item): void;
+    offset(id: number): Position;
+    readonly size: Size;
+};
+export declare function createStack(options: () => StackOptions): Stack;
+export declare function setStack(stack: Stack | undefined): void;
+export declare function getStack(): Stack | undefined;
+export declare function inStack(): boolean;
+export declare function useSlot(size: () => Item): () => Position;

package/dist/layout.svelte.js

@@ -0,0 +1,58 @@
+// 3D layout context. A container (ButtonGroup, Panel) creates a stack; each 3D
+// component inside calls useSlot() to report its size and get its position back.
+// In 2D, CSS does the layout and none of this is used.
+import { getContext, setContext } from 'svelte';
+import { SvelteMap } from 'svelte/reactivity';
+import { stackLayout } from './layout-math';
+const STACK = Symbol('ui-stack');
+export function createStack(options) {
+    // Ids increase in registration order, which is the layout order.
+    let nextId = 0;
+    const sizes = new SvelteMap();
+    // Iterating the map (not a plain list of ids) subscribes to items being added and
+    // removed, even when the layout is first read before any child has registered.
+    const layout = $derived.by(() => {
+        const ids = [...sizes.keys()].sort((a, b) => a - b);
+        const result = stackLayout(ids.map((id) => sizes.get(id)), options());
+        return { ...result, byId: new Map(ids.map((id, i) => [id, result.offsets[i]])) };
+    });
+    return {
+        register: () => nextId++,
+        unregister(id) {
+            sizes.delete(id);
+        },
+        setSize(id, size) {
+            const prev = sizes.get(id);
+            if (!prev || prev.width !== size.width || prev.height !== size.height || prev.align !== size.align)
+                sizes.set(id, size);
+        },
+        offset: (id) => layout.byId.get(id) ?? { x: 0, y: 0 },
+        get size() {
+            return { width: layout.width, height: layout.height };
+        },
+    };
+}
+export function setStack(stack) {
+    setContext(STACK, stack);
+}
+// For components that set up a different stack (or none) for part of their children.
+export function getStack() {
+    return getContext(STACK);
+}
+// True when called inside a container that lays its children out.
+export function inStack() {
+    return !!getContext(STACK);
+}
+// Call during component init, before setting a stack of your own.
+// Returns a getter for this item's position within the parent stack (0,0 when not in one).
+export function useSlot(size) {
+    const stack = getContext(STACK);
+    if (!stack)
+        return () => ({ x: 0, y: 0 });
+    const id = stack.register();
+    $effect(() => {
+        stack.setSize(id, size());
+    });
+    $effect(() => () => stack.unregister(id));
+    return () => stack.offset(id);
+}

package/dist/radial-math.d.ts

@@ -0,0 +1,33 @@
+export type RadialLayout = {
+    count: number;
+    startAngle: number;
+};
+export declare const sectorAngle: (count: number) => number;
+export declare function wedgeCenter(index: number, { count, startAngle }: RadialLayout): number;
+export declare function wedgeAt(x: number, y: number, { count, startAngle }: RadialLayout, deadzone?: number): number;
+export declare function polar(radius: number, angle: number): [number, number];
+export declare function sectorPath(index: number, layout: RadialLayout, inner: number, outer: number, gap?: number): string;
+export type Hand = 'left' | 'right';
+export type ControllerPlacement = {
+    position: string;
+    rotation: string;
+    startAngle: number;
+    angleOffset: number;
+    labelRotation: number;
+    radius: number;
+    innerRadius: number;
+};
+export declare const ON_CONTROLLER: Record<Hand, ControllerPlacement>;
+export declare class RadialInput {
+    open: boolean;
+    selected: number;
+    layout: RadialLayout;
+    deadzone: number;
+    disabled: (index: number) => boolean;
+    constructor(layout: RadialLayout, deadzone?: number, disabled?: (index: number) => boolean);
+    start(): void;
+    aim(x: number, y: number, angleOffset?: number): void;
+    point(index: number): void;
+    release(): number;
+    cancel(): void;
+}

package/dist/radial-math.js

@@ -0,0 +1,90 @@
+// Radial (pie) menu geometry and input, shared by the 2D and 3D renderers.
+// Angles are in degrees, counterclockwise from +x (right), with +y up.
+// Erasable TypeScript only — tests import it with Node's type stripping.
+const DEG = Math.PI / 180;
+const wrap = (deg) => ((deg % 360) + 360) % 360;
+export const sectorAngle = (count) => 360 / count;
+// Middle of wedge `index`.
+export function wedgeCenter(index, { count, startAngle }) {
+    return startAngle + (index + 0.5) * sectorAngle(count);
+}
+// The wedge a direction points into, or -1 for no direction (inside the deadzone).
+export function wedgeAt(x, y, { count, startAngle }, deadzone = 0) {
+    if (count <= 0 || Math.hypot(x, y) < deadzone)
+        return -1;
+    const angle = wrap(Math.atan2(y, x) / DEG - startAngle);
+    return Math.floor(angle / sectorAngle(count)) % count;
+}
+// Point at `radius` and `angle` (degrees), as [x, y] with +y up.
+export function polar(radius, angle) {
+    return [radius * Math.cos(angle * DEG), radius * Math.sin(angle * DEG)];
+}
+// SVG path (y down) for a ring sector, with `gap` degrees trimmed off each side.
+export function sectorPath(index, layout, inner, outer, gap = 0) {
+    const from = layout.startAngle + index * sectorAngle(layout.count) + gap / 2;
+    const to = from + sectorAngle(layout.count) - gap;
+    const large = to - from > 180 ? 1 : 0;
+    const pt = (r, a) => {
+        const [x, y] = polar(r, a);
+        return `${x.toFixed(3)} ${(-y).toFixed(3)}`;
+    };
+    // SVG's y axis points down, so counterclockwise on screen is sweep-flag 0.
+    return [
+        `M ${pt(outer, from)}`,
+        `A ${outer} ${outer} 0 ${large} 0 ${pt(outer, to)}`,
+        `L ${pt(inner, to)}`,
+        `A ${inner} ${inner} 0 ${large} 1 ${pt(inner, from)}`,
+        'Z',
+    ].join(' ');
+}
+export const ON_CONTROLLER = {
+    right: { position: '-.02 -0.0766 -0.1428', rotation: '-60 -170 -90', startAngle: 0, angleOffset: 72, labelRotation: -90, radius: 32, innerRadius: 8 },
+    left: { position: '.02 -0.0766 -0.1428', rotation: '-60 170 90', startAngle: 108, angleOffset: -72, labelRotation: 90, radius: 32, innerRadius: 8 },
+};
+// Hold-to-open, aim, release-to-pick — the same for a VR controller (trigger +
+// thumbstick), a held key + mouse, or a long press. Aiming back to the centre keeps
+// the last wedge, so letting go of the stick before the trigger still picks it.
+export class RadialInput {
+    open = false;
+    selected = -1;
+    layout;
+    deadzone;
+    // Wedges that can't be picked.
+    disabled;
+    constructor(layout, deadzone = 0.5, disabled = () => false) {
+        this.layout = layout;
+        this.deadzone = deadzone;
+        this.disabled = disabled;
+    }
+    start() {
+        this.open = true;
+        this.selected = -1;
+    }
+    // Aim with a direction (stick axes, or a pointer offset from the centre).
+    aim(x, y, angleOffset = 0) {
+        if (!this.open)
+            return;
+        const index = wedgeAt(x, y, { ...this.layout, startAngle: this.layout.startAngle + angleOffset }, this.deadzone);
+        if (index === -1)
+            return;
+        this.selected = this.disabled(index) ? -1 : index;
+    }
+    // Point straight at a wedge (hovering it with a cursor or laser).
+    point(index) {
+        if (this.open && !this.disabled(index))
+            this.selected = index;
+    }
+    // Closes the menu; returns the picked wedge, or -1.
+    release() {
+        if (!this.open)
+            return -1;
+        const picked = this.selected;
+        this.open = false;
+        this.selected = -1;
+        return picked;
+    }
+    cancel() {
+        this.open = false;
+        this.selected = -1;
+    }
+}

package/dist/tabs-context.d.ts

@@ -0,0 +1,13 @@
+export type TabEntry = {
+    readonly key: string;
+    readonly title: string;
+    readonly disabled: boolean;
+};
+export type TabsContext = {
+    readonly id: string;
+    register(tab: TabEntry): void;
+    unregister(tab: TabEntry): void;
+    readonly active: string | undefined;
+};
+export declare const setTabs: (tabs: TabsContext) => TabsContext;
+export declare const getTabs: () => TabsContext | undefined;

package/dist/tabs-context.js

@@ -0,0 +1,6 @@
+// Tabs <-> Tab: each Tab registers its key/title; Tabs draws the bar and tells
+// each Tab whether it's the active one.
+import { getContext, setContext } from 'svelte';
+const TABS = Symbol('ui-tabs');
+export const setTabs = (tabs) => setContext(TABS, tabs);
+export const getTabs = () => getContext(TABS);

package/dist/text-edit.d.ts

@@ -0,0 +1,46 @@
+export type TextState = {
+    text: string;
+    caret: number;
+};
+export type Splice = {
+    at: number;
+    remove: number;
+    insert: string;
+};
+export type Edit = {
+    state: TextState;
+    splice: Splice;
+};
+export type EditOptions = {
+    multiline?: boolean;
+    maxLength?: number;
+};
+export type EditAction = {
+    type: 'insert';
+    text: string;
+} | {
+    type: 'backspace';
+} | {
+    type: 'delete';
+} | {
+    type: 'left';
+} | {
+    type: 'right';
+} | {
+    type: 'home';
+} | {
+    type: 'end';
+};
+export declare function clampCaret(text: string, caret: number): number;
+export declare function sanitize(text: string, multiline?: boolean): string;
+export declare function applySplice(text: string, { at, remove, insert }: Splice): string;
+export declare function edit(state: TextState, action: EditAction, { multiline, maxLength }?: EditOptions): Edit | null;
+export declare function keyToAction(event: {
+    key: string;
+    ctrlKey?: boolean;
+    metaKey?: boolean;
+    altKey?: boolean;
+}): EditAction | 'enter' | 'escape' | null;
+export declare function caretX(index: number, positions: ArrayLike<number> | null | undefined, length: number): number;
+export declare function caretIndexAt(x: number, positions: ArrayLike<number> | null | undefined, length: number): number;
+export declare function scrollToCaret(caret: number, scroll: number, viewWidth: number, textWidth: number): number;

package/dist/text-edit.js

@@ -0,0 +1,133 @@
+// Text editing for the 3D Input (and its VR keyboard): a value plus a caret, changed
+// by splices. Every edit is one splice (`at`, `remove` chars, `insert` text), the form
+// a shared, networked document would send. Erasable TypeScript only (tested in Node).
+const isHigh = (code) => code >= 0xd800 && code <= 0xdbff;
+const isLow = (code) => code >= 0xdc00 && code <= 0xdfff;
+export function clampCaret(text, caret) {
+    const c = Math.min(text.length, Math.max(0, Math.round(caret) || 0));
+    // Never inside a surrogate pair (emoji etc.).
+    return c > 0 && c < text.length && isLow(text.charCodeAt(c)) && isHigh(text.charCodeAt(c - 1)) ? c - 1 : c;
+}
+// One character step left/right, keeping surrogate pairs together.
+function step(text, caret, direction) {
+    const next = caret + direction;
+    if (next < 0 || next > text.length)
+        return caret;
+    if (direction < 0 && next > 0 && isLow(text.charCodeAt(next)) && isHigh(text.charCodeAt(next - 1)))
+        return next - 1;
+    if (direction > 0 && next < text.length && isLow(text.charCodeAt(next)) && isHigh(text.charCodeAt(next - 1)))
+        return next + 1;
+    return next;
+}
+// What may be typed: no control characters; newlines only when multiline (else spaces).
+export function sanitize(text, multiline = false) {
+    const lines = text.replace(/\r\n?/g, '\n');
+    const flat = multiline ? lines : lines.replace(/\n+/g, ' ');
+    // eslint-disable-next-line no-control-regex
+    return flat.replace(/\t/g, ' ').replace(/[\u0000-\u0009\u000B-\u001F\u007F]/g, '');
+}
+export function applySplice(text, { at, remove, insert }) {
+    return text.slice(0, at) + insert + text.slice(at + remove);
+}
+function spliceEdit(state, splice, caret) {
+    if (!splice.remove && !splice.insert)
+        return null;
+    return { state: { text: applySplice(state.text, splice), caret }, splice };
+}
+// Applies an editing action. Returns null when nothing changes (e.g. backspace at the
+// start); caret-only moves return a state with an empty splice.
+export function edit(state, action, { multiline = false, maxLength } = {}) {
+    const text = state.text;
+    const caret = clampCaret(text, state.caret);
+    const move = (to) => (to === caret ? null : { state: { text, caret: to }, splice: { at: to, remove: 0, insert: '' } });
+    switch (action.type) {
+        case 'insert': {
+            let insert = sanitize(action.text, multiline);
+            if (maxLength !== undefined)
+                insert = insert.slice(0, Math.max(0, maxLength - text.length));
+            // Don't cut a surrogate pair in half at the limit.
+            if (insert && isHigh(insert.charCodeAt(insert.length - 1)))
+                insert = insert.slice(0, -1);
+            return spliceEdit({ text, caret }, { at: caret, remove: 0, insert }, caret + insert.length);
+        }
+        case 'backspace': {
+            const from = step(text, caret, -1);
+            return spliceEdit({ text, caret }, { at: from, remove: caret - from, insert: '' }, from);
+        }
+        case 'delete': {
+            const to = step(text, caret, 1);
+            return spliceEdit({ text, caret }, { at: caret, remove: to - caret, insert: '' }, caret);
+        }
+        case 'left':
+            return move(step(text, caret, -1));
+        case 'right':
+            return move(step(text, caret, 1));
+        case 'home':
+            return move(0);
+        case 'end':
+            return move(text.length);
+    }
+}
+// Physical keyboard → editing action. `enter` / `escape` are the field's own (submit /
+// cancel). Returns null for keys a text field leaves alone (shortcuts with Cmd/Ctrl,
+// function keys), so they keep working.
+export function keyToAction(event) {
+    if (event.ctrlKey || event.metaKey)
+        return null;
+    switch (event.key) {
+        case 'Enter':
+            return 'enter';
+        case 'Escape':
+            return 'escape';
+        case 'Backspace':
+            return { type: 'backspace' };
+        case 'Delete':
+            return { type: 'delete' };
+        case 'ArrowLeft':
+            return { type: 'left' };
+        case 'ArrowRight':
+            return { type: 'right' };
+        case 'Home':
+        case 'ArrowUp':
+            return { type: 'home' };
+        case 'End':
+        case 'ArrowDown':
+            return { type: 'end' };
+    }
+    // Printable characters have a one-character key (two for astral, e.g. emoji).
+    return [...event.key].length === 1 ? { type: 'insert', text: event.key } : null;
+}
+// ---- Caret placement (troika `caretPositions`: startX, endX, bottomY, topY per char) ----
+// x of the caret before character `index` (after the last one at index = length).
+export function caretX(index, positions, length) {
+    if (!positions || !length)
+        return 0;
+    const i = Math.min(Math.max(index, 0), length);
+    return i < length ? positions[i * 4] : positions[(length - 1) * 4 + 1];
+}
+// The caret index nearest to x (text-local) — where a click puts the caret.
+export function caretIndexAt(x, positions, length) {
+    if (!positions || !length)
+        return 0;
+    let best = 0;
+    let bestDistance = Infinity;
+    for (let i = 0; i <= length; i++) {
+        const distance = Math.abs(caretX(i, positions, length) - x);
+        if (distance < bestDistance) {
+            best = i;
+            bestDistance = distance;
+        }
+    }
+    return best;
+}
+// Horizontal scroll (how far the text is shifted left) that keeps the caret inside a
+// window `viewWidth` wide, moving as little as possible; `textWidth` stops it
+// scrolling past the end of the text.
+export function scrollToCaret(caret, scroll, viewWidth, textWidth) {
+    let next = scroll;
+    if (caret - next > viewWidth)
+        next = caret - viewWidth;
+    if (caret - next < 0)
+        next = caret;
+    return Math.min(Math.max(next, 0), Math.max(0, textWidth - viewWidth));
+}

package/dist/text-focus.svelte.d.ts

@@ -0,0 +1,24 @@
+import type { EnterKeyHint } from './keyboard-layout';
+import { type EditAction } from './text-edit';
+export type Editable = {
+    readonly text: string;
+    readonly caret: number;
+    readonly placeholder: string;
+    readonly inputmode: 'text' | 'numeric';
+    readonly enterKeyHint: EnterKeyHint;
+    readonly el: Element | undefined;
+    edit(action: EditAction): void;
+    setCaret(index: number): void;
+    enter(): void;
+    done(): void;
+    cancel(): void;
+};
+declare class TextFocus {
+    current: Editable | null;
+    readonly keyboards: Set<Element>;
+    focus(field: Editable): void;
+    blur(field: Editable): void;
+    contains(target: unknown): boolean;
+}
+export declare const textFocus: TextFocus;
+export {};