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

package/dist/scroll/position.d.ts

@@ -0,0 +1,31 @@
+/** `UnitPoint`: the vertical alignment of a scroll target. */
+export type ScrollAnchor = 'top' | 'center' | 'bottom';
+/** Vertical scroll geometry: the current viewport and content offset in points. */
+export type VerticalScrollGeometry = Readonly<{
+    contentOffset: number;
+    contentHeight: number;
+    containerHeight: number;
+    distanceToBottom: number;
+}>;
+/** `ScrollPosition`: a target identity and the callback that receives its changes. */
+export type ScrollPositionBinding = Readonly<{
+    id: string | null;
+    anchor?: ScrollAnchor;
+    onChange(id: string | null): void;
+}>;
+/** A scroll target binding, anchor and geometry observation policy. */
+export type ScrollPositionOptions = Readonly<{
+    defaultScrollAnchor?: 'top' | 'bottom';
+    maintainVisibleContentPosition?: boolean;
+    scrollPosition?: ScrollPositionBinding;
+    onScrollGeometryChange?: (geometry: VerticalScrollGeometry) => void;
+}>;
+export type ScrollTargets = Map<string, HTMLElement>;
+/** Vertical, normal-flow targets. Native scrolling still owns gestures and momentum. */
+export declare function createScrollPositionController(surface: HTMLElement, content: HTMLElement, targets: ScrollTargets, options: () => ScrollPositionOptions, beforeScroll: () => void): {
+    reconcile: () => void;
+    scrollTo: (id: string, alignment?: ScrollAnchor) => boolean;
+    adoptRestoredOffset(): void;
+    targetsChanged(): void;
+    dispose(): void;
+};

package/dist/scroll/position.js

@@ -0,0 +1,273 @@
+import { createInsertionMotion } from './insertionMotion.js';
+import { BOTTOM_INSET_CHANGED } from '../safe-area/bottomInsetGeometry.js';
+import { scrollAfterGlassPrepared } from './scrollJump.js';
+/** Vertical, normal-flow targets. Native scrolling still owns gestures and momentum. */
+export function createScrollPositionController(surface, content, targets, options, beforeScroll) {
+    const insertion = createInsertionMotion(surface, content);
+    let ordered = [];
+    let dirty = true;
+    let pinned = surface.scrollHeight - surface.clientHeight - surface.scrollTop <= 1;
+    let anchor;
+    let pending;
+    let requested;
+    let reported = null;
+    let lastGeometry = '';
+    let touching = false;
+    let disposed = false;
+    let mutationFrame = 0;
+    let lastOffset = surface.scrollTop;
+    let lastHeight = surface.scrollHeight;
+    let lastViewport = surface.clientHeight;
+    const maximum = () => Math.max(0, surface.scrollHeight - surface.clientHeight);
+    const top = (element) => element.getBoundingClientRect().top -
+        surface.getBoundingClientRect().top -
+        surface.clientTop -
+        insertion.offset();
+    const targetList = () => {
+        if (dirty) {
+            ordered = [...targets].sort((left, right) => left[1].compareDocumentPosition(right[1]) & Node.DOCUMENT_POSITION_FOLLOWING ? -1 : 1);
+            dirty = false;
+        }
+        return ordered;
+    };
+    const visible = () => {
+        const list = targetList();
+        const origin = surface.getBoundingClientRect().top + surface.clientTop;
+        let low = 0;
+        let high = list.length;
+        while (low < high) {
+            const middle = Math.floor((low + high) / 2);
+            const rect = list[middle][1].getBoundingClientRect();
+            if (rect.top + rect.height - insertion.offset() <= origin)
+                low = middle + 1;
+            else
+                high = middle;
+        }
+        return list[low];
+    };
+    const publish = () => {
+        const geometry = {
+            contentOffset: surface.scrollTop,
+            contentHeight: surface.scrollHeight,
+            containerHeight: surface.clientHeight,
+            distanceToBottom: Math.max(0, maximum() - surface.scrollTop),
+        };
+        const signature = `${geometry.contentOffset}/${geometry.contentHeight}/${geometry.containerHeight}`;
+        const target = visible();
+        anchor = target ? { id: target[0], top: top(target[1]) } : undefined;
+        const next = target?.[0] ?? null;
+        const geometryChanged = signature !== lastGeometry;
+        const positionChanged = !pending && next !== reported;
+        lastGeometry = signature;
+        if (positionChanged)
+            reported = next;
+        lastOffset = geometry.contentOffset;
+        lastHeight = geometry.contentHeight;
+        lastViewport = geometry.containerHeight;
+        // Finish this read batch before calling app callbacks that can write layout.
+        if (geometryChanged)
+            options().onScrollGeometryChange?.(geometry);
+        if (positionChanged)
+            options().scrollPosition?.onChange(next);
+    };
+    const setOffset = (offset) => {
+        surface.scrollTop = Math.max(0, Math.min(maximum(), offset));
+        lastOffset = surface.scrollTop;
+    };
+    const scrollTo = (id, alignment) => {
+        const target = targets.get(id);
+        if (!target) {
+            pending = { id, anchor: alignment };
+            return false;
+        }
+        beforeScroll();
+        pending = undefined;
+        const targetTop = top(target);
+        const height = target.getBoundingClientRect().height;
+        // Targets align within the content insets, as SwiftUI's do: a screen's primary scroll view
+        // reaches under the bar and the bottom bars, and its padding is the bar's and the bottom inset
+        // chain's content inset. Other scroll views only clear the enclosing bottom insets' accessories.
+        const style = getComputedStyle(surface);
+        const primary = surface.dataset?.satinPrimary === 'true';
+        const topInset = primary ? Number.parseFloat(style.paddingTop) || 0 : 0;
+        const bottomInset = Math.max(0, Number.parseFloat(style.getPropertyValue('--satin-scroll-inset-bottom')) || 0, primary ? Number.parseFloat(style.paddingBottom) || 0 : 0);
+        const availableHeight = Math.max(0, surface.clientHeight - topInset - bottomInset);
+        const visibleTop = targetTop - topInset;
+        const offset = alignment
+            ? visibleTop - (availableHeight - height) * { top: 0, center: 0.5, bottom: 1 }[alignment]
+            : visibleTop < 0
+                ? visibleTop
+                : Math.max(0, visibleTop + height - availableHeight);
+        const destination = Math.max(0, Math.min(maximum(), surface.scrollTop + offset));
+        // A send can request its not-yet-delivered terminal row. If already following
+        // the bottom, this is the same insertion, not a separate jump that cancels it.
+        const followsBottom = options().defaultScrollAnchor === 'bottom' &&
+            pinned &&
+            !touching &&
+            alignment === 'bottom' &&
+            Math.abs(destination - maximum()) <= 1;
+        if (!followsBottom)
+            insertion.cancel();
+        scrollAfterGlassPrepared(surface, destination, () => setOffset(destination));
+        pinned = maximum() - surface.scrollTop <= 1;
+        // Explicit jumps must also adopt the new baseline. Otherwise the next resize
+        // observer replays an already-visible append from the pre-jump row position.
+        insertion.reconcile(followsBottom);
+        publish();
+        return true;
+    };
+    const reconcile = () => {
+        if (disposed || surface.clientHeight === 0)
+            return;
+        // React layout effects can reconcile before MutationObserver's microtask.
+        // Consume queued replacements before adopting their new geometry baseline.
+        const records = mutations.takeRecords();
+        if (records.length)
+            onMutations(records);
+        // A native scroll can precede delivery of its scroll event. A token mutation
+        // in that interval must adopt the live offset instead of pulling the reader
+        // back to the old bottom. Only browser clamping after shrink is not intent.
+        if (surface.scrollTop !== lastOffset) {
+            const clamped = lastOffset > maximum() && Math.abs(surface.scrollTop - maximum()) <= 1;
+            if (!clamped) {
+                insertion.cancel();
+                pinned = maximum() - surface.scrollTop <= 1;
+                pending = undefined;
+                publish();
+            }
+        }
+        if (surface.scrollTop < 0 || surface.scrollTop > maximum())
+            return;
+        const binding = options().scrollPosition;
+        if (binding && binding.id !== requested) {
+            requested = binding.id;
+            if (binding.id !== null && binding.id !== reported)
+                pending = { id: binding.id, anchor: binding.anchor };
+            if (binding.id === null || binding.id === reported)
+                pending = undefined;
+        }
+        if (pending && targets.has(pending.id)) {
+            scrollTo(pending.id, pending.anchor);
+            return;
+        }
+        if (options().defaultScrollAnchor === 'bottom' && pinned && !touching)
+            setOffset(maximum());
+        else if (options().maintainVisibleContentPosition && anchor) {
+            const target = targets.get(anchor.id);
+            if (target)
+                setOffset(surface.scrollTop + top(target) - anchor.top);
+        }
+        insertion.reconcile(options().defaultScrollAnchor === 'bottom' && pinned && !touching, pending?.anchor === 'bottom');
+        publish();
+    };
+    const onScroll = () => {
+        // Resize/clamping can emit a scroll event before ResizeObserver. Preserve the
+        // previous reading anchor until layout reconciliation has run.
+        if (surface.scrollHeight !== lastHeight || surface.clientHeight !== lastViewport) {
+            reconcile();
+            return;
+        }
+        if (surface.scrollTop !== lastOffset) {
+            insertion.cancel();
+            pinned = maximum() - surface.scrollTop <= 1;
+            pending = undefined;
+        }
+        publish();
+    };
+    const stopInsertionForInput = () => {
+        const travel = insertion.offset();
+        if (travel === 0)
+            return;
+        const shown = surface.scrollTop - travel;
+        insertion.cancel();
+        setOffset(shown);
+        pinned = maximum() - surface.scrollTop <= 1;
+        publish();
+    };
+    const onPointerDown = () => {
+        stopInsertionForInput();
+        touching = true;
+        pending = undefined;
+    };
+    const onPointerUp = () => {
+        touching = false;
+    };
+    const onWheel = () => {
+        stopInsertionForInput();
+        pending = undefined;
+    };
+    // Inset publication can follow this surface's ResizeObserver in the same
+    // delivery. Reconcile now so the new padding and its anchor paint together.
+    surface.addEventListener(BOTTOM_INSET_CHANGED, reconcile);
+    surface.addEventListener('scroll', onScroll, { passive: true });
+    surface.addEventListener('pointerdown', onPointerDown, { passive: true });
+    window.addEventListener('pointerup', onPointerUp, { passive: true });
+    window.addEventListener('pointercancel', onPointerUp, { passive: true });
+    surface.addEventListener('wheel', onWheel, { passive: true });
+    const resize = new ResizeObserver(reconcile);
+    resize.observe(surface);
+    resize.observe(content);
+    const observedTargets = new Set();
+    const observeTargets = () => {
+        const current = new Set(targets.values());
+        for (const element of observedTargets) {
+            if (!current.has(element)) {
+                resize.unobserve(element);
+                observedTargets.delete(element);
+            }
+        }
+        for (const element of current) {
+            if (!observedTargets.has(element)) {
+                resize.observe(element);
+                observedTargets.add(element);
+            }
+        }
+    };
+    observeTargets();
+    const onMutations = (records) => {
+        insertion.contentChanged(records);
+        // Text delivery happens before layout. A token that does not resize a row
+        // cannot move any normal-flow target. Changed target sizes are delivered by
+        // ResizeObserver after layout, including offsetting grow/shrink pairs whose
+        // total content height stays unchanged.
+        if (!records.some(record => [...record.addedNodes, ...record.removedNodes].some(node => node.nodeType === Node.ELEMENT_NODE)))
+            return;
+        dirty = true;
+        // Structural reordering can change positions without changing any sizes.
+        if (!mutationFrame)
+            mutationFrame = requestAnimationFrame(() => {
+                mutationFrame = 0;
+                observeTargets();
+                reconcile();
+            });
+    };
+    const mutations = new MutationObserver(onMutations);
+    mutations.observe(content, { childList: true, subtree: true });
+    reconcile();
+    return {
+        reconcile,
+        scrollTo,
+        adoptRestoredOffset() {
+            insertion.cancel();
+            pinned = maximum() - surface.scrollTop <= 1;
+            pending = undefined;
+            publish();
+        },
+        targetsChanged() {
+            dirty = true;
+        },
+        dispose() {
+            disposed = true;
+            insertion.cancel();
+            cancelAnimationFrame(mutationFrame);
+            resize.disconnect();
+            mutations.disconnect();
+            surface.removeEventListener(BOTTOM_INSET_CHANGED, reconcile);
+            surface.removeEventListener('scroll', onScroll);
+            surface.removeEventListener('pointerdown', onPointerDown);
+            window.removeEventListener('pointerup', onPointerUp);
+            window.removeEventListener('pointercancel', onPointerUp);
+            surface.removeEventListener('wheel', onWheel);
+        },
+    };
+}

package/dist/scroll/pressOwnership.d.ts

@@ -0,0 +1,4 @@
+import type { ScrollAxis } from './types.js';
+export declare const SCROLL_PRESS_SLOP_PX = 10;
+/** Observe native pan intent without capturing, preventing, or emulating scroll. */
+export declare function installScrollPressOwnership(element: HTMLElement, axis: ScrollAxis): () => void;

package/dist/scroll/pressOwnership.js

@@ -0,0 +1,65 @@
+import { cancelOnNativeScroll } from './nativeScroll.js';
+import { armPointerClickSuppression } from '../press/activation.js';
+import { cancelPointerPressForOwnedGesture } from '../press/gestureArbitration.js';
+// Native Settings, iOS 26.5: 9 pt out-and-back selects; 10 pt cancels.
+// This is a scroll recognizer threshold, not the plain button retention region.
+export const SCROLL_PRESS_SLOP_PX = 10;
+/** Observe native pan intent without capturing, preventing, or emulating scroll. */
+export function installScrollPressOwnership(element, axis) {
+    const contacts = new Map();
+    const cancel = (id, contact) => {
+        if (contact.cancelled)
+            return;
+        contact.cancelled = true;
+        cancelPointerPressForOwnedGesture(id);
+    };
+    const down = (event) => {
+        if (event.pointerType === 'mouse')
+            return;
+        contacts.set(event.pointerId, { x: event.clientX, y: event.clientY, cancelled: false });
+    };
+    const move = (event) => {
+        const contact = contacts.get(event.pointerId);
+        if (!contact)
+            return;
+        const x = Math.abs(event.clientX - contact.x), y = Math.abs(event.clientY - contact.y);
+        const along = axis === 'vertical' ? y : x, across = axis === 'vertical' ? x : y;
+        if (along >= SCROLL_PRESS_SLOP_PX && along >= across)
+            cancel(event.pointerId, contact);
+    };
+    const up = (event) => {
+        // The final sample can cross the threshold without an intervening move.
+        move(event);
+        if (contacts.get(event.pointerId)?.cancelled) {
+            // Refresh at UP: a user can hold a cancelled pan longer than the receipt.
+            armPointerClickSuppression(performance.now());
+        }
+        contacts.delete(event.pointerId);
+    };
+    const cancelled = (event) => {
+        const contact = contacts.get(event.pointerId);
+        if (contact)
+            cancel(event.pointerId, contact);
+        contacts.delete(event.pointerId);
+    };
+    const scroll = () => {
+        for (const [id, contact] of contacts)
+            cancel(id, contact);
+    };
+    const options = { capture: true, passive: true };
+    element.addEventListener('pointerdown', down, options);
+    element.addEventListener('pointermove', move, options);
+    element.addEventListener('pointerup', up, options);
+    element.addEventListener('pointercancel', cancelled, options);
+    const releaseScroll = cancelOnNativeScroll(element, scroll);
+    return () => {
+        for (const [id, contact] of contacts)
+            cancel(id, contact);
+        contacts.clear();
+        element.removeEventListener('pointerdown', down, options);
+        element.removeEventListener('pointermove', move, options);
+        element.removeEventListener('pointerup', up, options);
+        element.removeEventListener('pointercancel', cancelled, options);
+        releaseScroll();
+    };
+}

package/dist/scroll/refreshMotion.d.ts

@@ -0,0 +1,9 @@
+export declare const refreshHeight = 60;
+export declare const refreshReleaseDuration = 300.171;
+export declare const refreshRelease: {
+    time: number;
+    height: number;
+}[];
+/** Preserve the old height curve when native bottom clamping consumes part of the spacer.
+ * The content stays pinned until the shrinking spacer reaches that consumed distance. */
+export declare function refreshReleaseOffset(height: number, displacement: number): number;

package/dist/scroll/refreshMotion.js

@@ -0,0 +1,15 @@
+// Native UIRefreshControl release, iPad iOS 27.0, reference native reference.
+// 19 native samples: cosine fit RMSE 0.142 pt, max 0.261 pt over 60 pt.
+// Fitting capture: skips 0.4065%, max 1, unreadable 0; source 58.696 Hz.
+// This is a measured ease, not a spring. Painted PWA acceptance is pending.
+export const refreshHeight = 60;
+export const refreshReleaseDuration = 300.171;
+export const refreshRelease = Array.from({ length: 31 }, (_, frame) => ({
+    time: (frame / 30) * refreshReleaseDuration,
+    height: (refreshHeight / 2) * (1 + Math.cos((Math.PI * frame) / 30)),
+}));
+/** Preserve the old height curve when native bottom clamping consumes part of the spacer.
+ * The content stays pinned until the shrinking spacer reaches that consumed distance. */
+export function refreshReleaseOffset(height, displacement) {
+    return Math.max(0, height - (refreshHeight - displacement));
+}

package/dist/scroll/refreshable.d.ts

@@ -0,0 +1,6 @@
+import type { TaskAction } from '../tasks/useTask.js';
+/** One awaited refresh per visible scroll surface, cancelled with its owner. */
+export declare function useRefreshAction(action: TaskAction | undefined, active: boolean): {
+    running: boolean;
+    run: () => void;
+};

package/dist/scroll/refreshable.js

@@ -0,0 +1,50 @@
+import { useCallback, useLayoutEffect, useRef, useState } from 'react';
+/** One awaited refresh per visible scroll surface, cancelled with its owner. */
+export function useRefreshAction(action, active) {
+    const actionRef = useRef(action);
+    const current = useRef(null);
+    const [running, setRunning] = useState(false);
+    const [failure, setFailure] = useState(null);
+    useLayoutEffect(() => {
+        actionRef.current = action;
+    });
+    const enabled = action !== undefined && active;
+    useLayoutEffect(() => {
+        if (!enabled)
+            setRunning(false);
+        return () => {
+            current.current?.abort();
+            current.current = null;
+        };
+    }, [enabled]);
+    const run = useCallback(() => {
+        if (!enabled || current.current || !actionRef.current)
+            return;
+        const controller = new AbortController();
+        current.current = controller;
+        setRunning(true);
+        const commit = update => {
+            if (controller.signal.aborted || current.current !== controller)
+                return false;
+            update();
+            return true;
+        };
+        const complete = (error) => {
+            if (current.current !== controller || controller.signal.aborted)
+                return;
+            current.current = null;
+            setRunning(false);
+            if (error)
+                setFailure(error);
+        };
+        try {
+            void Promise.resolve(actionRef.current(controller.signal, commit)).then(() => complete(), error => complete({ error }));
+        }
+        catch (error) {
+            complete({ error });
+        }
+    }, [enabled]);
+    if (failure)
+        throw failure.error;
+    return { running, run };
+}

package/dist/scroll/registry.d.ts

@@ -0,0 +1,38 @@
+import type { ScrollAxis, ScrollOffset, ScrollSnapshot } from './types.js';
+export type ScrollSurfaceNode = Pick<HTMLDivElement, 'scrollLeft' | 'scrollTo' | 'scrollTop'> & Partial<Pick<HTMLDivElement, 'scrollWidth' | 'scrollHeight' | 'clientWidth' | 'clientHeight'>>;
+export type ScrollSurfaceRegistration = Readonly<{
+    axis: ScrollAxis;
+    element: ScrollSurfaceNode;
+    id: string;
+    initialOffset?: () => ScrollOffset;
+    onRestore?: () => void;
+    /** `true` claims the screen; `'automatic'` is a candidate (the first in document order wins). */
+    primary: boolean | 'automatic';
+}>;
+export type ScrollRestorationResult = Readonly<{
+    id: string;
+    live: ScrollOffset;
+    matches: boolean;
+    snapshot: ScrollOffset;
+}>;
+export interface ScrollSurfaceRegistry {
+    subscribe(listener: () => void): () => void;
+    cancelRestoration(id: string): void;
+    capture(options?: Readonly<{
+        preservePending?: boolean;
+    }>): ScrollSnapshot;
+    get(id: string): ScrollSurfaceRegistration | undefined;
+    getPrimary(): ScrollSurfaceRegistration | undefined;
+    register(registration: ScrollSurfaceRegistration): () => void;
+    reset(): void;
+    restore(snapshot: ScrollSnapshot, options?: Readonly<{
+        warnOnMismatch?: boolean;
+    }>): readonly ScrollRestorationResult[];
+    setUncovered(uncovered: boolean): void;
+}
+export type CreateScrollSurfaceRegistryOptions = Readonly<{
+    development?: boolean;
+    screenKey?: string;
+}>;
+export declare function readScrollOffset(element: ScrollSurfaceNode): ScrollOffset;
+export declare function createScrollSurfaceRegistry(options?: CreateScrollSurfaceRegistryOptions): ScrollSurfaceRegistry;