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

package/dist/public/controls.d.ts

@@ -13,9 +13,9 @@ export type { ButtonBorderShape } from './buttonBorderShape.js';
 import type { RowActionsProps } from '../actions/types.js';
 import { type ListItemID } from '../list-form/editing.js';
 import type { Routes, RouteProps, RegisteredRoutes } from './routes.js';
-/** `swipeActions` and `contextMenu` for a row inside a `List`. */
+/** The `swipeActions` and `contextMenu` props of a row in a `List`. */
 export type RowInteractionProps = RowActionsProps;
-/** `textFieldStyle`: `automatic` adapts to the container; `plain` draws no field chrome. */
+/** How a text field draws. `automatic` adapts to its container; `plain` draws no field chrome. */
 export type TextFieldStyle = 'automatic' | 'plain';
 /** A number caps growth; a range also reserves its minimum number of lines. */
 export type LineLimit = number | {
@@ -37,14 +37,14 @@ export type FormProps = Omit<HTMLAttributes<HTMLDivElement>, 'id'> & {
     listSectionSpacing?: 'default' | 'compact' | number;
     scrollContentBackground?: 'hidden' | 'visible';
 };
-/** `listStyle`: the row chrome of a `List`. */
+/** How a `List` draws its rows and sections. `insetGrouped` is the default. */
 export type ListStyle = 'insetGrouped' | 'plain' | 'grouped' | 'sidebar';
 /** A `List` takes a `Form`'s options, its `listStyle` and an optional `selection`. */
 export type ListProps<ID extends ListItemID = ListItemID> = FormProps & {
     listStyle?: ListStyle;
 } & ListSelectionProps<ID>;
 /**
- * `List(selection:)`. An optional id selects one row: tapping a row selects it. A `Set`
+ * Row selection for a `List`. An optional id selects one row: tapping a row selects it. A `Set`
  * selects many: while editing, rows show selection circles and taps toggle them. Rows are
  * identified by their `ForEach` ids.
  */
@@ -59,8 +59,8 @@ export type ListSelectionProps<ID extends ListItemID = ListItemID> = {
     onSelectionChange: (next: Set<ID>) => void;
 };
 /**
- * `List`: a named vertical scroll view of rows, inset grouped by default. Controls inside
- * it render as rows. Its `id` keys scroll restoration, so keep it stable.
+ * A scrolling column of rows, inset grouped by default. Controls inside it render as rows.
+ * Its `id` keys scroll restoration, so keep it stable.
  *
  * With `selection`, rows from a `ForEach` become selectable; with an `EditButton` in the screen's
  * toolbar, `ForEach`'s `onDelete` and `onMove` add the editing controls.
@@ -87,8 +87,8 @@ export declare function List<ID extends ListItemID>(props: FormProps & {
 export declare function List(props: FormProps & {
     listStyle?: ListStyle;
 }): ReactElement;
-/** `Form`: an inset grouped `List` for settings and data entry, whose scroll dismisses
- * the keyboard immediately. */
+/** An inset grouped `List` for settings and data entry. Scrolling it dismisses the keyboard
+ * at once. */
 export declare function Form(props: FormProps): import("react").JSX.Element;
 /** Button's action, label and control properties. An `iconOnly` button needs an `aria-label`. */
 export type ButtonProps = AriaAttributes & RowInteractionProps & {
@@ -120,8 +120,8 @@ export type ButtonProps = AriaAttributes & RowInteractionProps & {
  */
 export declare const Button: import("react").ForwardRefExoticComponent<ButtonProps & RefAttributes<HTMLButtonElement>>;
 /**
- * `EditButton`: toggles the screen's edit mode. In a toolbar it reads Edit, then becomes
- * the prominent checkmark (Done) while editing, as in iOS 27.
+ * Toggles the screen's edit mode. In a toolbar it reads Edit, then becomes a prominent
+ * checkmark (Done) while editing.
  *
  * @example
  * <Screen toolbar={<ToolbarItem placement="topBarTrailing"><EditButton /></ToolbarItem>}>
@@ -154,8 +154,8 @@ export type NavigationLinkProps<R extends Routes = RegisteredRoutes> = [
     };
 }[keyof R['definitions'] & string];
 /**
- * `NavigationLink(value:)`: pushes a declared route. In a `List` it is a disclosure row;
- * elsewhere, a plain pressable.
+ * Pushes a declared route. In a `List` it draws a disclosure row; elsewhere it is a plain
+ * pressable.
  *
  * @example
  * <NavigationLink to="note" params={{ id: note.id }}>{note.title}</NavigationLink>
@@ -166,7 +166,7 @@ export type RowLabelProps = {
     children: ReactNode;
     detail: ReactNode;
 };
-/** A row's title with a secondary line under it, with a title and a subheadline. The framework owns its layout. */
+/** A row title with a secondary `detail` line under it. The framework owns its layout. */
 export declare function RowLabel({ children, detail }: RowLabelProps): import("react").JSX.Element;
 /** The row's label and the trailing value it shows. */
 export type LabeledContentProps = RowInteractionProps & {
@@ -178,7 +178,7 @@ export type LabeledContentProps = RowInteractionProps & {
     className?: string;
     'aria-label'?: string;
 };
-/** `LabeledContent`: a row with a label and a secondary trailing value. */
+/** A row with a label and a trailing value in secondary text. */
 export declare function LabeledContent({ 'aria-label': accessibilityLabel, ...props }: LabeledContentProps): import("react").JSX.Element;
 /** Toggle's controlled value, label and control properties. */
 export type ToggleProps = {
@@ -196,8 +196,8 @@ export type ToggleProps = {
     tint?: string;
 };
 /**
- * `Toggle`: a controlled boolean. It is a switch row in a `List` or `Form`, a bare switch
- * elsewhere, or a `button` or custom `ToggleStyle`.
+ * A controlled on/off value. It draws a switch row in a `List` or `Form` and a bare switch
+ * elsewhere. `toggleStyle` can make it a button or a custom `ToggleStyle`.
  *
  * @example
  * <Toggle label="Show Completed" isOn={showCompleted} onChange={setShowCompleted} />
@@ -216,9 +216,8 @@ export type PickerProps = {
     onSelectionChange(id: string): void;
 };
 /**
- * `Picker`: choose one option. `menu` (default) shows a menu from the row,
- * `navigationLink` pushes a list of options, `inline` lists them in place and `segmented` draws a
- * segmented control.
+ * Chooses one option. `menu` (the default) opens a menu from the row, `navigationLink` pushes a
+ * list of options, `inline` lists them in place and `segmented` draws a segmented control.
  *
  * An option can carry a `symbol` (or `icon`) and a `color`. Icons draw in colour in an inline or
  * navigationLink list, in the label colour inside the open menu, and not at all when segmented.
@@ -241,14 +240,14 @@ export type StepperProps = {
     label: string;
     onEditingChange?: (editing: boolean) => void;
 };
-/** `Stepper`: increments or decrements a controlled number within its bounds. A row in a
- * `List`, the bare control elsewhere. */
+/** Increments or decrements a controlled number within its bounds. It draws a row in a `List`
+ * and the bare control elsewhere. */
 export declare function Stepper({ disabled, ...rest }: StepperProps): import("react").JSX.Element;
 /** Slider's controlled value, range, step and accessibility label. */
 export type SliderProps = {
     value: number;
     onChange: (value: number) => void;
-    /** `in: min...max`; defaults to 0...1. */
+    /** The lower bound. `min` and `max` default to 0 and 1. */
     min?: number;
     max?: number;
     /** Snap to multiples of `step` from `min`; omit for a continuous Slider. */
@@ -261,7 +260,8 @@ export type SliderProps = {
     tint?: string;
     onEditingChange?: (editing: boolean) => void;
 };
-/** `Slider(value:in:step:)`: in a List or Form it fills its own 60 pt row. */
+/** Drags a controlled number between `min` and `max`, continuously or in steps. In a `List` or
+ * `Form` it fills its own 60 pt row. */
 export declare function Slider({ disabled, tint, ...rest }: SliderProps): import("react").JSX.Element;
 /** Horizontal TextField's controlled text and keyboard intent. */
 export type HorizontalTextFieldProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'value' | 'defaultValue' | 'onChange' | 'onSubmit' | 'size' | 'placeholder'> & {
@@ -314,7 +314,7 @@ export type SecureFieldProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'type
     prompt?: string;
     textFieldStyle?: TextFieldStyle;
 };
-/** Password entry with secure system input, adapting to a row in a form. */
+/** Password entry through secure system input. In a `List` or `Form` it becomes the row. */
 export declare const SecureField: import("react").ForwardRefExoticComponent<Omit<InputHTMLAttributes<HTMLInputElement>, "defaultValue" | "onChange" | "onSubmit" | "placeholder" | "size" | "type" | "value"> & {
     label: string;
     value: string;
@@ -336,7 +336,8 @@ export type TextEditorProps = Omit<TextareaHTMLAttributes<HTMLTextAreaElement>,
     prompt?: string;
     textFieldStyle?: TextFieldStyle;
 };
-/** Multiline text entry, adapting to a row in a form. */
+/** Multiline text entry. In a `List` or `Form` it becomes the row; elsewhere it shows three
+ * lines by default. */
 export declare const TextEditor: import("react").ForwardRefExoticComponent<Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, "defaultValue" | "onChange" | "placeholder" | "rows" | "value"> & {
     value: string;
     onChange(value: string): void;
@@ -356,5 +357,5 @@ export type ContentUnavailableViewProps = {
     className?: string;
     children?: ReactNode;
 };
-/** `ContentUnavailableView`: an icon, title and description shown for empty content. */
+/** An empty state: an icon, a title, an optional description and optional action children. */
 export declare function ContentUnavailableView({ symbol, title, description, icon, className, children, }: ContentUnavailableViewProps): import("react").JSX.Element;

package/dist/public/controls.js

@@ -46,8 +46,8 @@ function selectionBinding(selection, onSelectionChange) {
         onChange: onSelectionChange,
     };
 }
-/** `Form`: an inset grouped `List` for settings and data entry, whose scroll dismisses
- * the keyboard immediately. */
+/** An inset grouped `List` for settings and data entry. Scrolling it dismisses the keyboard
+ * at once. */
 export function Form(props) {
     return (_jsx(List, { ...props, listStyle: "insetGrouped", scrollDismissesKeyboard: props.scrollDismissesKeyboard ?? 'immediately' }));
 }
@@ -131,8 +131,8 @@ export const Button = forwardRef(function Button({ children, symbol, role, butto
             : props.style, "data-satin-row-intrinsic": "true", "data-satin-button-style": style, "data-satin-button-role": role, children: _jsx("span", { "data-satin-button-content": true, children: content }) }));
 });
 /**
- * `EditButton`: toggles the screen's edit mode. In a toolbar it reads Edit, then becomes
- * the prominent checkmark (Done) while editing, as in iOS 27.
+ * Toggles the screen's edit mode. In a toolbar it reads Edit, then becomes a prominent
+ * checkmark (Done) while editing.
  *
  * @example
  * <Screen toolbar={<ToolbarItem placement="topBarTrailing"><EditButton /></ToolbarItem>}>
@@ -147,8 +147,8 @@ export function EditButton() {
     return _jsx(Button, { onPress: toggle, children: editing ? 'Done' : 'Edit' });
 }
 /**
- * `NavigationLink(value:)`: pushes a declared route. In a `List` it is a disclosure row;
- * elsewhere, a plain pressable.
+ * Pushes a declared route. In a `List` it draws a disclosure row; elsewhere it is a plain
+ * pressable.
  *
  * @example
  * <NavigationLink to="note" params={{ id: note.id }}>{note.title}</NavigationLink>
@@ -165,17 +165,17 @@ export function NavigationLink({ to, params, children, swipeActions, contextMenu
     };
     return list ? (_jsx(Rows.NavigationRow, { ...props, swipeActions, contextMenu, label: children, leading: symbol ? (_jsx(SymbolImage, { name: symbol, style: { fontSize: 21.7, color: configuration.tint ?? 'var(--satin-tint)' } })) : (props.leading), onPress: onPress })) : (_jsxs(Pressable, { ...props, disabled: configuration.disabled, style: controlTintStyle(configuration.tint), "data-satin-navigation-link": "true", onPress: onPress, children: [symbol && _jsx(SymbolImage, { name: symbol }), children] }));
 }
-/** A row's title with a secondary line under it, with a title and a subheadline. The framework owns its layout. */
+/** A row title with a secondary `detail` line under it. The framework owns its layout. */
 export function RowLabel({ children, detail }) {
     return _jsx(RowLabelBody, { detail: detail, children: children });
 }
-/** `LabeledContent`: a row with a label and a secondary trailing value. */
+/** A row with a label and a trailing value in secondary text. */
 export function LabeledContent({ 'aria-label': accessibilityLabel, ...props }) {
     return _jsx(Rows.ValueRow, { ...props, accessibilityLabel: accessibilityLabel });
 }
 /**
- * `Toggle`: a controlled boolean. It is a switch row in a `List` or `Form`, a bare switch
- * elsewhere, or a `button` or custom `ToggleStyle`.
+ * A controlled on/off value. It draws a switch row in a `List` or `Form` and a bare switch
+ * elsewhere. `toggleStyle` can make it a button or a custom `ToggleStyle`.
  *
  * @example
  * <Toggle label="Show Completed" isOn={showCompleted} onChange={setShowCompleted} />
@@ -222,9 +222,8 @@ function toggleLabel(props, descriptionId) {
     return (_jsx(RowLabelBody, { detail: props.subtitle, detailId: descriptionId, children: props.label }));
 }
 /**
- * `Picker`: choose one option. `menu` (default) shows a menu from the row,
- * `navigationLink` pushes a list of options, `inline` lists them in place and `segmented` draws a
- * segmented control.
+ * Chooses one option. `menu` (the default) opens a menu from the row, `navigationLink` pushes a
+ * list of options, `inline` lists them in place and `segmented` draws a segmented control.
  *
  * An option can carry a `symbol` (or `icon`) and a `color`. Icons draw in colour in an inline or
  * navigationLink list, in the label colour inside the open menu, and not at all when segmented.
@@ -251,14 +250,15 @@ export function Picker({ pickerStyle = 'menu', selection, onSelectionChange, dis
         return _jsx(Rows.PickerOptions, { ...props });
     return (_jsx(Rows.PickerRow, { ...props, onNavigate: navigate, presentation: pickerStyle === 'navigationLink' ? 'navigation' : 'menu' }));
 }
-/** `Stepper`: increments or decrements a controlled number within its bounds. A row in a
- * `List`, the bare control elsewhere. */
+/** Increments or decrements a controlled number within its bounds. It draws a row in a `List`
+ * and the bare control elsewhere. */
 export function Stepper({ disabled, ...rest }) {
     const configuration = useControlStyle({ disabled });
     const props = { ...rest, disabled: configuration.disabled };
     return useContext(ListContext) ? (_jsx(Rows.StepperRow, { ...props })) : (_jsx(Rows.StepperControl, { ...props }));
 }
-/** `Slider(value:in:step:)`: in a List or Form it fills its own 60 pt row. */
+/** Drags a controlled number between `min` and `max`, continuously or in steps. In a `List` or
+ * `Form` it fills its own 60 pt row. */
 export function Slider({ disabled, tint, ...rest }) {
     const configuration = useControlStyle({ disabled, tint });
     const props = { ...rest, disabled: configuration.disabled, tint: configuration.tint };
@@ -285,17 +285,18 @@ const Field = forwardRef(function TextField({ prompt, textFieldStyle, style, ...
  */
 // The cast keeps single-line refs and events precisely typed when axis is omitted.
 export const TextField = Field;
-/** Password entry with secure system input, adapting to a row in a form. */
+/** Password entry through secure system input. In a `List` or `Form` it becomes the row. */
 export const SecureField = forwardRef(function SecureField({ prompt, textFieldStyle, style, ...props }, ref) {
     const variant = useFieldVariant(textFieldStyle);
     return (_jsx(Fields.SecureField, { ...props, style: style, ref: ref, placeholder: prompt ?? (variant !== 'standalone' ? props.label : undefined), variant: variant, labelVisibility: prompt !== undefined || variant !== 'standalone' ? 'hidden' : 'visible' }));
 });
-/** Multiline text entry, adapting to a row in a form. */
+/** Multiline text entry. In a `List` or `Form` it becomes the row; elsewhere it shows three
+ * lines by default. */
 export const TextEditor = forwardRef(function TextEditor({ prompt, textFieldStyle, style, ...props }, ref) {
     const variant = useFieldVariant(textFieldStyle);
     return (_jsx(Editor, { ...props, minLines: props.minLines ?? (variant === 'row' ? 1 : 3), style: style, ref: ref, placeholder: prompt ?? (variant === 'plain' ? props.label : undefined), variant: variant, labelVisibility: prompt !== undefined || variant !== 'standalone' ? 'hidden' : 'visible' }));
 });
-/** `ContentUnavailableView`: an icon, title and description shown for empty content. */
+/** An empty state: an icon, a title, an optional description and optional action children. */
 export function ContentUnavailableView({ symbol = 'tray', title, description, icon, className, children, }) {
     return (_jsxs("div", { "data-satin-empty-state": "true", className: className, children: [_jsx("div", { "data-satin-empty-state-icon": "true", "aria-hidden": "true", children: icon ?? _jsx(SymbolImage, { name: symbol }) }), _jsx("strong", { "data-satin-empty-state-title": "true", children: title }), description && _jsx("div", { "data-satin-empty-state-description": "true", children: description }), children && _jsx("div", { "data-satin-unavailable-actions": "true", children: children })] }));
 }

package/dist/public/deviceActions.d.ts

@@ -1,5 +1,5 @@
 import { type ReactNode } from 'react';
-/** Prepared text, URL or files to hand to the operating system's share sheet. */
+/** The text, URL or files to share, the button content and the completion and error callbacks. */
 export type ShareLinkProps = {
     item: ShareData;
     children?: ReactNode;
@@ -9,9 +9,10 @@ export type ShareLinkProps = {
     /** Includes AbortError for dismissal or absence of a suitable share target. */
     onError(error: Error): void;
 };
-/** Opens the system share sheet during the press. Prepare file bytes before rendering. */
+/** A button that opens the system share sheet. Prepare file bytes before rendering, because the
+ * sheet must open during the press. */
 export declare function ShareLink({ item, children, disabled, onCompletion, onError, }: ShareLinkProps): import("react").JSX.Element;
-/** A user-initiated plain-text paste, subject to WebKit's permission UI. */
+/** The button content and the callbacks that receive the pasted text or the error. */
 export type PasteButtonProps = {
     children?: ReactNode;
     disabled?: boolean;
@@ -19,5 +20,6 @@ export type PasteButtonProps = {
     /** Permission denial and dismissal are reported as browser errors. */
     onError(error: Error): void;
 };
-/** Reads text only when pressed; it never probes clipboard contents while rendering. */
+/** A button that pastes plain text from the clipboard when pressed. It never reads the clipboard
+ * before the press. The browser may ask the user to confirm. */
 export declare function PasteButton({ children, disabled, onPaste, onError }: PasteButtonProps): import("react").JSX.Element;

package/dist/public/deviceActions.js

@@ -63,7 +63,8 @@ function DeviceAction({ children, disabled, identity, start, onResult, onError,
     };
     return (_jsx(Button, { ref: button, disabled: unavailable || busy, onPress: activate, children: children }));
 }
-/** Opens the system share sheet during the press. Prepare file bytes before rendering. */
+/** A button that opens the system share sheet. Prepare file bytes before rendering, because the
+ * sheet must open during the press. */
 export function ShareLink({ item, children = 'Share', disabled, onCompletion, onError, }) {
     return (_jsx(DeviceAction, { disabled: disabled, identity: item, onResult: onCompletion, onError: onError, start: () => {
             if (typeof navigator.share !== 'function') {
@@ -76,7 +77,8 @@ export function ShareLink({ item, children = 'Share', disabled, onCompletion, on
             return navigator.share(item);
         }, children: children }));
 }
-/** Reads text only when pressed; it never probes clipboard contents while rendering. */
+/** A button that pastes plain text from the clipboard when pressed. It never reads the clipboard
+ * before the press. The browser may ask the user to confirm. */
 export function PasteButton({ children = 'Paste', disabled, onPaste, onError }) {
     return (_jsx(DeviceAction, { disabled: disabled, onResult: onPaste, onError: onError, start: () => {
             if (typeof navigator.clipboard?.readText !== 'function') {

package/dist/public/environment.d.ts

@@ -10,32 +10,34 @@ import { setAppBadge } from '../push/notifications.js';
 export declare function useAppUpdate(): Readonly<{
     justUpdated: JustUpdated | null;
 }>;
-/** `horizontalSizeClass`: a presentation's own class inside it, else the window's. */
+/** The horizontal size class: `compact` or `regular`. Inside a presentation it is the
+ * presentation's own class; elsewhere, the window's. */
 export declare function useHorizontalSizeClass(): UserInterfaceSizeClass;
-/** `verticalSizeClass`: a presentation's own class inside it, else the window's. */
+/** The vertical size class: `compact` or `regular`. Inside a presentation it is the
+ * presentation's own class; elsewhere, the window's. */
 export declare function useVerticalSizeClass(): UserInterfaceSizeClass;
 /** The live safe-area insets in CSS pixels. Use them instead of `env(safe-area-inset-*)`. */
 export declare function useSafeAreaInsets(): EdgeInsets;
-/** `scenePhase`: `active` in the foreground with focus, `inactive` without focus,
+/** Whether the app is in use: `active` in the foreground with focus, `inactive` without focus,
  * `background` when hidden. */
 export declare function useScenePhase(): ScenePhase;
-/** `colorScheme`: the appearance Satin is currently drawing, `light` or `dark`. */
+/** The appearance Satin is drawing right now, `light` or `dark`. */
 export declare function useColorScheme(): ColorScheme;
 /** Every glass renderer error so far, re-rendering when one is added. For diagnostics screens;
  * `runApp`'s `onGlassError` is the way to report them. */
 export declare function useGlassErrors(): readonly GlassError[];
 /**
- * `@SceneStorage`: state kept with the current navigation entry in the scene checkpoint,
- * so a draft survives a relaunch. Each pushed entry owns its own value. Values must be
- * JSON-serializable. Keep saved records in a collection, not here.
+ * State kept with the current navigation entry, so a draft survives a relaunch. Each pushed
+ * entry owns its own value. Values must be JSON-serializable. Keep saved records in a
+ * collection, not here.
  *
  * @example
  * const [draft, setDraft] = useSceneStorage('draft', '')
  */
 export declare function useSceneStorage<T>(key: string, initial: T): readonly [T, (next: SetStateAction<T>) => void];
 /**
- * `@AppStorage`: a small JSON-serializable preference, kept across launches and shared by
- * every component that reads the same key.
+ * A small preference kept in local storage across launches. Every component that reads the same
+ * key sees the same value. Values must be JSON-serializable.
  *
  * @example
  * const [units, setUnits] = useAppStorage('units', 'kg')
@@ -62,16 +64,17 @@ export type NotificationPermissionExplainerProps = {
 /** Explains what notifications are for before the user asks for them; its button requests
  * authorization from that gesture. */
 export declare function NotificationPermissionExplainer({ title, children, }: NotificationPermissionExplainerProps): import("react").JSX.Element;
-/** `EdgeInsets`: logical safe-area padding in points. */
+/** Insets on each edge in points. `leading` and `trailing` follow the layout direction. */
 export type EdgeInsets = Readonly<{
     top: number;
     leading: number;
     bottom: number;
     trailing: number;
 }>;
-/** `UserInterfaceSizeClass`: the available size along one axis. */
+/** How much room there is along one axis: `compact` or `regular`. */
 export type UserInterfaceSizeClass = 'compact' | 'regular';
-/** `ScenePhase`: the foreground, focus and suspension state. */
+/** Whether the app is in the foreground with focus (`active`), without focus (`inactive`) or
+ * hidden (`background`). */
 export type ScenePhase = 'active' | 'inactive' | 'background';
-/** `ColorScheme`: the appearance currently drawn by the scene. */
+/** A light or dark appearance. */
 export type ColorScheme = 'light' | 'dark';

package/dist/public/environment.js

@@ -18,13 +18,15 @@ export function useAppUpdate() {
     const { justUpdated, launchReady } = useSatinLayoutRuntime();
     return { justUpdated: launchReady ? justUpdated : null };
 }
-/** `horizontalSizeClass`: a presentation's own class inside it, else the window's. */
+/** The horizontal size class: `compact` or `regular`. Inside a presentation it is the
+ * presentation's own class; elsewhere, the window's. */
 export function useHorizontalSizeClass() {
     const presentation = useContext(PresentationLayoutClassContext);
     const runtime = useSatinLayoutRuntime().layoutClass;
     return (presentation ?? runtime).horizontal;
 }
-/** `verticalSizeClass`: a presentation's own class inside it, else the window's. */
+/** The vertical size class: `compact` or `regular`. Inside a presentation it is the
+ * presentation's own class; elsewhere, the window's. */
 export function useVerticalSizeClass() {
     const presentation = useContext(PresentationLayoutClassContext);
     const runtime = useSatinLayoutRuntime().layoutClass;
@@ -48,12 +50,12 @@ function subscribeScene(listener) {
         window.removeEventListener('blur', listener);
     };
 }
-/** `scenePhase`: `active` in the foreground with focus, `inactive` without focus,
+/** Whether the app is in use: `active` in the foreground with focus, `inactive` without focus,
  * `background` when hidden. */
 export function useScenePhase() {
     return useSyncExternalStore(subscribeScene, sceneSnapshot, () => 'inactive');
 }
-/** `colorScheme`: the appearance Satin is currently drawing, `light` or `dark`. */
+/** The appearance Satin is drawing right now, `light` or `dark`. */
 export function useColorScheme() {
     const store = window.__SATIN_APPEARANCE__;
     if (!store)
@@ -77,9 +79,9 @@ function schema(initial) {
     };
 }
 /**
- * `@SceneStorage`: state kept with the current navigation entry in the scene checkpoint,
- * so a draft survives a relaunch. Each pushed entry owns its own value. Values must be
- * JSON-serializable. Keep saved records in a collection, not here.
+ * State kept with the current navigation entry, so a draft survives a relaunch. Each pushed
+ * entry owns its own value. Values must be JSON-serializable. Keep saved records in a
+ * collection, not here.
  *
  * @example
  * const [draft, setDraft] = useSceneStorage('draft', '')
@@ -90,8 +92,8 @@ export function useSceneStorage(key, initial) {
 }
 const preferenceListeners = new Set();
 /**
- * `@AppStorage`: a small JSON-serializable preference, kept across launches and shared by
- * every component that reads the same key.
+ * A small preference kept in local storage across launches. Every component that reads the same
+ * key sees the same value. Values must be JSON-serializable.
  *
  * @example
  * const [units, setUnits] = useAppStorage('units', 'kg')

package/dist/public/filePickers.d.ts

@@ -1,4 +1,4 @@
-/** Select one photo or video as file bytes through the system chooser. */
+/** The picker's label, the selected file and the kind of media it accepts. */
 export type PhotosPickerProps = {
     label?: string;
     selection: File | null;
@@ -9,9 +9,10 @@ export type PhotosPickerProps = {
     disabled?: boolean;
     onError?(error: Error): void;
 };
-/** Photos-library identifiers and persistent access are not exposed by WebKit. */
+/** A button that opens the system photo chooser and returns one photo or video as a `File`. */
 export declare function PhotosPicker({ label, selection, onSelectionChange, matching, ...props }: PhotosPickerProps): import("react").JSX.Element;
-/** Import files from the system chooser. Content types are MIME types or extensions. */
+/** The importer's label, the selected files and the content types it accepts, as MIME types or
+ * extensions. */
 export type FileImporterProps = {
     label?: string;
     selection: readonly File[];
@@ -21,5 +22,6 @@ export type FileImporterProps = {
     disabled?: boolean;
     onError?(error: Error): void;
 };
-/** Open the system file chooser from a user gesture. Cancel preserves selection. */
+/** A button that opens the system file chooser and returns the chosen files. Cancelling keeps the
+ * current selection. */
 export declare function FileImporter({ label, selection, onSelectionChange, allowedContentTypes, allowsMultipleSelection, ...props }: FileImporterProps): import("react").JSX.Element;

package/dist/public/filePickers.js

@@ -1,11 +1,12 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { NativeFilePicker } from './NativeFilePicker.js';
-/** Photos-library identifiers and persistent access are not exposed by WebKit. */
+/** A button that opens the system photo chooser and returns one photo or video as a `File`. */
 export function PhotosPicker({ label = 'Choose Photo', selection, onSelectionChange, matching = 'images', ...props }) {
     const accept = matching === 'images' ? 'image/*' : matching === 'videos' ? 'video/*' : 'image/*,video/*';
     return (_jsx(NativeFilePicker, { ...props, label: label, value: selection, accept: accept, onChange: files => onSelectionChange(files[0]) }));
 }
-/** Open the system file chooser from a user gesture. Cancel preserves selection. */
+/** A button that opens the system file chooser and returns the chosen files. Cancelling keeps the
+ * current selection. */
 export function FileImporter({ label = 'Import File', selection, onSelectionChange, allowedContentTypes, allowsMultipleSelection = false, ...props }) {
     return (_jsx(NativeFilePicker, { ...props, label: label, value: selection, onChange: onSelectionChange, accept: allowedContentTypes?.join(','), multiple: allowsMultipleSelection }));
 }

package/dist/public/glass.d.ts

@@ -1,12 +1,14 @@
 import type { HTMLAttributes } from 'react';
 import type { NamespaceID } from '../motion/matchedGeometry.js';
 import { Glass } from './glassValue.js';
-/** Public glass outlines. Sheet-specific corner geometry stays internal. */
+/** The outline of a glass effect: `capsule`, `circle` or a rounded rectangle with a corner radius
+ * in points. */
 export type GlassShape = 'capsule' | 'circle' | Readonly<{
     kind: 'roundedRectangle';
     cornerRadius: number;
 }>;
-/** The glass material, shape, DOM attributes and independent morph identity. */
+/** The glass material and shape, plus the namespace and id that let effects morph into each
+ * other. Plain div attributes also apply. */
 export type GlassEffectProps = HTMLAttributes<HTMLDivElement> & {
     glass?: Glass;
     shape?: GlassShape;
@@ -20,7 +22,8 @@ export type GlassEffectProps = HTMLAttributes<HTMLDivElement> & {
     glassEffectTransition?: 'matchedGeometry' | 'materialize' | 'identity';
 };
 /**
- * Draws glass behind its content in the given shape, using a capsule by default. Inside a `GlassEffectContainer`, effects with ids morph into one another.
+ * Draws glass behind its content in the given shape, a capsule by default. Inside a
+ * `GlassEffectContainer`, effects with ids morph into one another.
  *
  * @example
  * <GlassEffect glass={Glass.regular.interactive()} shape="circle">

package/dist/public/glass.js

@@ -3,7 +3,8 @@ import { Glass, resolveGlass } from './glassValue.js';
 import { GlassFieldContext } from './fieldContext.js';
 import { GlassEffect as Effect } from '../glass/GlassEffect.js';
 /**
- * Draws glass behind its content in the given shape, using a capsule by default. Inside a `GlassEffectContainer`, effects with ids morph into one another.
+ * Draws glass behind its content in the given shape, a capsule by default. Inside a
+ * `GlassEffectContainer`, effects with ids morph into one another.
  *
  * @example
  * <GlassEffect glass={Glass.regular.interactive()} shape="circle">

package/dist/public/glassValue.d.ts

@@ -1,8 +1,7 @@
 import { Glass as Material, type GlassTint } from '../glass/regions.js';
 /**
- * `Glass`: the material intent for a `GlassEffect`. Start from `Glass.regular` or
- * `Glass.clear` and refine it; each call returns a new value. The renderer's treatment stays
- * internal.
+ * The glass material for a `GlassEffect`. Start from `Glass.regular` or `Glass.clear` and refine
+ * it with a tint or `interactive()`; each call returns a new value.
  *
  * @example
  * Glass.regular.tintRGBA([0, 0.48, 1, 0.2]).interactive()
@@ -13,7 +12,7 @@ export declare class Glass {
     private constructor();
     /** Tints the glass with `[red, green, blue, alpha]`, each 0...1; no argument removes the tint. */
     tintRGBA(color?: GlassTint): Glass;
-    /** `interactive()`: the glass responds to touch. */
+    /** Makes the glass respond to touch. */
     interactive(enabled?: boolean): Glass;
 }
 export declare function resolveGlass(glass: Glass): Material;

package/dist/public/glassValue.js

@@ -1,9 +1,8 @@
 import { Glass as Material } from '../glass/regions.js';
 const materials = new WeakMap();
 /**
- * `Glass`: the material intent for a `GlassEffect`. Start from `Glass.regular` or
- * `Glass.clear` and refine it; each call returns a new value. The renderer's treatment stays
- * internal.
+ * The glass material for a `GlassEffect`. Start from `Glass.regular` or `Glass.clear` and refine
+ * it with a tint or `interactive()`; each call returns a new value.
  *
  * @example
  * Glass.regular.tintRGBA([0, 0.48, 1, 0.2]).interactive()
@@ -19,7 +18,7 @@ export class Glass {
     tintRGBA(color) {
         return new Glass(resolveGlass(this).tint(color));
     }
-    /** `interactive()`: the glass responds to touch. */
+    /** Makes the glass respond to touch. */
     interactive(enabled = true) {
         return new Glass(resolveGlass(this).interactive(enabled));
     }

package/dist/public/keyboard.d.ts

@@ -1,4 +1,7 @@
 import { type KeyboardMetrics as InternalKeyboardMetrics } from '../keyboard/adapter.js';
+/** The keyboard's current geometry in points, plus the software keyboard height to plan for at
+ * this window size. */
 export type KeyboardMetrics = Omit<InternalKeyboardMetrics, 'presentation' | 'anticipated'>;
-/** Keyboard geometry in points, including the expected software-keyboard height. */
+/** Returns the keyboard's geometry in points and re-renders as it changes. `expectedHeight` is the
+ * keyboard height to plan for before the keyboard has shown. */
 export declare function useKeyboardMetrics(): KeyboardMetrics;

package/dist/public/keyboard.js

@@ -1,5 +1,6 @@
 import { useKeyboardMetrics as useInternalKeyboardMetrics, } from '../keyboard/adapter.js';
-/** Keyboard geometry in points, including the expected software-keyboard height. */
+/** Returns the keyboard's geometry in points and re-renders as it changes. `expectedHeight` is the
+ * keyboard height to plan for before the keyboard has shown. */
 export function useKeyboardMetrics() {
     const { presentation: _presentation, anticipated: _anticipated, ...geometry } = useInternalKeyboardMetrics();
     return geometry;