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

package/dist/navigation/toolbarGlassMotion.d.ts

@@ -0,0 +1,40 @@
+import { type ShapeFrame } from '../glass/shapeTrack.js';
+import { type GlassShape } from '../glass/regions.js';
+type Knot = Readonly<{
+    offset: number;
+    value: number;
+}>;
+/** Chrome uses linear, explicitly offset keyframes. Keep their original knots, including
+ * interrupted opacity origins, rather than restarting a measured curve when glass mounts. */
+export declare function toolbarTrackValue(knots: readonly Knot[], progress: number): number;
+export declare function toolbarShapeFrames(from: ShapeFrame, to: ShapeFrame, opacity: readonly Knot[], duration: number, morph: boolean, padding: number, scale?: readonly Knot[]): {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}[];
+/** One toolbar capsule's delivery of the existing chrome animation. Its canvas keeps a fixed
+ * envelope so resizing glass never stretches the backdrop. The worker samples the aperture;
+ * WAAPI carries opacity and blur on the chrome animation's document timeline. */
+export declare class ToolbarGlassMotion {
+    private source?;
+    private fade?;
+    private signature;
+    private travelFrame?;
+    private owner;
+    constructor(owner: HTMLElement);
+    update(input: {
+        slot: HTMLElement | undefined;
+        content: HTMLElement;
+        from: ShapeFrame;
+        to: ShapeFrame;
+        morph: boolean;
+        padding: number;
+        hidden: boolean;
+        shape?: GlassShape;
+        fromRadius?: number;
+        toRadius?: number;
+    }): boolean;
+    clear(): void;
+}
+export {};

package/dist/navigation/toolbarGlassMotion.js

@@ -0,0 +1,202 @@
+import { animateElement, timelineStart } from '../motion/animate.js';
+import { shapeTrackEnvelope, shapeTrackFrame, shapeTrackRadius, } from '../glass/shapeTrack.js';
+import { setGlassShapeTrack } from '../glass/shapeTrackRegistry.js';
+import { toolbarMotionAnimation } from './toolbarMotionOwner.js';
+import { glassRadius } from '../glass/regions.js';
+import { sampleNavigationCurve } from './motionTokens.js';
+/** Chrome uses linear, explicitly offset keyframes. Keep their original knots, including
+ * interrupted opacity origins, rather than restarting a measured curve when glass mounts. */
+export function toolbarTrackValue(knots, progress) {
+    const next = knots.findIndex(knot => knot.offset >= progress);
+    if (next === 0)
+        return knots[0].value;
+    if (next < 0)
+        return knots.at(-1).value;
+    const from = knots[next - 1];
+    const to = knots[next];
+    const mix = (progress - from.offset) / (to.offset - from.offset);
+    return from.value + (to.value - from.value) * mix;
+}
+export function toolbarShapeFrames(from, to, opacity, duration, morph, padding, scale) {
+    // Native chrome knots use integer milliseconds. Sampling each millisecond retains those
+    // corners exactly; the worker still presents at its existing, at-most-60-Hz cadence.
+    const count = Math.ceil(duration);
+    return Array.from({ length: count + 1 }, (_, index) => {
+        const progress = index / count;
+        const mix = toolbarTrackValue(opacity, progress);
+        if (morph)
+            return {
+                x: from.x + (to.x - from.x) * mix,
+                y: from.y + (to.y - from.y) * mix,
+                width: from.width + (to.width - from.width) * mix,
+                height: from.height + (to.height - from.height) * mix,
+            };
+        const size = scale ? toolbarTrackValue(scale, progress) : 1;
+        const width = (to.width - 2 * padding) * size + 2 * padding;
+        const height = (to.height - 2 * padding) * size + 2 * padding;
+        return {
+            x: to.x + (to.width - width) / 2,
+            y: to.y + (to.height - height) / 2,
+            width,
+            height,
+        };
+    });
+}
+function chromeAnimation(element, property) {
+    return toolbarMotionAnimation(element, property);
+}
+/** Principal travel is the page's pixel translation, with its original easing. */
+function translation(animation, progress) {
+    const easing = animation.effect.getTiming().easing;
+    const position = easing && easing !== 'linear' ? sampleNavigationCurve(progress) : progress;
+    const frames = animation.effect.getKeyframes();
+    const values = frames.map(frame => {
+        const matrix = new DOMMatrixReadOnly(String(frame.transform));
+        return { offset: frame.computedOffset, x: matrix.m41, y: matrix.m42 };
+    });
+    return {
+        x: toolbarTrackValue(values.map(frame => ({ offset: frame.offset, value: frame.x })), position),
+        y: toolbarTrackValue(values.map(frame => ({ offset: frame.offset, value: frame.y })), position),
+    };
+}
+function knots(animation, property) {
+    return animation.effect.getKeyframes().map(frame => ({
+        offset: frame.computedOffset,
+        value: frame[property] === 'none' ? 1 : Number(frame[property]),
+    }));
+}
+/** One toolbar capsule's delivery of the existing chrome animation. Its canvas keeps a fixed
+ * envelope so resizing glass never stretches the backdrop. The worker samples the aperture;
+ * WAAPI carries opacity and blur on the chrome animation's document timeline. */
+export class ToolbarGlassMotion {
+    source;
+    fade;
+    signature = '';
+    travelFrame;
+    owner;
+    constructor(owner) {
+        this.owner = owner;
+    }
+    update(input) {
+        const opacitySource = chromeAnimation(input.slot, 'opacity');
+        const travel = !opacitySource && chromeAnimation(input.slot, 'transform');
+        const source = opacitySource || travel;
+        if (!source || source.playState === 'idle') {
+            this.clear();
+            return false;
+        }
+        const timing = source.effect.getTiming();
+        const duration = Number(timing.duration);
+        if (!(duration > 0) || source.playbackRate !== 1) {
+            this.clear();
+            return false;
+        }
+        const scale = chromeAnimation(input.content, 'scale');
+        // Rect reads of compositor-scaled ancestors can differ at floating-point precision.
+        // They must not restart a run whose endpoints are otherwise unchanged.
+        const stable = (frame) => ({
+            x: Math.round(frame.x * 10000) / 10000,
+            y: Math.round(frame.y * 10000) / 10000,
+            width: Math.round(frame.width * 10000) / 10000,
+            height: Math.round(frame.height * 10000) / 10000,
+        });
+        const displacement = travel
+            ? translation(travel, Math.max(0, Math.min(1, Number(travel.currentTime ?? 0) / duration)))
+            : { x: 0, y: 0 };
+        const to = travel &&
+            source === this.source &&
+            this.travelFrame &&
+            this.travelFrame.width === input.to.width &&
+            this.travelFrame.height === input.to.height
+            ? this.travelFrame
+            : stable({ ...input.to, x: input.to.x - displacement.x, y: input.to.y - displacement.y });
+        const from = stable(input.morph && !travel ? input.from : to);
+        const signature = JSON.stringify([
+            from,
+            to,
+            input.morph,
+            input.padding,
+            input.hidden,
+            source.startTime,
+            source.playState === 'paused',
+            input.morph ? undefined : input.shape,
+            input.morph ? input.fromRadius : undefined,
+            input.morph ? input.toRadius : undefined,
+        ]);
+        if (source === this.source && signature === this.signature)
+            return true;
+        this.clear();
+        this.source = source;
+        this.travelFrame = travel ? to : undefined;
+        this.signature = signature;
+        const opacity = opacitySource
+            ? knots(opacitySource, 'opacity')
+            : [
+                { offset: 0, value: 1 },
+                { offset: 1, value: 1 },
+            ];
+        const frames = travel
+            ? Array.from({ length: Math.ceil(duration) + 1 }, (_, index) => {
+                const offset = translation(travel, index / Math.ceil(duration));
+                return { ...to, x: to.x + offset.x, y: to.y + offset.y };
+            })
+            : toolbarShapeFrames(from, to, opacity, duration, input.morph, input.padding, scale ? knots(scale, 'scale') : undefined);
+        const envelope = shapeTrackEnvelope(frames);
+        const radii = frames.map((frame, index) => input.morph && !travel
+            ? (input.fromRadius ?? glassRadius(input.shape ?? 'capsule', from.width, from.height)) +
+                ((input.toRadius ?? glassRadius(input.shape ?? 'capsule', to.width, to.height)) -
+                    (input.fromRadius ?? glassRadius(input.shape ?? 'capsule', from.width, from.height))) *
+                    toolbarTrackValue(opacity, index / (frames.length - 1))
+            : glassRadius(input.shape ?? 'capsule', frame.width, frame.height));
+        Object.assign(this.owner.style, {
+            left: `${envelope.x}px`,
+            top: `${envelope.y}px`,
+            width: `${envelope.width}px`,
+            height: `${envelope.height}px`,
+            opacity: input.hidden ? '0' : '1',
+            filter: '',
+        });
+        const held = source.startTime === null || source.playState === 'paused';
+        const at = Number(source.currentTime ?? 0);
+        // A paused preparation has not begun. Keep its sampled aperture until the original
+        // chrome starts; no independent performance.now() epoch can race that admission.
+        const samples = { epoch: 0, duration, frames, radii };
+        const sampled = held ? [shapeTrackFrame(samples, at)] : frames;
+        setGlassShapeTrack(this.owner, {
+            epoch: held
+                ? Number.MAX_VALUE
+                : performance.timeOrigin + Number(source.startTime) - timelineStart(0),
+            duration,
+            frames: sampled.map(frame => ({
+                ...frame,
+                x: frame.x - envelope.x,
+                y: frame.y - envelope.y,
+            })),
+            radii: held ? [shapeTrackRadius(samples, at, 0)] : radii,
+        });
+        if (opacitySource && !input.morph && !input.hidden) {
+            this.fade = animateElement(this.owner, source.effect.getKeyframes().map(frame => ({
+                offset: frame.computedOffset,
+                opacity: frame.opacity,
+                filter: frame.filter,
+            })), { duration, easing: 'linear', fill: 'both' });
+            if (held) {
+                this.fade.pause();
+                this.fade.currentTime = at;
+            }
+            else
+                this.fade.startTime = source.startTime;
+        }
+        return true;
+    }
+    clear() {
+        if (!this.source)
+            return;
+        this.fade?.cancel();
+        this.fade = undefined;
+        this.source = undefined;
+        this.travelFrame = undefined;
+        this.signature = '';
+        setGlassShapeTrack(this.owner, undefined);
+    }
+}

package/dist/navigation/toolbarMinimization.d.ts

@@ -0,0 +1,9 @@
+/** `ToolbarMinimizationBehavior`: when a toolbar may minimize. */
+export type ToolbarMinimizationBehavior = 'onScrollDown' | 'onScrollUp' | 'never';
+/** The interaction that restores a minimized toolbar. */
+export type ToolbarMinimizationRestoration = 'automatic' | 'atScrollEdge';
+/** Whether toolbar minimization changes its reserved content inset. */
+export type ToolbarMinimizationSafeAreaAdjustment = 'automatic' | 'enabled' | 'disabled';
+export declare function nextToolbarMinimization(minimized: boolean, previousOffset: number, offset: number, behavior: ToolbarMinimizationBehavior, restoration?: ToolbarMinimizationRestoration): boolean;
+/** Bind only an elected primary. Compensate released inset so its content does not jump. */
+export declare function observeToolbarMinimization(scroller: HTMLElement, behavior: ToolbarMinimizationBehavior, restoration: ToolbarMinimizationRestoration | undefined, adjustment: ToolbarMinimizationSafeAreaAdjustment | undefined): () => void;

package/dist/navigation/toolbarMinimization.js

@@ -0,0 +1,76 @@
+/* Settled policy from the iOS 27 music-scroll native reference. Motion fitting remains pending. */
+export function nextToolbarMinimization(minimized, previousOffset, offset, behavior, restoration = 'automatic') {
+    if (behavior === 'never' || offset <= 0)
+        return false;
+    const direction = offset - previousOffset;
+    if (direction === 0)
+        return minimized;
+    const minimizing = behavior === 'onScrollDown' ? direction > 0 : direction < 0;
+    if (minimizing)
+        return true;
+    return restoration === 'atScrollEdge' ? minimized : false;
+}
+/** Bind only an elected primary. Compensate released inset so its content does not jump. */
+export function observeToolbarMinimization(scroller, behavior, restoration, adjustment) {
+    let previousOffset = Math.max(0, scroller.scrollTop);
+    let minimized = false;
+    let collapsed = false;
+    let minimumOffset = 0;
+    const notify = () => scroller.dispatchEvent(new CustomEvent('satin:toolbar-minimization', { bubbles: true }));
+    const update = () => {
+        const offset = Math.max(0, scroller.scrollTop);
+        // Rubber-band movement is not a direction reversal in the content.
+        if (scroller.scrollTop < 0)
+            return;
+        const next = nextToolbarMinimization(minimized, previousOffset, offset, behavior, restoration);
+        if (next && !minimized && offset <= minimumOffset) {
+            previousOffset = offset;
+            return;
+        }
+        const nextCollapsed = offset > 0 && (collapsed || next);
+        previousOffset = offset;
+        if (next === minimized && nextCollapsed === collapsed)
+            return;
+        // A generated large title is part of the released inset too. Anchor ordinary content,
+        // not padding alone, so removing that row does not add a second scroll displacement.
+        const content = scroller.querySelector(':scope > [data-satin-scroll-content]') ?? scroller;
+        const anchor = content.querySelector(':scope > :not([data-satin-scroll-title]):not([data-satin-list-title]):not([data-satin-refresh])');
+        const oldOrigin = anchor?.getBoundingClientRect().top ?? parseFloat(getComputedStyle(scroller).paddingTop);
+        const previousMinimized = minimized;
+        const previousCollapsed = collapsed;
+        minimized = next;
+        collapsed = nextCollapsed;
+        scroller.dataset.satinToolbarMinimized = String(minimized);
+        scroller.dataset.satinToolbarCollapsed = String(collapsed);
+        scroller.dataset.satinToolbarInsetAdjustment =
+            adjustment === 'disabled' ? 'disabled' : 'enabled';
+        const newOrigin = anchor?.getBoundingClientRect().top ?? parseFloat(getComputedStyle(scroller).paddingTop);
+        const displacement = newOrigin - oldOrigin;
+        if (next && !previousMinimized && offset + displacement <= 0) {
+            // WebKit cannot hold a negative scroll offset. Wait until the released row can fit
+            // without clamping content back to the top. Native's partial motion is still debt.
+            minimumOffset = Math.max(0, -displacement);
+            minimized = previousMinimized;
+            collapsed = previousCollapsed;
+            scroller.dataset.satinToolbarMinimized = String(minimized);
+            scroller.dataset.satinToolbarCollapsed = String(collapsed);
+            return;
+        }
+        if (!minimized)
+            minimumOffset = 0;
+        // At the top, retain offset zero so the large title returns. Else keep the visible content anchored.
+        if (offset > 0 && Number.isFinite(oldOrigin) && Number.isFinite(newOrigin)) {
+            scroller.scrollTop = Math.max(0, offset + displacement);
+            previousOffset = Math.max(0, scroller.scrollTop);
+        }
+        notify();
+    };
+    scroller.addEventListener('scroll', update, { passive: true });
+    return () => {
+        scroller.removeEventListener('scroll', update);
+        delete scroller.dataset.satinToolbarMinimized;
+        delete scroller.dataset.satinToolbarCollapsed;
+        delete scroller.dataset.satinToolbarInsetAdjustment;
+        notify();
+    };
+}

package/dist/navigation/toolbarMotionOwner.d.ts

@@ -0,0 +1,6 @@
+/** The actual navigation animation owns timing, including paused preparation and tails. */
+type Property = 'opacity' | 'scale' | 'transform';
+export declare function toolbarMotionAnimation(element: HTMLElement | undefined, property: Property): Animation | undefined;
+export declare function announceToolbarMotion(element: Element): void;
+export declare function registerToolbarMotion(element: HTMLElement, property: Property, animation: Animation): void;
+export {};

package/dist/navigation/toolbarMotionOwner.js

@@ -0,0 +1,30 @@
+const tracks = new WeakMap();
+export function toolbarMotionAnimation(element, property) {
+    return element ? tracks.get(element)?.get(property) : undefined;
+}
+export function announceToolbarMotion(element) {
+    element.dispatchEvent?.(new Event('satin-toolbar-material', { bubbles: true }));
+}
+export function registerToolbarMotion(element, property, animation) {
+    let owned = tracks.get(element);
+    if (!owned) {
+        owned = new Map();
+        tracks.set(element, owned);
+    }
+    owned.set(property, animation);
+    const notify = () => {
+        if (owned.get(property) === animation)
+            announceToolbarMotion(element);
+    };
+    const retire = () => {
+        if (owned.get(property) !== animation)
+            return;
+        owned.delete(property);
+        announceToolbarMotion(element);
+    };
+    void animation.ready?.then(notify, () => { });
+    // Finished fill owns the endpoint until navigation cancels or replaces it.
+    animation.addEventListener?.('finish', notify);
+    animation.addEventListener?.('cancel', retire, { once: true });
+    notify();
+}

package/dist/navigation/touchArbitration.d.ts

@@ -0,0 +1,34 @@
+import type { RefObject } from 'react';
+import type { AxisLayoutClass } from '../layout/layoutClass.js';
+import { type InteractivePopGesture } from './interactivePop.js';
+import { type EarlyTouchArbitration, type InteractivePopDiagnostic, type InteractiveTransitionController, type NavigatorHostGeometry, type ScrubDiagnosticState } from './interactivePopTypes.js';
+import type { ScreenRegistry } from './registry.js';
+import type { InteractiveScrubFrameLoop } from './scrubFrameLoop.js';
+import { type NavigatorStore } from './store.js';
+/** What the navigator host's touch arbitration reads when its listeners are bound. */
+export type TouchArbitrationContext = {
+    navigator: NavigatorStore<ScreenRegistry>;
+    nativeNavigation: boolean;
+    automaticPushActive: boolean;
+    split: boolean;
+    horizontal: AxisLayoutClass;
+    appliedHorizontal: AxisLayoutClass;
+    onInteractivePopDiagnostic: ((diagnostic: InteractivePopDiagnostic) => void) | undefined;
+    startScrubFrameLoop: (controller: InteractiveTransitionController, diagnosticState: ScrubDiagnosticState) => InteractiveScrubFrameLoop;
+    hostGeometryRef: RefObject<NavigatorHostGeometry | undefined>;
+    earlyTouchArbitrationRef: RefObject<EarlyTouchArbitration | undefined>;
+    earlyTouchControllerRef: RefObject<InteractiveTransitionController | undefined>;
+    scrubFrameLoopRef: RefObject<InteractiveScrubFrameLoop | undefined>;
+    scrubDiagnosticStateRef: RefObject<ScrubDiagnosticState | undefined>;
+    gestureRef: RefObject<InteractivePopGesture | undefined>;
+    interactiveControllerRef: RefObject<InteractiveTransitionController | undefined>;
+    nativeSourceRef: RefObject<HTMLDivElement | null>;
+};
+/** Touch arbitration for the interactive pop: a contact is tracked from touch-down, claimed on a
+ * horizontal direction lock, recognized past the intent distance (acquiring the pop), scrubbed by
+ * the private ScrollTimeline source or a frame loop, and released on touchend/touchcancel.
+ * Returns the listeners' cleanup. */
+export declare function bindTouchArbitration(host: HTMLDivElement, context: TouchArbitrationContext): {
+    dispose: () => void;
+    releaseClaim: () => void;
+};