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

package/dist/content/scaledMetric.js

@@ -0,0 +1,68 @@
+import { useSyncExternalStore } from 'react';
+import { contentFonts, contentTypography } from './typography.js';
+function createMetricStore(style) {
+    const listeners = new Set();
+    let probe = null;
+    let observer = null;
+    let scale = 1;
+    const measure = () => {
+        if (!probe)
+            return;
+        const fontSize = Number.parseFloat(getComputedStyle(probe).fontSize);
+        const next = Number.isFinite(fontSize) && fontSize > 0 ? fontSize / contentTypography[style].size : 1;
+        if (next === scale)
+            return;
+        scale = next;
+        listeners.forEach(listener => listener());
+    };
+    return {
+        snapshot: () => scale,
+        subscribe(listener) {
+            listeners.add(listener);
+            if (!probe) {
+                probe = document.createElement('span');
+                probe.setAttribute('aria-hidden', 'true');
+                // One shared, invisible em box per subscribed style. Font changes resize it without
+                // a per-frame read or a global text policy. Last unsubscription removes all work.
+                Object.assign(probe.style, {
+                    position: 'absolute',
+                    top: '0',
+                    left: '0',
+                    visibility: 'hidden',
+                    pointerEvents: 'none',
+                    width: '1em',
+                    height: '1em',
+                    overflow: 'hidden',
+                    font: contentFonts[style],
+                });
+                document.body.append(probe);
+                observer = new ResizeObserver(measure);
+                observer.observe(probe);
+                measure();
+            }
+            return () => {
+                listeners.delete(listener);
+                if (listeners.size === 0) {
+                    observer?.disconnect();
+                    observer = null;
+                    probe?.remove();
+                    probe = null;
+                    scale = 1;
+                }
+            };
+        },
+    };
+}
+const stores = new Map();
+/** Scale a dimension by the target WebKit system text style's Dynamic Type ratio. */
+export function useScaledMetric(value, relativeTo = 'body') {
+    if (!Number.isFinite(value))
+        throw new Error('useScaledMetric requires a finite value.');
+    let store = stores.get(relativeTo);
+    if (!store) {
+        store = createMetricStore(relativeTo);
+        stores.set(relativeTo, store);
+    }
+    const scale = useSyncExternalStore(store.subscribe, store.snapshot, () => 1);
+    return value * scale;
+}

package/dist/content/typography.d.ts

@@ -0,0 +1,83 @@
+export declare const contentTypography: {
+    readonly largeTitle: {
+        readonly size: 34;
+        readonly lineHeight: 40.57421875;
+        readonly lineAdvance: 41;
+        readonly weight: 400;
+    };
+    readonly title: {
+        readonly size: 28;
+        readonly lineHeight: 33.4140625;
+        readonly lineAdvance: 34;
+        readonly weight: 400;
+    };
+    readonly title2: {
+        readonly size: 22;
+        readonly lineHeight: 26.25390625;
+        readonly lineAdvance: 28;
+        readonly weight: 400;
+    };
+    readonly title3: {
+        readonly size: 20;
+        readonly lineHeight: 23.8671875;
+        readonly lineAdvance: 25;
+        readonly weight: 400;
+    };
+    readonly headline: {
+        readonly size: 17;
+        readonly lineHeight: 20.287109375;
+        readonly lineAdvance: 22;
+        readonly weight: 600;
+    };
+    readonly subheadline: {
+        readonly size: 15;
+        readonly lineHeight: 17.900390625;
+        readonly lineAdvance: 20;
+        readonly weight: 400;
+    };
+    readonly body: {
+        readonly size: 17;
+        readonly lineHeight: 20.287109375;
+        readonly lineAdvance: 22;
+        readonly weight: 400;
+    };
+    readonly callout: {
+        readonly size: 16;
+        readonly lineHeight: 19.09375;
+        readonly lineAdvance: 21;
+        readonly weight: 400;
+    };
+    readonly footnote: {
+        readonly size: 13;
+        readonly lineHeight: 15.513671875;
+        readonly lineAdvance: 18;
+        readonly weight: 400;
+    };
+    readonly caption: {
+        readonly size: 12;
+        readonly lineHeight: 14.3203125;
+        readonly lineAdvance: 16;
+        readonly weight: 400;
+    };
+    readonly caption2: {
+        readonly size: 11;
+        readonly lineHeight: 13.126953125;
+        readonly lineAdvance: 13;
+        readonly weight: 400;
+    };
+};
+/** Shared Text/probe font policy. WebKit does not support the large-title or callout
+ * keywords, so those styles retain Text's measured, fixed-size fallback. */
+export declare const contentFonts: {
+    readonly largeTitle: "400 34px -apple-system";
+    readonly title: '-apple-system-title1';
+    readonly title2: '-apple-system-title2';
+    readonly title3: '-apple-system-title3';
+    readonly headline: '-apple-system-headline';
+    readonly subheadline: '-apple-system-subheadline';
+    readonly body: '-apple-system-body';
+    readonly callout: "400 16px -apple-system";
+    readonly footnote: '-apple-system-footnote';
+    readonly caption: '-apple-system-caption1';
+    readonly caption2: '-apple-system-caption2';
+};

package/dist/content/typography.js

@@ -0,0 +1,32 @@
+/* iOS 27.0 (24A434), default Dynamic Type, reference native-sim-light/geometry.json.
+ * lineHeight is the glyph line box; lineAdvance includes UIFont leading.
+ * Keep Settings large-title geometry tied to this source of type metrics.
+ */
+export const contentTypography = {
+    largeTitle: { size: 34, lineHeight: 40.57421875, lineAdvance: 41, weight: 400 },
+    title: { size: 28, lineHeight: 33.4140625, lineAdvance: 34, weight: 400 },
+    title2: { size: 22, lineHeight: 26.25390625, lineAdvance: 28, weight: 400 },
+    title3: { size: 20, lineHeight: 23.8671875, lineAdvance: 25, weight: 400 },
+    headline: { size: 17, lineHeight: 20.287109375, lineAdvance: 22, weight: 600 },
+    subheadline: { size: 15, lineHeight: 17.900390625, lineAdvance: 20, weight: 400 },
+    body: { size: 17, lineHeight: 20.287109375, lineAdvance: 22, weight: 400 },
+    callout: { size: 16, lineHeight: 19.09375, lineAdvance: 21, weight: 400 },
+    footnote: { size: 13, lineHeight: 15.513671875, lineAdvance: 18, weight: 400 },
+    caption: { size: 12, lineHeight: 14.3203125, lineAdvance: 16, weight: 400 },
+    caption2: { size: 11, lineHeight: 13.126953125, lineAdvance: 13, weight: 400 },
+};
+/** Shared Text/probe font policy. WebKit does not support the large-title or callout
+ * keywords, so those styles retain Text's measured, fixed-size fallback. */
+export const contentFonts = {
+    largeTitle: `${contentTypography.largeTitle.weight} ${contentTypography.largeTitle.size}px -apple-system`,
+    title: '-apple-system-title1',
+    title2: '-apple-system-title2',
+    title3: '-apple-system-title3',
+    headline: '-apple-system-headline',
+    subheadline: '-apple-system-subheadline',
+    body: '-apple-system-body',
+    callout: `${contentTypography.callout.weight} ${contentTypography.callout.size}px -apple-system`,
+    footnote: '-apple-system-footnote',
+    caption: '-apple-system-caption1',
+    caption2: '-apple-system-caption2',
+};

package/dist/controls/ActivityIndicatorSegments.d.ts

@@ -0,0 +1,4 @@
+/** Shared with pull-to-refresh. Its historical cycle remains pending a native motion fit. */
+export declare function ActivityIndicatorSegments({ running }: {
+    running: boolean;
+}): import("react").JSX.Element[];

package/dist/controls/ActivityIndicatorSegments.js

@@ -0,0 +1,5 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/** Shared with pull-to-refresh. Its historical cycle remains pending a native motion fit. */
+export function ActivityIndicatorSegments({ running }) {
+    return Array.from({ length: 8 }, (_, index) => (_jsx("rect", { x: "9", y: "1", width: "2", height: "5", rx: "1", fill: "currentColor", transform: `rotate(${index * 45} 10 10)`, opacity: (index + 1) / 8, children: running && (_jsx("animate", { attributeName: "opacity", values: "1;0.15", dur: "1.5s", begin: `${index * 0.1875}s`, repeatCount: "indefinite" })) }, index)));
+}

package/dist/controls/ColorPicker.d.ts

@@ -0,0 +1,20 @@
+/** ColorPicker's label and controlled colour. */
+export type ColorPickerProps = {
+    label: string;
+    /** sRGB hexadecimal colour, `#RRGGBB` or `#RRGGBBAA`. */
+    selection: string;
+    onSelectionChange(selection: string): void;
+    /** Shows the system picker's opacity slider. Defaults to true. */
+    supportsOpacity?: boolean;
+    disabled?: boolean;
+};
+/**
+ * `ColorPicker`: a row with a colour well that opens the system colour picker (grid,
+ * spectrum, sliders, eyedropper and, with `supportsOpacity`, opacity).
+ *
+ * The system picker is titled "Colors", not with the label.
+ *
+ * @example
+ * <ColorPicker label="List Colour" selection={color} onSelectionChange={setColor} supportsOpacity={false} />
+ */
+export declare function ColorPicker({ label, selection, onSelectionChange, supportsOpacity, disabled, }: ColorPickerProps): import("react").JSX.Element;

package/dist/controls/ColorPicker.js

@@ -0,0 +1,70 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
+import { useControlStyle } from '../public/controlStyle.js';
+import { ControlRow } from './ControlRow.js';
+const hexPattern = /^#([\da-f]{2})([\da-f]{2})([\da-f]{2})([\da-f]{2})?$/i;
+// WebKit reports an input with the `alpha` attribute as `color(srgb r g b / a)`, channels 0–1.
+const srgbPattern = /^color\(srgb\s+([\d.e+-]+)\s+([\d.e+-]+)\s+([\d.e+-]+)(?:\s*\/\s*([\d.e+-]+))?\)$/i;
+function readHex(text) {
+    const parts = hexPattern.exec(text);
+    if (!parts)
+        return null;
+    const [red, green, blue] = [parts[1], parts[2], parts[3]].map(part => parseInt(part, 16));
+    const alpha = parts[4] === undefined ? 255 : parseInt(parts[4], 16);
+    return { red: red, green: green, blue: blue, alpha };
+}
+function readSystemValue(text) {
+    const hex = readHex(text);
+    if (hex)
+        return hex;
+    const parts = srgbPattern.exec(text.trim());
+    if (!parts)
+        return null;
+    const unit = [parts[1], parts[2], parts[3], parts[4] ?? '1'].map(Number);
+    if (unit.some(value => !Number.isFinite(value)))
+        return null;
+    const [red, green, blue, alpha] = unit.map(value => Math.round(Math.min(1, Math.max(0, value)) * 255));
+    return { red: red, green: green, blue: blue, alpha: alpha };
+}
+function writeHex(channels, withAlpha) {
+    const values = [
+        channels.red,
+        channels.green,
+        channels.blue,
+        ...(withAlpha ? [channels.alpha] : []),
+    ];
+    return '#' + values.map(value => value.toString(16).padStart(2, '0')).join('');
+}
+/**
+ * `ColorPicker`: a row with a colour well that opens the system colour picker (grid,
+ * spectrum, sliders, eyedropper and, with `supportsOpacity`, opacity).
+ *
+ * The system picker is titled "Colors", not with the label.
+ *
+ * @example
+ * <ColorPicker label="List Colour" selection={color} onSelectionChange={setColor} supportsOpacity={false} />
+ */
+export function ColorPicker({ label, selection, onSelectionChange, supportsOpacity = true, disabled, }) {
+    const labelId = useId();
+    const appearance = useControlStyle({ disabled });
+    const channels = readHex(selection);
+    if (!channels) {
+        // Persisted data can be malformed. Say so, and render an inert well rather than crash.
+        console.error('ColorPicker selection must be #RRGGBB or #RRGGBBAA.', { selection });
+    }
+    const shown = channels && writeHex(channels, supportsOpacity);
+    function propose(text) {
+        if (!channels || appearance.disabled)
+            return;
+        const next = readSystemValue(text);
+        if (!next)
+            return;
+        const value = writeHex(next, supportsOpacity);
+        if (value !== shown)
+            onSelectionChange(value);
+    }
+    // `alpha` turns on the system picker's opacity slider (WebKit, iOS 26+). React passes it
+    // through as a plain attribute.
+    const opacityAttribute = supportsOpacity ? { alpha: '' } : {};
+    return (_jsx(ControlRow, { children: _jsxs("div", { "data-satin-color-picker": "true", children: [_jsx("span", { id: labelId, hidden: appearance.labelsHidden, "data-satin-color-picker-label": "true", children: label }), _jsxs("span", { "data-satin-color-well": "true", "data-disabled": appearance.disabled || undefined, children: [_jsx("span", { "aria-hidden": "true", "data-satin-color-swatch": "true", style: shown ? { background: shown } : undefined }), _jsx("input", { type: "color", ...opacityAttribute, "aria-label": label, disabled: appearance.disabled || !channels, value: shown ?? '#000000', onChange: event => propose(event.currentTarget.value) })] })] }) }));
+}

package/dist/controls/ControlRow.d.ts

@@ -0,0 +1,5 @@
+import { type ReactNode } from 'react';
+/** A custom ListRow already owns its cell and insets. */
+export declare function ControlRow({ children }: {
+    children: ReactNode;
+}): string | number | bigint | boolean | import("react").JSX.Element | Iterable<ReactNode> | Promise<string | number | bigint | boolean | Iterable<ReactNode> | import("react").ReactElement<unknown, string | import("react").JSXElementConstructor<any>> | import("react").ReactPortal | null | undefined> | null | undefined;

package/dist/controls/ControlRow.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useContext } from 'react';
+import { ListRow } from '../list-form/ListForm.js';
+import { ListContext, ListRowContentContext } from '../list-form/listContext.js';
+/** A custom ListRow already owns its cell and insets. */
+export function ControlRow({ children }) {
+    const inList = useContext(ListContext);
+    const inRow = useContext(ListRowContentContext);
+    return inList && !inRow ? _jsx(ListRow, { children: children }) : children;
+}

package/dist/controls/DatePicker.d.ts

@@ -0,0 +1,41 @@
+import { type ReactNode } from 'react';
+/** `DatePickerComponents`. */
+export type DatePickerComponent = 'date' | 'hourAndMinute';
+/** `DatePickerStyle`. `automatic` is `compact`. */
+export type DatePickerStyle = 'automatic' | 'compact';
+/**
+ * A DatePicker's selectable range. Omit a bound for a one-sided range
+ * (`start...` or `...end`). Bounds use the same kind of value as the selection.
+ */
+export type DatePickerRange<Selection extends Date | string> = {
+    lowerBound?: Selection;
+    upperBound?: Selection;
+};
+/**
+ * DatePicker's label, controlled selection, range and the components it edits.
+ *
+ * `selection` is a `Date`, or a civil string with no time zone: `'2026-10-14'` for a date,
+ * `'09:41'` for a time, `'2026-10-14T09:41'` for both. The callback returns the same kind.
+ */
+export type DatePickerProps<Selection extends Date | string = Date> = {
+    label: ReactNode;
+    selection: Selection;
+    onSelectionChange(selection: NoInfer<Selection>): void;
+    in?: DatePickerRange<NoInfer<Selection>>;
+    /** Defaults to `['date', 'hourAndMinute']`. */
+    displayedComponents?: readonly DatePickerComponent[];
+    datePickerStyle?: DatePickerStyle;
+    disabled?: boolean;
+    'aria-label'?: string;
+};
+/**
+ * `DatePicker` in its compact style: the row's grey value capsules open the system date
+ * or time picker.
+ *
+ * Use a civil string selection (`'2026-10-14'`) for a day that must stay the same day in every
+ * time zone, such as a due date; use a `Date` for a moment in time.
+ *
+ * @example
+ * <DatePicker label="Due" selection={due} onSelectionChange={setDue} displayedComponents={['date']} />
+ */
+export declare function DatePicker<Selection extends Date | string = Date>({ label, selection, onSelectionChange, in: range, displayedComponents, datePickerStyle, disabled, 'aria-label': accessibleLabel, }: DatePickerProps<Selection>): import("react").JSX.Element;

package/dist/controls/DatePicker.js

@@ -0,0 +1,148 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from 'react';
+import { useControlStyle } from '../public/controlStyle.js';
+import { ControlRow } from './ControlRow.js';
+import { civilShapeFor, compareCivil, fieldsOfInstant, formatCivil, inputDate, inputTime, instantWithFields, parseCivil, utcCarrier, } from './civilDate.js';
+// Fields a civil string doesn't carry. They are never displayed or written back.
+const unusedFields = { year: 2000, month: 1, day: 1, hour: 0, minute: 0 };
+function readSelection(selection, hasDate, hasTime) {
+    if (selection instanceof Date) {
+        if (!Number.isFinite(selection.getTime()))
+            return null;
+        return {
+            fields: fieldsOfInstant(selection),
+            write: (fields, editedTime) => instantWithFields(selection, fields, editedTime),
+            compare: (left, right) => left.getTime() - right.getTime(),
+        };
+    }
+    if (typeof selection !== 'string')
+        return null;
+    const shape = civilShapeFor(hasDate, hasTime);
+    const fields = parseCivil(selection, shape, unusedFields);
+    if (!fields)
+        return null;
+    return {
+        fields,
+        write: next => formatCivil(next, shape),
+        compare: (left, right) => compareCivil(left, right),
+    };
+}
+/** True when a bound is the same kind of value as the selection and readable in its shape. */
+function validBound(bound, selection, hasDate, hasTime) {
+    if (bound === undefined)
+        return true;
+    if (selection instanceof Date)
+        return bound instanceof Date && Number.isFinite(bound.getTime());
+    return typeof bound === 'string' && readSelection(bound, hasDate, hasTime) !== null;
+}
+/**
+ * Keeps a proposal inside the range. UIDatePicker clamps rather than refusing: picking today
+ * when the range starts at noon selects noon.
+ */
+function clamp(value, range, compare) {
+    if (range.lowerBound !== undefined && compare(value, range.lowerBound) < 0)
+        return range.lowerBound;
+    if (range.upperBound !== undefined && compare(value, range.upperBound) > 0)
+        return range.upperBound;
+    return value;
+}
+function sameDay(left, right) {
+    return left.year === right.year && left.month === right.month && left.day === right.day;
+}
+/**
+ * The native input's `min`/`max`. The date input gets the bound's day. The time input only
+ * gets a bound on that bound's own day (or always, for a time-only picker); on any other day
+ * every time is in range.
+ */
+function inputBound(field, bound, selected, hasDate) {
+    if (!bound)
+        return undefined;
+    if (field === 'date')
+        return inputDate(bound);
+    if (!hasDate || sameDay(bound, selected))
+        return inputTime(bound);
+    return undefined;
+}
+/** What the capsule shows, in the user's locale: "Oct 14, 2026" and "9:41 AM" in en-US. */
+function displayText(field, fields) {
+    // The fields are already local (or civil), so format them in UTC to keep them as they are.
+    const options = field === 'date'
+        ? { dateStyle: 'medium', timeZone: 'UTC' }
+        : { timeStyle: 'short', timeZone: 'UTC' };
+    const parts = new Intl.DateTimeFormat(undefined, options).formatToParts(utcCarrier(fields));
+    return parts
+        .map((part, index) => {
+        // WebKit's Intl turns ICU's narrow no-break space before "AM"/"PM" into a plain space for
+        // web compatibility. UIKit keeps the narrow one, so "9:41 AM" sets tighter natively.
+        const nextToDayPeriod = parts[index + 1]?.type === 'dayPeriod' || parts[index - 1]?.type === 'dayPeriod';
+        return part.type === 'literal' && nextToDayPeriod
+            ? part.value.replace(/ /g, '\u202f')
+            : part.value;
+    })
+        .join('');
+}
+/**
+ * `DatePicker` in its compact style: the row's grey value capsules open the system date
+ * or time picker.
+ *
+ * Use a civil string selection (`'2026-10-14'`) for a day that must stay the same day in every
+ * time zone, such as a due date; use a `Date` for a moment in time.
+ *
+ * @example
+ * <DatePicker label="Due" selection={due} onSelectionChange={setDue} displayedComponents={['date']} />
+ */
+export function DatePicker({ label, selection, onSelectionChange, in: range = {}, displayedComponents = ['date', 'hourAndMinute'], datePickerStyle = 'automatic', disabled, 'aria-label': accessibleLabel, }) {
+    const labelId = useId();
+    const appearance = useControlStyle({ disabled });
+    if (datePickerStyle !== 'automatic' && datePickerStyle !== 'compact') {
+        throw new Error(`DatePicker style "${String(datePickerStyle)}" is not available.`);
+    }
+    const hasDate = displayedComponents.includes('date');
+    const hasTime = displayedComponents.includes('hourAndMinute');
+    if ((!hasDate && !hasTime) ||
+        displayedComponents.some(component => component !== 'date' && component !== 'hourAndMinute')) {
+        throw new Error('DatePicker displayedComponents must include date or hourAndMinute.');
+    }
+    const model = readSelection(selection, hasDate, hasTime);
+    const rangeValid = validBound(range.lowerBound, selection, hasDate, hasTime) &&
+        validBound(range.upperBound, selection, hasDate, hasTime) &&
+        !(model &&
+            range.lowerBound !== undefined &&
+            range.upperBound !== undefined &&
+            model.compare(range.lowerBound, range.upperBound) > 0);
+    if (!model || !rangeValid) {
+        // Persisted data can be malformed. Say so, and render an inert row rather than crash.
+        console.error('DatePicker needs a valid selection of the documented shape and an ordered range.', { selection, range });
+    }
+    const usable = model !== null && rangeValid;
+    const lower = usable && range.lowerBound !== undefined
+        ? readSelection(range.lowerBound, hasDate, hasTime)
+        : null;
+    const upper = usable && range.upperBound !== undefined
+        ? readSelection(range.upperBound, hasDate, hasTime)
+        : null;
+    function propose(field, text) {
+        if (!model || !usable || appearance.disabled)
+            return;
+        // The system picker's Reset clears the input. A DatePicker always has a value, so the
+        // selection stays and React restores the input.
+        const shape = field === 'date' ? 'date' : 'time';
+        const fields = parseCivil(text, shape, model.fields);
+        if (!fields)
+            return;
+        const candidate = clamp(model.write(fields, field === 'time'), range, model.compare);
+        if (model.compare(candidate, selection) !== 0)
+            onSelectionChange(candidate);
+    }
+    const fieldsShown = [
+        ...(hasDate ? ['date'] : []),
+        ...(hasTime ? ['time'] : []),
+    ];
+    const nameOf = (field) => accessibleLabel ?? (typeof label === 'string' ? `${label}, ${field}` : undefined);
+    return (_jsx(ControlRow, { children: _jsxs("div", { "data-satin-date-picker": "compact", children: [_jsx("span", { id: labelId, hidden: appearance.labelsHidden, "data-satin-date-picker-label": "true", children: label }), _jsx("div", { "data-satin-date-fields": "true", "data-components": fieldsShown.join(' '), children: fieldsShown.map(field => (_jsx(DateField, { field: field, selected: usable ? model.fields : null, lower: lower?.fields ?? null, upper: upper?.fields ?? null, hasDate: hasDate, disabled: appearance.disabled, name: nameOf(field), labelId: labelId, onPick: text => propose(field, text) }, field))) })] }) }));
+}
+/** One capsule. `selected` is null when the selection is unusable: the capsule is then inert. */
+function DateField({ field, selected, lower, upper, hasDate, disabled, name, labelId, onPick, }) {
+    const inputValue = selected ? (field === 'date' ? inputDate(selected) : inputTime(selected)) : '';
+    return (_jsxs("span", { "data-satin-date-field": field, children: [_jsx("span", { "aria-hidden": "true", "data-satin-date-value": "true", children: selected ? displayText(field, selected) : '' }), _jsx("input", { type: field, required: true, disabled: disabled || !selected, "aria-label": name, "aria-labelledby": name === undefined ? labelId : undefined, value: inputValue, min: selected ? inputBound(field, lower, selected, hasDate) : undefined, max: selected ? inputBound(field, upper, selected, hasDate) : undefined, onChange: event => onPick(event.currentTarget.value) })] }));
+}

package/dist/controls/ProgressView.d.ts

@@ -0,0 +1,17 @@
+import { type ReactNode } from 'react';
+/** `ProgressViewStyle`: `automatic` is linear with a value, circular without. */
+export type ProgressViewStyle = 'automatic' | 'linear' | 'circular';
+/** ProgressView's optional label and progress; without `value` it is indeterminate. */
+export type ProgressViewProps = {
+    /** The iOS style. Automatic preserves the value-dependent default. */
+    progressViewStyle?: ProgressViewStyle;
+    label?: ReactNode;
+    /** Omit value for an indeterminate activity indicator. */
+    value?: number;
+    total?: number;
+    tint?: string;
+    'aria-label'?: string;
+};
+/** `ProgressView`: a spinning activity indicator, or a linear bar for `value` of
+ * `total` (default 1). */
+export declare function ProgressView({ label, progressViewStyle, value, total, tint, 'aria-label': accessibleLabel, }: ProgressViewProps): import("react").JSX.Element;

package/dist/controls/ProgressView.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useContext, useId } from 'react';
+import { ScreenContext } from '../navigation/navigationContext.js';
+import { TabActivityContext } from '../tabs/context.js';
+import { controlTintStyle, useControlStyle } from '../public/controlStyle.js';
+import { ControlRow } from './ControlRow.js';
+import { ActivityIndicatorSegments } from './ActivityIndicatorSegments.js';
+/** `ProgressView`: a spinning activity indicator, or a linear bar for `value` of
+ * `total` (default 1). */
+export function ProgressView({ label, progressViewStyle = 'automatic', value, total = 1, tint, 'aria-label': accessibleLabel, }) {
+    const labelId = useId();
+    const screen = useContext(ScreenContext);
+    const tabActive = useContext(TabActivityContext);
+    const running = tabActive && !screen?.lifecycle.isCovered;
+    const appearance = useControlStyle({ tint });
+    if (!Number.isFinite(total) || total <= 0 || (value !== undefined && !Number.isFinite(value))) {
+        throw new Error('ProgressView requires a finite value and a finite positive total.');
+    }
+    const determinate = value !== undefined;
+    const resolvedStyle = progressViewStyle === 'automatic' ? (determinate ? 'linear' : 'circular') : progressViewStyle;
+    const linear = resolvedStyle === 'linear';
+    const clampedValue = determinate ? Math.min(total, Math.max(0, value)) : undefined;
+    return (_jsx(ControlRow, { children: _jsxs("div", { "data-satin-row-intrinsic": linear ? undefined : 'true', "data-satin-progress-view": resolvedStyle, style: controlTintStyle(appearance.tint), children: [linear && label != null && (_jsx("div", { id: labelId, hidden: appearance.labelsHidden, children: label })), _jsx("div", { role: "progressbar", "aria-label": accessibleLabel ?? (label == null ? 'Loading' : undefined), "aria-labelledby": accessibleLabel === undefined && label != null ? labelId : undefined, "aria-valuemin": determinate ? 0 : undefined, "aria-valuemax": determinate ? total : undefined, "aria-valuenow": clampedValue, children: linear ? (_jsx("div", { "data-satin-progress-track": "true", children: _jsx("div", { "data-satin-progress-fill": "true", style: { transform: `scaleX(${(clampedValue ?? 0) / total})` } }) })) : (_jsx("svg", { width: "20", height: "20", viewBox: "0 0 20 20", "aria-hidden": "true", children: _jsx(ActivityIndicatorSegments, { running: running }) })) }), !linear && label != null && (_jsx("div", { id: labelId, hidden: appearance.labelsHidden, "data-satin-progress-label": "true", children: label }))] }) }));
+}

package/dist/controls/civilDate.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Calendar fields for DatePicker, kept apart from instants.
+ *
+ * A DatePicker edits calendar fields: a day, a time of day, or both. A `Date` selection reads and
+ * writes those fields in the device's time zone, as SwiftUI does. A string selection is a civil
+ * value with no time zone at all ('2026-10-14', '09:41', '2026-10-14T09:41'), so a due date
+ * chosen in New York is still October 14 when the app is opened in Tokyo.
+ *
+ * Nothing here parses a civil string with `new Date(string)`: that reads 'YYYY-MM-DD' as UTC
+ * midnight, which is the previous day west of Greenwich.
+ */
+/** The fields a DatePicker can edit. Missing fields are not displayed and never change. */
+export type CivilFields = {
+    year: number;
+    /** 1–12. */
+    month: number;
+    day: number;
+    hour: number;
+    minute: number;
+};
+/** Which civil string shape a selection uses; `instant` means a `Date`. */
+export type CivilShape = 'instant' | 'date' | 'time' | 'dateTime';
+/** The string shape a civil selection must use for the components it displays. */
+export declare function civilShapeFor(hasDate: boolean, hasTime: boolean): Exclude<CivilShape, 'instant'>;
+/**
+ * Reads a civil string of the given shape. Returns null for anything malformed, including
+ * impossible days such as '2026-02-29'. Fields the shape lacks come from `fallback`.
+ */
+export declare function parseCivil(text: string, shape: Exclude<CivilShape, 'instant'>, fallback: CivilFields): CivilFields | null;
+/** Writes fields as a civil string of the given shape. */
+export declare function formatCivil(fields: CivilFields, shape: Exclude<CivilShape, 'instant'>): string;
+/** The calendar fields of an instant in the device's time zone. */
+export declare function fieldsOfInstant(instant: Date): CivilFields;
+/**
+ * The instant with `previous`'s seconds and the given local fields. If a daylight-saving gap
+ * skips the requested time, JavaScript moves it forward, as UIDatePicker does.
+ */
+export declare function instantWithFields(previous: Date, fields: CivilFields, editedTime: boolean): Date;
+/** Same-shape civil strings compare correctly as text: every field is fixed width. */
+export declare function compareCivil(left: string, right: string): -1 | 0 | 1;
+/** The value a native `<input type="date">` uses. */
+export declare function inputDate(fields: CivilFields): string;
+/** The value a native `<input type="time">` uses. */
+export declare function inputTime(fields: CivilFields): string;
+/**
+ * Fields as a Date whose UTC reading equals the civil fields. Only for `Intl` formatting with
+ * `timeZone: 'UTC'`, so a civil date is displayed exactly as written in every time zone.
+ */
+export declare function utcCarrier(fields: CivilFields): Date;