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

package/dist/navigation/types.d.ts

@@ -3,20 +3,22 @@ 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;
     display?: TitleDisplayMode;
     visibility?: Visibility;
     title: string | ((params: Params) => string);
-    /** SwiftUI `navigationSubtitle`: a line under the title, inline or large. */
+    /** A line under the title, inline or large. */
     subtitle?: string;
 }>;
 export type TransitionControllerContext = Readonly<{
@@ -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/navigation/zoomGeometry.js

@@ -1,5 +1,5 @@
 /*
- * The geometry of SwiftUI's zoom navigation transition, as pure functions of a rectangle.
+ * Zoom navigation geometry, as pure functions of a rectangle.
  *
  * At every moment the pushed screen is shown inside a rounded "window" rectangle that moves between
  * the source view's frame and the full screen. As natively, the screen's content is scaled so its

package/dist/navigation/zoomMotion.d.ts

@@ -9,7 +9,7 @@ export type ZoomSprings = Readonly<{
     size: ZoomSpring;
 }>;
 /**
- * Push: the centre and the width move together, critically damped (half way at 88 ms; SwiftUI's
+ * Push: the centre and the width move together, critically damped (half way at 88 ms; the measured
  * duration 0.33 s); the height lags slightly. Native moves the width with the centre, so the
  * width shares the centre's spring here and the height takes the size spring (rms 0.002, 51 ticks).
  */

package/dist/navigation/zoomMotion.js

@@ -1,5 +1,5 @@
 /*
- * Measured values of SwiftUI's `.navigationTransition(.zoom(sourceID:in:))` on iOS 27.
+ * Measured spring values for the zoom navigation transition on iOS 27.
  *
  * native reference: a stock native fixture (a 180 pt tile with a 10 pt corner in a
  * NavigationStack grid, pushed to a full-screen page), iPhone 17 Pro Max Simulator, iOS 27.0.
@@ -10,7 +10,7 @@
  * (the measured reference, October 11).
  */
 /**
- * Push: the centre and the width move together, critically damped (half way at 88 ms; SwiftUI's
+ * Push: the centre and the width move together, critically damped (half way at 88 ms; the measured
  * duration 0.33 s); the height lags slightly. Native moves the width with the centre, so the
  * width shares the centre's spring here and the height takes the size spring (rms 0.002, 51 ticks).
  */

package/dist/navigation/zoomTransition.js

@@ -1,6 +1,5 @@
 /*
- * SwiftUI's zoom navigation transition: `matchedTransitionSource(id:in:)` on the view a push starts
- * from, and `.navigationTransition(.zoom(sourceID:in:))` on the pushed screen.
+ * Zoom navigation connects a MatchedTransitionSource to a screen configured with a zoom transition.
  *
  * A push whose screen asks for a zoom, and whose source is on screen in the screen it covers, grows
  * out of the source instead of sliding in. Its pop (the back button) and a downward drag on the
@@ -116,7 +115,7 @@ export function visibleZoomSource(entryKey, rear, excluded) {
     }
     return chosen?.view;
 }
-/** SwiftUI zooms only from a source the user can see: at least part of it in the viewport. */
+/** Zoom transitions require a visible source: at least part of it in the viewport. */
 function isOnScreen(view) {
     const bounds = view.getBoundingClientRect();
     if (!(bounds.width > 0 && bounds.height > 0))
@@ -950,7 +949,7 @@ export function windowKeyframes(from, to, springs, velocity) {
     frames.push({ ms: frames.at(-1).ms + FRAME_MS, rect: to });
     return frames;
 }
-/** A measured Core Animation spring as Satin's `Animation` (SwiftUI's duration/bounce mapping is
+/** A measured Core Animation spring as Satin's `Animation` (the duration/bounce representation is
  * exact: omega = 2π / duration, damping ratio = 1 − bounce). */
 function animationOf(spring) {
     return SpringAnimation.spring({

package/dist/presentation/Presentation.d.ts

@@ -19,7 +19,7 @@ export type SheetProps = PresentationProps & {
      * content that fills the card (Now Playing). A modal NavigationStack root's title is drawn by
      * its navigation bar either way. */
     titleVisibility?: 'visible' | 'hidden';
-    /** SwiftUI's `presentationDragIndicator`. `automatic` shows it only when there is more than one
+    /** Control the sheet drag indicator. `automatic` shows it only when there is more than one
      * detent to drag between, as native does. */
     dragIndicator?: 'automatic' | 'visible' | 'hidden';
 };
@@ -27,11 +27,11 @@ export declare function Sheet(props: SheetProps): import("react").JSX.Element |
 export type FullScreenCoverProps = PresentationProps & {
     children: ReactNode;
 };
-/** SwiftUI's `fullScreenCover`: an opaque presentation over the whole screen that slides up from
+/** An opaque presentation over the whole screen that slides up from
  * 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

@@ -23,7 +23,7 @@ export function Sheet(props) {
             props.onDismiss?.();
         } })) : null;
 }
-/** SwiftUI's `fullScreenCover`: an opaque presentation over the whole screen that slides up from
+/** An opaque presentation over the whole screen that slides up from
  * 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 function FullScreenCover({ children, ...props }) {
@@ -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/presentation/presentationSource.js

@@ -1,7 +1,7 @@
 /** The control a presentation grows from when the app names no anchor. Native iOS 27 presents
  * `confirmationDialog` as a popover from the view that asked for it: a swipe action's dialog points
  * at its row, a toolbar button's dialog grows out of the button. Satin's natural structure attaches
- * the dialog at screen level, so the pressed control stands in for SwiftUI's attachment point. */
+ * the dialog at screen level, so the pressed control supplies the attachment point. */
 const lastPress = new WeakMap();
 const tracked = new WeakSet();
 // A press older than this did not open the dialog (a timer or a data change did).

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<{