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

package/dist/public/Label.js

@@ -0,0 +1,40 @@
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+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. */
+export function Label({ children, icon, symbol, labelStyle: requestedStyle, style: cssStyle, }) {
+    const environment = useControlStyle({ labelStyle: requestedStyle });
+    const toolbar = useContext(ToolbarContext) !== false;
+    const style = environment.labelStyle ?? 'automatic';
+    // A toolbar draws symbols at its own 22 pt size, as a toolbar Button's `symbol` does.
+    const resolvedIcon = icon ??
+        (symbol ? _jsx(SymbolImage, { name: symbol, style: toolbar ? { fontSize: 22 } : undefined }) : null);
+    if (typeof style === 'object') {
+        const body = style.makeBody({ title: children, icon: resolvedIcon });
+        return cssStyle ? _jsx("span", { style: cssStyle, children: body }) : _jsx(_Fragment, { children: body });
+    }
+    const iconOnly = style === 'iconOnly' ||
+        (style === 'automatic' && environment.labelsHidden) ||
+        (toolbar && resolvedIcon !== null);
+    return (_jsxs("span", { style: cssStyle, "data-satin-label": "true", "data-satin-label-style": iconOnly ? 'iconOnly' : style, children: [style !== 'titleOnly' && (_jsx("span", { "aria-hidden": "true", style: environment.tint
+                    ? { '--satin-label-tint': environment.tint }
+                    : undefined, children: resolvedIcon })), _jsx("span", { className: iconOnly ? 'satin-control-accessible-title' : undefined, children: children })] }));
+}
+/** 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. */
+export function toolbarIconName(label) {
+    if (!isValidElement(label))
+        return;
+    if (label.type === SymbolImage) {
+        const props = label.props;
+        return props.label ?? props.name;
+    }
+    if (label.type !== Label)
+        return;
+    const props = label.props;
+    if (!props.icon && !props.symbol)
+        return;
+    return typeof props.children === 'string' ? props.children : (props.symbol ?? 'Icon');
+}

package/dist/public/NativeFilePicker.d.ts

@@ -0,0 +1,19 @@
+/** One image candidate as File bytes, without PhotosUI selection identity. */
+export type NativeFilePickerProps = {
+    label: string;
+    /** The app's accepted selection. Never populates the native FileList. */
+    value: File | readonly File[] | null;
+    onChange(files: File[]): void;
+    accept?: string;
+    capture?: 'user' | 'environment';
+    multiple?: boolean;
+    disabled?: boolean;
+    /** Only synchronous activation failures, never cancellation or decoding errors. */
+    onError?(error: Error): void;
+};
+/**
+ * A native file-input bridge. Decoding, storage and preview URLs belong to the app.
+ * Key or unmount this control when replacing a draft whose accepted File is unchanged.
+ * Chooser results have no platform session ID; overlapping chooser attribution is not promised.
+ */
+export declare function NativeFilePicker({ label, value, onChange, disabled, onError, accept, capture, multiple, }: NativeFilePickerProps): import("react").JSX.Element;

package/dist/public/NativeFilePicker.js

@@ -0,0 +1,75 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useContext, useId, useLayoutEffect, useRef } from 'react';
+import { usePressInteraction } from '../press/usePressInteraction.js';
+import { Row } from '../list-form/ListForm.js';
+import { ScreenContext } from '../navigation/navigationContext.js';
+import { controlTintStyle, useControlStyle } from './controlStyle.js';
+/**
+ * A native file-input bridge. Decoding, storage and preview URLs belong to the app.
+ * Key or unmount this control when replacing a draft whose accepted File is unchanged.
+ * Chooser results have no platform session ID; overlapping chooser attribution is not promised.
+ */
+export function NativeFilePicker({ label, value, onChange, disabled, onError, accept, capture, multiple = false, }) {
+    const configuration = useControlStyle({ disabled });
+    const screen = useContext(ScreenContext);
+    const labelId = useId();
+    const owner = useRef({ generation: 0, mounted: false, disabled: true, onChange, onError });
+    const activationGeneration = useRef(undefined);
+    const covered = screen?.lifecycle.isCovered ?? false;
+    const press = usePressInteraction({
+        disabled: configuration.disabled || covered,
+        feedback: 'row',
+        nativeActivation: true,
+    });
+    useLayoutEffect(() => {
+        const current = owner.current;
+        current.generation += 1;
+        current.disabled = configuration.disabled || covered;
+        current.mounted = true;
+        return () => {
+            current.mounted = false;
+            current.generation += 1;
+        };
+    }, [configuration.disabled, covered, screen?.key, value, accept, capture, multiple]);
+    useLayoutEffect(() => {
+        owner.current.onChange = onChange;
+        owner.current.onError = onError;
+    });
+    const available = (input) => owner.current.mounted &&
+        !owner.current.disabled &&
+        input.isConnected &&
+        !input.closest('[inert], [aria-hidden="true"]');
+    return (_jsxs("div", { "data-satin-file-picker": "true", ...press.attributes, style: controlTintStyle(configuration.tint), children: [_jsx(Row, { className: "satin-list-button", disabled: configuration.disabled, label: _jsx("span", { id: labelId, "data-satin-row-text": "true", children: label }) }), _jsx("input", { ref: press.elementRef, ...press.handlers, "data-satin-role": "chrome", type: "file", accept: accept, capture: capture, multiple: multiple, "aria-labelledby": labelId, disabled: configuration.disabled || covered, onClick: event => {
+                    const input = event.currentTarget;
+                    if (!available(input)) {
+                        event.preventDefault();
+                        return;
+                    }
+                    activationGeneration.current = owner.current.generation;
+                    // Preserve the input's native default when showPicker is unavailable.
+                    if (typeof input.showPicker !== 'function')
+                        return;
+                    event.preventDefault();
+                    try {
+                        input.showPicker();
+                    }
+                    catch (failure) {
+                        activationGeneration.current = undefined;
+                        owner.current.onError?.(failure instanceof Error ? failure : new Error(String(failure)));
+                    }
+                }, onChange: event => {
+                    const input = event.currentTarget;
+                    const files = Array.from(input.files ?? []);
+                    // Retain bytes before clearing so the same file can be chosen again.
+                    input.value = '';
+                    const generation = activationGeneration.current;
+                    activationGeneration.current = undefined;
+                    if (files.length === 0 || generation !== owner.current.generation || !available(input))
+                        return;
+                    queueMicrotask(() => {
+                        if (owner.current.generation === generation && available(input)) {
+                            owner.current.onChange(files);
+                        }
+                    });
+                } })] }));
+}

package/dist/public/Screen.d.ts

@@ -0,0 +1,42 @@
+import type { ToolbarMinimizationBehavior, ToolbarMinimizationRestoration, ToolbarMinimizationSafeAreaAdjustment } from '../navigation/toolbarMinimization.js';
+import { type ReactNode } from 'react';
+import type { Visibility } from '../navigation/types.js';
+import type { Searchable } from '../search/searchable.js';
+import { type NavigationTransition } from './navigationTransition.js';
+/** A screen's own chrome, overriding its route's static options. */
+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. */
+    subtitle?: string;
+    titleDisplay?: 'large' | 'inline' | 'inlineLarge' | 'none';
+    backButton?: 'automatic' | 'hidden';
+    /** The navigation bar's visibility. */
+    toolbarVisibility?: Visibility;
+    /** Opt-in navigation-bar minimization; use never to keep the bar expanded. */
+    toolbarMinimizationBehavior?: ToolbarMinimizationBehavior;
+    toolbarMinimizationRestoration?: ToolbarMinimizationRestoration;
+    toolbarMinimizationSafeAreaAdjustment?: ToolbarMinimizationSafeAreaAdjustment;
+    /** `toolbar`: `ToolbarItem`, `ToolbarItemGroup` and `ToolbarSpacer` elements. */
+    toolbar?: ReactNode;
+    /** `searchable`: a search field in the navigation bar drawer of this screen's primary
+     * scroll view. */
+    searchable?: Searchable;
+    /** `navigationTransition`: how this screen arrives when pushed and leaves when popped.
+     * `NavigationTransition.zoom(...)` grows it out of a `MatchedTransitionSource`. */
+    navigationTransition?: NavigationTransition;
+};
+/**
+ * A route component's navigation chrome: title, toolbar, search and
+ * related options, declared by the screen that owns them. Use it when the title or toolbar
+ * depends on the screen's data; static chrome belongs in the route's options.
+ *
+ * @example
+ * <Screen title={note.title} toolbar={
+ *   <ToolbarItem placement="confirmationAction"><Button onPress={save}>Done</Button></ToolbarItem>
+ * }>
+ *   <List id="note">...</List>
+ * </Screen>
+ */
+export declare function Screen({ children, title, subtitle, titleDisplay, backButton, toolbarVisibility, toolbarMinimizationBehavior, toolbarMinimizationRestoration, toolbarMinimizationSafeAreaAdjustment, toolbar, searchable, navigationTransition, }: ScreenProps): import("react").JSX.Element;

package/dist/public/Screen.js

@@ -0,0 +1,87 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Children, useCallback, useContext, useLayoutEffect, useState, useSyncExternalStore, } from 'react';
+import { ScreenContext } from '../navigation/navigationContext.js';
+import { NavigationLayoutContext } from '../layout/navigationLayoutContext.js';
+import { useLayoutClass } from '../root/runtimeContext.js';
+import { ScreenChromeContext, ScreenContentContext } from './screenChrome.js';
+import { useNavigationTransition } from './navigationTransition.js';
+import { BottomBarRegistrationContext, SearchToolbarItemContext, ToolbarSlotsContext, } from './toolbar.js';
+/**
+ * A route component's navigation chrome: title, toolbar, search and
+ * related options, declared by the screen that owns them. Use it when the title or toolbar
+ * depends on the screen's data; static chrome belongs in the route's options.
+ *
+ * @example
+ * <Screen title={note.title} toolbar={
+ *   <ToolbarItem placement="confirmationAction"><Button onPress={save}>Done</Button></ToolbarItem>
+ * }>
+ *   <List id="note">...</List>
+ * </Screen>
+ */
+export function Screen({ children, title, subtitle, titleDisplay, backButton, toolbarVisibility, toolbarMinimizationBehavior, toolbarMinimizationRestoration, toolbarMinimizationSafeAreaAdjustment, toolbar, searchable, navigationTransition, }) {
+    const screen = useContext(ScreenContext), store = useContext(ScreenChromeContext);
+    if (!screen || !store)
+        throw new Error('Screen requires NavigationStack');
+    useNavigationTransition(screen.key, navigationTransition);
+    useSyncExternalStore(store.subscribe, store.snapshot, store.snapshot);
+    const hasToolbar = Children.toArray(toolbar).length > 0;
+    useLayoutEffect(() => {
+        store.set(screen.key, {
+            title,
+            subtitle,
+            titleDisplay,
+            backButton,
+            toolbarVisibility,
+            toolbarMinimizationBehavior,
+            toolbarMinimizationRestoration,
+            toolbarMinimizationSafeAreaAdjustment,
+            hasToolbar,
+        });
+        return () => store.set(screen.key);
+    }, [
+        store,
+        screen.key,
+        title,
+        subtitle,
+        titleDisplay,
+        backButton,
+        toolbarVisibility,
+        hasToolbar,
+        toolbarMinimizationBehavior,
+        toolbarMinimizationRestoration,
+        toolbarMinimizationSafeAreaAdjustment,
+    ]);
+    const defaults = useContext(ScreenContentContext);
+    // The bottom toolbar occupies the bottom safe area, so the primary scroll view's content clears it.
+    const [bottomBars, setBottomBars] = useState(0);
+    const registerBottomBar = useCallback(() => {
+        setBottomBars(count => count + 1);
+        return () => setBottomBars(count => count - 1);
+    }, []);
+    const [searchToolbarItem, setSearchToolbarItem] = useState(null);
+    const bottomToolbar = store.slots.get(screen.key)?.bottom ?? undefined;
+    const scopedHorizontal = useContext(NavigationLayoutContext);
+    const runtimeHorizontal = useLayoutClass().horizontal;
+    const horizontalSizeClass = scopedHorizontal ?? runtimeHorizontal;
+    return (_jsxs(ScreenContentContext, { value: {
+            ...defaults,
+            ...(bottomBars > 0 ? { hasBottomBar: true } : {}),
+            hasToolbar,
+            bottomToolbar,
+            trailingToolbar: store.slots.get(screen.key)?.trailing ?? undefined,
+            searchToolbarItem: searchToolbarItem ?? undefined,
+            horizontalSizeClass,
+            ...(title !== undefined ? { title } : {}),
+            ...(subtitle !== undefined ? { subtitle } : {}),
+            ...(titleDisplay !== undefined ? { titleDisplay } : {}),
+            ...(backButton !== undefined ? { backButton } : {}),
+            ...(toolbarVisibility !== undefined ? { toolbarVisibility } : {}),
+            ...(toolbarMinimizationBehavior !== undefined ? { toolbarMinimizationBehavior } : {}),
+            ...(toolbarMinimizationRestoration !== undefined ? { toolbarMinimizationRestoration } : {}),
+            ...(toolbarMinimizationSafeAreaAdjustment !== undefined
+                ? { toolbarMinimizationSafeAreaAdjustment }
+                : {}),
+            // A screen's search belongs to that screen alone, never to a screen presented from it.
+            searchable,
+        }, children: [children, store.slots.has(screen.key) && (_jsx(BottomBarRegistrationContext, { value: registerBottomBar, children: _jsx(SearchToolbarItemContext, { value: setSearchToolbarItem, children: _jsx(ToolbarSlotsContext, { value: store.slots.get(screen.key), children: toolbar }) }) }))] }));
+}

package/dist/public/actions.d.ts

@@ -0,0 +1,16 @@
+import { type ReactNode } from 'react';
+import { type MenuTriggerProps } from '../glass/Menu.js';
+import type { Action } from '../actions/types.js';
+export { ContextMenu } from '../actions/RowActions.js';
+export type { Action } from '../actions/types.js';
+/** A menu's label and its actions. */
+export type MenuProps = Readonly<{
+    /** What the menu's button shows. In a toolbar a Symbol or an icon Label draws a glass circle. */
+    label: ReactNode;
+    actions: readonly Action[];
+    /** Draws a custom trigger. Forward every supplied trigger prop.
+     * @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. */
+export declare function Menu(props: MenuProps): import("react").JSX.Element;

package/dist/public/actions.js

@@ -0,0 +1,15 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useContext } from 'react';
+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. */
+export function Menu(props) {
+    const toolbar = useContext(ToolbarContext);
+    const trigger = props.trigger ??
+        (toolbar === true
+            ? (triggerProps) => _jsx(Button, { ...triggerProps, children: props.label })
+            : undefined);
+    return _jsx(EngineMenu, { ...props, trigger: trigger });
+}

package/dist/public/buttonBorderShape.d.ts

@@ -0,0 +1,7 @@
+import { type GlassShape } from '../glass/regions.js';
+/** `buttonBorderShape`. Fixed radii are measured in points. */
+export type ButtonBorderShape = 'automatic' | 'capsule' | Readonly<{
+    kind: 'roundedRectangle';
+    cornerRadius: number;
+}>;
+export declare function resolveButtonBorderShape(shape?: ButtonBorderShape): GlassShape;

package/dist/public/buttonBorderShape.js

@@ -0,0 +1,9 @@
+import { glassRadius } from '../glass/regions.js';
+export function resolveButtonBorderShape(shape = 'automatic') {
+    if (typeof shape === 'string')
+        return 'capsule';
+    const resolved = { kind: 'roundedRectangle', cornerRadius: shape.cornerRadius };
+    // Use the material's geometry validation and renderer for every button shape.
+    glassRadius(resolved, Number.MAX_VALUE, Number.MAX_VALUE);
+    return resolved;
+}

package/dist/public/chrome.d.ts

@@ -0,0 +1,3 @@
+export { Screen, type ScreenProps } from './Screen.js';
+export { DefaultToolbarItem, ToolbarConfirmationContext, ToolbarContext, ToolbarItem, ToolbarItemGroup, ToolbarSpacer, type DefaultToolbarItemProps, type ToolbarItemProps, type ToolbarSpacerProps, } from './toolbar.js';
+export { NavigationSizeClassContext, ScreenChromeContext, ScreenContentContext, ScreenToolbar, createScreenChrome, screenNavigation, useScreenChrome, useScreenContentNavigation, useScreenNavigation, } from './screenChrome.js';

package/dist/public/chrome.js

@@ -0,0 +1,5 @@
+// Engine modules and tests import screen chrome from this path. New code imports the module that
+// owns the name: Screen.tsx, toolbar.tsx or screenChrome.tsx.
+export { Screen } from './Screen.js';
+export { DefaultToolbarItem, ToolbarConfirmationContext, ToolbarContext, ToolbarItem, ToolbarItemGroup, ToolbarSpacer, } from './toolbar.js';
+export { NavigationSizeClassContext, ScreenChromeContext, ScreenContentContext, ScreenToolbar, createScreenChrome, screenNavigation, useScreenChrome, useScreenContentNavigation, useScreenNavigation, } from './screenChrome.js';

package/dist/public/colors.d.ts

@@ -0,0 +1,29 @@
+/** Appearance-aware UIKit system palette. Explicit CSS colors remain supported. */
+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.
+ * @example <Button tint={systemColor('orange')} onPress={start}>Start</Button> */
+export declare function systemColor(name: SystemColorName): string;
+declare const semanticColors: {
+    readonly label: '--satin-label';
+    readonly opaqueSeparator: '--satin-opaque-separator';
+    readonly quaternaryLabel: '--satin-quaternary-label';
+    readonly quaternarySystemFill: '--satin-quaternary-system-fill';
+    readonly secondaryLabel: '--satin-secondary-label';
+    readonly secondarySystemBackground: '--satin-secondary-system-background';
+    readonly secondarySystemFill: '--satin-secondary-system-fill';
+    readonly secondarySystemGroupedBackground: '--satin-secondary-system-grouped-background';
+    readonly separator: '--satin-separator';
+    readonly systemBackground: '--satin-system-background';
+    readonly systemFill: '--satin-system-fill';
+    readonly systemGroupedBackground: '--satin-system-grouped-background';
+    readonly tertiaryLabel: '--satin-tertiary-label';
+    readonly tertiarySystemBackground: '--satin-tertiary-system-background';
+    readonly tertiarySystemFill: '--satin-tertiary-system-fill';
+    readonly tertiarySystemGroupedBackground: '--satin-tertiary-system-grouped-background';
+    readonly tint: '--satin-tint';
+};
+/** UIKit's semantic colour names (`label`, `secondarySystemBackground`, …). */
+export type SemanticColorName = keyof typeof semanticColors;
+/** UIKit semantic content colors, inherited by app content and portals. */
+export declare function semanticColor(name: SemanticColorName): string;
+export {};

package/dist/public/colors.js

@@ -0,0 +1,28 @@
+/** A named system color as a CSS color that follows the appearance.
+ * @example <Button tint={systemColor('orange')} onPress={start}>Start</Button> */
+export function systemColor(name) {
+    return `var(--satin-system-${name})`;
+}
+const semanticColors = {
+    label: '--satin-label',
+    opaqueSeparator: '--satin-opaque-separator',
+    quaternaryLabel: '--satin-quaternary-label',
+    quaternarySystemFill: '--satin-quaternary-system-fill',
+    secondaryLabel: '--satin-secondary-label',
+    secondarySystemBackground: '--satin-secondary-system-background',
+    secondarySystemFill: '--satin-secondary-system-fill',
+    secondarySystemGroupedBackground: '--satin-secondary-system-grouped-background',
+    separator: '--satin-separator',
+    systemBackground: '--satin-system-background',
+    systemFill: '--satin-system-fill',
+    systemGroupedBackground: '--satin-system-grouped-background',
+    tertiaryLabel: '--satin-tertiary-label',
+    tertiarySystemBackground: '--satin-tertiary-system-background',
+    tertiarySystemFill: '--satin-tertiary-system-fill',
+    tertiarySystemGroupedBackground: '--satin-tertiary-system-grouped-background',
+    tint: '--satin-tint',
+};
+/** UIKit semantic content colors, inherited by app content and portals. */
+export function semanticColor(name) {
+    return `var(${semanticColors[name]})`;
+}

package/dist/public/context.d.ts

@@ -0,0 +1,19 @@
+import type { NavigationDeclaration } from './structure.js';
+import type { AppDefinition } from '../app/definition.js';
+import type { NavigatorStore } from '../navigation/store.js';
+import type { SceneRestoration } from '../restoration/scene.js';
+import type { prepareSceneRoutes } from '../restoration/routes.js';
+import type { PushNotifications } from '../push/notifications.js';
+import type { Routes } from './routes.js';
+export type AppRuntime = {
+    app: AppDefinition;
+    routes: Routes;
+    structure: NavigationDeclaration<Routes>;
+    mountedStacks: Set<string>;
+    scene: SceneRestoration;
+    stacks: Map<string, NavigatorStore>;
+    sceneRoutes?: ReturnType<typeof prepareSceneRoutes>;
+    notifications: PushNotifications | null;
+};
+export declare const AppContext: import("react").Context<AppRuntime | null>;
+export declare function useAppContext(): AppRuntime;

package/dist/public/context.js

@@ -0,0 +1,8 @@
+import { createContext, useContext } from 'react';
+export const AppContext = createContext(null);
+export function useAppContext() {
+    const context = useContext(AppContext);
+    if (!context)
+        throw new Error('This API requires runApp');
+    return context;
+}

package/dist/public/controlStyle.d.ts

@@ -0,0 +1,93 @@
+import { type CSSProperties, type ReactNode } from 'react';
+/** `ControlSize`. */
+export type ControlSize = 'mini' | 'small' | 'regular' | 'large' | 'extraLarge';
+/** `ButtonRole`. */
+export type ButtonRole = 'destructive' | 'cancel';
+/** Built-in button styles, by their `buttonStyle` names. */
+export type BuiltInButtonStyle = 'automatic' | 'bordered' | 'borderedProminent' | 'borderless' | 'plain' | 'glass' | 'glassProminent';
+/** The environment every custom control style receives. */
+export type ControlConfiguration = Readonly<{
+    isEnabled: boolean;
+    controlSize: ControlSize;
+    tint: string | undefined;
+}>;
+/** `ButtonStyleConfiguration`: what a custom `ButtonStyle` draws from. */
+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. */
+export type ButtonStyle = Readonly<{
+    makeBody(configuration: ButtonStyleConfiguration): ReactNode;
+}>;
+/** `LabelStyleConfiguration`: 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. */
+export type LabelStyle = Readonly<{
+    makeBody(configuration: LabelStyleConfiguration): ReactNode;
+}>;
+/** Built-in label styles. */
+export type BuiltInLabelStyle = 'automatic' | 'titleAndIcon' | 'titleOnly' | 'iconOnly';
+/** `ToggleStyleConfiguration`: what a custom `ToggleStyle` draws from. */
+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. */
+export type ToggleStyle = Readonly<{
+    semantics: 'switch' | 'checkbox' | 'button';
+    makeBody(configuration: ToggleStyleConfiguration): ReactNode;
+}>;
+/** Built-in toggle styles. */
+export type BuiltInToggleStyle = 'automatic' | 'switch' | 'button';
+/** The control environment a `ControlStyleProvider` sets for its subtree. */
+export type ControlStyleValues = Readonly<{
+    buttonStyle?: BuiltInButtonStyle | ButtonStyle;
+    toggleStyle?: BuiltInToggleStyle | ToggleStyle;
+    labelStyle?: BuiltInLabelStyle | LabelStyle;
+    controlSize?: ControlSize;
+    tint?: string;
+    disabled?: boolean;
+    labelsHidden?: boolean;
+}>;
+/**
+ * Sets control defaults for a subtree through `buttonStyle`, `toggleStyle`, `labelStyle`,
+ * `controlSize`, `tint` and `disabled`. A control's own props win
+ * over the provider, except that a disabled ancestor cannot be re-enabled by a child.
+ *
+ * @example
+ * <ControlStyleProvider buttonStyle="borderedProminent" controlSize="large">
+ *   <Button onPress={save}>Save</Button>
+ * </ControlStyleProvider>
+ */
+export declare function ControlStyleProvider({ children, ...values }: ControlStyleValues & {
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function useControlStyle(values?: ControlStyleValues): {
+    buttonStyle: Readonly<{
+        makeBody(configuration: ButtonStyleConfiguration): ReactNode;
+    }> | BuiltInButtonStyle | undefined;
+    toggleStyle: Readonly<{
+        semantics: 'switch' | 'checkbox' | 'button';
+        makeBody(configuration: ToggleStyleConfiguration): ReactNode;
+    }> | BuiltInToggleStyle | undefined;
+    labelStyle: Readonly<{
+        makeBody(configuration: LabelStyleConfiguration): ReactNode;
+    }> | BuiltInLabelStyle | undefined;
+    labelsHidden: boolean | undefined;
+    controlSize: ControlSize;
+    tint: string | undefined;
+    disabled: boolean;
+};
+export declare function controlTintStyle(tint: string | undefined): CSSProperties | undefined;
+/** Reject nested activation owners in appearance-only styles, including custom components. */
+export declare function ControlStyleBody({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;

package/dist/public/controlStyle.js

@@ -0,0 +1,52 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo, useLayoutEffect, useRef, } from 'react';
+const ControlStyleContext = createContext({});
+/**
+ * Sets control defaults for a subtree through `buttonStyle`, `toggleStyle`, `labelStyle`,
+ * `controlSize`, `tint` and `disabled`. A control's own props win
+ * over the provider, except that a disabled ancestor cannot be re-enabled by a child.
+ *
+ * @example
+ * <ControlStyleProvider buttonStyle="borderedProminent" controlSize="large">
+ *   <Button onPress={save}>Save</Button>
+ * </ControlStyleProvider>
+ */
+export function ControlStyleProvider({ children, ...values }) {
+    const parent = useContext(ControlStyleContext);
+    const { buttonStyle, toggleStyle, labelStyle, controlSize, tint, disabled, labelsHidden } = values;
+    const value = useMemo(() => ({
+        buttonStyle: buttonStyle ?? parent.buttonStyle,
+        toggleStyle: toggleStyle ?? parent.toggleStyle,
+        labelStyle: labelStyle ?? parent.labelStyle,
+        controlSize: controlSize ?? parent.controlSize,
+        tint: tint ?? parent.tint,
+        disabled: Boolean(parent.disabled || disabled),
+        labelsHidden: labelsHidden ?? parent.labelsHidden,
+    }), [parent, buttonStyle, toggleStyle, labelStyle, controlSize, tint, disabled, labelsHidden]);
+    return _jsx(ControlStyleContext, { value: value, children: children });
+}
+export function useControlStyle(values = {}) {
+    const parent = useContext(ControlStyleContext);
+    return {
+        buttonStyle: values.buttonStyle ?? parent.buttonStyle,
+        toggleStyle: values.toggleStyle ?? parent.toggleStyle,
+        labelStyle: values.labelStyle ?? parent.labelStyle,
+        labelsHidden: values.labelsHidden ?? parent.labelsHidden,
+        controlSize: values.controlSize ?? parent.controlSize ?? 'regular',
+        tint: values.tint ?? parent.tint,
+        disabled: Boolean(parent.disabled || values.disabled),
+    };
+}
+export function controlTintStyle(tint) {
+    return tint ? { '--satin-tint': tint, '--satin-list-accent': tint } : undefined;
+}
+/** Reject nested activation owners in appearance-only styles, including custom components. */
+export function ControlStyleBody({ children }) {
+    const ref = useRef(null);
+    useLayoutEffect(() => {
+        if (ref.current?.querySelector('button, input, select, textarea, a[href], [contenteditable="true"], [tabindex], [role="button"], [role="checkbox"], [role="switch"]')) {
+            throw new Error('Control styles return noninteractive content. Satin owns the interactive element.');
+        }
+    });
+    return (_jsx("span", { ref: ref, style: { display: 'contents' }, children: children }));
+}