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

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;
@@ -45,8 +46,8 @@ export declare function MatchedGeometryEffect({ id, in: namespace, isSource, chi
  * 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

@@ -22,7 +22,8 @@ import { fadeSettleMs, runFrameTimes, sampleChannel, sampleProgress, } from './s
  */
 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;

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/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/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. */

package/dist/navigation/types.d.ts

@@ -3,13 +3,15 @@ import type { ComponentType } from 'react';
 import type { ScrollSnapshot } from '../scroll/types.js';
 declare const screenParamsType: unique symbol;
 export type PresentationKind = 'push';
-/** The progress phase of a navigation transition. */
+/** Where a screen is in a navigation transition: `entering`, `exiting` or `settled`. */
 export type TransitionPhase = 'settled' | 'entering' | 'exiting';
 export type TransitionOperation = 'pop' | 'popToRoot' | 'push' | 'replace';
+/** Whether a pushed screen shows its back button. `automatic` shows it; `hidden` removes it. */
 export type NavigationBackButtonBehavior = 'automatic' | 'hidden';
-/** `toolbarTitleDisplayMode`; `inlineLarge` draws the large title inside the bar row. */
+/** How a screen title is drawn: `inline` in the bar, `large` below it, `inlineLarge` large inside
+ * the bar row, or `none`. */
 export type TitleDisplayMode = 'inline' | 'large' | 'inlineLarge' | 'none';
-/** `toolbarVisibility(_:for: .navigationBar)`: a hidden bar reserves no row. */
+/** Whether the navigation bar shows. A hidden bar reserves no row. */
 export type Visibility = 'automatic' | 'visible' | 'hidden';
 export type NavigationBarDefinition<Params = unknown> = Readonly<{
     backButton?: NavigationBackButtonBehavior;
@@ -120,12 +122,12 @@ export type ScreenEntry<Id extends string = string, Params = unknown> = Readonly
 export type NavigatorState<Entry extends ScreenEntry = ScreenEntry> = Readonly<{
     entries: readonly Entry[];
 }>;
-/** The lifecycle state of a retained navigation entry. */
+/** Whether a screen is covered by another, and the phase of its current transition. */
 export type ScreenLifecycle = Readonly<{
     isCovered: boolean;
     phase: TransitionPhase;
 }>;
-/** Callbacks for a retained navigation entry appearing, being covered or disappearing. */
+/** The `appear` and `disappear` callbacks for `useScreenLifecycle`. */
 export type ScreenLifecycleCallbacks = Readonly<{
     appear?: () => void;
     disappear?: () => void;

package/dist/presentation/Presentation.d.ts

@@ -31,7 +31,7 @@ export type FullScreenCoverProps = PresentationProps & {
  * the bottom edge. It has no grabber and no interactive dismissal; close it with its binding or
  * `useDismiss()`. Its title labels the dialog for assistive technology and is not drawn. */
 export declare function FullScreenCover({ children, ...props }: FullScreenCoverProps): import("react").JSX.Element | null;
-/** The controlled text and keyboard intent of an alert's embedded field. */
+/** The text field inside an alert: its label, controlled text, prompt and keyboard intent. */
 export type AlertTextFieldProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'value' | 'defaultValue' | 'onChange' | 'onSubmit' | 'size' | 'placeholder'> & {
     label: string;
     value: string;
@@ -42,20 +42,21 @@ export type AlertTextFieldProps = Omit<InputHTMLAttributes<HTMLInputElement>, 'v
     labelPlacement?: 'leading' | 'above';
     prompt?: string;
 };
-/** An alert's presentation binding, message and leaf actions. */
+/** An alert's presentation binding, title, message, actions and optional text field. */
 export type AlertProps = PresentationProps & {
     message?: string;
     actions: readonly ActionItem[];
     textField?: AlertTextFieldProps;
 };
-/** A confirmation dialog's presentation binding, leaf actions and optional anchor. */
+/** A confirmation dialog's presentation binding, title, message, actions and optional anchor. */
 export type ConfirmationDialogProps = Omit<AlertProps, 'textField'> & {
     /** The view the popover points at. Defaults to the control that was pressed to open it (a swipe
-     * action's row). Native draws no Cancel
-     * button in the popover: a tap outside cancels, and the Cancel action stays for assistive technology. */
+     * action's row). The popover draws no Cancel button: a tap outside cancels, and the Cancel
+     * action stays for assistive technology. */
     anchor?: RefObject<HTMLElement | null>;
 };
-/** `alert`: a titled presentation with up to three leaf actions and an optional text field. */
+/** A centred alert with a title, an optional message, up to three actions and an optional text
+ * field. */
 export declare function Alert({ message, actions, textField, ...props }: AlertProps): import("react").JSX.Element;
-/** `confirmationDialog`: a titled action presentation anchored to its initiating control. */
+/** A titled set of actions, such as Delete and Cancel, shown next to the control that opened it. */
 export declare function ConfirmationDialog({ message, actions, anchor, ...props }: ConfirmationDialogProps): import("react").JSX.Element;

package/dist/presentation/Presentation.js

@@ -70,7 +70,8 @@ function validateActions(actions, alert) {
     if (actions.filter(action => action.role === 'cancel').length > 1)
         throw new Error('Presentation accepts at most one Cancel action.');
 }
-/** `alert`: a titled presentation with up to three leaf actions and an optional text field. */
+/** A centred alert with a title, an optional message, up to three actions and an optional text
+ * field. */
 export function Alert({ message, actions, textField, ...props }) {
     const isPresented = useColdLaunchPresentation(props.isPresented, props.onPresentedChange);
     props = { ...props, isPresented };
@@ -80,7 +81,7 @@ export function Alert({ message, actions, textField, ...props }) {
     // Input alerts retain the description while their editing target owns focus.
     return (_jsxs(Surface, { ...props, kind: "alert", describedBy: textField && message ? messageId : undefined, children: [message && (_jsx("p", { id: messageId, className: "satin-presentation-message", children: message })), textField && _jsx(AlertTextField, { ...textField }), _jsx(Actions, { actions: actions, active: props.isPresented, dismiss: () => props.onPresentedChange(false) })] }));
 }
-/** `confirmationDialog`: a titled action presentation anchored to its initiating control. */
+/** A titled set of actions, such as Delete and Cancel, shown next to the control that opened it. */
 export function ConfirmationDialog({ message, actions, anchor, ...props }) {
     const isPresented = useColdLaunchPresentation(props.isPresented, props.onPresentedChange);
     props = { ...props, isPresented };

package/dist/presentation/model.d.ts

@@ -41,7 +41,8 @@ export declare function sheetCornerShape(frame: ReturnType<typeof sheetFrame>, p
     bottomCornerRadius?: number | undefined;
     cornerStyle: 'continuous';
 };
-/** `PresentationDetent`: a sheet's supported resting height. */
+/** A height a sheet can rest at: `medium`, `large`, a fixed `height` in points or a `fraction` of
+ * the available height. */
 export type PresentationDetent = 'medium' | 'large' | Readonly<{
     height: number;
 }> | Readonly<{

package/dist/press/Pressable.d.ts

@@ -1,7 +1,9 @@
 import { type ButtonHTMLAttributes, type CSSProperties, type ReactNode } from 'react';
 import type { PressState } from './stateMachine.js';
-/** DOM activation handlers reserved for the Pressable interaction policy. */
+/** The DOM event handlers `Pressable` owns. Use `onPress` and `onPressStateChange` instead. */
 export type PressableOwnedHandlers = 'children' | 'disabled' | 'onBlur' | 'onClick' | 'onKeyDown' | 'onKeyUp' | 'onLostPointerCapture' | 'onPointerCancel' | 'onPointerDown' | 'onPointerMove' | 'onPointerUp';
+/** A pressable's `onPress` action, content and press feedback. An `iconOnly` pressable needs an
+ * `aria-label`. */
 export type PressableProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, PressableOwnedHandlers> & Readonly<{
     children?: ReactNode;
     disabled?: boolean;
@@ -16,4 +18,6 @@ export type PressableProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, Press
 }> | Readonly<{
     iconOnly?: false;
 }>);
+/** A plain tap target with no button chrome. It dims while pressed, and a touch that turns into a
+ * scroll does not fire `onPress`. Use it for custom tappable content. */
 export declare const Pressable: import("react").ForwardRefExoticComponent<PressableProps & import("react").RefAttributes<HTMLButtonElement>>;

package/dist/press/Pressable.js

@@ -1,6 +1,8 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { forwardRef } from 'react';
 import { usePressInteraction } from './usePressInteraction.js';
+/** A plain tap target with no button chrome. It dims while pressed, and a touch that turns into a
+ * scroll does not fire `onPress`. Use it for custom tappable content. */
 export const Pressable = forwardRef(function Pressable({ children, disabled = false, onPress, onPressStateChange, pressedStyle, feedback = 'opacity', iconOnly = false, style, type = 'button', ...props }, forwardedRef) {
     if (iconOnly && !props['aria-label']?.trim())
         throw new Error('An icon-only Pressable requires a meaningful aria-label.');

package/dist/press/stateMachine.d.ts

@@ -1,4 +1,4 @@
-/** Whether a press is idle, held or cancelled. */
+/** Whether a press is `idle`, held down (`pressed`) or cancelled (`deactivated`). */
 export type PressState = 'idle' | 'pressed' | 'deactivated';
 export interface PressBounds {
     readonly bottom: number;

package/dist/public/Label.d.ts

@@ -9,7 +9,8 @@ export type LabelProps = {
     labelStyle?: BuiltInLabelStyle | LabelStyle;
     style?: CSSProperties;
 };
-/** Combines a semantic title and icon. Hidden titles remain available to assistive technology; toolbar labels with icons show the icon alone. */
+/** A title with an icon. In a toolbar a label with an icon shows the icon alone; a hidden title
+ * stays available to assistive technology. */
 export declare function Label({ children, icon, symbol, labelStyle: requestedStyle, style: cssStyle, }: LabelProps): import("react").JSX.Element;
 /** The accessible name of a toolbar label that draws only an icon: a `Label` with an icon, or a
  * `SymbolImage`. A toolbar button or menu with such a label is a glass circle. */

package/dist/public/Label.js

@@ -3,7 +3,8 @@ import { isValidElement, useContext } from 'react';
 import { SymbolImage } from '../symbols/Symbol.js';
 import { ToolbarContext } from './toolbar.js';
 import { useControlStyle } from './controlStyle.js';
-/** Combines a semantic title and icon. Hidden titles remain available to assistive technology; toolbar labels with icons show the icon alone. */
+/** A title with an icon. In a toolbar a label with an icon shows the icon alone; a hidden title
+ * stays available to assistive technology. */
 export function Label({ children, icon, symbol, labelStyle: requestedStyle, style: cssStyle, }) {
     const environment = useControlStyle({ labelStyle: requestedStyle });
     const toolbar = useContext(ToolbarContext) !== false;

package/dist/public/Screen.d.ts

@@ -7,8 +7,7 @@ import { type NavigationTransition } from './navigationTransition.js';
 export type ScreenProps = {
     children: ReactNode;
     title?: string;
-    /** `navigationSubtitle`: inline, a 12 pt line under a 15 pt title; large, an 11 pt line
-     * under the large title. */
+    /** A line under the title: 12 pt under an inline 15 pt title, 11 pt under a large title. */
     subtitle?: string;
     titleDisplay?: 'large' | 'inline' | 'inlineLarge' | 'none';
     backButton?: 'automatic' | 'hidden';
@@ -18,12 +17,11 @@ export type ScreenProps = {
     toolbarMinimizationBehavior?: ToolbarMinimizationBehavior;
     toolbarMinimizationRestoration?: ToolbarMinimizationRestoration;
     toolbarMinimizationSafeAreaAdjustment?: ToolbarMinimizationSafeAreaAdjustment;
-    /** `toolbar`: `ToolbarItem`, `ToolbarItemGroup` and `ToolbarSpacer` elements. */
+    /** The screen's `ToolbarItem`, `ToolbarItemGroup` and `ToolbarSpacer` elements. */
     toolbar?: ReactNode;
-    /** `searchable`: a search field in the navigation bar drawer of this screen's primary
-     * scroll view. */
+    /** A search field for this screen, placed in the navigation bar drawer or the bottom toolbar. */
     searchable?: Searchable;
-    /** `navigationTransition`: how this screen arrives when pushed and leaves when popped.
+    /** How this screen arrives when pushed and leaves when popped.
      * `NavigationTransition.zoom(...)` grows it out of a `MatchedTransitionSource`. */
     navigationTransition?: NavigationTransition;
 };

package/dist/public/actions.d.ts

@@ -12,5 +12,6 @@ export type MenuProps = Readonly<{
      * @experimental Custom menu triggers may change. */
     trigger?: (props: MenuTriggerProps) => ReactNode;
 }>;
-/** Opens a menu of actions. Toolbar labels with symbols render as icon buttons; text labels render as capsules. */
+/** A button that opens a menu of actions. In a toolbar a symbol label draws an icon button and a
+ * text label draws a capsule. */
 export declare function Menu(props: MenuProps): import("react").JSX.Element;

package/dist/public/actions.js

@@ -4,7 +4,8 @@ import { Menu as EngineMenu } from '../glass/Menu.js';
 import { ToolbarContext } from './toolbar.js';
 import { Button } from './controls.js';
 export { ContextMenu } from '../actions/RowActions.js';
-/** Opens a menu of actions. Toolbar labels with symbols render as icon buttons; text labels render as capsules. */
+/** A button that opens a menu of actions. In a toolbar a symbol label draws an icon button and a
+ * text label draws a capsule. */
 export function Menu(props) {
     const toolbar = useContext(ToolbarContext);
     const trigger = props.trigger ??

package/dist/public/buttonBorderShape.d.ts

@@ -1,5 +1,6 @@
 import { type GlassShape } from '../glass/regions.js';
-/** `buttonBorderShape`. Fixed radii are measured in points. */
+/** The outline of a bordered button: `automatic`, `capsule`, or a rounded rectangle with a fixed
+ * corner radius in points. */
 export type ButtonBorderShape = 'automatic' | 'capsule' | Readonly<{
     kind: 'roundedRectangle';
     cornerRadius: number;

package/dist/public/colors.d.ts

@@ -1,6 +1,7 @@
-/** Appearance-aware UIKit system palette. Explicit CSS colors remain supported. */
+/** The names of the iOS system colours. Each has a light and a dark value. Plain CSS colours work
+ * too. */
 export type SystemColorName = 'blue' | 'brown' | 'cyan' | 'gray' | 'gray2' | 'gray3' | 'gray4' | 'gray5' | 'gray6' | 'green' | 'indigo' | 'mint' | 'orange' | 'pink' | 'purple' | 'red' | 'teal' | 'yellow';
-/** A named system color as a CSS color that follows the appearance.
+/** Returns a system colour as a CSS colour that follows light and dark appearance.
  * @example <Button tint={systemColor('orange')} onPress={start}>Start</Button> */
 export declare function systemColor(name: SystemColorName): string;
 declare const semanticColors: {
@@ -22,8 +23,10 @@ declare const semanticColors: {
     readonly tertiarySystemGroupedBackground: '--satin-tertiary-system-grouped-background';
     readonly tint: '--satin-tint';
 };
-/** UIKit's semantic colour names (`label`, `secondarySystemBackground`, …). */
+/** The names of the iOS semantic colours for text, fills, backgrounds, separators and tint
+ * (`label`, `secondarySystemBackground`, …). */
 export type SemanticColorName = keyof typeof semanticColors;
-/** UIKit semantic content colors, inherited by app content and portals. */
+/** Returns a semantic colour, such as `label` or `systemGroupedBackground`, as a CSS colour that
+ * follows light and dark appearance. It also resolves inside portals. */
 export declare function semanticColor(name: SemanticColorName): string;
 export {};

package/dist/public/colors.js

@@ -1,4 +1,4 @@
-/** A named system color as a CSS color that follows the appearance.
+/** Returns a system colour as a CSS colour that follows light and dark appearance.
  * @example <Button tint={systemColor('orange')} onPress={start}>Start</Button> */
 export function systemColor(name) {
     return `var(--satin-system-${name})`;
@@ -22,7 +22,8 @@ const semanticColors = {
     tertiarySystemGroupedBackground: '--satin-tertiary-system-grouped-background',
     tint: '--satin-tint',
 };
-/** UIKit semantic content colors, inherited by app content and portals. */
+/** Returns a semantic colour, such as `label` or `systemGroupedBackground`, as a CSS colour that
+ * follows light and dark appearance. It also resolves inside portals. */
 export function semanticColor(name) {
     return `var(${semanticColors[name]})`;
 }

package/dist/public/controlStyle.d.ts

@@ -1,51 +1,54 @@
 import { type CSSProperties, type ReactNode } from 'react';
-/** `ControlSize`. */
+/** A control's size, from `mini` to `extraLarge`. `regular` is the default. */
 export type ControlSize = 'mini' | 'small' | 'regular' | 'large' | 'extraLarge';
-/** `ButtonRole`. */
+/** A button's role. `destructive` draws it in red; `cancel` marks the action that backs out. */
 export type ButtonRole = 'destructive' | 'cancel';
-/** Built-in button styles, by their `buttonStyle` names. */
+/** The built-in button styles, by their `buttonStyle` names. `automatic` picks one for the
+ * context. */
 export type BuiltInButtonStyle = 'automatic' | 'bordered' | 'borderedProminent' | 'borderless' | 'plain' | 'glass' | 'glassProminent';
-/** The environment every custom control style receives. */
+/** What every custom control style receives: enabled state, control size and tint. */
 export type ControlConfiguration = Readonly<{
     isEnabled: boolean;
     controlSize: ControlSize;
     tint: string | undefined;
 }>;
-/** `ButtonStyleConfiguration`: what a custom `ButtonStyle` draws from. */
+/** What a custom `ButtonStyle` draws from: the label, the pressed state and the role, plus the
+ * shared control values. */
 export type ButtonStyleConfiguration = ControlConfiguration & Readonly<{
     label: ReactNode;
     isPressed: boolean;
     role: ButtonRole | undefined;
 }>;
-/** A custom framework `ButtonStyle`. Appearance only: return noninteractive content; Satin
- * owns the button. */
+/** A custom look for `Button`. `makeBody` returns noninteractive content; Satin still owns the
+ * button's press handling and accessibility. */
 export type ButtonStyle = Readonly<{
     makeBody(configuration: ButtonStyleConfiguration): ReactNode;
 }>;
-/** `LabelStyleConfiguration`: the label's title and icon. */
+/** What a custom `LabelStyle` draws from: the label's title and icon. */
 export type LabelStyleConfiguration = Readonly<{
     title: ReactNode;
     icon: ReactNode;
 }>;
-/** A custom framework `LabelStyle` that arranges a label's title and icon. */
+/** A custom arrangement of a label's title and icon. */
 export type LabelStyle = Readonly<{
     makeBody(configuration: LabelStyleConfiguration): ReactNode;
 }>;
-/** Built-in label styles. */
+/** The built-in label styles: the title, the icon or both. `automatic` picks for the context. */
 export type BuiltInLabelStyle = 'automatic' | 'titleAndIcon' | 'titleOnly' | 'iconOnly';
-/** `ToggleStyleConfiguration`: what a custom `ToggleStyle` draws from. */
+/** What a custom `ToggleStyle` draws from: the label, the on state and the pressed state, plus
+ * the shared control values. */
 export type ToggleStyleConfiguration = ControlConfiguration & Readonly<{
     label: ReactNode;
     isOn: boolean;
     isPressed: boolean;
 }>;
-/** A custom framework `ToggleStyle`. Its declared semantics are applied to the
- * framework-owned interactive element. */
+/** A custom look for `Toggle`. Satin applies the declared `semantics` (switch, checkbox or button)
+ * to the element it owns; `makeBody` draws the appearance. */
 export type ToggleStyle = Readonly<{
     semantics: 'switch' | 'checkbox' | 'button';
     makeBody(configuration: ToggleStyleConfiguration): ReactNode;
 }>;
-/** Built-in toggle styles. */
+/** The built-in toggle styles: `switch` or `button`. `automatic` picks for the context. */
 export type BuiltInToggleStyle = 'automatic' | 'switch' | 'button';
 /** The control environment a `ControlStyleProvider` sets for its subtree. */
 export type ControlStyleValues = Readonly<{