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

package/dist/scroll/registry.js

@@ -0,0 +1,261 @@
+export function readScrollOffset(element) {
+    return Object.freeze({ x: element.scrollLeft, y: element.scrollTop });
+}
+function documentOrder(left, right) {
+    if (typeof Node === 'undefined' || !(left instanceof Node) || !(right instanceof Node))
+        return 0;
+    return left.compareDocumentPosition(right) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1;
+}
+function offsetsMatch(left, right) {
+    return Math.abs(left.x - right.x) <= 0.5 && Math.abs(left.y - right.y) <= 0.5;
+}
+export function createScrollSurfaceRegistry(options = {}) {
+    const development = options.development ?? import.meta.env.DEV;
+    const listeners = new Set();
+    const registrations = new Map();
+    let pendingSnapshot;
+    const waiting = new Map();
+    const stopWaiting = (id) => {
+        waiting.get(id)?.();
+        waiting.delete(id);
+    };
+    const cancelRestoration = (id) => {
+        const cancelled = pendingSnapshot?.delete(id);
+        stopWaiting(id);
+        if (cancelled)
+            for (const listener of listeners)
+                listener();
+    };
+    let pendingWarnOnMismatch = false;
+    let primaryId;
+    let uncovered = false;
+    // An explicit primary wins; otherwise the first automatic candidate in document order. Each
+    // surface learns the result through its data attribute and the registry's listeners.
+    const electPrimary = () => {
+        const candidates = [...registrations.values()];
+        const explicit = candidates.find(entry => entry.primary === true);
+        const automatic = candidates
+            .filter(entry => entry.primary === 'automatic')
+            .sort((left, right) => documentOrder(left.element, right.element));
+        const elected = (explicit ?? automatic[0])?.id;
+        if (elected === primaryId)
+            return;
+        primaryId = elected;
+        for (const entry of candidates) {
+            const element = entry.element;
+            if (element.dataset)
+                element.dataset.satinPrimary = String(entry.id === primaryId);
+        }
+        for (const listener of listeners)
+            listener();
+    };
+    const rejectRegistration = (message, registration) => {
+        if (development)
+            throw new Error(message);
+        console.error(`[Satin fidelity: invalid-scroll-registration] ${message}`, {
+            registration,
+            screenKey: options.screenKey,
+        });
+        return () => undefined;
+    };
+    const restoreRegistration = (registration, snapshotOffset, warnOnMismatch) => {
+        const live = readScrollOffset(registration.element);
+        const matches = offsetsMatch(live, snapshotOffset);
+        const result = Object.freeze({
+            id: registration.id,
+            live,
+            matches,
+            snapshot: snapshotOffset,
+        });
+        if (warnOnMismatch && !matches) {
+            console.warn(`[Satin fidelity: scroll-snapshot-mismatch] ScrollSurface "${registration.id}" ` +
+                `in screen entry "${options.screenKey ?? 'unknown'}" had live offset ` +
+                `(${live.x}, ${live.y}) but its snapshot was ` +
+                `(${snapshotOffset.x}, ${snapshotOffset.y}) on uncover. ` +
+                'Satin restored the framework-owned snapshot before paint.', { id: registration.id, live, snapshot: snapshotOffset });
+        }
+        registration.element.scrollTo({
+            behavior: 'auto',
+            left: snapshotOffset.x,
+            top: snapshotOffset.y,
+        });
+        registration.onRestore?.();
+        return result;
+    };
+    const attemptRestore = (registration) => {
+        const target = pendingSnapshot?.get(registration.id);
+        if (!target)
+            return;
+        const element = registration.element;
+        // Do not clamp a saved offset into an empty or partially loaded list. Keep
+        // the original target durable while content arrives, even across another kill.
+        const maxX = element.scrollWidth === undefined || element.clientWidth === undefined
+            ? Infinity
+            : Math.max(0, element.scrollWidth - element.clientWidth);
+        const maxY = element.scrollHeight === undefined || element.clientHeight === undefined
+            ? Infinity
+            : Math.max(0, element.scrollHeight - element.clientHeight);
+        if (target.x > maxX + 0.5 || target.y > maxY + 0.5)
+            return;
+        const result = restoreRegistration(registration, target, pendingWarnOnMismatch);
+        if (offsetsMatch(readScrollOffset(element), target))
+            cancelRestoration(registration.id);
+        return result;
+    };
+    const awaitContent = (registration) => {
+        if (!pendingSnapshot?.has(registration.id) || waiting.has(registration.id))
+            return;
+        const element = registration.element;
+        if (typeof element.addEventListener !== 'function')
+            return;
+        const retry = () => {
+            attemptRestore(registration);
+        };
+        const userIntent = () => {
+            cancelRestoration(registration.id);
+        };
+        // Observe only while an offset is waiting. Direct children cover ordinary
+        // lists and virtual-list spacers without one observer per descendant.
+        const resize = typeof ResizeObserver === 'undefined' ? undefined : new ResizeObserver(retry);
+        const observeChildren = () => {
+            resize?.disconnect();
+            resize?.observe(element);
+            for (const child of element.children)
+                resize?.observe(child);
+        };
+        const mutation = typeof MutationObserver === 'undefined'
+            ? undefined
+            : new MutationObserver(() => {
+                retry();
+                if (pendingSnapshot?.has(registration.id))
+                    observeChildren();
+            });
+        observeChildren();
+        mutation?.observe(element, {
+            childList: true,
+            subtree: true,
+            characterData: true,
+            attributes: true,
+            attributeFilter: ['style', 'class', 'hidden', 'src'],
+        });
+        element.addEventListener('load', retry, true);
+        for (const event of ['pointerdown', 'wheel', 'keydown'])
+            element.addEventListener(event, userIntent, { passive: true });
+        waiting.set(registration.id, () => {
+            resize?.disconnect();
+            mutation?.disconnect();
+            element.removeEventListener('load', retry, true);
+            for (const event of ['pointerdown', 'wheel', 'keydown'])
+                element.removeEventListener(event, userIntent);
+        });
+    };
+    return {
+        cancelRestoration,
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+        capture(captureOptions = {}) {
+            // Persistence observes partially mounted screens without consuming the
+            // offsets that a late registering surface still needs before paint.
+            if (captureOptions.preservePending)
+                return new Map([
+                    ...Array.from(registrations, ([id, registration]) => [id, readScrollOffset(registration.element)]),
+                    ...(pendingSnapshot ?? []),
+                ]);
+            const unregistered = [...(pendingSnapshot?.keys() ?? [])].filter(id => !registrations.has(id));
+            if (development && unregistered.length > 0) {
+                console.warn(`[Satin fidelity: unconsumed-scroll-snapshot] Screen entry ` +
+                    `"${options.screenKey ?? 'unknown'}" was captured with pending snapshot ` +
+                    `entries for: ${unregistered.join(', ')}. ` +
+                    'Those surfaces did not register while the screen was uncovered; the new capture replaces the pending snapshot.', {
+                    pendingIds: unregistered,
+                    screenKey: options.screenKey,
+                });
+            }
+            for (const id of unregistered)
+                pendingSnapshot?.delete(id);
+            return new Map(Array.from(registrations, ([id, registration]) => [
+                id,
+                pendingSnapshot?.get(id) ?? readScrollOffset(registration.element),
+            ]));
+        },
+        get(id) {
+            return registrations.get(id);
+        },
+        getPrimary() {
+            return primaryId ? registrations.get(primaryId) : undefined;
+        },
+        register(registration) {
+            if (registration.id.trim().length === 0) {
+                return rejectRegistration('A Satin ScrollSurface id must be a non-empty string.', registration);
+            }
+            const existing = registrations.get(registration.id);
+            if (existing) {
+                return rejectRegistration(`Satin ScrollSurface id "${registration.id}" is already registered` +
+                    `${options.screenKey ? ` in screen entry "${options.screenKey}"` : ''}. ` +
+                    'Surface ids must be stable and unique within a screen.', registration);
+            }
+            if (registration.primary === true &&
+                primaryId &&
+                registrations.get(primaryId)?.primary === true) {
+                return rejectRegistration(`Satin screen entry${options.screenKey ? ` "${options.screenKey}"` : ''} ` +
+                    `already has primary ScrollSurface "${primaryId}".`, registration);
+            }
+            const element = registration.element;
+            const changed = () => {
+                for (const listener of listeners)
+                    listener();
+            };
+            element.addEventListener?.('scroll', changed, { passive: true });
+            registrations.set(registration.id, registration);
+            electPrimary();
+            const pendingOffset = pendingSnapshot?.get(registration.id);
+            if (uncovered && pendingOffset) {
+                attemptRestore(registration);
+                awaitContent(registration);
+            }
+            return () => {
+                if (registrations.get(registration.id) !== registration)
+                    return;
+                stopWaiting(registration.id);
+                element.removeEventListener?.('scroll', changed);
+                registrations.delete(registration.id);
+                electPrimary();
+            };
+        },
+        reset() {
+            for (const id of waiting.keys())
+                stopWaiting(id);
+            pendingSnapshot = undefined;
+            pendingWarnOnMismatch = false;
+            for (const registration of registrations.values()) {
+                const initial = registration.initialOffset?.() ?? { x: 0, y: 0 };
+                registration.element.scrollTo({ behavior: 'auto', left: initial.x, top: initial.y });
+                registration.onRestore?.();
+            }
+        },
+        restore(snapshot, restoreOptions = {}) {
+            const results = [];
+            for (const id of waiting.keys())
+                stopWaiting(id);
+            pendingSnapshot = new Map(snapshot);
+            pendingWarnOnMismatch = Boolean(restoreOptions.warnOnMismatch);
+            for (const [id] of snapshot) {
+                const registration = registrations.get(id);
+                if (!registration)
+                    continue;
+                const result = attemptRestore(registration);
+                if (result)
+                    results.push(result);
+                awaitContent(registration);
+            }
+            return results;
+        },
+        setUncovered(nextUncovered) {
+            uncovered = nextUncovered;
+        },
+    };
+}

package/dist/scroll/screenGeometry.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Whether a scroll view starts its screen's content, as a SwiftUI scroll view that reaches the
+ * top safe-area edge does. Only such a scroll view extends under the navigation bar and takes the
+ * bar's content inset; one placed below other content keeps its own frame, like a Form under a
+ * header in a VStack.
+ */
+export declare function startsScreenContent(element: Element): boolean;
+export declare function observeListLayoutMargins(list: HTMLElement, safeAreaPadding?: number): () => void;

package/dist/scroll/screenGeometry.js

@@ -0,0 +1,50 @@
+/** The box a screen's (or a sheet's) content is laid out in. */
+const SCREEN_CONTENT_BOUNDARY = '[data-satin-navigation-motion-layer], .satin-sheet-content-scale';
+/** Content before the element in flow: a visible box that is not positioned out of flow. */
+function occupiesFlow(element) {
+    if (!(element instanceof HTMLElement) || element.offsetHeight === 0)
+        return false;
+    // The screen's own static large title stands in the bar's title row, never in the content.
+    if (element.hasAttribute('data-satin-screen-title'))
+        return false;
+    const position = getComputedStyle(element).position;
+    return position !== 'absolute' && position !== 'fixed';
+}
+/**
+ * Whether a scroll view starts its screen's content, as a SwiftUI scroll view that reaches the
+ * top safe-area edge does. Only such a scroll view extends under the navigation bar and takes the
+ * bar's content inset; one placed below other content keeps its own frame, like a Form under a
+ * header in a VStack.
+ */
+export function startsScreenContent(element) {
+    const boundary = element.closest(SCREEN_CONTENT_BOUNDARY);
+    for (let node = element; node && node !== boundary; node = node.parentElement) {
+        for (let sibling = node.previousElementSibling; sibling; sibling = sibling.previousElementSibling) {
+            if (occupiesFlow(sibling))
+                return false;
+        }
+    }
+    return true;
+}
+/** The widest List frame that keeps compact (16 pt) layout margins; wider frames use 20 pt. */
+const COMPACT_LIST_MAX_WIDTH_PX = 402;
+/*
+ * Marks a List's layout margins from its own width (styles.css `data-satin-list-margins`), less
+ * the horizontal safe-area padding it lays its cards out inside (iOS 27 native reference `padding-list`: a
+ * 440 pt List with 40 pt safe-area padding each side keeps the compact 16 pt margin).
+ */
+export function observeListLayoutMargins(list, safeAreaPadding = 0) {
+    const apply = (frame) => {
+        const width = frame - safeAreaPadding;
+        const margins = width > COMPACT_LIST_MAX_WIDTH_PX ? 'wide' : 'compact';
+        if (list.dataset.satinListMargins !== margins)
+            list.dataset.satinListMargins = margins;
+    };
+    apply(list.getBoundingClientRect().width);
+    const observer = new ResizeObserver(entries => {
+        const size = entries.at(-1)?.borderBoxSize?.[0];
+        apply(size ? size.inlineSize : list.getBoundingClientRect().width);
+    });
+    observer.observe(list);
+    return () => observer.disconnect();
+}

package/dist/scroll/scrollIndicator.d.ts

@@ -0,0 +1,7 @@
+export type ScrollIndicatorParts = Readonly<{
+    /** The screen's frame the track is laid out in (the screen's motion layer). */
+    frame: HTMLElement;
+    track: HTMLElement;
+    thumb: HTMLElement;
+}>;
+export declare function installScrollIndicator(scroller: HTMLElement, parts: ScrollIndicatorParts): () => void;

package/dist/scroll/scrollIndicator.js

@@ -0,0 +1,114 @@
+/*
+ * The vertical scroll indicator of a screen's primary scroll view.
+ *
+ * WebKit's own indicator spans the scroll view's whole frame, and the primary scroll view's frame
+ * runs under the navigation bar and the bottom bars. Its indicator therefore starts under the bar
+ * at rest and below it once scrolled. Native ranges the indicator over the content insets instead
+ * (`verticalScrollIndicatorInsets`), so it never jumps. This draws that indicator in the screen's
+ * frame: the track runs from 3 pt below the bar to 3 pt above the bottom inset chain (never into the
+ * display's rounded corner), and the thumb
+ * follows UIKit's proportions (iOS 27 native reference, iPhone 17 Pro Max: 3 pt wide, 3 pt from the edge,
+ * top at the bar's safe edge + 3 pt even under a large title).
+ */
+/** Minimum thumb length while not rubber-banding, as UIKit keeps. */
+const MINIMUM_THUMB_PX = 36;
+/** Shortest the thumb gets while rubber-banding past an end. */
+const MINIMUM_BANDED_THUMB_PX = 7;
+/** The indicator's distance from the bar's safe edge and from the bottom inset chain. */
+const TRACK_INSET_PX = 3;
+/*
+ * The indicator's floor above the bottom safe edge: UIKit keeps it clear of the display's rounded
+ * corner (iOS 27 native reference, iPhone 17 Pro Max: 65 pt above the screen bottom with a 34 pt home
+ * indicator, with or without a bottom toolbar; 86 pt over a tab bar; 95 pt over a 50 pt composer).
+ */
+const CORNER_FLOOR_PX = 31;
+/** How long the indicator stays after the last scroll before it fades. */
+const HIDE_DELAY_MS = 500;
+/** The bar's safe edge below the frame top: `--satin-screen-bar-inset` (styles.css). */
+function barInset(frame) {
+    return parseFloat(getComputedStyle(frame).getPropertyValue('--satin-screen-bar-inset')) || 0;
+}
+/** The bottom content inset the indicator respects: the inset chain without a bottom toolbar. */
+function indicatorBottomInset(scroller) {
+    const style = getComputedStyle(scroller);
+    const padding = parseFloat(style.paddingBottom) || 0;
+    const bottomBar = parseFloat(style.getPropertyValue('--satin-bottom-bar-inset')) || 0;
+    const safeBottom = parseFloat(style.getPropertyValue('--satin-inset-bottom')) || 0;
+    return Math.max(padding - bottomBar + TRACK_INSET_PX, safeBottom + CORNER_FLOOR_PX);
+}
+export function installScrollIndicator(scroller, parts) {
+    const { frame, track, thumb } = parts;
+    let trackLength = 0;
+    let hideTimer = 0;
+    let interacting = false;
+    const place = () => {
+        const visible = scroller.clientHeight;
+        const total = scroller.scrollHeight;
+        const range = total - visible;
+        if (range <= 0 || trackLength <= 0) {
+            track.dataset.satinScrollIndicatorScrollable = 'false';
+            return;
+        }
+        track.dataset.satinScrollIndicatorScrollable = 'true';
+        const offset = scroller.scrollTop;
+        const overshoot = offset < 0 ? -offset : Math.max(0, offset - range);
+        const resting = Math.max(MINIMUM_THUMB_PX, (trackLength * visible) / total);
+        const length = Math.max(MINIMUM_BANDED_THUMB_PX, resting - overshoot);
+        const progress = Math.min(1, Math.max(0, offset / range));
+        const position = progress * (trackLength - length);
+        thumb.style.height = `${length}px`;
+        thumb.style.transform = `translate3d(0, ${position}px, 0)`;
+    };
+    // The track follows the primary's frame and insets; it changes only on layout, never per scroll.
+    const measure = () => {
+        const frameBox = frame.getBoundingClientRect();
+        const scrollerBox = scroller.getBoundingClientRect();
+        const top = scrollerBox.top - frameBox.top + barInset(frame) + TRACK_INSET_PX;
+        const bottom = frameBox.bottom - scrollerBox.bottom + indicatorBottomInset(scroller);
+        track.style.top = `${top}px`;
+        track.style.bottom = `${bottom}px`;
+        trackLength = Math.max(0, frameBox.height - top - bottom);
+        place();
+    };
+    const hide = () => {
+        interacting = false;
+        track.dataset.satinScrollIndicatorVisible = 'false';
+    };
+    // Only a scroll the person drives shows the indicator; restoration and scrollTo do not flash it.
+    const startInteraction = () => {
+        interacting = true;
+    };
+    const scrolled = () => {
+        if (!interacting)
+            return;
+        place();
+        if (track.dataset.satinScrollIndicatorVisible !== 'true')
+            track.dataset.satinScrollIndicatorVisible = 'true';
+        window.clearTimeout(hideTimer);
+        hideTimer = window.setTimeout(hide, HIDE_DELAY_MS);
+    };
+    const resize = new ResizeObserver(measure);
+    resize.observe(frame);
+    resize.observe(scroller);
+    for (const child of scroller.children)
+        resize.observe(child);
+    const children = new MutationObserver(() => {
+        for (const child of scroller.children)
+            resize.observe(child);
+        measure();
+    });
+    children.observe(scroller, { childList: true });
+    scroller.addEventListener('scroll', scrolled, { passive: true });
+    scroller.addEventListener('touchstart', startInteraction, { passive: true });
+    scroller.addEventListener('wheel', startInteraction, { passive: true });
+    measure();
+    return () => {
+        window.clearTimeout(hideTimer);
+        resize.disconnect();
+        children.disconnect();
+        scroller.removeEventListener('scroll', scrolled);
+        scroller.removeEventListener('touchstart', startInteraction);
+        scroller.removeEventListener('wheel', startInteraction);
+        hide();
+    };
+}

package/dist/scroll/scrollJump.d.ts

@@ -0,0 +1,7 @@
+/** Framework scrolls start on the tap. Glass preparation is advisory and never owns a
+ * deferred scroll callback: completing a capture must not restart a scroll under a finger. */
+export type ScrollJumpPreparer = (element: object, top: number) => Promise<void> | undefined;
+/** Register a preparer (the glass runtime); returns its removal. */
+export declare function onScrollJump(preparer: ScrollJumpPreparer): () => void;
+/** Announce the destination and start scrolling in the same turn. */
+export declare function scrollAfterGlassPrepared(element: object, top: number, scroll: () => void): void;

package/dist/scroll/scrollJump.js

@@ -0,0 +1,16 @@
+const preparers = new Set();
+/** Register a preparer (the glass runtime); returns its removal. */
+export function onScrollJump(preparer) {
+    preparers.add(preparer);
+    return () => {
+        preparers.delete(preparer);
+    };
+}
+/** Announce the destination and start scrolling in the same turn. */
+export function scrollAfterGlassPrepared(element, top, scroll) {
+    scroll();
+    for (const preparer of preparers) {
+        // The runtime reports capture errors through its glass error channel.
+        void preparer(element, top)?.catch(() => { });
+    }
+}

package/dist/scroll/types.d.ts

@@ -0,0 +1,12 @@
+/** The axis along which a scroll surface accepts scrolling. */
+export type ScrollAxis = 'horizontal' | 'vertical';
+/** The scroll position in points along the physical x and y axes. */
+export type ScrollOffset = Readonly<{
+    x: number;
+    y: number;
+}>;
+export type ScrollSnapshot = ReadonlyMap<string, ScrollOffset>;
+/** Options for restoring a named scroll surface to its top. */
+export type ScrollToTopOptions = Readonly<{
+    animated?: boolean;
+}>;

package/dist/scroll/types.js

@@ -0,0 +1 @@
+export {};

package/dist/search/SearchDrawer.d.ts

@@ -0,0 +1,16 @@
+import { type RefObject } from 'react';
+import { type Searchable } from './searchable.js';
+/**
+ * The navigation bar drawer of a screen's primary scroll view: the search field under the title,
+ * its close button and scope bar, and the suggestions that stand in for the content.
+ *
+ * Every element keeps its place in the DOM in both states, so presenting or dismissing never
+ * inserts or removes chrome. The two layouts are CSS states of the scroll view
+ * (`data-satin-search-presented`), and the change between them is animated from the measured
+ * visual state of each part (FLIP), on the native springs (searchMotion.ts). A retarget mid-way
+ * starts from where everything is on screen, keeping the field's velocity.
+ */
+export declare function SearchDrawer({ configuration, scroller, }: {
+    configuration: Searchable;
+    scroller: RefObject<HTMLDivElement | null>;
+}): import("react").JSX.Element;