@satinhq/kit 0.1.0-beta.2 → 0.1.0-beta.4

package/dist/list-form/editing.d.ts

@@ -1,19 +1,19 @@
 import { type ReactNode } from 'react';
 import type { RowActionsProps } from '../actions/types.js';
-/** `EditMode`: whether a screen's lists show their editing controls. */
+/** Whether a screen's lists show their editing controls: `active` or `inactive`. */
 export type EditMode = 'inactive' | 'active';
 /** A row's identity in `List` selection: the `ForEach` id. */
 export type ListItemID = string | number;
 /**
- * Every navigation destination owns one edit mode, as a SwiftUI `NavigationStack` destination does:
+ * Every navigation destination owns one edit mode, for its retained entry:
  * its `EditButton` and its lists read and write the same value, and another screen keeps its own.
  */
 export declare function EditModeScope({ children }: {
     children: ReactNode;
 }): import("react").JSX.Element;
 /**
- * `@Environment(\.editMode)`: this screen's edit mode and a setter. `EditButton` toggles
- * the same value, so a toolbar or bottom bar can follow it.
+ * Returns this screen's edit mode and a setter. `EditButton` toggles the same value, so a
+ * toolbar or bottom bar can follow it.
  *
  * @example
  * const [editMode] = useEditMode()
@@ -25,14 +25,14 @@ export type ListSelectionModel = Readonly<{
     /** `single` selects one row (an optional binding); `multiple` collects a set. */
     mode: 'single' | 'multiple';
     isSelected(id: ListItemID): boolean;
-    /** A row tap: replaces a single selection; toggles a set only while editing, as SwiftUI does. */
+    /** A row tap: replaces a single selection; toggles a set only while editing. */
     activate(id: ListItemID, editing: boolean): void;
 }>;
 export declare const ListSelectionContext: import("react").Context<Readonly<{
     /** `single` selects one row (an optional binding); `multiple` collects a set. */
     mode: 'single' | 'multiple';
     isSelected(id: ListItemID): boolean;
-    /** A row tap: replaces a single selection; toggles a set only while editing, as SwiftUI does. */
+    /** A row tap: replaces a single selection; toggles a set only while editing. */
     activate(id: ListItemID, editing: boolean): void;
 }> | null>;
 /**
@@ -58,10 +58,9 @@ export type ForEachEditing = Readonly<Pick<ForEachProps<{
     id: ListItemID;
 }>, 'onDelete' | 'onMove'>>;
 /**
- * `ForEach`: one row per element of `data`, identified by its `id` (or `id` function). In a
+ * Makes one row per element of `data`, identified by its `id` (or an `id` function). In a
  * `List`, `onDelete` adds swipe-to-delete and the editing delete control; `onMove` adds the
- * reorder handle. Both receive offsets into `data`; apply them with `removing` and
- * `moving`.
+ * reorder handle. Both receive offsets into `data`; apply them with `removing` and `moving`.
  *
  * Put `ForEach` directly in a `List` or `Section`: the list reads it to know each row's identity.
  *
@@ -82,7 +81,7 @@ export declare function forEachRows<T>(props: ForEachProps<T>): ForEachRow[];
 /** What an editable row needs from its list item: edit state, selection and the item's actions. */
 export type ListItemState = Readonly<{
     editing: boolean;
-    /** While editing with a selection, a row's own press selects it, as a SwiftUI list row does. */
+    /** While editing with a selection, a row's own press selects it, as a list row does. */
     pressSelects: boolean;
     select(): void;
     /** Rows that also declare actions hand them to the item, which owns the row's one gesture host. */
@@ -94,7 +93,7 @@ export type RowActionsDelegation = RowActionsProps & Readonly<{
 }>;
 export declare const ListItemContext: import("react").Context<Readonly<{
     editing: boolean;
-    /** While editing with a selection, a row's own press selects it, as a SwiftUI list row does. */
+    /** While editing with a selection, a row's own press selects it, as a list row does. */
     pressSelects: boolean;
     select(): void;
     /** Rows that also declare actions hand them to the item, which owns the row's one gesture host. */

package/dist/list-form/editing.js

@@ -3,7 +3,7 @@ import { createContext, Fragment, useContext, useMemo, useState } from 'react';
 const inactiveEverywhere = ['inactive', () => { }];
 const EditModeContext = createContext(inactiveEverywhere);
 /**
- * Every navigation destination owns one edit mode, as a SwiftUI `NavigationStack` destination does:
+ * Every navigation destination owns one edit mode, for its retained entry:
  * its `EditButton` and its lists read and write the same value, and another screen keeps its own.
  */
 export function EditModeScope({ children }) {
@@ -12,8 +12,8 @@ export function EditModeScope({ children }) {
     return _jsx(EditModeContext, { value: binding, children: children });
 }
 /**
- * `@Environment(\.editMode)`: this screen's edit mode and a setter. `EditButton` toggles
- * the same value, so a toolbar or bottom bar can follow it.
+ * Returns this screen's edit mode and a setter. `EditButton` toggles the same value, so a
+ * toolbar or bottom bar can follow it.
  *
  * @example
  * const [editMode] = useEditMode()
@@ -24,10 +24,9 @@ export function useEditMode() {
 }
 export const ListSelectionContext = createContext(null);
 /**
- * `ForEach`: one row per element of `data`, identified by its `id` (or `id` function). In a
+ * Makes one row per element of `data`, identified by its `id` (or an `id` function). In a
  * `List`, `onDelete` adds swipe-to-delete and the editing delete control; `onMove` adds the
- * reorder handle. Both receive offsets into `data`; apply them with `removing` and
- * `moving`.
+ * reorder handle. Both receive offsets into `data`; apply them with `removing` and `moving`.
  *
  * Put `ForEach` directly in a `List` or `Section`: the list reads it to know each row's identity.
  *

package/dist/list-form/offsets.d.ts

@@ -17,8 +17,8 @@ export declare function moving<T>(items: readonly T[], { fromOffsets, toOffset }
     toOffset: number;
 }): T[];
 /**
- * Swift `remove(atOffsets:)`, returning a new array without the elements at `offsets`. Pass it
- * exactly what `ForEach`'s `onDelete` reports.
+ * Returns a new array without the elements at `offsets`. Pass it exactly what `ForEach`'s
+ * `onDelete` reports.
  *
  * @example
  * <ForEach data={todos} onDelete={offsets => setTodos(todos => removing(todos, offsets))}>

package/dist/list-form/offsets.js

@@ -22,8 +22,8 @@ export function moving(items, { fromOffsets, toOffset }) {
     return kept;
 }
 /**
- * Swift `remove(atOffsets:)`, returning a new array without the elements at `offsets`. Pass it
- * exactly what `ForEach`'s `onDelete` reports.
+ * Returns a new array without the elements at `offsets`. Pass it exactly what `ForEach`'s
+ * `onDelete` reports.
  *
  * @example
  * <ForEach data={todos} onDelete={offsets => setTodos(todos => removing(todos, offsets))}>

package/dist/media/react.d.ts

@@ -5,5 +5,6 @@ export declare function MediaPlayerRoot({ children, onActivityChange, }: {
     children: ReactNode;
     onActivityChange?: (active: boolean) => void;
 }): import("react").JSX.Element;
-/** Subscribe to the root-owned audio queue and system media commands. Video playback is not supported. */
+/** Returns the app's audio player: its commands and its live state. The system's Lock Screen
+ * media controls drive the same player. Audio only; there is no video playback. */
 export declare function useMediaPlayer(): MediaPlayer;

package/dist/media/react.js

@@ -17,7 +17,8 @@ export function MediaPlayerRoot({ children, onActivityChange, }) {
     }, [store]);
     return _jsx(MediaContext, { value: store, children: children });
 }
-/** Subscribe to the root-owned audio queue and system media commands. Video playback is not supported. */
+/** Returns the app's audio player: its commands and its live state. The system's Lock Screen
+ * media controls drive the same player. Audio only; there is no video playback. */
 export function useMediaPlayer() {
     const store = useContext(MediaContext);
     if (!store)

package/dist/media/types.d.ts

@@ -1,4 +1,5 @@
-/** Each occurrence has its own entryId, including repeated songs. */
+/** One item in the audio queue: its source URL, media id and display metadata. Each occurrence
+ * has its own `entryId`, so a repeated song appears twice. */
 export type MediaQueueEntry = Readonly<{
     entryId: string;
     mediaId: string;
@@ -22,7 +23,7 @@ export type MediaCommandResult = Readonly<{
     code: string;
     cause?: unknown;
 }>;
-/** The queue's repeat mode. */
+/** The queue's repeat mode: `off`, `one` or `all`. */
 export type MediaRepeat = 'off' | 'one' | 'all';
 /** Everything the player shows: the queue, the current entry, status, position and modes. */
 export type MediaSnapshot = Readonly<{
@@ -60,7 +61,9 @@ export type MediaQueueOptions = Readonly<{
     position?: number;
     autoplay?: boolean;
 }>;
-/** Queue results acknowledge the transaction. Playback and seek results acknowledge observed completion. */
+/** The audio player's commands: queue editing, transport, seek, repeat and shuffle. Queue
+ * commands resolve once the change is made; `play` and `seek` resolve once playback is seen to
+ * respond. */
 export interface MediaController {
     replaceQueue(entries: readonly MediaQueueEntry[], options?: MediaQueueOptions): Promise<MediaCommandResult>;
     play(): Promise<MediaCommandResult>;

package/dist/motion/TransitionView.d.ts

@@ -1,12 +1,14 @@
 import { type ReactNode } from 'react';
 import { Transition } from './transition.js';
+/** Whether the content is visible, the transition to use and the content. */
 export type TransitionViewProps = Readonly<{
     visible: boolean;
     transition?: Transition;
     children: ReactNode;
 }>;
-/** Keep this boundary mounted; change visible inside withAnimation. Removed content
- * stays mounted and inert until its exit finishes. Initial content does not animate.
+/** Shows or hides its content with a transition when `visible` changes inside `withAnimation`.
+ * Keep the view itself mounted. Hidden content stays mounted and inert until its exit finishes,
+ * and the first render does not animate.
  * @experimental General transitions still require installed-device motion qualification.
  */
 export declare function TransitionView({ visible, transition, children, }: TransitionViewProps): import("react").JSX.Element;

package/dist/motion/TransitionView.js

@@ -22,8 +22,9 @@ function frame(pose) {
         opacity: Math.max(0, Math.min(1, pose.opacity)),
     };
 }
-/** Keep this boundary mounted; change visible inside withAnimation. Removed content
- * stays mounted and inert until its exit finishes. Initial content does not animate.
+/** Shows or hides its content with a transition when `visible` changes inside `withAnimation`.
+ * Keep the view itself mounted. Hidden content stays mounted and inert until its exit finishes,
+ * and the first render does not animate.
  * @experimental General transitions still require installed-device motion qualification.
  */
 export function TransitionView({ visible, transition = Transition.opacity, children, }) {

package/dist/motion/animationValue.d.ts

@@ -4,14 +4,14 @@ declare const brand: unique symbol;
 export type Animation = Readonly<{
     [brand]: true;
 }>;
-/** Duration and bounce options for `Animation.spring`. */
+/** A spring's duration in milliseconds and its bounce, for `Animation.spring`. */
 export type SpringOptions = Readonly<{
     /** The perceptual duration in milliseconds. Defaults to 500. */
     durationMs?: number;
     /** 0 settles without overshoot. Values are clamped to 0 through 0.99. Defaults to 0. */
     bounce?: number;
 }>;
-/** SwiftUI's named springs. `default` is the curve `withAnimation` uses with no argument. */
+/** Named spring timing values. `default` is the curve `withAnimation` uses with no argument. */
 export declare const Animation: Readonly<{
     spring: (options?: SpringOptions) => Animation;
     smooth: Animation;

package/dist/motion/animationValue.js

@@ -1,8 +1,8 @@
 const brand = Symbol('satin.animation');
 /**
- * SwiftUI's `spring(duration:bounce:)` mapping, as Apple documents it: the duration is the
+ * Duration is the
  * period of the undamped spring (omega = 2π / duration), and bounce is 1 − damping ratio for
- * bounce ≥ 0. SwiftUI's negative (over-damped) bounces are not offered: the shared spring
+ * bounce ≥ 0. Negative, over-damped bounces are not offered: the shared spring
  * solver (glass/lens/menuSpring.ts) models damping ratios up to 1.
  */
 function spring({ durationMs = 500, bounce = 0 } = {}) {
@@ -15,24 +15,23 @@ function spring({ durationMs = 500, bounce = 0 } = {}) {
     const animation = Object.freeze({ [brand]: true, omega, zeta });
     return animation;
 }
-/** SwiftUI's named springs. `default` is the curve `withAnimation` uses with no argument. */
+/** Named spring timing values. `default` is the curve `withAnimation` uses with no argument. */
 export const Animation = Object.freeze({
     spring,
-    /** SwiftUI `.smooth`: duration 0.5 s, bounce 0. */
+    /** Smooth spring: duration 0.5 s, bounce 0. */
     smooth: spring({ durationMs: 500, bounce: 0 }),
-    /** SwiftUI `.snappy`: duration 0.5 s, bounce 0.15. */
+    /** Snappy spring: duration 0.5 s, bounce 0.15. */
     snappy: spring({ durationMs: 500, bounce: 0.15 }),
-    /** SwiftUI `.bouncy`: duration 0.5 s, bounce 0.3. */
+    /** Bouncy spring: duration 0.5 s, bounce 0.3. */
     bouncy: spring({ durationMs: 500, bounce: 0.3 }),
-    /** SwiftUI `.default`. The value is the measured fit recorded in the measured reference
+    /** Default spring. The value is the measured fit recorded in the measured reference
      * (matchedGeometryEffect, October 11); see DEFAULT_ANIMATION_DURATION_MS. */
     get default() {
         return defaultAnimation;
     },
 });
-/* The perceptual duration of SwiftUI's `.default` animation on iOS 27, which is a critically
- * damped spring. Source: the stock SwiftUI matchedGeometryEffect fixture recorded by the
- * matched-geometry implementation (the measured reference, October 11). */
+/* Default perceptual duration for the critically damped animation spring. The measured
+ * fit and recording provenance live in the measured reference. */
 export const DEFAULT_ANIMATION_DURATION_MS = 500;
 const defaultAnimation = spring({ durationMs: DEFAULT_ANIMATION_DURATION_MS, bounce: 0 });
 /** The spring with a unit displacement and the given initial velocity (units per second). */

package/dist/motion/matchedGeometry.d.ts

@@ -1,11 +1,12 @@
 import { type ReactNode } from 'react';
 import { Animation } from './animationValue.js';
 declare const namespaceBrand: unique symbol;
-/** `Namespace.ID`: the scope `MatchedGeometryEffect` ids are matched within. */
+/** A scope for matched-geometry ids. Two views match only if they share an id and a namespace. */
 export type NamespaceID = Readonly<{
     [namespaceBrand]: true;
 }>;
-/** `@Namespace`: a stable id scope for `MatchedGeometryEffect`, one per component. */
+/** Returns a namespace that stays the same for the life of the component. Pass it to
+ * `MatchedGeometryEffect` and `MatchedTransitionSource`. */
 export declare function useNamespace(): NamespaceID;
 /**
  * A namespace declared once at module scope, for views that share no parent component: a
@@ -16,7 +17,7 @@ export declare function useNamespace(): NamespaceID;
  * @experimental Shared by the zoom navigation transition.
  */
 export declare function defineNamespace(): NamespaceID;
-/** Props of `MatchedGeometryEffect`. */
+/** The effect's id and namespace, whether it is the source, and the one element it wraps. */
 export type MatchedGeometryEffectProps = Readonly<{
     /** Views with the same id in the same namespace are one view in two places. */
     id: string;
@@ -27,26 +28,26 @@ export type MatchedGeometryEffectProps = Readonly<{
     children: ReactNode;
 }>;
 /**
- * SwiftUI `matchedGeometryEffect(id:in:isSource:)`: when a `withAnimation` change removes this
+ * When a `withAnimation` change removes this
  * view and inserts another with the same id, the new one moves from the old one's frame to its
  * own while the two cross-fade. A view that only moves or resizes
  * animates from where it was. A matched view with no partner fades in or out.
  *
  * Wrap one element that has no transform of its own. Changes made outside `withAnimation`
- * apply at once, as in SwiftUI.
+ * apply at once.
  * @example
  * const art = useNamespace()
  * <MatchedGeometryEffect id="artwork" in={art}><Image src={cover} alt="" /></MatchedGeometryEffect>
- * @experimental Frame matching only (SwiftUI's default `properties: .frame`, `anchor: .center`).
+ * @experimental Matches the frame around its center only.
  * A non-source view does not follow its source outside an animation.
  */
 export declare function MatchedGeometryEffect({ id, in: namespace, isSource, children, }: MatchedGeometryEffectProps): import("react").JSX.Element;
 /**
- * `withAnimation` applies the state changes in `update`, then animates the
+ * Applies the state changes in `update`, then animates the
  * `MatchedGeometryEffect` views they move, insert or remove. Call it from an event handler.
  * Keyed List rows also move to their new positions. Other views take their new layout at once.
- * Returns the callback result and propagates errors. Only synchronous updates participate.
- * Nested calls share the outer List transaction; per-update nested timing is not supported.
+ * Returns the callback result and passes errors through. Only synchronous updates take part,
+ * and nested calls join the outer one.
  * @example
  * <Button onPress={() => withAnimation(() => setShowQueue(!showQueue))}>Playing Next</Button>
  */

package/dist/motion/matchedGeometry.js

@@ -17,13 +17,13 @@ import { fadeSettleMs, runFrameTimes, sampleChannel, sampleProgress, } from './s
  *
  * A view whose id leaves and enters in the same change keeps its identity: the new view starts
  * from the old one's frame and fades in, and the old view stays on screen as a "ghost" (its own
- * detached DOM node, already decoded) that travels with it and fades out. That cross-fade is
- * SwiftUI's: a stock iOS 27 fixture shows both views on one frame, with opacities that sum to 1
- * on the animation's own spring (the measured reference, October 11).
+ * detached DOM node, already decoded) that travels with it and fades out. Their opacities sum to 1
+ * throughout the spring-driven cross-fade. Measurement provenance lives in the measured reference.
  */
 const namespaceBrand = Symbol('satin.namespace');
 const entries = new Set();
-/** `@Namespace`: a stable id scope for `MatchedGeometryEffect`, one per component. */
+/** Returns a namespace that stays the same for the life of the component. Pass it to
+ * `MatchedGeometryEffect` and `MatchedTransitionSource`. */
 export function useNamespace() {
     const [namespace] = useState(defineNamespace);
     return namespace;
@@ -40,17 +40,17 @@ export function defineNamespace() {
     return Object.freeze({ [namespaceBrand]: true });
 }
 /**
- * SwiftUI `matchedGeometryEffect(id:in:isSource:)`: when a `withAnimation` change removes this
+ * When a `withAnimation` change removes this
  * view and inserts another with the same id, the new one moves from the old one's frame to its
  * own while the two cross-fade. A view that only moves or resizes
  * animates from where it was. A matched view with no partner fades in or out.
  *
  * Wrap one element that has no transform of its own. Changes made outside `withAnimation`
- * apply at once, as in SwiftUI.
+ * apply at once.
  * @example
  * const art = useNamespace()
  * <MatchedGeometryEffect id="artwork" in={art}><Image src={cover} alt="" /></MatchedGeometryEffect>
- * @experimental Frame matching only (SwiftUI's default `properties: .frame`, `anchor: .center`).
+ * @experimental Matches the frame around its center only.
  * A non-source view does not follow its source outside an animation.
  */
 export function MatchedGeometryEffect({ id, in: namespace, isSource = true, children, }) {
@@ -226,13 +226,13 @@ function moveView(element, key, from, box, animation) {
         target: box,
         velocity: from.velocity,
         animation,
-        // A new partner fades in (SwiftUI's default .opacity insertion); a view that stays carries
+        // A new partner fades in through the default opacity transition; a view that stays carries
         // on from the opacity it is showing.
         opacity: { from: stayed ? from.opacity : 0, to: 1 },
         ghost: false,
     });
 }
-/** SwiftUI's default `.opacity` transition for a matched view with no partner. */
+/** An opacity transition for a matched view with no partner. */
 function fadeView(element, key, box, animation, opacity) {
     startRun({
         element,

package/dist/motion/springTrack.d.ts

@@ -1,6 +1,5 @@
 import { type MenuSpring } from '../glass/lens/menuSpring.js';
-/** A measured spring: SwiftUI's `.interpolatingSpring(stiffness:damping:)` with unit mass, released
- * `delay` ms after the animation starts. */
+/** A unit-mass spring defined by stiffness and damping, released after an optional delay in ms. */
 export type SpringParameters = Readonly<{
     stiffness: number;
     damping: number;

package/dist/motion/springTrack.js

@@ -28,19 +28,22 @@ export function sampledKeyframes(track, frame) {
     return track.progress.map((progress, index) => ({ ...frame(progress), offset: index / last }));
 }
 export function sampledMotionTrack(duration, sample, tolerance = 0.2) {
-    if (!(duration > 0) || !Number.isFinite(duration) || !(tolerance > 0) || !Number.isFinite(tolerance))
+    if (!(duration > 0) ||
+        !Number.isFinite(duration) ||
+        !(tolerance > 0) ||
+        !Number.isFinite(tolerance))
         throw Error('Motion tracks require a finite positive duration and tolerance');
     let count = Math.max(1, Math.ceil(duration / (1000 / 120)));
     // GPU and compositor consumers require even offsets. Refine the whole grid,
     // rather than giving them independent adaptive sample positions.
     while (count <= 4096) {
-        const values = Array.from({ length: count + 1 }, (_, index) => sample(duration * index / count));
+        const values = Array.from({ length: count + 1 }, (_, index) => sample((duration * index) / count));
         if (!values.every(Number.isFinite))
             throw Error('Motion track contains a non-finite value');
         let accurate = true;
         for (let index = 0; accurate && index < count; index++) {
             for (const fraction of [0.25, 0.5, 0.75]) {
-                const exact = sample(duration * (index + fraction) / count);
+                const exact = sample((duration * (index + fraction)) / count);
                 const linear = values[index] + (values[index + 1] - values[index]) * fraction;
                 if (!Number.isFinite(exact))
                     throw Error('Motion track contains a non-finite value');
@@ -59,11 +62,13 @@ export function sampledMotionTrack(duration, sample, tolerance = 0.2) {
 /** Read the submitted segment, including its velocity, when a run is interrupted. */
 export function sampledMotionState(track, milliseconds) {
     const last = track.values.length - 1;
-    const position = Math.max(0, Math.min(last, milliseconds / track.duration * last));
+    const position = Math.max(0, Math.min(last, (milliseconds / track.duration) * last));
     const index = Math.min(last - 1, Math.floor(position));
     const from = track.values[index], to = track.values[index + 1];
     return {
         value: from + (to - from) * (position - index),
-        velocity: milliseconds < 0 || milliseconds >= track.duration ? 0 : (to - from) * last / track.duration * 1000,
+        velocity: milliseconds < 0 || milliseconds >= track.duration
+            ? 0
+            : (((to - from) * last) / track.duration) * 1000,
     };
 }

package/dist/motion/transition.d.ts

@@ -9,7 +9,8 @@ type Effect = Readonly<{
     kind: 'move';
     edge: TransitionEdge;
 }>;
-/** Immutable insertion and removal effects. Timing belongs to withAnimation. */
+/** How a view enters and leaves: opacity, scale and move effects. `withAnimation` sets the
+ * timing. */
 export type Transition = Readonly<{
     insertion: readonly Effect[];
     removal: readonly Effect[];
@@ -18,6 +19,8 @@ declare function move(edge: TransitionEdge): Transition;
 declare function scale(value?: number): Transition;
 declare function asymmetric(insertion: Transition, removal: Transition): Transition;
 declare function combined(...transitions: readonly Transition[]): Transition;
+/** Builds transitions: `identity`, `opacity`, `move`, `scale`, `slide`, `push` and their
+ * combinations. Each returns a new value. */
 export declare const Transition: Readonly<{
     identity: Readonly<{
         insertion: readonly Effect[];

package/dist/motion/transition.js

@@ -19,6 +19,8 @@ function combined(...transitions) {
     return effects(transitions.flatMap(value => value.insertion), transitions.flatMap(value => value.removal));
 }
 const opacity = effects([{ kind: 'opacity' }]);
+/** Builds transitions: `identity`, `opacity`, `move`, `scale`, `slide`, `push` and their
+ * combinations. Each returns a new value. */
 export const Transition = Object.freeze({
     identity: effects([]),
     opacity,

package/dist/navigation/DetailList.d.ts

@@ -1,5 +1,5 @@
 import type { ReactNode } from 'react';
-/** Regular-width grouped detail content beneath NavigatorHost's inline title. */
+/** A grouped list of rows for a split view's detail column at regular width. */
 export declare function DetailList({ items, }: {
     items: readonly {
         id: string;

package/dist/navigation/DetailList.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { ScrollSurface } from '../scroll/ScrollSurface.js';
 import { Pressable } from '../press/Pressable.js';
-/** Regular-width grouped detail content beneath NavigatorHost's inline title. */
+/** A grouped list of rows for a split view's detail column at regular width. */
 export function DetailList({ items, }) {
     return (_jsx(ScrollSurface, { id: "detail", axis: "vertical", primary: true, "data-satin-detail-list": "true", children: _jsx("div", { "data-satin-detail-group": "true", children: items.map(item => item.onPress ? (_jsx(Pressable, { feedback: "row", "data-satin-detail-row": "true", onPress: item.onPress, children: item.label }, item.id)) : (_jsx("div", { "data-satin-detail-row": "true", children: item.label }, item.id))) }) }));
 }

package/dist/navigation/ScreenContainer.js

@@ -130,7 +130,7 @@ export function ScreenContainer({ children, entry, interactionBlocked = false, c
     }), [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.
+    // 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);

package/dist/navigation/Sidebar.d.ts

@@ -1,10 +1,12 @@
 import { type ReactNode } from 'react';
+/** One sidebar destination: its id, label, optional icon and disabled state. */
 export type SidebarEntry = Readonly<{
     id: string;
     label: string;
     icon?: ReactNode;
     disabled?: boolean;
 }>;
+/** The sidebar's entries, the selection callback and which entry starts selected. */
 export type SidebarProps = Readonly<{
     entries: readonly SidebarEntry[];
     onSelect: (id: string) => void;
@@ -12,5 +14,5 @@ export type SidebarProps = Readonly<{
     /** 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. */
+/** A list of sidebar destinations. Selecting one shows it in the split view's detail column. */
 export declare function Sidebar({ entries, onSelect, section, initialSelection }: SidebarProps): import("react").JSX.Element;

package/dist/navigation/Sidebar.js

@@ -4,7 +4,7 @@ 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. */
+/** A list of sidebar destinations. Selecting one shows it in the split view's detail column. */
 export function Sidebar({ entries, onSelect, section, initialSelection = 'first' }) {
     const split = useContext(SplitContext);
     useLayoutEffect(() => {

package/dist/navigation/SidebarSymbol.d.ts

@@ -1,4 +1,5 @@
-/** Framework7 Icons (MIT), through the shared SymbolImage renderer. */
+/** Draws the sidebar's `gearshape` or `sidebar.left` icon with `SymbolImage`. The artwork is from
+ * Framework7 Icons (MIT). */
 export declare function SidebarSymbol({ name }: {
     name: 'gearshape' | 'sidebar.left';
 }): import("react").JSX.Element;

package/dist/navigation/SidebarSymbol.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { SymbolImage } from '../symbols/Symbol.js';
-/** Framework7 Icons (MIT), through the shared SymbolImage renderer. */
+/** Draws the sidebar's `gearshape` or `sidebar.left` icon with `SymbolImage`. The artwork is from
+ * Framework7 Icons (MIT). */
 export function SidebarSymbol({ name }) {
     return _jsx(SymbolImage, { name: name, "data-satin-sidebar-symbol": name });
 }

package/dist/navigation/chromeCurves.js

@@ -1,7 +1,7 @@
 // Measured iOS 27 navigation bar chrome curves (what bar items do while a page moves) and the
 // keyframe builders that turn them into Web Animations keyframes. Pure data and math: no DOM.
 /** Incoming bar chrome, measured on the iOS 27.0 Simulator from the presentation layers of stock
- * SwiftUI (every display frame,
+ * Measured at every display frame,
  * light and dark agree within 0.04): milliseconds since the page starts moving. A push brings the
  * destination's glass items in faster than a pop brings the revealed screen's back: a push shows
  * 0.56 at 100 ms (Reminders-style list → list, back circle and trailing "…" together), a pop 0.30

package/dist/navigation/navigationContext.d.ts

@@ -17,6 +17,7 @@ export declare function useNavigator<Registry extends ScreenRegistry = ScreenReg
 export declare function useNavigatorState<Registry extends ScreenRegistry = ScreenRegistry>(): NavigatorState<RegistryScreenEntry<Registry>>;
 export declare function useParams<Params = unknown>(): Params;
 export declare function useScreenScrollRegistry(): ScrollSurfaceRegistry;
-/** `onAppear` and `onDisappear`: callbacks for a retained navigation entry's visible lifecycle. */
+/** Runs `appear` and `disappear` callbacks as the screen is shown and covered or removed, and
+ * returns whether it is covered and its transition phase. */
 export declare function useScreenLifecycle(callbacks?: ScreenLifecycleCallbacks): ScreenLifecycle;
 export {};

package/dist/navigation/navigationContext.js

@@ -44,7 +44,8 @@ export function useScreenScrollRegistry() {
     }
     return standalone.current;
 }
-/** `onAppear` and `onDisappear`: callbacks for a retained navigation entry's visible lifecycle. */
+/** Runs `appear` and `disappear` callbacks as the screen is shown and covered or removed, and
+ * returns whether it is covered and its transition phase. */
 export function useScreenLifecycle(callbacks = EMPTY_LIFECYCLE_CALLBACKS) {
     const screen = useContext(ScreenContext);
     if (!screen) {

package/dist/navigation/splitContext.d.ts

@@ -13,5 +13,6 @@ export declare const SplitContext: import("react").Context<Readonly<{
     entry: ScreenEntry | undefined;
     identity: string | undefined;
 }> | undefined>;
-/** Entry identity owns navigation/scroll; identity is the registry's semantic row key. */
+/** Returns the split view's mode and the entry shown in its detail column. It throws outside a
+ * split view. */
 export declare function useSplitSelection(): SplitSelection;

package/dist/navigation/splitContext.js

@@ -1,6 +1,7 @@
 import { createContext, useContext } from 'react';
 export const SplitContext = createContext(undefined);
-/** Entry identity owns navigation/scroll; identity is the registry's semantic row key. */
+/** Returns the split view's mode and the entry shown in its detail column. It throws outside a
+ * split view. */
 export function useSplitSelection() {
     const selection = useContext(SplitContext);
     if (!selection)

package/dist/navigation/toolbarMinimization.d.ts

@@ -1,8 +1,9 @@
-/** `ToolbarMinimizationBehavior`: when a toolbar may minimize. */
+/** When the navigation bar minimizes: `onScrollDown`, `onScrollUp` or `never`. */
 export type ToolbarMinimizationBehavior = 'onScrollDown' | 'onScrollUp' | 'never';
-/** The interaction that restores a minimized toolbar. */
+/** What brings back a minimized bar: `automatic`, or only reaching the scroll edge
+ * (`atScrollEdge`). */
 export type ToolbarMinimizationRestoration = 'automatic' | 'atScrollEdge';
-/** Whether toolbar minimization changes its reserved content inset. */
+/** Whether the content inset shrinks when the bar minimizes. */
 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. */