@satinhq/kit 0.0.0-stage → 0.1.0-beta.1

package/dist/list-form/sliderContact.js

@@ -0,0 +1,98 @@
+import { CONTROL_LIFT, controlLiftProfile } from '../glass/lens/controlLift.js';
+import { InteractivePress } from '../glass/lens/interactivePress.js';
+/** Horizontal movement that turns a contact into a drag (the Toggle's slop, not a native value). */
+const DRAG_SLOP_PX = 4;
+/**
+ * One Slider contact transaction: pressed (white thumb) → lifted after the native stationary hold
+ * (CONTROL_LIFT.activationMs) or as a drag starts → dragging (the thumb follows the finger,
+ * snapped to `snap`'s positions) → the lens restores on release. The thumb stays where it was
+ * released: a Slider has no ends to settle to. Times are epoch milliseconds.
+ */
+export class SliderContact {
+    liftSpring = new InteractivePress(controlLiftProfile('slider'));
+    contact;
+    lifted = false;
+    position;
+    /** Reduce Motion: the lens never lifts. */
+    reducedMotion = false;
+    constructor(position) {
+        this.position = position;
+    }
+    get active() {
+        return this.contact !== undefined;
+    }
+    get isLifted() {
+        return this.lifted;
+    }
+    get dragging() {
+        return !!this.contact?.dragging;
+    }
+    /** Same activation rule as the Toggle: native evidence covers stationary holds only. */
+    liftDue(at) {
+        const contact = this.contact;
+        if (!contact || this.lifted)
+            return false;
+        return contact.dragging || at - contact.downAt >= CONTROL_LIFT.activationMs - 1;
+    }
+    get needsFrame() {
+        return !!this.contact || this.liftSpring.needsFrame;
+    }
+    /** A value from outside a drag (keyboard, assistive technology, the app). */
+    setPosition(position) {
+        if (!this.contact?.dragging)
+            this.position = position;
+    }
+    down(pointerId, x, y, at, ownsVertical = false) {
+        this.contact = {
+            pointerId,
+            x,
+            y,
+            ownsVertical,
+            from: this.position,
+            downAt: at,
+            dragging: false,
+        };
+    }
+    /**
+     * `travel` is the thumb's travel in CSS px; `snap` maps a raw position to a shown one (steps).
+     * Returns `vertical` when the contact moved vertically first: the page's scroll owns it.
+     */
+    move(pointerId, x, y, travel, snap) {
+        const contact = this.contact;
+        if (!contact || contact.pointerId !== pointerId)
+            return;
+        const dx = x - contact.x;
+        const dy = y - contact.y;
+        if (!contact.dragging) {
+            if (!contact.ownsVertical && Math.abs(dy) > DRAG_SLOP_PX && Math.abs(dy) > Math.abs(dx))
+                return 'vertical';
+            if (Math.abs(dx) <= DRAG_SLOP_PX)
+                return;
+            contact.dragging = true;
+        }
+        const raw = travel > 0 ? contact.from + dx / travel : contact.from;
+        this.position = snap(Math.min(1, Math.max(0, raw)));
+        return 'drag';
+    }
+    /** Start the lens lift (the page calls this once the lens can be shown in this frame). */
+    lift(at) {
+        if (!this.contact || this.lifted)
+            return;
+        this.lifted = true;
+        this.liftSpring.down(at);
+    }
+    /** End the contact (release, cancel or a vertical scroll). Returns whether it dragged. */
+    end(at) {
+        const contact = this.contact;
+        if (!contact)
+            return false;
+        this.contact = undefined;
+        if (this.lifted)
+            this.liftSpring.up(at);
+        this.lifted = false;
+        return contact.dragging;
+    }
+    sample(at) {
+        return { position: this.position, lift: this.liftSpring.sample(at, this.reducedMotion) };
+    }
+}

package/dist/list-form/state.d.ts

@@ -0,0 +1,5 @@
+export declare function clampStepper(value: number, min: number, max: number, step: number): number;
+export declare function pickerSelection(options: readonly {
+    id: string;
+    label: string;
+}[], id: string): string | undefined;

package/dist/list-form/state.js

@@ -0,0 +1,8 @@
+export function clampStepper(value, min, max, step) {
+    if (!Number.isFinite(step) || step === 0 || min > max)
+        throw new Error('Invalid stepper bounds or step.');
+    return Math.min(max, Math.max(min, value + step));
+}
+export function pickerSelection(options, id) {
+    return options.find(option => option.id === id)?.label;
+}

package/dist/list-form/toggleContact.d.ts

@@ -0,0 +1,55 @@
+/** The native Toggle thumb travels 22 pt between its ends (63 × 28 pt track, 37 × 24 pt thumb). */
+export declare const TOGGLE_TRAVEL_PT = 22;
+export type ToggleFrame = Readonly<{
+    /** Thumb position: 0 at the off end, 1 at the on end. */
+    position: number;
+    /** Lens lift: 0 is the white resting thumb, 1 the held lens (the springs overshoot). */
+    lift: number;
+    /** The side the dragged thumb is on; undefined without a drag. */
+    side?: boolean;
+}>;
+/**
+ * One Toggle contact transaction: pressed (white thumb) → lifted after a stationary hold or as a
+ * drag starts → dragging (the thumb follows the finger) → settling. The page owns the logical
+ * value and the thumb position; the glass lens follows them. Times are epoch milliseconds.
+ */
+export declare class ToggleContact {
+    private readonly position;
+    private readonly liftSpring;
+    private contact?;
+    private lifted;
+    /** Reduce Motion: the thumb jumps to its end and the lens never lifts. */
+    reducedMotion: boolean;
+    constructor(checked: boolean, at: number);
+    get active(): boolean;
+    get isLifted(): boolean;
+    get dragging(): boolean;
+    /** The lens is due to lift: the contact has been held for the native activation time, or it
+     * became a drag first. (Native evidence covers stationary holds only; lifting a fast drag at once
+     * keeps the dragged thumb from sliding as a white pill. Pending a native early-drag capture.) */
+    liftDue(at: number): boolean;
+    get needsFrame(): boolean;
+    /** A value change from outside a contact (tap commit, keyboard, assistive technology, app). */
+    setChecked(checked: boolean, at: number, animate: boolean): void;
+    down(pointerId: number, x: number, y: number, checked: boolean, at: number, ownsVertical?: boolean): void;
+    /** `vertical`: the contact moved vertically first; the page's scroll owns it. */
+    move(pointerId: number, x: number, y: number, at: number): 'drag' | 'vertical' | undefined;
+    /** Start the lens lift (the page calls this once the lens can be shown in this frame). */
+    lift(at: number): void;
+    /**
+     * End the contact. Returns the committed value. A drag that crossed the middle commits the side
+     * it is released on; any other contact (tap, hold, a drag that stayed on its side) toggles. That
+     * rule reproduces every native receipt so far (native control measurements `toggle-value-trials.json`:
+     * ±10/±14 pt crossings and same-side 14/35 pt drags all toggled); it is not a measured threshold.
+     */
+    up(pointerId: number, at: number): {
+        value: boolean;
+        dragged: boolean;
+    } | undefined;
+    /** The browser took the contact (a vertical scroll) or it was retired: no value change. */
+    cancel(at: number): void;
+    /** Spring the thumb from where it is (and how fast it moves) to the end of `value`. */
+    private settle;
+    private release;
+    sample(at: number): ToggleFrame;
+}

package/dist/list-form/toggleContact.js

@@ -0,0 +1,164 @@
+import { CONTROL_LIFT, CONTROL_THUMB_POSITION, controlLiftProfile, } from '../glass/lens/controlLift.js';
+import { InteractivePress } from '../glass/lens/interactivePress.js';
+import { SCROLL_PRESS_SLOP_PX } from '../scroll/pressOwnership.js';
+/** The native Toggle thumb travels 22 pt between its ends (63 × 28 pt track, 37 × 24 pt thumb). */
+export const TOGGLE_TRAVEL_PT = 22;
+/** Horizontal movement that turns a contact into a drag. Not a native measurement: small enough
+ * that the thumb follows from the first visible movement, large enough to absorb tap jitter. */
+const DRAG_SLOP_PX = 4;
+/**
+ * One Toggle contact transaction: pressed (white thumb) → lifted after a stationary hold or as a
+ * drag starts → dragging (the thumb follows the finger) → settling. The page owns the logical
+ * value and the thumb position; the glass lens follows them. Times are epoch milliseconds.
+ */
+export class ToggleContact {
+    position = new InteractivePress(CONTROL_THUMB_POSITION);
+    liftSpring = new InteractivePress(controlLiftProfile('toggle'));
+    contact;
+    lifted = false;
+    /** Reduce Motion: the thumb jumps to its end and the lens never lifts. */
+    reducedMotion = false;
+    constructor(checked, at) {
+        this.position.place(checked ? 1 : 0, 0, at);
+    }
+    get active() {
+        return this.contact !== undefined;
+    }
+    get isLifted() {
+        return this.lifted;
+    }
+    get dragging() {
+        return !!this.contact?.dragging;
+    }
+    /** The lens is due to lift: the contact has been held for the native activation time, or it
+     * became a drag first. (Native evidence covers stationary holds only; lifting a fast drag at once
+     * keeps the dragged thumb from sliding as a white pill. Pending a native early-drag capture.) */
+    liftDue(at) {
+        const contact = this.contact;
+        if (!contact || this.lifted)
+            return false;
+        return contact.dragging || at - contact.downAt >= CONTROL_LIFT.activationMs - 1;
+    }
+    get needsFrame() {
+        return ((!!this.contact && !this.lifted) || this.position.needsFrame || this.liftSpring.needsFrame);
+    }
+    /** A value change from outside a contact (tap commit, keyboard, assistive technology, app). */
+    setChecked(checked, at, animate) {
+        if (this.contact)
+            return;
+        if (!animate)
+            this.position.place(checked ? 1 : 0, 0, at);
+        else
+            this.settle(checked, 0, at);
+    }
+    down(pointerId, x, y, checked, at, ownsVertical = false) {
+        this.position.sample(at);
+        const from = this.position.amount;
+        this.position.place(from, 0, at);
+        this.contact = {
+            pointerId,
+            x,
+            y,
+            ownsVertical,
+            checked,
+            from,
+            downAt: at,
+            dragging: false,
+            crossed: false,
+            lastX: x,
+            lastAt: at,
+            velocity: 0,
+        };
+    }
+    /** `vertical`: the contact moved vertically first; the page's scroll owns it. */
+    move(pointerId, x, y, at) {
+        const contact = this.contact;
+        if (!contact || contact.pointerId !== pointerId)
+            return;
+        const dx = x - contact.x;
+        const dy = y - contact.y;
+        if (!contact.dragging) {
+            // The switch and its scroll surface must agree on when tremor becomes a pan.
+            if (!contact.ownsVertical &&
+                Math.abs(dy) >= SCROLL_PRESS_SLOP_PX &&
+                Math.abs(dy) >= Math.abs(dx))
+                return 'vertical';
+            if (Math.abs(dx) <= DRAG_SLOP_PX)
+                return;
+            contact.dragging = true;
+        }
+        const position = Math.min(1, Math.max(0, contact.from + dx / TOGGLE_TRAVEL_PT));
+        if (position >= 0.5 !== contact.from >= 0.5)
+            contact.crossed = true;
+        const elapsed = (at - contact.lastAt) / 1000;
+        if (elapsed > 0) {
+            const instant = (position - this.position.amount) / elapsed;
+            // A short exponential average keeps the release velocity from one jittered sample.
+            contact.velocity = contact.velocity * 0.4 + instant * 0.6;
+        }
+        contact.lastX = x;
+        contact.lastAt = at;
+        this.position.place(position, 0, at);
+        return 'drag';
+    }
+    /** Start the lens lift (the page calls this once the lens can be shown in this frame). */
+    lift(at) {
+        if (!this.contact || this.lifted)
+            return;
+        this.lifted = true;
+        this.liftSpring.down(at);
+    }
+    /**
+     * End the contact. Returns the committed value. A drag that crossed the middle commits the side
+     * it is released on; any other contact (tap, hold, a drag that stayed on its side) toggles. That
+     * rule reproduces every native receipt so far (native control measurements `toggle-value-trials.json`:
+     * ±10/±14 pt crossings and same-side 14/35 pt drags all toggled); it is not a measured threshold.
+     */
+    up(pointerId, at) {
+        const contact = this.contact;
+        if (!contact || contact.pointerId !== pointerId)
+            return;
+        this.contact = undefined;
+        const value = contact.crossed ? this.position.amount >= 0.5 : !contact.checked;
+        // Release owns the value and its motion. A compatibility click is optional on WebKit.
+        const velocity = contact.dragging && at - contact.lastAt < 50 ? contact.velocity : 0;
+        this.settle(value, velocity, at);
+        this.release(at);
+        return { value, dragged: contact.dragging };
+    }
+    /** The browser took the contact (a vertical scroll) or it was retired: no value change. */
+    cancel(at) {
+        const contact = this.contact;
+        if (!contact)
+            return;
+        this.contact = undefined;
+        this.settle(contact.checked, 0, at);
+        this.release(at);
+    }
+    /** Spring the thumb from where it is (and how fast it moves) to the end of `value`. */
+    settle(value, velocity, at) {
+        this.position.sample(at);
+        if (this.reducedMotion) {
+            this.position.place(value ? 1 : 0, 0, at);
+            return;
+        }
+        this.position.place(this.position.amount, velocity, at);
+        if (value)
+            this.position.down(at);
+        else
+            this.position.up(at);
+    }
+    release(at) {
+        if (this.lifted)
+            this.liftSpring.up(at);
+        this.lifted = false;
+    }
+    sample(at) {
+        const position = this.position.sample(at);
+        return {
+            position,
+            lift: this.liftSpring.sample(at, this.reducedMotion),
+            side: this.contact?.dragging ? position >= 0.5 : undefined,
+        };
+    }
+}

package/dist/media/controller.d.ts

@@ -0,0 +1,7 @@
+import type { MediaController, InternalMediaSnapshot } from './types.js';
+export declare function createMediaStore(createAudio?: () => HTMLAudioElement, onActivityChange?: (active: boolean) => void): {
+    controller: MediaController;
+    getSnapshot: () => InternalMediaSnapshot;
+    subscribe(listener: () => void): () => void;
+    dispose(): void;
+};