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

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

@@ -0,0 +1,158 @@
+import type { SystemColorName } from '../public/colors.js';
+import { type SymbolName } from '../symbols/Symbol.js';
+import { type ListItemID } from './editing.js';
+import type { RowActionsProps } from '../actions/types.js';
+import { type ForwardRefExoticComponent, type RefAttributes, type CSSProperties, type ReactNode } from 'react';
+import { type ScrollSurfaceProps } from '../scroll/ScrollSurface.js';
+import { type PressableProps } from '../press/Pressable.js';
+import type { Searchable } from '../search/searchable.js';
+export type ListEngineProps = Omit<ScrollSurfaceProps, 'axis'> & {
+    style?: CSSProperties;
+    variant?: 'insetGrouped' | 'plain' | 'grouped' | 'sidebar';
+    navigationTitle?: string;
+    navigationTitleDisplay?: 'large' | 'inline';
+    /** SwiftUI `searchable`: a search field in the navigation bar drawer above this List. */
+    searchable?: Searchable;
+    /** Default keeps measured header/footer gaps. Numbers are section gaps in points. */
+    listSectionSpacing?: 'default' | 'compact' | number;
+    /** Controls the scroll surface background, leaving row backgrounds intact. */
+    scrollContentBackground?: 'hidden' | 'visible';
+    /** SwiftUI `List(selection:)`, resolved by the public List. */
+    selectionBinding?: ListSelectionBinding;
+};
+/** A controlled List selection: one optional row, or a set of rows. */
+export type ListSelectionBinding = Readonly<{
+    mode: 'single';
+    value: ListItemID | null;
+    onChange: (next: ListItemID | null) => void;
+}> | Readonly<{
+    mode: 'multiple';
+    value: ReadonlySet<ListItemID>;
+    onChange: (next: Set<ListItemID>) => void;
+}>;
+export declare function List({ children, className, variant, navigationTitle, navigationTitleDisplay, searchable, listSectionSpacing, scrollContentBackground, selectionBinding, ...props }: ListEngineProps): import("react").JSX.Element;
+/** A section's rows and its optional header and footer. */
+export type SectionProps = {
+    style?: CSSProperties;
+    children: ReactNode;
+    header?: ReactNode;
+    footer?: ReactNode;
+    className?: string;
+};
+/** Per-row list properties. Insets are in points. */
+export type ListRowProps = RowActionsProps & {
+    children: ReactNode;
+    listRowInsets?: number | {
+        top?: number;
+        leading?: number;
+        bottom?: number;
+        trailing?: number;
+    };
+    listRowBackground?: string;
+    listRowSeparator?: 'visible' | 'hidden';
+    /** `moveDisabled`: no reorder handle in edit mode. Other rows can still pass it. */
+    moveDisabled?: boolean;
+    /** `deleteDisabled`: no swipe-to-delete or delete control for this row. */
+    deleteDisabled?: boolean;
+    /** `selectionDisabled`: the List selection skips this row. */
+    selectionDisabled?: boolean;
+};
+/**
+ * Explicit framework overrides for a single row, including custom content.
+ *
+ * A ListRow is always one row. Several children share it side by side, laid out
+ * as an HStack would (centred, 8 pt apart, a NavigationLink filling the rest);
+ * each separate row needs its own ListRow.
+ */
+export declare function ListRow({ children, listRowSeparator, listRowInsets, listRowBackground, }: ListRowProps): import("react").JSX.Element;
+/** `Section`: a group of rows in a `List` or `Form`, with an optional header and footer. */
+export declare function Section({ children, header, footer, className, style }: SectionProps): import("react").JSX.Element;
+export type RowProps = RowActionsProps & {
+    buttonProps?: Omit<PressableProps, 'children' | 'onPress'>;
+    label: ReactNode;
+    leading?: ReactNode;
+    trailing?: ReactNode;
+    onPress?: () => void;
+    disabled?: boolean;
+    destructive?: boolean;
+    className?: string;
+    value?: ReactNode;
+    accessibilityLabel?: string;
+};
+export declare const Row: ForwardRefExoticComponent<RowProps & RefAttributes<HTMLButtonElement>>;
+/** The symbol and its tile colour: a system colour name or any CSS colour. */
+export type RowIconProps = {
+    symbol: SymbolName;
+    color: SystemColorName | (string & {});
+};
+/** A Settings-style icon: a white symbol on a rounded colour tile, for a row's leading edge. */
+export declare function RowIcon({ symbol, color }: RowIconProps): import("react").JSX.Element;
+export declare function NavigationRow(props: Omit<RowProps, 'trailing'> & {
+    trailing?: ReactNode;
+}): import("react").JSX.Element;
+export declare function ValueRow(props: Omit<RowProps, 'onPress'> & {
+    value: ReactNode;
+}): import("react").JSX.Element;
+export declare function ButtonRow({ children, role, onPress, disabled, ...actions }: RowActionsProps & {
+    children: ReactNode;
+    role?: 'destructive';
+    onPress: () => void;
+    disabled?: boolean;
+}): import("react").JSX.Element;
+export { Toggle, ToggleRow, type ToggleProps } from './Toggle.js';
+export { Slider, SliderRow, type SliderProps } from './Slider.js';
+/** One option of a `Picker`. */
+export type Choice = {
+    id: string;
+    label: string;
+    /** The option's icon by symbol name. */
+    symbol?: SymbolName;
+    /** The option's icon as a React node, for an icon that is not a symbol. */
+    icon?: ReactNode;
+    /** The icon's colour (its `foregroundStyle`). An option with a colour and no icon shows a
+     * filled circle in that colour, the usual way to offer a colour. */
+    color?: string;
+    /** The option shows dimmed and can't be chosen. */
+    disabled?: boolean;
+};
+export type PickerRowProps = {
+    style?: CSSProperties;
+    label: string;
+    value: string;
+    onChange: (id: string) => void;
+    options: readonly Choice[];
+    presentation?: 'menu' | 'navigation';
+    onNavigate?: () => void;
+    disabled?: boolean;
+    leading?: ReactNode;
+};
+export declare function PickerRow({ label, value, onChange, options, presentation, onNavigate, disabled, leading, style, }: PickerRowProps): import("react").JSX.Element;
+export declare function PickerOptions({ label, value, onChange, options, disabled, style, labelPlacement, }: {
+    style?: CSSProperties;
+    label: string;
+    value: string;
+    onChange: (id: string) => void;
+    options: readonly Choice[];
+    disabled?: boolean;
+    labelPlacement?: 'row' | 'navigationTitle';
+}): import("react").JSX.Element;
+export type StepperProps = {
+    value: number;
+    onChange: (value: number) => void;
+    min?: number;
+    max?: number;
+    step?: number;
+    disabled?: boolean;
+    label: string;
+    onEditingChange?: (editing: boolean) => void;
+};
+export declare function StepperControl({ value, onChange, min, max, step, disabled, label, onEditingChange, }: StepperProps): import("react").JSX.Element;
+export declare function StepperRow(props: StepperProps): import("react").JSX.Element;
+export declare function SegmentedControl({ value, onChange, options, disabled, label, style: cssStyle, }: {
+    style?: CSSProperties;
+    value: string;
+    onChange: (id: string) => void;
+    options: readonly Choice[];
+    disabled?: boolean;
+    label?: string;
+}): import("react").JSX.Element;

package/dist/list-form/ListForm.js

@@ -0,0 +1,427 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { NavigationPaneContext } from '../navigation/navigationContext.js';
+import { SensoryButton } from '../haptics/SensoryButton.js';
+import { StepperButton } from './StepperButton.js';
+import { SymbolImage } from '../symbols/Symbol.js';
+import { Menu } from '../glass/Menu.js';
+import { observeSeparatorInsets } from './separatorInsets.js';
+import { ListRowContentContext } from './listContext.js';
+import { RowActions } from '../actions/RowActions.js';
+import { ForEach, forEachRows, ListItemContext, ListSelectionContext, useEditMode, } from './editing.js';
+import { ListItem } from './ListItem.js';
+import { resetReorderTransforms } from './reorder.js';
+import { RowMotionScope, useRowMotionGroup } from './rowMotionScope.js';
+import { isLayoutTransaction } from '../motion/layoutTransaction.js';
+import { Children, Fragment, forwardRef, isValidElement, useId, useContext, useLayoutEffect, useMemo, useRef, } from 'react';
+import { ListNavigationContext, ScrollSurface, } from '../scroll/ScrollSurface.js';
+import { Pressable } from '../press/Pressable.js';
+import { DisclosureIndicator } from '../settings/DisclosureIndicator.js';
+import { readDeviceIdiom } from '../layout/deviceIdiom.js';
+/*
+ * The selection the rows see. A tap replaces a single selection and never clears it; a set
+ * selection toggles while editing and is replaced outside editing (native reference native reference `native editing fixture`
+ * and `native editing fixture` retap probes). Entering edit mode clears what was selected outside it.
+ */
+function useSelectionModel(binding) {
+    const [editMode] = useEditMode();
+    const latest = useRef(binding);
+    latest.current = binding;
+    const wasEditing = useRef(editMode === 'active');
+    useLayoutEffect(() => {
+        const entering = editMode === 'active' && !wasEditing.current;
+        wasEditing.current = editMode === 'active';
+        const current = latest.current;
+        if (!entering || !current)
+            return;
+        if (current.mode === 'single' && current.value !== null)
+            current.onChange(null);
+        if (current.mode === 'multiple' && current.value.size)
+            current.onChange(new Set());
+    }, [editMode]);
+    return useMemo(() => {
+        if (!binding)
+            return null;
+        return {
+            mode: binding.mode,
+            isSelected: id => (binding.mode === 'single' ? binding.value === id : binding.value.has(id)),
+            activate(id, editing) {
+                if (binding.mode === 'single') {
+                    if (binding.value !== id)
+                        binding.onChange(id);
+                    return;
+                }
+                if (!editing) {
+                    if (binding.value.size !== 1 || !binding.value.has(id))
+                        binding.onChange(new Set([id]));
+                    return;
+                }
+                const next = new Set(binding.value);
+                if (!next.delete(id))
+                    next.add(id);
+                binding.onChange(next);
+            },
+        };
+    }, [binding]);
+}
+export function List({ children, className, variant, navigationTitle, navigationTitleDisplay = 'large', searchable, listSectionSpacing = 'default', scrollContentBackground, selectionBinding, ...props }) {
+    const selection = useSelectionModel(selectionBinding);
+    if (listSectionSpacing !== 'default' &&
+        listSectionSpacing !== 'compact' &&
+        (typeof listSectionSpacing !== 'number' ||
+            !Number.isFinite(listSectionSpacing) ||
+            listSectionSpacing < 0)) {
+        throw new Error('listSectionSpacing requires default, compact, or a finite nonnegative point value.');
+    }
+    const pane = useContext(NavigationPaneContext);
+    const resolvedVariant = variant ?? (pane === 'sidebar' ? 'sidebar' : 'insetGrouped');
+    // The title and the bar's content inset belong to the screen's primary scroll view
+    // (ScrollSurface): a List nested below other content keeps its own frame.
+    return (_jsx(ListNavigationContext, { value: { title: navigationTitle, display: navigationTitleDisplay, searchable }, children: _jsx(ScrollSurface, { ...props, style: {
+                ...props.style,
+                ['--satin-list-section-spacing']: typeof listSectionSpacing === 'number' ? `${listSectionSpacing}px` : 'initial',
+            }, axis: "vertical", role: "list", "data-satin-list": resolvedVariant, "data-satin-scroll-content-background": scrollContentBackground, "data-satin-list-idiom": readDeviceIdiom(), "data-satin-list-section-spacing": listSectionSpacing === 'compact' ? 'compact' : undefined, className: className, children: _jsx(ListSelectionContext, { value: selection, children: _jsx(RowMotionScope, { children: _jsx(ListItems, { children: children }) }) }) }) }));
+}
+/** The rows of a list or section: fragments flatten, and each `ForEach` element becomes a row
+ * that knows its identity, offset and the `ForEach`'s editing. */
+function sectionRows(children, parentKeys = []) {
+    // Children.map gives every element a reconciliation key, including unkeyed ones.
+    // Read authored keys first so positional identity never becomes data identity.
+    const authoredKeys = [];
+    const normalized = Children.map(children, child => {
+        if (child !== null && child !== undefined && typeof child !== 'boolean') {
+            authoredKeys.push(isValidElement(child) ? child.key : null);
+        }
+        return child;
+    });
+    return (normalized ?? []).flatMap((child, index) => {
+        const keys = [...parentKeys, isValidElement(child) ? String(child.key ?? index) : String(index)];
+        if (isValidElement(child) && child.type === Fragment) {
+            return sectionRows(child.props.children, keys);
+        }
+        if (isValidElement(child) && child.type === ForEach) {
+            const { onDelete, onMove } = child.props;
+            const group = JSON.stringify(keys);
+            return forEachRows(child.props).map(row => ({
+                child: row.child,
+                key: JSON.stringify([...keys, row.key]),
+                motionID: row.id,
+                item: { id: row.id, offset: row.offset, editing: { onDelete, onMove }, group },
+            }));
+        }
+        return [{ child, key: JSON.stringify(keys), motionID: authoredKeys[index] ?? undefined }];
+    });
+}
+function listRowStyle({ listRowInsets, listRowBackground, }) {
+    const insets = typeof listRowInsets === 'number'
+        ? {
+            top: listRowInsets,
+            leading: listRowInsets,
+            bottom: listRowInsets,
+            trailing: listRowInsets,
+        }
+        : listRowInsets;
+    return {
+        '--satin-row-inset-top': insets?.top === undefined ? undefined : `${insets.top}px`,
+        '--satin-row-inset-leading': insets?.leading === undefined ? undefined : `${insets.leading}px`,
+        '--satin-row-inset-bottom': insets?.bottom === undefined ? undefined : `${insets.bottom}px`,
+        '--satin-row-inset-trailing': insets?.trailing === undefined ? undefined : `${insets.trailing}px`,
+        '--satin-row-background': listRowBackground,
+        '--satin-settings-separator-trailing': insets?.trailing === undefined ? undefined : `${insets.trailing}px`,
+        '--satin-row-separator-inset': insets?.leading === undefined ? undefined : `${insets.leading}px`,
+    };
+}
+/**
+ * Explicit framework overrides for a single row, including custom content.
+ *
+ * A ListRow is always one row. Several children share it side by side, laid out
+ * as an HStack would (centred, 8 pt apart, a NavigationLink filling the rest);
+ * each separate row needs its own ListRow.
+ */
+export function ListRow({ children, listRowSeparator, listRowInsets, listRowBackground, }) {
+    const options = { children, listRowInsets, listRowBackground };
+    return (_jsx("div", { "data-satin-list-row-options": "true", "data-satin-row-separator": listRowSeparator, "data-satin-row-insets": options.listRowInsets === undefined ? undefined : 'explicit', style: listRowStyle(options), children: _jsx(ListRowContentContext, { value: true, children: children }) }));
+}
+// React components may render null, portals, or hidden helpers. Keep them mounted,
+// but derive row participation from their local output rather than their type.
+function hasRowContent(node) {
+    return [...node.childNodes].some(child => {
+        if (child.nodeType === Node.TEXT_NODE)
+            return Boolean(child.textContent);
+        if (!(child instanceof Element))
+            return false;
+        // A presentation's <dialog> is shown in the top layer, never inside the row (Sheet, Alert).
+        if (child.matches('script, style, template, dialog, [hidden], input[type="hidden"], [data-satin-edit-control]'))
+            return false;
+        if (getComputedStyle(child).display === 'none')
+            return false;
+        if (child.hasAttribute('data-satin-list-row-options'))
+            return hasRowContent(child);
+        return true;
+    });
+}
+function ListItems({ children, section = false }) {
+    const rows = sectionRows(children);
+    const parentRef = useRef(null);
+    // An empty map must stay registered to animate its first insertion and last removal.
+    const { rows: motionGroup, settle } = useRowMotionGroup(true);
+    const order = rows
+        .filter(row => row.motionID !== undefined)
+        .map(row => row.key)
+        .join('\n');
+    const previousOrder = useRef(order);
+    useLayoutEffect(() => {
+        if (previousOrder.current !== order && !isLayoutTransaction())
+            settle();
+        previousOrder.current = order;
+    });
+    useLayoutEffect(() => {
+        const parent = parentRef.current;
+        if (!parent)
+            return;
+        const update = () => {
+            const siblings = [...parent.children];
+            const visible = siblings.filter(item => {
+                if (!item.hasAttribute('data-satin-section-item'))
+                    return true;
+                const empty = !hasRowContent(item);
+                item.toggleAttribute('data-satin-empty-row', empty);
+                const group = item.querySelector('[data-satin-list-section]');
+                item.setAttribute('role', empty || group ? 'presentation' : 'listitem');
+                return !empty;
+            });
+            visible.forEach((item, index) => {
+                const next = visible[index + 1];
+                item.toggleAttribute('data-satin-next-header', Boolean(next?.querySelector('[data-satin-section-header]')));
+                item.toggleAttribute('data-satin-next-empty-state', Boolean(next?.querySelector('[data-satin-empty-state]')));
+                if (!item.hasAttribute('data-satin-section-item'))
+                    return;
+                const isBoundary = (sibling) => !sibling ||
+                    !sibling.hasAttribute('data-satin-section-item') ||
+                    sibling.querySelector('[data-satin-list-section]') !== null;
+                item.toggleAttribute('data-satin-first-row', isBoundary(visible[index - 1]));
+                item.setAttribute('data-satin-last-row', String(isBoundary(visible[index + 1])));
+                item.toggleAttribute('data-satin-row-group-end', Boolean(visible[index + 1]) && isBoundary(visible[index + 1]));
+            });
+        };
+        update();
+        // A drop leaves rows where they landed until the new order renders; this is that render.
+        if (!parent.querySelector(':scope > [data-satin-reorder-lifted]'))
+            resetReorderTransforms(parent);
+        const observer = new MutationObserver(records => {
+            if (records.some(record => record.type !== 'attributes' ||
+                (record.target instanceof Element &&
+                    record.target.parentElement?.matches('[data-satin-section-item], [data-satin-list-row-options]'))))
+                update();
+        });
+        observer.observe(parent, {
+            childList: true,
+            subtree: true,
+            characterData: true,
+            attributes: true,
+            attributeFilter: ['hidden', 'style', 'class'],
+        });
+        return () => observer.disconnect();
+    }, [children]);
+    return (_jsx(_Fragment, { children: rows.map(({ child, key, motionID, item }, index) => {
+            // Keep explicit sections and authored titles as siblings. Opaque components
+            // that render sections are unboxed by the same semantic CSS boundary.
+            if (!section && isValidElement(child) && (child.type === Section || child.type === 'h1')) {
+                return _jsx(Fragment, { children: child }, key);
+            }
+            const options = isValidElement(child) && child.type === ListRow ? child.props : undefined;
+            const next = rows[index + 1]?.child;
+            const groupEnds = !section && isValidElement(next) && next.type === Section;
+            const itemRef = (element) => {
+                if (element)
+                    parentRef.current = element.parentElement;
+                if (motionID !== undefined) {
+                    if (element) {
+                        motionGroup.set(key, {
+                            identity: JSON.stringify([typeof motionID, motionID]),
+                            element,
+                        });
+                    }
+                    else {
+                        motionGroup.delete(key);
+                    }
+                }
+            };
+            const attributes = {
+                role: 'listitem',
+                'data-satin-section-item': 'true',
+                'data-satin-list-direct-row': section ? undefined : 'true',
+                'data-satin-last-row': index === rows.length - 1 || groupEnds ? 'true' : undefined,
+            };
+            const style = options ? listRowStyle(options) : undefined;
+            // Only rows that can edit or carry row actions pay for the editing item.
+            if (item || options?.swipeActions || options?.contextMenu)
+                return (_jsx(ListItem, { item: item, options: options, style: style, attributes: attributes, itemRef: itemRef, children: child }, key));
+            return (_jsx("div", { ref: itemRef, style: style, ...attributes, children: child }, key));
+        }) }));
+}
+/** `Section`: a group of rows in a `List` or `Form`, with an optional header and footer. */
+export function Section({ children, header, footer, className, style }) {
+    const headerId = useId();
+    const rowsRef = useRef(null);
+    const { rows: boundaryMotion } = useRowMotionGroup(Boolean(header || footer));
+    const boundaryRef = (kind) => (element) => {
+        if (element)
+            boundaryMotion.set(kind, { identity: JSON.stringify([kind, headerId]), element });
+        else
+            boundaryMotion.delete(kind);
+    };
+    useLayoutEffect(() => {
+        if (rowsRef.current)
+            return observeSeparatorInsets(rowsRef.current);
+    }, []);
+    return (_jsxs("section", { style: style, className: className, "data-satin-list-section": "true", role: "group", "aria-labelledby": header ? headerId : undefined, children: [header && (_jsx("div", { ref: boundaryRef('header'), id: headerId, role: "heading", "aria-level": 2, "data-satin-section-header": "true", children: header })), _jsx("div", { ref: rowsRef, "data-satin-section-rows": "true", children: _jsx(ListItems, { section: true, children: children }) }), footer && (_jsx("div", { ref: boundaryRef('footer'), "data-satin-section-footer": "true", children: footer }))] }));
+}
+export const Row = forwardRef(function Row({ swipeActions, contextMenu, buttonProps, label, leading, trailing, onPress, disabled = false, destructive = false, className, value, accessibilityLabel, }, ref) {
+    // While its List edits with a selection, the row's own action gives way to selecting it.
+    const item = useContext(ListItemContext);
+    const labels = (_jsxs(_Fragment, { children: [_jsx("span", { "data-satin-row-label": "true", children: typeof label === 'string' || typeof label === 'number' ? (_jsx("span", { "data-satin-row-text": "true", children: label })) : (label) }), _jsxs("span", { "data-satin-row-trailing": "true", children: [value != null && (_jsx("span", { "data-satin-row-value": "true", children: _jsx("span", { "data-satin-row-text": "true", children: value }) })), trailing] })] }));
+    const content = (_jsxs(_Fragment, { children: [_jsx("span", { "data-satin-row-leading": "true", children: leading }), value == null ? labels : _jsx("span", { "data-satin-row-value-content": "true", children: labels })] }));
+    const shared = {
+        className,
+        'data-satin-row': 'true',
+        'data-satin-row-disabled': disabled ? 'true' : undefined,
+        'data-satin-row-destructive': destructive ? 'true' : undefined,
+    };
+    const row = onPress ? (_jsx(Pressable, { ...buttonProps, iconOnly: false, ...shared, ref: ref, feedback: "row", disabled: disabled, onPress: item?.pressSelects ? item.select : onPress, "aria-label": accessibilityLabel, children: content })) : (_jsx("div", { ...shared, "aria-label": accessibilityLabel, children: content }));
+    return swipeActions || contextMenu ? (_jsx(RowActions, { swipeActions: swipeActions, contextMenu: contextMenu, disabled: disabled, children: row })) : (row);
+});
+const tileColors = {
+    blue: 'var(--satin-system-blue, #0088ff)',
+    green: 'var(--satin-system-green, #34c759)',
+    red: 'var(--satin-system-red, #ff383c)',
+    orange: '#ff9500',
+    purple: '#af52de',
+    gray: '#8e8e93',
+};
+/** A Settings-style icon: a white symbol on a rounded colour tile, for a row's leading edge. */
+export function RowIcon({ symbol, color }) {
+    return (_jsx("span", { role: "presentation", "data-satin-row-icon": "true", style: { backgroundColor: tileColors[color] ?? color }, children: _jsx(SymbolImage, { name: symbol, style: { fontSize: 21.7 } }) }));
+}
+export function NavigationRow(props) {
+    return _jsx(Row, { ...props, trailing: props.trailing ?? _jsx(DisclosureIndicator, {}) });
+}
+export function ValueRow(props) {
+    return _jsx(Row, { ...props });
+}
+export function ButtonRow({ children, role, onPress, disabled, ...actions }) {
+    return (_jsx(Row, { ...actions, className: "satin-list-button", label: children, onPress: onPress, disabled: disabled, destructive: role === 'destructive' }));
+}
+export { Toggle, ToggleRow } from './Toggle.js';
+export { Slider, SliderRow } from './Slider.js';
+function isDecorated(choice) {
+    return choice.symbol !== undefined || choice.icon !== undefined || choice.color !== undefined;
+}
+function choiceGlyph(choice) {
+    if (choice.icon !== undefined && choice.symbol === undefined)
+        return choice.icon;
+    return _jsx(SymbolImage, { name: choice.symbol ?? 'circle.fill' });
+}
+/** The option's icon in a list row, in its own colour. Lists draw a Label's icon in colour. */
+function ChoiceIcon({ choice, colored }) {
+    if (!isDecorated(choice))
+        return null;
+    return (_jsx("span", { "data-satin-picker-choice-icon": "true", "aria-hidden": "true", style: colored && choice.color ? { color: choice.color } : undefined, children: choiceGlyph(choice) }));
+}
+/* The option as an entry in the open menu. Menus draw every icon in the label colour, so the
+ * option's colour is not passed on (iOS 27 native reference: a red `house` draws black in the menu). */
+function choiceMenuIcon(choice) {
+    if (!isDecorated(choice))
+        return {};
+    if (choice.symbol !== undefined)
+        return { symbol: choice.symbol };
+    if (choice.icon !== undefined)
+        return { icon: choice.icon };
+    return { symbol: 'circle.fill' };
+}
+/**
+ * Returns the function every Picker style calls to choose an option. It commits only what the
+ * Picker offers now: a menu entry or a pushed options list can outlive a render, so the press
+ * is checked against the latest options and disabled state, and ignored once the Picker is gone.
+ */
+function useChooseOption(state) {
+    const latest = useRef(state);
+    assertUniqueChoiceIds(state.options);
+    useLayoutEffect(() => {
+        latest.current = state;
+        return () => {
+            latest.current = null;
+        };
+    }, [state]);
+    return (id) => {
+        const current = latest.current;
+        if (!current || current.disabled)
+            return;
+        const option = current.options.find(choice => choice.id === id);
+        if (option && !option.disabled)
+            current.onChange(id);
+    };
+}
+function assertUniqueChoiceIds(options) {
+    const ids = new Set();
+    for (const option of options) {
+        if (ids.has(option.id))
+            throw new Error(`Picker option id "${option.id}" is duplicated.`);
+        ids.add(option.id);
+    }
+}
+function PickerMenuIndicator() {
+    return _jsx(SymbolImage, { name: "chevron.up.chevron.down", "data-satin-picker-indicator": "true" });
+}
+export function PickerRow({ label, value, onChange, options, presentation = 'menu', onNavigate, disabled = false, leading, style, }) {
+    const choose = useChooseOption({ options, disabled, onChange });
+    const selected = options.find(option => option.id === value);
+    const navigate = presentation === 'navigation';
+    if (navigate && !onNavigate)
+        throw new Error('PickerRow navigation presentation requires onNavigate.');
+    const valueLabel = pickerSelection(options, value) ?? value;
+    // A selected Label shows as its icon and title in the accent colour (iOS 27 native reference menu rest).
+    const decoratedValue = !navigate && selected !== undefined && isDecorated(selected);
+    return (_jsx("div", { style: style, "data-satin-picker": "true", "data-satin-picker-mode": presentation, children: _jsx(Row, { label: label, leading: leading, value: navigate ? (valueLabel) : (_jsx(Menu, { label: label, disabled: disabled, actions: options.map(option => ({
+                    id: option.id,
+                    label: option.label,
+                    ...choiceMenuIcon(option),
+                    checked: option.id === value,
+                    disabled: disabled || option.disabled,
+                    onPress: () => choose(option.id),
+                })), trigger: props => (_jsxs(Pressable, { ...props, disabled: disabled, "aria-label": `${label}, ${valueLabel}`, "data-satin-picker-trigger": "true", "data-satin-picker-decorated": decoratedValue ? 'true' : undefined, children: [decoratedValue && _jsx(ChoiceIcon, { choice: selected, colored: false }), _jsx("span", { children: valueLabel }), _jsx(PickerMenuIndicator, {})] })) })), trailing: navigate ? _jsx(DisclosureIndicator, {}) : undefined, disabled: disabled, onPress: navigate ? onNavigate : undefined, accessibilityLabel: navigate ? `${label}, ${valueLabel}` : undefined }) }));
+}
+export function PickerOptions({ label, value, onChange, options, disabled, style, labelPlacement = 'row', }) {
+    const choose = useChooseOption({ options, disabled, onChange });
+    return (_jsxs(Section, { style: style, children: [labelPlacement === 'row' && _jsx(Row, { label: label, disabled: disabled }), options.map(option => (_jsx(Row, { disabled: disabled || option.disabled, label: option.label, leading: _jsx(ChoiceIcon, { choice: option, colored: true }), className: isDecorated(option)
+                    ? 'satin-picker-choice satin-picker-choice-decorated'
+                    : 'satin-picker-choice', trailing: option.id === value ? _jsx(SymbolImage, { name: "checkmark" }) : undefined, onPress: () => choose(option.id), accessibilityLabel: `${option.label}${option.id === value ? ', selected' : ''}` }, option.id)))] }));
+}
+import { clampStepper, pickerSelection } from './state.js';
+export function StepperControl({ value, onChange, min = -Infinity, max = Infinity, step = 1, disabled = false, label, onEditingChange, }) {
+    if (Number.isNaN(min) || Number.isNaN(max) || min > max) {
+        throw new Error('StepperControl bounds must be ordered numbers.');
+    }
+    if (!Number.isFinite(value)) {
+        throw new Error('StepperControl value must be finite.');
+    }
+    if (!Number.isFinite(step) || step <= 0) {
+        throw new Error('StepperControl step must be finite and greater than zero.');
+    }
+    return (_jsxs("span", { "data-satin-row-intrinsic": "true", "data-satin-stepper": "true", "data-satin-stepper-disabled": disabled ? 'true' : undefined, role: "group", "aria-label": `${label}, ${value}`, children: [_jsx(StepperButton, { onEditingChange: onEditingChange, label: `Decrease ${label}, ${value}`, disabled: disabled || value <= min, onStep: () => onChange(clampStepper(value, min, max, -step)), children: _jsx(SymbolImage, { name: "minus", weight: "medium" }) }), _jsx(StepperButton, { onEditingChange: onEditingChange, label: `Increase ${label}, ${value}`, disabled: disabled || value >= max, onStep: () => onChange(clampStepper(value, min, max, step)), children: _jsx(SymbolImage, { name: "plus", weight: "semibold" }) })] }));
+}
+export function StepperRow(props) {
+    return _jsx(Row, { label: props.label, trailing: _jsx(StepperControl, { ...props }) });
+}
+export function SegmentedControl({ value, onChange, options, disabled = false, label = 'Options', style: cssStyle, }) {
+    const choose = useChooseOption({ options, disabled, onChange });
+    const selectionIndex = options.findIndex(option => option.id === value);
+    if (selectionIndex < 0) {
+        throw new Error(`SegmentedControl value "${value}" is not present in options.`);
+    }
+    const style = {
+        '--satin-segment-count': options.length,
+        '--satin-segment-index': selectionIndex,
+        ...cssStyle,
+    };
+    return (_jsxs("div", { "data-satin-segmented": "true", "data-satin-segmented-disabled": disabled ? 'true' : undefined, role: "group", "aria-label": label, style: style, children: [_jsx("span", { "data-satin-segmented-selection": "true", role: "presentation" }), options.map(option => (_jsx(SensoryButton, { sensoryFeedback: value === option.id ? false : 'selection', "aria-pressed": value === option.id, disabled: disabled || option.disabled, "data-satin-segment-disabled": option.disabled ? 'true' : undefined, onPress: () => choose(option.id), children: _jsx("span", { children: option.label }) }, option.id)))] }));
+}

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

@@ -0,0 +1,30 @@
+import { type CSSProperties, type ReactNode } from 'react';
+import type { RowActionsProps } from '../actions/types.js';
+import { type ForEachEditing, type ListItemID } from './editing.js';
+/** Where a `ForEach` row came from: its identity, offset and the editing its `ForEach` declares. */
+export type ForEachItem = Readonly<{
+    id: ListItemID;
+    offset: number;
+    editing: ForEachEditing;
+    /** Rows of one `ForEach` in one section reorder among themselves. */
+    group: string;
+}>;
+/** The `ListRow` modifiers an item applies to its row. */
+export type ListItemOptions = RowActionsProps & Readonly<{
+    moveDisabled?: boolean;
+    deleteDisabled?: boolean;
+    selectionDisabled?: boolean;
+}>;
+/**
+ * One row of a `List` or `Section`. For a `ForEach` row it also draws edit mode: the delete and
+ * selection controls before the content, the reorder handle after it, the selected highlight, and
+ * the measured shift between the two layouts.
+ */
+export declare function ListItem({ children, item, options, style, attributes, itemRef, }: {
+    children: ReactNode;
+    item?: ForEachItem;
+    options?: ListItemOptions;
+    style?: CSSProperties;
+    attributes: Record<string, string | undefined>;
+    itemRef: (element: HTMLDivElement | null) => void;
+}): import("react").JSX.Element;