@phreshos/react-ui 0.1.36 → 0.1.38

package/dist/control/control.d.ts

@@ -0,0 +1,60 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { Color } from "../foundation/color.js";
+import { type Radius } from "../foundation/radius.js";
+import { type ScaleLevel } from "../foundation/scale.js";
+import { type Visual } from "../foundation/visual.js";
+/** Properties shared by every component that owns a paint. */
+export interface ControlProps {
+    /** Base paint. Every interaction state is derived from it. */
+    readonly color?: Color;
+    /** Scale of the whole control, relative to Appearance spacing and inherited text. */
+    readonly size?: ScaleLevel;
+    readonly className?: string;
+    readonly style?: CSSProperties;
+    /** Prevents focus and activation. */
+    readonly disabled?: boolean;
+}
+/** Properties shared by every component that holds a value. */
+export interface FieldProps {
+    /** Visible accessible label. Otherwise supply aria-label or aria-labelledby. */
+    readonly label?: ReactNode;
+    readonly description?: ReactNode;
+    readonly errorMessage?: ReactNode;
+    readonly required?: boolean;
+    readonly invalid?: boolean;
+}
+/** Names owned by our contract, never exposed again under their React Aria spelling. */
+export type ControlOverrides = keyof ControlProps | keyof FieldProps | "children" | "isDisabled" | "isRequired" | "isInvalid" | "isReadOnly";
+/** Relative text scale for control content. Only a component's root applies it. */
+export declare const controlFontSizes: Readonly<Record<ScaleLevel, string>>;
+export declare const controlFontWeight = 600;
+/** Attenuation shared by every control family. */
+export declare const controlOpacity: Readonly<{
+    pending: 0.68;
+    secondary: 0.66;
+    placeholder: 0.55;
+}>;
+/** Geometry of one control size, derived from Appearance spacing and radius. */
+export interface ControlMetrics {
+    readonly visual: Visual;
+    readonly spacing: number;
+    readonly height: number;
+    readonly inset: number;
+    readonly gap: number;
+    readonly indicator: number;
+    /** Space between a collection's edge and its Items. */
+    readonly listInset: number;
+    readonly radius: CSSProperties["borderRadius"];
+    readonly fontSize: string;
+}
+/** Returns the shared metrics for one size and radius in the active Appearance. */
+export declare function useControlMetrics(size?: ScaleLevel, radius?: Radius): ControlMetrics;
+export declare function controlMetrics(visual: Visual, size: ScaleLevel, radius: Radius): ControlMetrics;
+/**
+ * An Appearance radius level scaled to one control height, so a control keeps
+ * the same shape at every size: the medium control height carries the
+ * Appearance radius itself.
+ */
+export declare function proportionalRadius(visual: Visual, height: number, level?: ScaleLevel): number;
+/** A CSS transition for the given properties using the Appearance transaction. */
+export declare function transition(visual: Visual, properties: string, factor?: number): CSSProperties;

package/dist/control/control.js

@@ -0,0 +1,71 @@
+import { resolveRadius } from "../foundation/radius.js";
+import { isScaleLevel } from "../foundation/scale.js";
+import { scale } from "../foundation/scale.js";
+import { useVisual } from "../foundation/visual.js";
+/** Relative text scale for control content. Only a component's root applies it. */
+export const controlFontSizes = Object.freeze({
+    xsmall: "0.6875em",
+    small: "0.75em",
+    medium: "0.8125em",
+    large: "0.875em",
+    xlarge: "0.9375em"
+});
+export const controlFontWeight = 600;
+/** Attenuation shared by every control family. */
+export const controlOpacity = Object.freeze({
+    pending: 0.68,
+    secondary: 0.66,
+    placeholder: 0.55
+});
+const metrics = new WeakMap();
+/** Returns the shared metrics for one size and radius in the active Appearance. */
+export function useControlMetrics(size = "medium", radius = "medium") {
+    return controlMetrics(useVisual(), size, radius);
+}
+export function controlMetrics(visual, size, radius) {
+    let cache = metrics.get(visual);
+    if (cache === undefined)
+        metrics.set(visual, cache = new Map());
+    const key = `${size}:${radius}`;
+    const cached = cache.get(key);
+    if (cached !== undefined)
+        return cached;
+    const spacing = scale(visual.spacing, size);
+    const height = controlHeight(spacing);
+    const result = Object.freeze({
+        visual,
+        spacing,
+        height,
+        // Side padding follows the size, never below half the Appearance spacing,
+        // so a compact icon-only control stays close to square.
+        inset: Math.max(visual.spacing / 2, spacing),
+        gap: Math.max(4, spacing / 2),
+        indicator: Math.round(14 + spacing / 3),
+        listInset: Math.max(4, spacing / 3),
+        radius: isScaleLevel(radius) ? proportionalRadius(visual, height, radius) : resolveRadius(radius, visual.radius),
+        fontSize: controlFontSizes[size]
+    });
+    cache.set(key, result);
+    return result;
+}
+/** The height of a control whose size level resolves to this spacing. */
+function controlHeight(spacing) {
+    return Math.round(22 + spacing);
+}
+/**
+ * An Appearance radius level scaled to one control height, so a control keeps
+ * the same shape at every size: the medium control height carries the
+ * Appearance radius itself.
+ */
+export function proportionalRadius(visual, height, level = "medium") {
+    const medium = controlHeight(visual.spacing);
+    return Math.round(scale(visual.radius, level) * height / medium * 100) / 100;
+}
+/** A CSS transition for the given properties using the Appearance transaction. */
+export function transition(visual, properties, factor = 1) {
+    return {
+        transitionProperty: properties,
+        transitionDuration: `${visual.duration * factor}ms`,
+        transitionTimingFunction: visual.easing
+    };
+}

package/dist/control/field-button.d.ts

@@ -0,0 +1,13 @@
+import type { CSSProperties, ReactNode } from "react";
+import { type ButtonProps as AriaButtonProps } from "react-aria-components";
+import type { ControlMetrics } from "./control.js";
+/**
+ * A quiet button held at the end of a field's well, such as a date picker's
+ * calendar or a number field's steppers. It veils like any quiet control and
+ * sits the same distance from every edge of the well.
+ */
+export declare function FieldButton({ metrics, children, style, ...properties }: Readonly<Omit<AriaButtonProps, "children" | "render" | "style"> & {
+    metrics: ControlMetrics;
+    children: ReactNode;
+    style?: CSSProperties;
+}>): import("react").JSX.Element;

package/dist/control/field-button.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { Button as AriaButton } from "react-aria-components";
+import { surfaceRender } from "./surface-render.js";
+/**
+ * A quiet button held at the end of a field's well, such as a date picker's
+ * calendar or a number field's steppers. It veils like any quiet control and
+ * sits the same distance from every edge of the well.
+ */
+export function FieldButton({ metrics, children, style, ...properties }) {
+    const size = metrics.height - 8;
+    return _jsx(AriaButton, { ...properties, render: surfaceRender("button", state => ({
+            color: "transparent",
+            radius: metrics.radius,
+            interaction: { hovered: state.isHovered, pressed: state.isPressed, focusVisible: state.isFocusVisible, disabled: state.isDisabled }
+        })), style: {
+            appearance: "none",
+            display: "grid",
+            placeItems: "center",
+            flex: "0 0 auto",
+            width: size,
+            height: size,
+            padding: 0,
+            border: 0,
+            background: "none",
+            cursor: "pointer",
+            ...style
+        }, children: children });
+}

package/dist/control/field.d.ts

@@ -0,0 +1,20 @@
+import type { CSSProperties, ReactNode } from "react";
+import { type ControlMetrics } from "./control.js";
+/**
+ * The root of every value-holding component. It is the only element that
+ * applies the control text scale; every part inherits from it.
+ */
+export declare function fieldStyle(metrics: ControlMetrics, style?: CSSProperties): CSSProperties;
+export declare function FieldLabel({ label }: Readonly<{
+    label?: ReactNode;
+}>): import("react").JSX.Element | null;
+/** Description and validation text shared by every field. */
+export declare function FieldFeedback({ description, errorMessage, metrics }: Readonly<{
+    description?: ReactNode;
+    errorMessage?: ReactNode;
+    metrics: ControlMetrics;
+}>): import("react").JSX.Element;
+/** How strongly every separator shows its text color. */
+export declare const separatorOpacity = 0.1;
+/** Separator paint shared by menus, tables, layouts, and toolbars. */
+export declare function separatorColor(metrics: ControlMetrics): string;

package/dist/control/field.js

@@ -0,0 +1,34 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { FieldError, Label, Text } from "react-aria-components";
+import { colorOpacity, mixColor } from "../foundation/color.js";
+import { controlFontWeight, controlOpacity } from "./control.js";
+/**
+ * The root of every value-holding component. It is the only element that
+ * applies the control text scale; every part inherits from it.
+ */
+export function fieldStyle(metrics, style) {
+    return {
+        display: "grid",
+        alignContent: "start",
+        gap: metrics.gap,
+        minWidth: 0,
+        fontFamily: "inherit",
+        fontSize: metrics.fontSize,
+        lineHeight: 1.45,
+        ...style
+    };
+}
+export function FieldLabel({ label }) {
+    return label == null ? null : _jsx(Label, { style: { fontWeight: controlFontWeight }, children: label });
+}
+/** Description and validation text shared by every field. */
+export function FieldFeedback({ description, errorMessage, metrics }) {
+    const { colors } = metrics.visual;
+    return _jsxs(_Fragment, { children: [description != null && _jsx(Text, { slot: "description", style: { fontSize: "0.92em", opacity: controlOpacity.secondary }, children: description }), _jsx(FieldError, { style: { fontSize: "0.92em", color: mixColor(colors.danger, colors.foreground, 0.15) }, children: errorMessage })] });
+}
+/** How strongly every separator shows its text color. */
+export const separatorOpacity = 0.1;
+/** Separator paint shared by menus, tables, layouts, and toolbars. */
+export function separatorColor(metrics) {
+    return colorOpacity(metrics.visual.colors.foreground, separatorOpacity);
+}

package/dist/control/icon.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The treatment of every icon React UI draws inside its own components: a
+ * constant 1.5px stroke at any size, hidden from assistive technology because
+ * the control that holds it carries the name.
+ */
+export declare function iconProps(size: number): {
+    readonly size: number;
+    readonly strokeWidth: 1.5;
+    readonly nonScalingStroke: true;
+    readonly "aria-hidden": true;
+};

package/dist/control/icon.js

@@ -0,0 +1,8 @@
+/**
+ * The treatment of every icon React UI draws inside its own components: a
+ * constant 1.5px stroke at any size, hidden from assistive technology because
+ * the control that holds it carries the name.
+ */
+export function iconProps(size) {
+    return { size, strokeWidth: 1.5, nonScalingStroke: true, "aria-hidden": true };
+}

package/dist/control/item.d.ts

@@ -0,0 +1,37 @@
+import type { CSSProperties } from "react";
+import type { AppearanceColors } from "../foundation/appearance.js";
+import { type Color } from "../foundation/color.js";
+import type { Visual } from "../foundation/visual.js";
+import { type ControlMetrics } from "./control.js";
+import type { SurfaceRenderProps } from "./surface-render.js";
+/**
+ * What marks a selection, in every collection and inside a calendar range:
+ * the subtle level of its color under the same veil as hover. The veil keeps
+ * a light color apart from its canvas, so a selection never shows less
+ * clearly than hovering does.
+ */
+export declare function selectionColor(base: string, colors: AppearanceColors): string;
+export type ItemState = Readonly<{
+    selected: boolean;
+    hovered: boolean;
+    pressed: boolean;
+    focusVisible: boolean;
+    disabled: boolean;
+}>;
+/**
+ * One entry of a collection. At rest it has no paint of its own; hover and
+ * press veil it, and selection lays the selection color of the collection
+ * color beneath it. Every collection uses this same treatment.
+ */
+export declare function itemSurface(visual: Visual, color: Color, state: ItemState, radius: CSSProperties["borderRadius"]): SurfaceRenderProps;
+/** The same treatment as a plain paint, for elements that cannot host a Surface. */
+export declare function itemPaint(visual: Visual, color: Color, state: ItemState): Readonly<{
+    background: string;
+    color: string;
+}>;
+/** Layout shared by list, menu, and tree entries. */
+export declare function itemStyle(metrics: ControlMetrics, disabled: boolean): CSSProperties;
+/** The selection mark drawn at the end of a selected entry. */
+export declare function SelectionMark({ visible }: Readonly<{
+    visible: boolean;
+}>): import("react").JSX.Element;

package/dist/control/item.js

@@ -0,0 +1,57 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { colorLevel, mixColor, resolveColor } from "../foundation/color.js";
+import { clearVeil, interactionShift, surfacePaint } from "../surface/surface.js";
+import { transition } from "./control.js";
+import { Check } from "lucide-react";
+import { iconProps } from "./icon.js";
+/**
+ * What marks a selection, in every collection and inside a calendar range:
+ * the subtle level of its color under the same veil as hover. The veil keeps
+ * a light color apart from its canvas, so a selection never shows less
+ * clearly than hovering does.
+ */
+export function selectionColor(base, colors) {
+    return mixColor(colorLevel(base, "subtle", colors), colors.foreground, interactionShift.hovered * clearVeil);
+}
+/**
+ * One entry of a collection. At rest it has no paint of its own; hover and
+ * press veil it, and selection lays the selection color of the collection
+ * color beneath it. Every collection uses this same treatment.
+ */
+export function itemSurface(visual, color, state, radius) {
+    return {
+        color: state.selected ? selectionColor(resolveColor(color, visual.colors), visual.colors) : "transparent",
+        depth: "flat",
+        material: "none",
+        radius,
+        interaction: itemInteraction(state)
+    };
+}
+/** The same treatment as a plain paint, for elements that cannot host a Surface. */
+export function itemPaint(visual, color, state) {
+    const paint = surfacePaint(visual, state.selected ? selectionColor(resolveColor(color, visual.colors), visual.colors) : "transparent", "flat", "none", false, itemInteraction(state));
+    return { background: paint.fill, color: paint.text };
+}
+function itemInteraction(state) {
+    return { hovered: state.hovered, pressed: state.pressed, focusVisible: state.focusVisible, disabled: state.disabled };
+}
+/** Layout shared by list, menu, and tree entries. */
+export function itemStyle(metrics, disabled) {
+    return {
+        ...transition(metrics.visual, "box-shadow, color, outline-color, opacity"),
+        display: "flex",
+        alignItems: "center",
+        gap: metrics.gap,
+        minWidth: 0,
+        minHeight: metrics.height,
+        paddingInline: metrics.inset,
+        boxSizing: "border-box",
+        cursor: disabled ? "not-allowed" : "pointer",
+        userSelect: "none",
+        outlineOffset: -1
+    };
+}
+/** The selection mark drawn at the end of a selected entry. */
+export function SelectionMark({ visible }) {
+    return _jsx(Check, { ...iconProps(14), style: { flexShrink: 0, marginInlineStart: "auto", opacity: visible ? 1 : 0 } });
+}

package/dist/control/open-state.d.ts

@@ -0,0 +1,25 @@
+import type { ReactNode } from "react";
+/**
+ * Whether an overlay is shown. Its root owns this state; triggers and
+ * positioned parts only read it, so they never repeat it.
+ */
+export type OpenStateProps = Readonly<{
+    open?: boolean;
+    defaultOpen?: boolean;
+    onOpenChange?: (open: boolean) => void;
+}>;
+/** The root of an overlay family: its open state and its parts. */
+export type OverlayRootProps = OpenStateProps & Readonly<{
+    children: ReactNode;
+}>;
+/**
+ * React Aria props that overlay parts own internally, or that belong to the
+ * family root as open state. They never appear on React UI overlay parts.
+ */
+export type AriaOverlayInternals = "isOpen" | "defaultOpen" | "onOpenChange" | "isEntering" | "isExiting" | "isNonModal" | "isDismissable" | "isKeyboardDismissDisabled" | "shouldCloseOnInteractOutside" | "shouldFlip" | "shouldUpdatePosition" | "shouldSkipAnimation" | "trigger" | "triggerRef" | "UNSTABLE_portalContainer" | "arrowRef" | "arrowBoundaryOffset" | "scrollRef" | "getTargetRect";
+/** The one translation from React UI's open-state names to React Aria's. */
+export declare function ariaOpenState({ open, defaultOpen, onOpenChange }: OpenStateProps): {
+    onOpenChange?: ((open: boolean) => void) | undefined;
+    defaultOpen?: boolean | undefined;
+    isOpen?: boolean | undefined;
+};

package/dist/control/open-state.js

@@ -0,0 +1,8 @@
+/** The one translation from React UI's open-state names to React Aria's. */
+export function ariaOpenState({ open, defaultOpen, onOpenChange }) {
+    return {
+        ...(open !== undefined ? { isOpen: open } : {}),
+        ...(defaultOpen !== undefined ? { defaultOpen } : {}),
+        ...(onOpenChange !== undefined ? { onOpenChange } : {})
+    };
+}

package/dist/control/selection-track.d.ts

@@ -0,0 +1,39 @@
+import type { CSSProperties, ReactNode } from "react";
+import { type Color } from "../foundation/color.js";
+import type { MaterialOverrides } from "../surface/material-options.js";
+import { type ControlMetrics } from "./control.js";
+type Orientation = "horizontal" | "vertical";
+/** The track's padding around the items it holds. */
+export declare const selectionTrackInset = 3;
+/**
+ * A recessed track holding a row of mutually exclusive items, such as Tabs or
+ * a SegmentedControl; the selection rises out of it as one raised Surface that
+ * slides to whichever item is selected. The list inside marks itself with
+ * `data-selection-list`, and React Aria marks the selected item `data-selected`.
+ */
+export declare function SelectionTrack({ metrics, color, material, orientation, selectedKey, className, style, children }: Readonly<{
+    metrics: ControlMetrics;
+    color: Color;
+    material: MaterialOverrides["material"];
+    orientation: Orientation;
+    selectedKey: unknown;
+    className?: string;
+    style?: CSSProperties;
+    children: ReactNode;
+}>): import("react").JSX.Element;
+/** Layout of the list inside a SelectionTrack: equal columns across, or a stack. */
+export declare function selectionListStyle(orientation: Orientation): CSSProperties;
+type ItemState = Readonly<{
+    isSelected: boolean;
+    isFocusVisible: boolean;
+    isDisabled: boolean;
+}>;
+/** One item of a SelectionTrack; its label reads against the selection when selected. */
+export declare function selectionItemStyle(metrics: ControlMetrics, color: Color, orientation: Orientation, state: ItemState): CSSProperties;
+/** An item's label: an optional leading icon and text, centered a gap apart. */
+export declare function SelectionItemLabel({ metrics, emphasized, children }: Readonly<{
+    metrics: ControlMetrics;
+    emphasized: boolean;
+    children: ReactNode;
+}>): import("react").JSX.Element;
+export {};

package/dist/control/selection-track.js

@@ -0,0 +1,122 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useLayoutEffect, useRef, useState } from "react";
+import { colorOpacity, readableColor, resolveColor } from "../foundation/color.js";
+import { Surface, SurfaceView } from "../surface/surface.js";
+import { controlOpacity, transition } from "./control.js";
+/** The track's padding around the items it holds. */
+export const selectionTrackInset = 3;
+/**
+ * A recessed track holding a row of mutually exclusive items, such as Tabs or
+ * a SegmentedControl; the selection rises out of it as one raised Surface that
+ * slides to whichever item is selected. The list inside marks itself with
+ * `data-selection-list`, and React Aria marks the selected item `data-selected`.
+ */
+export function SelectionTrack({ metrics, color, material, orientation, selectedKey, className, style, children }) {
+    const track = useRef(null);
+    const selection = useSelectionPlacement(track, selectedKey, orientation);
+    return _jsxs(SurfaceView, { ref: track, color: "background", depth: "recessed", material: material, radius: metrics.radius, className: className, style: { padding: selectionTrackInset, width: orientation === "horizontal" ? "100%" : undefined, boxSizing: "border-box", ...style }, children: [selection !== null && _jsx(Surface, { "data-selection-indicator": "", "aria-hidden": "true", color: color, material: material, radius: metrics.radius, style: {
+                    ...(selection.moving ? transition(metrics.visual, "translate, width, height") : {}),
+                    position: "absolute",
+                    top: 0,
+                    left: 0,
+                    zIndex: 1,
+                    width: selection.width,
+                    height: selection.height,
+                    translate: `${selection.x}px ${selection.y}px`
+                } }), children] });
+}
+/** Layout of the list inside a SelectionTrack: equal columns across, or a stack. */
+export function selectionListStyle(orientation) {
+    return {
+        position: "relative",
+        zIndex: 2,
+        display: "grid",
+        gridAutoFlow: orientation === "horizontal" ? "column" : "row",
+        gridAutoColumns: orientation === "horizontal" ? "minmax(0, 1fr)" : undefined,
+        alignContent: "start",
+        gap: 2,
+        minWidth: 0
+    };
+}
+/** One item of a SelectionTrack; its label reads against the selection when selected. */
+export function selectionItemStyle(metrics, color, orientation, state) {
+    const { colors } = metrics.visual;
+    return {
+        ...transition(metrics.visual, "color, outline-color"),
+        position: "relative",
+        display: "flex",
+        alignItems: "center",
+        justifyContent: orientation === "vertical" ? "start" : "center",
+        minWidth: 0,
+        minHeight: metrics.height - selectionTrackInset * 2,
+        paddingInline: metrics.inset,
+        boxSizing: "border-box",
+        border: 0,
+        background: "none",
+        font: "inherit",
+        borderRadius: metrics.radius,
+        outline: `3px solid ${state.isFocusVisible ? colorOpacity(colors.primary, 0.34) : "transparent"}`,
+        outlineOffset: 1,
+        cursor: state.isDisabled ? "not-allowed" : "pointer",
+        userSelect: "none",
+        fontWeight: 500,
+        color: state.isSelected ? readableColor(resolveColor(color, colors), colors) : colors.foreground
+    };
+}
+/** An item's label: an optional leading icon and text, centered a gap apart. */
+export function SelectionItemLabel({ metrics, emphasized, children }) {
+    return _jsx("span", { style: {
+            ...transition(metrics.visual, "opacity"),
+            display: "flex",
+            alignItems: "center",
+            gap: metrics.gap,
+            minWidth: 0,
+            overflow: "hidden",
+            whiteSpace: "nowrap",
+            opacity: emphasized ? 1 : controlOpacity.secondary
+        }, children: children });
+}
+/**
+ * Where the selected item sits inside the track. The first placement appears
+ * in place; later ones slide.
+ */
+function useSelectionPlacement(track, selectedKey, orientation) {
+    const [placement, setPlacement] = useState(null);
+    useLayoutEffect(() => {
+        const element = track.current;
+        const list = element?.querySelector("[data-selection-list]");
+        if (element == null || list == null)
+            return;
+        const measure = () => {
+            const item = list.querySelector("[data-selected]");
+            if (item == null)
+                return setPlacement(null);
+            const outer = element.getBoundingClientRect();
+            const inner = item.getBoundingClientRect();
+            // Rectangles keep subpixel precision; dividing by the track's own
+            // scale undoes any transform, such as an entering overlay's.
+            const scale = element.offsetWidth > 0 ? outer.width / element.offsetWidth : 1;
+            const next = {
+                x: (inner.left - outer.left) / scale - element.clientLeft,
+                y: (inner.top - outer.top) / scale - element.clientTop,
+                width: inner.width / scale,
+                height: inner.height / scale
+            };
+            setPlacement(previous => previous !== null && previous.x === next.x && previous.y === next.y
+                && previous.width === next.width && previous.height === next.height
+                ? previous
+                : { ...next, moving: previous !== null });
+        };
+        measure();
+        // Items render after the list itself, and selection is written onto them.
+        const mutations = new MutationObserver(measure);
+        mutations.observe(list, { subtree: true, childList: true, attributeFilter: ["data-selected"] });
+        const resizes = typeof ResizeObserver === "function" ? new ResizeObserver(measure) : null;
+        resizes?.observe(list);
+        return () => {
+            mutations.disconnect();
+            resizes?.disconnect();
+        };
+    }, [track, selectedKey, orientation]);
+    return placement;
+}

package/dist/control/selection.d.ts

@@ -0,0 +1,44 @@
+import type { Key, Selection } from "react-aria-components";
+export type MultipleStringSelection = readonly string[] | "all";
+export type SingleStringSelectionProps = Readonly<{
+    value?: string | null;
+    defaultValue?: string | null;
+    onChange?: (value: string | null) => void;
+}>;
+export type MultipleStringSelectionProps = Readonly<{
+    value?: MultipleStringSelection;
+    defaultValue?: MultipleStringSelection;
+    onChange?: (value: MultipleStringSelection) => void;
+}>;
+export declare function toAriaSelection(value: string | null | MultipleStringSelection | undefined): "all" | Set<string> | undefined;
+export declare function stringKey(value: Key): string;
+export declare function optionalStringKey(value: Key | null): string | null;
+export declare function singleSelection(selection: Selection): string | null;
+export declare function multipleSelection(selection: Selection): MultipleStringSelection;
+export declare function stringKeys(values: Iterable<Key>): readonly string[];
+export type NoSelectionProps = Readonly<{
+    selectionMode?: "none";
+    value?: never;
+    defaultValue?: never;
+    onChange?: never;
+}>;
+export type SingleSelectionProps = SingleStringSelectionProps & Readonly<{
+    selectionMode: "single";
+}>;
+export type MultipleSelectionProps = MultipleStringSelectionProps & Readonly<{
+    selectionMode: "multiple";
+}>;
+type AnySelection = Readonly<{
+    selectionMode?: "none" | "single" | "multiple";
+    value?: string | null | MultipleStringSelection;
+    defaultValue?: string | null | MultipleStringSelection;
+    onChange?: ((value: string | null) => void) | ((value: MultipleStringSelection) => void);
+}>;
+/** Translates one string-valued selection contract into React Aria collection props. */
+export declare function ariaSelection(properties: AnySelection, fallbackMode: "none" | "single" | "multiple"): {
+    onSelectionChange?: ((selection: Selection) => void) | undefined;
+    defaultSelectedKeys?: "all" | Set<string> | undefined;
+    selectedKeys?: "all" | Set<string> | undefined;
+    selectionMode: "none" | "multiple" | "single";
+};
+export {};

package/dist/{selection.js → control/selection.js}

@@ -26,3 +26,19 @@ export function multipleSelection(selection) {
 export function stringKeys(values) {
     return [...values].map(stringKey);
 }
+/** Translates one string-valued selection contract into React Aria collection props. */
+export function ariaSelection(properties, fallbackMode) {
+    const mode = properties.selectionMode ?? fallbackMode;
+    const selectedKeys = toAriaSelection(properties.value);
+    const defaultSelectedKeys = toAriaSelection(properties.defaultValue);
+    const onChange = properties.onChange;
+    const onSelectionChange = onChange === undefined || mode === "none"
+        ? undefined
+        : (selection) => onChange(mode === "multiple" ? multipleSelection(selection) : singleSelection(selection));
+    return {
+        selectionMode: mode,
+        ...(selectedKeys !== undefined ? { selectedKeys } : {}),
+        ...(defaultSelectedKeys !== undefined ? { defaultSelectedKeys } : {}),
+        ...(onSelectionChange !== undefined ? { onSelectionChange } : {})
+    };
+}

package/dist/control/surface-render.d.ts

@@ -0,0 +1,10 @@
+import type { ElementType, ReactElement } from "react";
+import { type SurfaceInteraction, type SurfaceOwnProps } from "../surface/surface.js";
+export type SurfaceRenderProps = SurfaceOwnProps & Readonly<{
+    interaction?: SurfaceInteraction;
+}>;
+/**
+ * Lets a React Aria component render its own DOM element as a Surface. React
+ * Aria keeps behavior, semantics, and state; the Surface owns every paint.
+ */
+export declare function surfaceRender<State>(as: ElementType, derive: (state: State) => SurfaceRenderProps): (native: object, state: State) => ReactElement;

package/dist/control/surface-render.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { SurfaceView } from "../surface/surface.js";
+/**
+ * Lets a React Aria component render its own DOM element as a Surface. React
+ * Aria keeps behavior, semantics, and state; the Surface owns every paint.
+ */
+export function surfaceRender(as, derive) {
+    return (native, state) => {
+        const { ref, ...properties } = native;
+        return _jsx(SurfaceView, { ...properties, ...derive(state), as: as, ref: ref });
+    };
+}