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

package/dist/navigation/ScreenContainer.js

@@ -0,0 +1,219 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { ExpandedNavigationTitle } from './NavigationTitleSlots.js';
+import { ContentAdmission } from '../image/ContentAdmission.js';
+import { useContext, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore, } from 'react';
+import { RestoredScreenMountContext } from '../public/presentationContext.js';
+import { hasFocusedTab, navigatorFocusRuntime } from '../focus/navigationFocus.js';
+import { recordMotionPreparation } from '../motionProbe.js';
+import { useScreenNavigation, useScreenChrome, ScreenChromeContext } from '../public/chrome.js';
+import { createScrollSurfaceRegistry } from '../scroll/registry.js';
+import { installScrollIndicator } from '../scroll/scrollIndicator.js';
+import { TabActivityContext } from '../tabs/context.js';
+import { ScreenContext, SystemScrollRegistryContext } from './navigationContext.js';
+import { DismissContext } from '../presentation/dismiss.js';
+import { EditModeScope } from '../list-form/editing.js';
+import { shouldRestoreOnUncover } from './stack.js';
+import { navigatorRestoredMounts, navigatorScrollRuntime, } from './store.js';
+import { TransitionEdge } from './TransitionEdge.js';
+import { transitionParticipants } from './transitionBindings.js';
+/** Painted ownership follows the same primary/rear groups as transition
+ * bindings, not a contiguous stack floor. In particular, popToRoot must not
+ * reveal every intermediate retained screen. Root remains warm by contract. */
+export function renderedScreenIndices(entries) {
+    const painted = new Set();
+    if (!entries.length)
+        return painted;
+    painted.add(0);
+    painted.add(entries.length - 1);
+    const participants = transitionParticipants(entries);
+    if (!participants.length && entries.length > 1)
+        painted.add(entries.length - 2);
+    for (const { primaryIndex, secondaryIndex } of participants) {
+        painted.add(primaryIndex);
+        painted.add(secondaryIndex);
+    }
+    return painted;
+}
+/** Only the next back-swipe pair stays composited at rest. Active transitions may reach deeper. */
+export function compositedScreenIndices(entries) {
+    const composited = new Set();
+    if (!entries.length)
+        return composited;
+    composited.add(entries.length - 1);
+    if (entries.length > 1)
+        composited.add(entries.length - 2);
+    for (const { primaryIndex, secondaryIndex } of transitionParticipants(entries)) {
+        composited.add(primaryIndex);
+        composited.add(secondaryIndex);
+    }
+    return composited;
+}
+export function ScreenContainer({ children, entry, interactionBlocked = false, contentFirst = false, isCovered, navigator, renderSuspended = false, prepareMotion = false, screenRef, ...props }) {
+    const [restoring, setRestoring] = useState(() => navigator[navigatorRestoredMounts].has(entry.key));
+    useLayoutEffect(() => {
+        navigator[navigatorRestoredMounts].delete(entry.key);
+        setRestoring(false);
+    }, [navigator, entry.key]);
+    const tabActive = useContext(TabActivityContext);
+    const scrollRegistry = useMemo(() => createScrollSurfaceRegistry({ screenKey: entry.key }), [entry.key]);
+    const hasPrimaryScroll = useSyncExternalStore(scrollRegistry.subscribe, () => Boolean(scrollRegistry.getPrimary()), () => false);
+    const focusScope = useRef(null);
+    const definition = navigator.registry.resolve(entry.screenId);
+    const chrome = useScreenChrome();
+    const chromeStore = useContext(ScreenChromeContext);
+    const screenNavigation = useScreenNavigation();
+    const entryIndex = navigator
+        .getState()
+        .entries.findIndex(candidate => candidate.key === entry.key);
+    const navigation = screenNavigation(definition?.navigation, chrome?.get(entry.key), entry.params, entryIndex);
+    const routeTitle = navigation?.title;
+    const title = typeof routeTitle === 'function' ? routeTitle(entry.params) : (routeTitle ?? entry.screenId);
+    const wasTabActive = useRef(tabActive);
+    useLayoutEffect(() => {
+        const element = focusScope.current;
+        if (!element)
+            return;
+        const runtime = navigator[navigatorFocusRuntime];
+        const unbind = runtime.bind(entry.key, {
+            element,
+            title,
+            contentFirst,
+            chromeExpected: !!navigation && navigation.display !== 'none',
+        });
+        const capture = () => runtime.capture([entry.key]);
+        const panel = element.closest('[data-satin-tab-panel]');
+        const activate = (event) => {
+            if (event instanceof CustomEvent && event.detail?.focus === false)
+                return;
+            if (hasFocusedTab(element.ownerDocument))
+                return;
+            if (element.dataset.satinCovered === 'true')
+                return;
+            runtime.request(entry.key, 'dismiss');
+            runtime.flush(navigator.getState(), entry.key, true);
+        };
+        element.addEventListener('focusin', capture);
+        panel?.addEventListener('satin:tab-activate', activate);
+        return () => {
+            unbind();
+            element.removeEventListener('focusin', capture);
+            panel?.removeEventListener('satin:tab-activate', activate);
+        };
+    }, [entry.key, navigator, title, contentFirst, navigation?.display]);
+    useLayoutEffect(() => {
+        if (!wasTabActive.current && tabActive && !isCovered && !hasFocusedTab(document))
+            navigator[navigatorFocusRuntime].request(entry.key, 'dismiss');
+        wasTabActive.current = tabActive;
+        navigator[navigatorFocusRuntime].flush(navigator.getState(), entry.key, tabActive && !isCovered && !interactionBlocked);
+    });
+    const previousCovered = useRef(undefined);
+    const previousSuspended = useRef(renderSuspended);
+    useLayoutEffect(() => {
+        if (previousSuspended.current !== renderSuspended)
+            recordMotionPreparation(() => ({
+                kind: renderSuspended ? 'screen-render-suspended' : 'screen-render-resumed',
+                at: performance.now(),
+                key: entry.key,
+                phase: entry.transition.phase,
+                covered: isCovered,
+            }));
+        previousSuspended.current = renderSuspended;
+    }, [entry.key, entry.transition.phase, isCovered, renderSuspended]);
+    const screen = useMemo(() => ({
+        key: entry.key,
+        lifecycle: {
+            isCovered: isCovered || !tabActive,
+            phase: entry.transition.phase,
+        },
+        params: entry.params,
+        scrollRegistry,
+    }), [entry.key, entry.params, entry.transition.phase, isCovered, scrollRegistry, tabActive]);
+    useLayoutEffect(() => navigator[navigatorScrollRuntime].bind(entry.key, scrollRegistry), [entry.key, navigator, scrollRegistry]);
+    // Without a primary scroll view, content is laid out in the safe area below the bar, as a
+    // SwiftUI VStack is (styles.css). The attribute follows the registry in the same frame.
+    // The primary's vertical scroll indicator is drawn in the screen frame (scroll/scrollIndicator.ts).
+    const motionLayer = useRef(null);
+    const indicatorTrack = useRef(null);
+    const indicatorThumb = useRef(null);
+    useLayoutEffect(() => {
+        const element = motionLayer.current;
+        const track = indicatorTrack.current;
+        const thumb = indicatorThumb.current;
+        if (!element || !track || !thumb)
+            return;
+        let indicated;
+        let releaseIndicator;
+        // The registry also notifies on scroll; only a change touches the DOM.
+        const update = () => {
+            const primary = scrollRegistry.getPrimary();
+            const state = primary ? 'primary' : 'none';
+            if (element.dataset.satinScreenScroll !== state)
+                element.dataset.satinScreenScroll = state;
+            const scroller = primary?.axis === 'vertical' && primary.element instanceof HTMLElement
+                ? primary.element
+                : undefined;
+            if (scroller === indicated)
+                return;
+            releaseIndicator?.();
+            indicated = scroller;
+            // NavigationChrome re-binds its title collapse and scroll edge to the new primary.
+            element.dispatchEvent(new CustomEvent('satin:primary-scroll', { bubbles: true }));
+            releaseIndicator = scroller
+                ? installScrollIndicator(scroller, { frame: element, track, thumb })
+                : undefined;
+        };
+        update();
+        const unsubscribe = scrollRegistry.subscribe(update);
+        return () => {
+            unsubscribe();
+            releaseIndicator?.();
+        };
+    }, [scrollRegistry]);
+    const display = navigation?.visibility === 'hidden'
+        ? 'none'
+        : navigation
+            ? (navigation.display ?? 'inline')
+            : 'none';
+    useLayoutEffect(() => {
+        scrollRegistry.setUncovered(!isCovered);
+        return () => scrollRegistry.setUncovered(false);
+    }, [isCovered, scrollRegistry]);
+    useLayoutEffect(() => {
+        const wasCovered = previousCovered.current;
+        previousCovered.current = isCovered;
+        if (!shouldRestoreOnUncover(wasCovered, isCovered) &&
+            !(wasCovered === undefined && entry.scrollSnapshot))
+            return;
+        if (entry.scrollSnapshot) {
+            scrollRegistry.restore(entry.scrollSnapshot, {
+                warnOnMismatch: import.meta.env.DEV,
+            });
+        }
+        else {
+            scrollRegistry.reset();
+        }
+    }, [entry.scrollSnapshot, isCovered, scrollRegistry]);
+    const entries = navigator.getState().entries;
+    const index = entries.findIndex(candidate => candidate.key === entry.key);
+    const transitioning = transitionParticipants(entries).some(pair => pair.primaryIndex === index || pair.secondaryIndex === index);
+    // A pushed screen's dismissal pops it; a root screen's belongs to whatever presents its stack.
+    const outerDismiss = useContext(DismissContext);
+    const dismiss = () => {
+        const entries = navigator.getState().entries;
+        const index = entries.findIndex(candidate => candidate.key === entry.key);
+        if (index > 0 && index === entries.length - 1)
+            navigator.pop();
+        else if (index === 0)
+            outerDismiss?.();
+    };
+    return (_jsx(ScreenContext, { value: screen, children: _jsx(EditModeScope, { children: _jsx(DismissContext, { value: dismiss, children: _jsx("div", { ...props, ref: element => {
+                        focusScope.current = element;
+                        if (typeof screenRef === 'function')
+                            screenRef(element);
+                        else if (screenRef)
+                            screenRef.current = element;
+                    }, "aria-hidden": isCovered || undefined, "data-satin-covered": isCovered ? 'true' : 'false', "data-satin-interaction-blocked": interactionBlocked ? 'true' : 'false', "data-satin-presentation": entry.presentation, "data-satin-motion-prepared": prepareMotion ? 'true' : undefined, "data-satin-render-suspended": renderSuspended ? 'true' : undefined, "data-satin-screen": entry.screenId, "data-satin-screen-key": entry.key, "data-satin-screen-container": "true", style: {
+                        ['--satin-inline-title-content-height']: `${display === 'none' ? 0 : (chromeStore?.inlineTitleHeights.get(entry.key) ?? 0)}px`,
+                    }, "data-satin-transition": entry.transition.phase, inert: isCovered || interactionBlocked, children: _jsxs("div", { ref: motionLayer, "data-satin-navigation-motion-layer": "true", "data-satin-screen-title-display": display, children: [display === 'large' && !hasPrimaryScroll && (_jsx(ExpandedNavigationTitle, { entryKey: entry.key, title: title, subtitle: navigation?.subtitle, stationary: true })), transitioning &&
+                                (navigation?.display !== 'none' || navigation.visibility === 'hidden') && (_jsx(TransitionEdge, { barHidden: navigation?.visibility === 'hidden' })), _jsx(SystemScrollRegistryContext, { value: undefined, children: _jsx(RestoredScreenMountContext, { value: restoring, children: _jsx(ContentAdmission, { children: children }) }) }), _jsx("span", { "aria-hidden": "true", "data-satin-scroll-indicator-track": "true", ref: indicatorTrack, children: _jsx("span", { "data-satin-scroll-indicator-thumb": "true", ref: indicatorThumb }) }), _jsx("span", { "aria-hidden": "true", "data-satin-navigation-dim": "true" })] }) }) }) }) }));
+}

package/dist/navigation/ScrubSourceFrames.d.ts

@@ -0,0 +1,18 @@
+import type { CSSProperties, ReactNode, RefObject } from 'react';
+/** The stack host's own style while it is the sticky content of the stack's scrub source. Keep
+ * the visual pop endpoint inside the private native scroll range: at the physical boundary
+ * WebKit can briefly recommit an older timeline sample when asynchronous scrolling ends. One
+ * pane of constant effects beyond either endpoint makes that transfer independent of the pose. */
+export declare const stackScrubHostStyle: CSSProperties;
+export declare function StackScrubSource({ enabled, sourceRef, children, }: {
+    enabled: boolean;
+    sourceRef: RefObject<HTMLDivElement | null>;
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** The split layout's detail column scrub source, beside the sidebar (`left`). */
+export declare function DetailScrubSource({ enabled, sourceRef, left, children, }: {
+    enabled: boolean;
+    sourceRef: RefObject<HTMLDivElement | null>;
+    left: number;
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/navigation/ScrubSourceFrames.js

@@ -0,0 +1,67 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// The private horizontal scrollers an installed back swipe drives (nativeScrubSource.ts). Each is
+// a scroller over a track five panes wide, with its content held sticky at the track's left edge:
+// scrolling moves no content, and the page tracks follow the scroll offset through a
+// ScrollTimeline. Without native navigation every layer is `display: contents`, so the DOM keeps
+// one shape across layouts.
+const contents = { display: 'contents' };
+/** Five panes wide: a source at rest sits two panes in (clientWidth * 2), leaving two panes of
+ * travel either way (see stackScrubHostStyle). */
+const scrubTrack = { width: '500%', height: '100%' };
+/** The stack host's own style while it is the sticky content of the stack's scrub source. Keep
+ * the visual pop endpoint inside the private native scroll range: at the physical boundary
+ * WebKit can briefly recommit an older timeline sample when asynchronous scrolling ends. One
+ * pane of constant effects beyond either endpoint makes that transfer independent of the pose. */
+// A framework module, not an app file: fast refresh never reloads it on its own.
+// oxlint-disable-next-line react/only-export-components
+export const stackScrubHostStyle = {
+    position: 'sticky',
+    transform: 'translateZ(0)',
+    width: '20%',
+    left: 0,
+    top: 0,
+    right: 'auto',
+    bottom: 'auto',
+};
+export function StackScrubSource({ enabled, sourceRef, children, }) {
+    return (_jsx("div", { ref: sourceRef, "data-satin-native-scrub": enabled ? 'true' : undefined, style: enabled
+            ? {
+                position: 'absolute',
+                inset: 0,
+                // Keep the source mounted across pushes and takeovers. Retirement briefly
+                // disables overflow to stop UIKit consuming the next tap as a momentum stop.
+                // Content owns touch-action. The private source never narrows it.
+                overflowX: 'scroll',
+                overflowY: 'hidden',
+                overscrollBehaviorX: 'none',
+                scrollbarWidth: 'none',
+            }
+            : contents, children: _jsx("div", { style: enabled ? scrubTrack : contents, children: children }) }));
+}
+/** The split layout's detail column scrub source, beside the sidebar (`left`). */
+export function DetailScrubSource({ enabled, sourceRef, left, children, }) {
+    return (_jsx("div", { ref: sourceRef, "data-satin-detail-scrub": enabled ? 'true' : undefined, style: enabled
+            ? {
+                position: 'absolute',
+                left,
+                right: 0,
+                // Floating regular-width tabs reserve content inset, not pane space.
+                top: 0,
+                bottom: 0,
+                // Always a scroller; content retains its own touch-action policy.
+                overflowX: 'scroll',
+                overflowY: 'hidden',
+                overscrollBehaviorX: 'none',
+                scrollbarWidth: 'none',
+            }
+            : contents, children: _jsx("div", { style: enabled ? scrubTrack : contents, children: _jsx("div", { "data-satin-detail-content": "true", style: enabled
+                    ? {
+                        position: 'sticky',
+                        transform: 'translateZ(0)',
+                        width: '20%',
+                        height: '100%',
+                        left: 0,
+                        top: 0,
+                    }
+                    : contents, children: children }) }) }));
+}

package/dist/navigation/Sidebar.d.ts

@@ -0,0 +1,16 @@
+import { type ReactNode } from 'react';
+export type SidebarEntry = Readonly<{
+    id: string;
+    label: string;
+    icon?: ReactNode;
+    disabled?: boolean;
+}>;
+export type SidebarProps = Readonly<{
+    entries: readonly SidebarEntry[];
+    onSelect: (id: string) => void;
+    section?: string;
+    /** First enabled entry by default, false for an empty detail, or an explicit entry id. */
+    initialSelection?: 'first' | false | string;
+}>;
+/** Ordered sidebar destinations, sharing NavigatorHost's canonical detail selection. */
+export declare function Sidebar({ entries, onSelect, section, initialSelection }: SidebarProps): import("react").JSX.Element;

package/dist/navigation/Sidebar.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useContext, useLayoutEffect } from 'react';
+import { Pressable } from '../press/Pressable.js';
+import { ScrollSurface } from '../scroll/ScrollSurface.js';
+import { SplitContext } from './splitContext.js';
+import { chooseSidebarInitialEntry } from './sidebarSelection.js';
+/** Ordered sidebar destinations, sharing NavigatorHost's canonical detail selection. */
+export function Sidebar({ entries, onSelect, section, initialSelection = 'first' }) {
+    const split = useContext(SplitContext);
+    useLayoutEffect(() => {
+        if (split?.mode !== 'split' || !entries.length || !split.claimInitialSelection?.())
+            return;
+        if (split.entry || initialSelection === false)
+            return;
+        const initial = chooseSidebarInitialEntry(entries, initialSelection);
+        if (initial)
+            onSelect(initial.id);
+    }, [entries, initialSelection, onSelect, split]);
+    return (_jsxs(ScrollSurface, { id: "sidebar", axis: "vertical", primary: true, "data-satin-sidebar-list": "true", children: [section && _jsx("h2", { "data-satin-sidebar-section": "true", children: section }), entries.map(entry => (_jsxs(Pressable, { disabled: entry.disabled, "data-satin-sidebar-row": "true", "aria-current": split?.identity === entry.id ? 'page' : undefined, onPress: () => onSelect(entry.id), children: [entry.icon && (_jsx("span", { "aria-hidden": "true", "data-satin-sidebar-icon": "true", children: entry.icon })), _jsx("span", { children: entry.label })] }, entry.id)))] }));
+}

package/dist/navigation/SidebarSymbol.d.ts

@@ -0,0 +1,4 @@
+/** Framework7 Icons (MIT), through the shared SymbolImage renderer. */
+export declare function SidebarSymbol({ name }: {
+    name: 'gearshape' | 'sidebar.left';
+}): import("react").JSX.Element;

package/dist/navigation/SidebarSymbol.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { SymbolImage } from '../symbols/Symbol.js';
+/** Framework7 Icons (MIT), through the shared SymbolImage renderer. */
+export function SidebarSymbol({ name }) {
+    return _jsx(SymbolImage, { name: name, "data-satin-sidebar-symbol": name });
+}

package/dist/navigation/ToolbarGlass.d.ts

@@ -0,0 +1,2 @@
+/** Outgoing and incoming item i share one persistent region, including its live shape. */
+export declare function ToolbarGlass(): import("react").JSX.Element;