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

package/dist/presentation/presentationMotion.js

@@ -0,0 +1,74 @@
+import { reportGlassError } from '../glass/errors.js';
+import { GLASS_READINESS_BUDGET_MS, VisibleDeadline } from '../glass/visibleDeadline.js';
+import { preparePresentationGlassMotion, retargetPresentationGlassMotion } from './glassMotion.js';
+/** One admission, clock and cancellation contract for programmatic and gesture sheet tails. */
+export function runPresentationMotion({ layer, movement, dimming, tracksGlass, phase, invalidate, complete, }) {
+    const node = layer.closest('dialog');
+    const epoch = tracksGlass
+        ? retargetPresentationGlassMotion(layer, movement, performance.now())
+        : undefined;
+    const glass = tracksGlass && epoch === undefined
+        ? preparePresentationGlassMotion(layer, movement, { retain: true })
+        : undefined;
+    let cancelled = false;
+    let frame = 0;
+    const sample = () => {
+        if (epoch !== undefined || glass?.admitted)
+            return;
+        invalidate();
+        frame = requestAnimationFrame(sample);
+    };
+    const deadline = glass
+        ? new VisibleDeadline(GLASS_READINESS_BUDGET_MS, () => {
+            if (cancelled)
+                return;
+            reportGlassError('readiness-timeout', new Error('Sheet motion coverage did not submit'), 'presentation-motion');
+            movement.finish();
+            dimming.finish();
+        })
+        : undefined;
+    const start = (epoch) => {
+        if (cancelled)
+            return;
+        deadline?.cancel();
+        if (glass || epoch !== undefined) {
+            for (const animation of [movement, dimming]) {
+                animation.play();
+                animation.startTime = epoch ?? document.timeline.currentTime;
+            }
+        }
+        node.setAttribute('data-satin-presentation-moving', phase);
+        frame = requestAnimationFrame(sample);
+    };
+    if (glass) {
+        for (const animation of [movement, dimming]) {
+            animation.pause();
+            animation.currentTime = 0;
+        }
+        // Coverage capture is deferred while movement is marked; the release pose stays visible.
+        node.removeAttribute('data-satin-presentation-moving');
+        deadline.start();
+        void glass.start().then(start);
+        invalidate();
+    }
+    else
+        start(epoch);
+    const stopSampling = () => {
+        deadline?.cancel();
+        cancelAnimationFrame(frame);
+        if (glass && !glass.admitted)
+            glass.dispose();
+    };
+    void Promise.all([movement.finished, dimming.finished]).then(() => {
+        if (cancelled)
+            return;
+        stopSampling();
+        complete();
+    }, () => { });
+    return () => {
+        cancelled = true;
+        stopSampling();
+        movement.cancel();
+        dimming.cancel();
+    };
+}

package/dist/presentation/presentationSource.d.ts

@@ -0,0 +1,2 @@
+export declare function trackPresentationSource(document: Document): void;
+export declare function presentationSource(document: Document, now: number): Element | null;

package/dist/presentation/presentationSource.js

@@ -0,0 +1,28 @@
+/** The control a presentation grows from when the app names no anchor. Native iOS 27 presents
+ * `confirmationDialog` as a popover from the view that asked for it: a swipe action's dialog points
+ * at its row, a toolbar button's dialog grows out of the button. Satin's natural structure attaches
+ * the dialog at screen level, so the pressed control stands in for SwiftUI's attachment point. */
+const lastPress = new WeakMap();
+const tracked = new WeakSet();
+// A press older than this did not open the dialog (a timer or a data change did).
+const PRESS_FRESHNESS_MS = 1500;
+export function trackPresentationSource(document) {
+    if (tracked.has(document) || typeof document.addEventListener !== 'function')
+        return;
+    tracked.add(document);
+    document.addEventListener('pointerdown', event => {
+        if (event.target instanceof Element)
+            lastPress.set(document, { target: event.target, time: event.timeStamp });
+    }, { capture: true, passive: true });
+}
+export function presentationSource(document, now) {
+    const press = lastPress.get(document);
+    const pressed = press && now - press.time < PRESS_FRESHNESS_MS ? press.target : null;
+    const focused = document.activeElement !== document.body ? document.activeElement : null;
+    const origin = pressed?.isConnected ? pressed : focused;
+    if (!origin || origin.closest('dialog'))
+        return null;
+    // A swipe action belongs to its row: the swipe closes, and native points at the row.
+    return (origin.closest('[data-satin-row-actions]') ??
+        origin.closest('button, [role="button"], [data-satin-pressable="true"], a[href]'));
+}

package/dist/presentation/sheetChromeContext.d.ts

@@ -0,0 +1,2 @@
+/** The nearest sheet keeps its accessible label while a navigator owns visible chrome. */
+export declare const SheetChromeContext: import("react").Context<(() => () => void) | null>;

package/dist/presentation/sheetChromeContext.js

@@ -0,0 +1,3 @@
+import { createContext } from 'react';
+/** The nearest sheet keeps its accessible label while a navigator owns visible chrome. */
+export const SheetChromeContext = createContext(null);

package/dist/presentation/sheetMaterialTransition.d.ts

@@ -0,0 +1,14 @@
+/** Native iOS 27 material fade: midpoint-triggered, with its own ~0.3 s timeline.
+ * Slow-drag 10–90% backdrop-contrast change measured 183–208 ms on September 30.
+ * Geometry remains position-driven. Retargeting preserves the currently painted material.
+ */
+export declare class SheetMaterialTransition {
+    private value;
+    private from;
+    private destination;
+    private started;
+    active: boolean;
+    constructor(initial: number);
+    target(destination: number, timestamp: number, immediate?: boolean): void;
+    sample(timestamp: number): number;
+}

package/dist/presentation/sheetMaterialTransition.js

@@ -0,0 +1,33 @@
+/** Native iOS 27 material fade: midpoint-triggered, with its own ~0.3 s timeline.
+ * Slow-drag 10–90% backdrop-contrast change measured 183–208 ms on September 30.
+ * Geometry remains position-driven. Retargeting preserves the currently painted material.
+ */
+export class SheetMaterialTransition {
+    value;
+    from;
+    destination;
+    started = 0;
+    active = false;
+    constructor(initial) {
+        this.value = this.from = this.destination = initial;
+    }
+    target(destination, timestamp, immediate = false) {
+        if (destination === this.destination && !immediate)
+            return;
+        this.from = this.sample(timestamp);
+        this.destination = destination;
+        this.started = timestamp;
+        this.active = !immediate && this.from !== destination;
+        if (immediate)
+            this.value = destination;
+    }
+    sample(timestamp) {
+        if (!this.active)
+            return this.value;
+        const progress = Math.min(1, Math.max(0, (timestamp - this.started) / 300));
+        const eased = progress * progress * (3 - 2 * progress);
+        this.value = this.from + (this.destination - this.from) * eased;
+        this.active = progress < 1;
+        return this.value;
+    }
+}

package/dist/presentation/sheetReleaseMotion.d.ts

@@ -0,0 +1,18 @@
+/** This rollout translates one settled layout. It performs no FLIP or reflow:
+ * releases above the smallest detent still use the existing layout owner.
+ * Static nested glass travels with its captured content. Independently tracked
+ * glass cannot reuse that rigid snapshot and stays on the existing path too. */
+export declare function canReleaseSheetOnCompositor(layer: HTMLElement, from: number, smallest: number, downwardVelocity: number): boolean;
+/** The existing velocity-bearing dismissal fit, submitted once instead of rewritten each frame.
+ * Only the translating part below the smallest detent belongs on the compositor. */
+export declare function sheetReleaseFrames(from: number, smallest: number, gap: number, velocity: number): {
+    transform: Keyframe[];
+    dim: Keyframe[];
+    duration: number;
+};
+export type SheetReleaseMotion = {
+    cancel: () => number;
+};
+/** Keep the released pose while the renderer admits its swept source, then share one clock.
+ * Cancellation samples the compositor before retiring it, so a new touch cannot jump backwards. */
+export declare function startSheetReleaseMotion(layer: HTMLElement, from: number, smallest: number, gap: number, velocity: number, invalidate: () => void, complete: () => void): SheetReleaseMotion;

package/dist/presentation/sheetReleaseMotion.js

@@ -0,0 +1,123 @@
+import { animateElement } from '../motion/animate.js';
+import { runPresentationMotion } from './presentationMotion.js';
+import { sheetReleasePosition } from './motion.js';
+import { holdPresentationGlassMotion } from './glassMotion.js';
+import { sampledMotionTrack } from '../motion/springTrack.js';
+import { glassShapeTrack } from '../glass/shapeTrackRegistry.js';
+import { accessoryGlassMotion } from '../glass/webgpu/accessoryMorph.js';
+/** This rollout translates one settled layout. It performs no FLIP or reflow:
+ * releases above the smallest detent still use the existing layout owner.
+ * Static nested glass travels with its captured content. Independently tracked
+ * glass cannot reuse that rigid snapshot and stays on the existing path too. */
+export function canReleaseSheetOnCompositor(layer, from, smallest, downwardVelocity) {
+    if (from > smallest || downwardVelocity < 0)
+        return false;
+    const surface = layer.querySelector('.satin-presentation-surface');
+    if (!surface)
+        return false;
+    const nested = [...surface.querySelectorAll('[data-satin-glass-region-id]')];
+    for (const glass of nested) {
+        if (glassShapeTrack(glass) || accessoryGlassMotion(glass))
+            return false;
+    }
+    // A nested material can sample a moving sibling as well as its own children.
+    // Do not freeze its source while an independent layout/transform track runs.
+    if (nested.length &&
+        surface.getAnimations({ subtree: true }).some(animation => {
+            if (animation.playState !== 'running' && animation.playState !== 'paused')
+                return false;
+            const effect = animation.effect;
+            return effect
+                ?.getKeyframes()
+                .some(frame => [
+                'transform',
+                'translate',
+                'scale',
+                'rotate',
+                'width',
+                'height',
+                'top',
+                'left',
+                'bottom',
+                'right',
+                'clipPath',
+            ].some(property => property in frame));
+        }))
+        return false;
+    return true;
+}
+/** The existing velocity-bearing dismissal fit, submitted once instead of rewritten each frame.
+ * Only the translating part below the smallest detent belongs on the compositor. */
+export function sheetReleaseFrames(from, smallest, gap, velocity) {
+    const transform = [];
+    const dim = [];
+    // Preserve the old tail's endpoint rule (within half a point or 700 ms).
+    // Solve its crossing instead of letting the callback cadence set the duration.
+    let seconds = 0.7;
+    for (let step = 0; step <= 168; step++) {
+        const at = step / 240;
+        if (sheetReleasePosition(from, -gap, velocity, at, 'dismiss') <= -gap + 0.5) {
+            let low = Math.max(0, at - 1 / 240);
+            let high = at;
+            for (let iteration = 0; iteration < 24; iteration++) {
+                const middle = (low + high) / 2;
+                if (sheetReleasePosition(from, -gap, velocity, middle, 'dismiss') <= -gap + 0.5)
+                    high = middle;
+                else
+                    low = middle;
+            }
+            seconds = high;
+            break;
+        }
+    }
+    const track = sampledMotionTrack(Math.max(0.001, seconds * 1000), at => sheetReleasePosition(from, -gap, velocity, at / 1000, 'dismiss'));
+    for (let index = 0; index < track.values.length; index++) {
+        const offset = index / (track.values.length - 1);
+        const translation = smallest - (index === track.values.length - 1 ? -gap : track.values[index]);
+        transform.push({ offset, transform: `translateY(${translation}px)` });
+        dim.push({ offset, opacity: Math.max(0, 1 - translation / (smallest + gap)) });
+    }
+    return { transform, dim, duration: Math.max(0.001, seconds * 1000) };
+}
+/** Keep the released pose while the renderer admits its swept source, then share one clock.
+ * Cancellation samples the compositor before retiring it, so a new touch cannot jump backwards. */
+export function startSheetReleaseMotion(layer, from, smallest, gap, velocity, invalidate, complete) {
+    const dialog = layer.closest('dialog');
+    const dimmer = dialog.querySelector('[data-satin-presentation-dimmer]');
+    const usesDimmer = dimmer && getComputedStyle(dimmer).display !== 'none';
+    const frames = sheetReleaseFrames(from, smallest, gap, velocity);
+    const options = {
+        duration: frames.duration,
+        easing: 'linear',
+        fill: 'both',
+    };
+    const movement = animateElement(layer, frames.transform, options);
+    const dimming = usesDimmer
+        ? animateElement(dimmer, frames.dim, options)
+        : animateElement(dialog, frames.dim, { ...options, pseudoElement: '::backdrop' });
+    const retire = runPresentationMotion({
+        layer,
+        movement,
+        dimming,
+        tracksGlass: true,
+        phase: 'drag',
+        invalidate,
+        complete: () => {
+            // Write the endpoint before dropping fill, including when an owner declines dismissal.
+            layer.style.transform = `translateY(${smallest + gap}px)`;
+            holdPresentationGlassMotion(layer, smallest + gap);
+            dialog.style.setProperty('--satin-presentation-dim', '0');
+            retire();
+            complete();
+        },
+    });
+    return {
+        cancel() {
+            const transform = getComputedStyle(layer).transform;
+            const offset = transform && transform !== 'none' ? new DOMMatrixReadOnly(transform).m42 : smallest - from;
+            holdPresentationGlassMotion(layer, offset);
+            retire();
+            return smallest - offset;
+        },
+    };
+}

package/dist/presentation/useAlertKeyboardMotion.d.ts

@@ -0,0 +1,8 @@
+import { type RefObject } from 'react';
+import type { GlassRegionRegistry } from '../glass/regionRegistry.js';
+/** Animate the measured viewport destination without guessing the keyboard's height.
+ * Commit the new layout once and carry its old visible centre with a transform.
+ */
+export declare function useAlertKeyboardMotion(dialog: RefObject<HTMLDialogElement | null>, enabled: boolean, center: number, keyboardVisible: boolean, regions?: GlassRegionRegistry, 
+/** False while the keyboard's geometry is anticipated (a tap focus), not yet reported. */
+keyboardReported?: boolean): void;

package/dist/presentation/useAlertKeyboardMotion.js

@@ -0,0 +1,104 @@
+import { animateElement, timelineStart } from '../motion/animate.js';
+import { useLayoutEffect, useRef } from 'react';
+import { alertKeyboardState } from './motion.js';
+import { editable } from '../keyboard/adapter.js';
+function stopMotion(active, dialog) {
+    const value = active.current;
+    active.current = null;
+    if (value) {
+        cancelAnimationFrame(value.frame);
+        value.animation.cancel();
+        value.panel.style.top = `${value.target}px`;
+        value.panel.style.transform = 'translateY(-50%)';
+    }
+    if (dialog?.getAttribute('data-satin-presentation-moving') === 'keyboard')
+        dialog.removeAttribute('data-satin-presentation-moving');
+}
+/** Animate the measured viewport destination without guessing the keyboard's height.
+ * Commit the new layout once and carry its old visible centre with a transform.
+ */
+export function useAlertKeyboardMotion(dialog, enabled, center, keyboardVisible, regions, 
+/** False while the keyboard's geometry is anticipated (a tap focus), not yet reported. */
+keyboardReported = keyboardVisible) {
+    const previous = useRef(null);
+    const active = useRef(null);
+    useLayoutEffect(() => {
+        if (!enabled) {
+            previous.current = null;
+            stopMotion(active, dialog.current);
+            return;
+        }
+        const before = previous.current;
+        previous.current = { center, keyboardVisible, keyboardReported };
+        // A keyboard that was only anticipated and never came (a hardware keyboard) keeps editing.
+        if (before?.keyboardReported && !keyboardVisible) {
+            const editor = document.activeElement;
+            // WebKit's native caret can retain the old composited position while
+            // the panel returns. End editing before applying that return motion.
+            if (editable(editor) && dialog.current?.contains(editor))
+                editor.blur();
+        }
+        if (before === null || before.center === center)
+            return;
+        // Safe-area/rotation updates without a keyboard retain their existing policy.
+        if (!before.keyboardVisible && !keyboardVisible && !active.current)
+            return;
+        const panel = dialog.current?.querySelector('[data-satin-glass-layer]');
+        const value = active.current;
+        const pose = value
+            ? alertKeyboardState(value.from, 0, value.velocity, (performance.now() - value.start) / 1000)
+            : { position: 0, velocity: 0 };
+        stopMotion(active, dialog.current);
+        if (!panel || window.matchMedia('(prefers-reduced-motion: reduce)').matches) {
+            if (panel) {
+                panel.style.top = `${center}px`;
+                panel.style.transform = 'translateY(-50%)';
+            }
+            regions?.invalidate();
+            return;
+        }
+        const from = before.center - center + pose.position;
+        const frames = Array.from({ length: 85 }, (_, index) => ({
+            offset: index / 84,
+            transform: `translateY(-50%) translateY(${index === 84 ? 0 : alertKeyboardState(from, 0, pose.velocity, index / 120).position}px)`,
+        }));
+        // WebKit can paint the new layout before a pending animation contributes its
+        // first keyframe. Keep the old visible centre in the underlying style too.
+        panel.style.top = `${center}px`;
+        panel.style.transform = `translateY(-50%) translateY(${from}px)`;
+        const start = performance.now();
+        const animation = animateElement(panel, frames, {
+            duration: 700,
+            easing: 'linear',
+            fill: 'both',
+        });
+        animation.startTime = timelineStart(start);
+        const motion = {
+            panel,
+            animation,
+            target: center,
+            from,
+            velocity: pose.velocity,
+            start,
+            frame: 0,
+        };
+        active.current = motion;
+        dialog.current?.setAttribute('data-satin-presentation-moving', 'keyboard');
+        const sample = () => {
+            regions?.invalidate();
+            motion.frame = requestAnimationFrame(sample);
+        };
+        motion.frame = requestAnimationFrame(sample);
+        const settled = () => {
+            if (active.current === motion) {
+                stopMotion(active, dialog.current);
+                regions?.invalidate();
+            }
+        };
+        void animation.finished.then(settled, settled);
+    }, [dialog, enabled, center, keyboardVisible, keyboardReported, regions]);
+    useLayoutEffect(() => () => {
+        previous.current = null;
+        stopMotion(active, dialog.current);
+    }, [dialog]);
+}

package/dist/press/Pressable.d.ts

@@ -0,0 +1,19 @@
+import { type ButtonHTMLAttributes, type CSSProperties, type ReactNode } from 'react';
+import type { PressState } from './stateMachine.js';
+/** DOM activation handlers reserved for the Pressable interaction policy. */
+export type PressableOwnedHandlers = 'children' | 'disabled' | 'onBlur' | 'onClick' | 'onKeyDown' | 'onKeyUp' | 'onLostPointerCapture' | 'onPointerCancel' | 'onPointerDown' | 'onPointerMove' | 'onPointerUp';
+export type PressableProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, PressableOwnedHandlers> & Readonly<{
+    children?: ReactNode;
+    disabled?: boolean;
+    onPress: () => void;
+    onPressStateChange?: (state: PressState) => void;
+    /** Grouped rows highlight their background after the scroll-intent delay. */
+    feedback?: 'opacity' | 'row';
+    pressedStyle?: CSSProperties;
+}> & (Readonly<{
+    iconOnly: true;
+    'aria-label': string;
+}> | Readonly<{
+    iconOnly?: false;
+}>);
+export declare const Pressable: import("react").ForwardRefExoticComponent<PressableProps & import("react").RefAttributes<HTMLButtonElement>>;

package/dist/press/Pressable.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef } from 'react';
+import { usePressInteraction } from './usePressInteraction.js';
+export const Pressable = forwardRef(function Pressable({ children, disabled = false, onPress, onPressStateChange, pressedStyle, feedback = 'opacity', iconOnly = false, style, type = 'button', ...props }, forwardedRef) {
+    if (iconOnly && !props['aria-label']?.trim())
+        throw new Error('An icon-only Pressable requires a meaningful aria-label.');
+    const { elementRef, pressState, attributes, handlers, onClick } = usePressInteraction({ disabled, feedback, onPress, onPressStateChange });
+    const renderedStyle = pressState === 'pressed' && pressedStyle ? { ...style, ...pressedStyle } : style;
+    return (_jsx("button", { ...props, ref: element => {
+            elementRef.current = element;
+            if (typeof forwardedRef === 'function')
+                forwardedRef(element);
+            else if (forwardedRef)
+                forwardedRef.current = element;
+        }, "aria-disabled": disabled || undefined, ...attributes, "data-satin-icon-only": iconOnly || undefined, "data-satin-pressable": "true", "data-satin-row-intrinsic": "true", "data-satin-role": "chrome", disabled: disabled, ...handlers, onClick: onClick, style: renderedStyle, type: type, children: children }));
+});

package/dist/press/activation.d.ts

@@ -0,0 +1,20 @@
+export type PressKey = 'Enter' | ' ';
+export type KeyboardActivationSession = Readonly<{
+    fired: boolean;
+    key: PressKey;
+    released: boolean;
+    source: 'keyboard';
+}>;
+export type ClickDedupSession = KeyboardActivationSession;
+export type KeyboardActivationResult = Readonly<{
+    fire: boolean;
+    session: KeyboardActivationSession;
+    started: boolean;
+}>;
+export declare function beginKeyboardActivation(current: KeyboardActivationSession | undefined, key: PressKey): KeyboardActivationResult;
+export declare function releaseKeyboardActivation(current: KeyboardActivationSession | undefined, key: PressKey): KeyboardActivationResult | undefined;
+export declare function resolveClickActivation(session: ClickDedupSession | undefined): Readonly<{
+    fire: boolean;
+    session: ClickDedupSession | undefined;
+}>;
+export { PRESS_CONTACT_CLICK_WINDOW_MS as POINTER_CLICK_SUPPRESSION_WINDOW_MS, armPointerClickSuppression, consumePointerClickSuppression, resetPointerClickSuppression, } from './contactReceipt.js';

package/dist/press/activation.js

@@ -0,0 +1,28 @@
+export function beginKeyboardActivation(current, key) {
+    if (current && !current.released) {
+        return { fire: false, session: current, started: false };
+    }
+    const fire = key === 'Enter';
+    return {
+        fire,
+        session: { fired: fire, key, released: false, source: 'keyboard' },
+        started: true,
+    };
+}
+export function releaseKeyboardActivation(current, key) {
+    if (!current || current.key !== key || current.released)
+        return undefined;
+    return {
+        fire: !current.fired,
+        session: { ...current, fired: true, released: true },
+        started: false,
+    };
+}
+export function resolveClickActivation(session) {
+    if (!session)
+        return { fire: true, session: undefined };
+    if (!session.released)
+        return { fire: false, session };
+    return { fire: false, session: undefined };
+}
+export { PRESS_CONTACT_CLICK_WINDOW_MS as POINTER_CLICK_SUPPRESSION_WINDOW_MS, armPointerClickSuppression, consumePointerClickSuppression, resetPointerClickSuppression, } from './contactReceipt.js';

package/dist/press/contactReceipt.d.ts

@@ -0,0 +1,23 @@
+/** Existing release budgets, preserved separately from contact ownership. */
+export declare const PRESS_CONTACT_CLICK_WINDOW_MS = 1000;
+export declare const MENU_CONTACT_CLICK_WINDOW_MS = 750;
+export declare const TOGGLE_CONTACT_CLICK_WINDOW_MS = 350;
+export declare function contactTarget(): EventTarget;
+/** A receipt belongs to one pointer and one DOWN sequence. Later contacts cannot
+ * erase it or spend it. Legacy WebKit mouse clicks have no usable pointer id;
+ * those consume released receipts in release order, including after unmount.
+ */
+export declare function ownPhysicalContact(target: EventTarget, owner: object, windowMs: number, options?: {
+    now?: number;
+    pointerId?: number;
+    suppressTouchEnd?: boolean;
+    consumed?: () => void;
+    nativeLabel?: HTMLLabelElement;
+}): void;
+export declare function consumePhysicalContact(target: EventTarget, now: number, detail: number, pointerId?: number): boolean;
+/** Explicit cancellation affects only this owner, including all its contacts. */
+export declare function retirePhysicalContact(target: EventTarget, owner?: object): void;
+export declare function ownMenuCompatibilityClick(target: EventTarget, pointerId?: number): void;
+export declare function armPointerClickSuppression(now: number, pointerId?: number): void;
+export declare function consumePointerClickSuppression(now: number, detail?: number): boolean;
+export declare function resetPointerClickSuppression(): void;