@phreshos/react-ui 0.1.35 → 0.1.37

package/dist/disclosure.d.ts

@@ -1,23 +1,24 @@
 import type { CSSProperties, ReactElement, ReactNode } from "react";
 import type { ButtonProps as AriaButtonProps, DisclosurePanelProps as AriaDisclosurePanelProps, DisclosureProps as AriaDisclosureProps } from "react-aria-components";
-import type { ControlColor } from "./control.js";
-import type { RadiusProps } from "./radius.js";
-import type { ScaleLevel } from "./scale.js";
-import { type Spacing } from "./spacing.js";
+import type { Color } from "./foundation/color.js";
+import type { RadiusProps } from "./foundation/radius.js";
+import type { ScaleLevel } from "./foundation/scale.js";
+import { type Spacing } from "./foundation/spacing.js";
 export interface DisclosureRootProps extends Omit<AriaDisclosureProps, "children" | "className" | "defaultExpanded" | "isDisabled" | "isExpanded" | "onExpandedChange" | "style">, RadiusProps {
     readonly children?: ReactNode;
     readonly className?: string;
-    readonly color?: ControlColor;
+    /** Paint of the trigger. Transparent by default, so it only veils on interaction. */
+    readonly color?: Color;
     readonly defaultExpanded?: boolean;
     readonly disabled?: boolean;
     readonly expanded?: boolean;
-    readonly onChange?: (expanded: boolean) => void;
+    readonly onExpandedChange?: (expanded: boolean) => void;
     readonly size?: ScaleLevel;
     readonly style?: CSSProperties;
 }
 /** One independently expandable region. */
 export declare const DisclosureRoot: import("react").ForwardRefExoticComponent<DisclosureRootProps & import("react").RefAttributes<HTMLDivElement>>;
-export interface DisclosureTriggerProps extends Omit<AriaButtonProps, "children" | "className" | "isDisabled" | "onPress" | "style"> {
+export interface DisclosureTriggerProps extends Omit<AriaButtonProps, "children" | "className" | "isDisabled" | "isPending" | "onPress" | "render" | "style"> {
     readonly children?: ReactNode;
     readonly className?: string;
     readonly style?: CSSProperties;

package/dist/disclosure.js

@@ -1,83 +1,62 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { createContext, forwardRef, useContext, useMemo } from "react";
 import { Button as AriaButton, Disclosure as AriaDisclosure, DisclosurePanel as AriaDisclosurePanel, DisclosureStateContext } from "react-aria-components";
-import { useResolvedAppearance } from "./appearance-context.js";
-import { controlOpacity, useControlTheme } from "./control.js";
-import { transitionTiming } from "./motion-style.js";
-import { resolveSpacing } from "./spacing.js";
-const DisclosureThemeContext = createContext(null);
+import { transition, useControlMetrics } from "./control/control.js";
+import { surfaceRender } from "./control/surface-render.js";
+import { resolveSpacing } from "./foundation/spacing.js";
+import { ChevronDown } from "lucide-react";
+import { iconProps } from "./control/icon.js";
+const DisclosureStyleContext = createContext(null);
 /** One independently expandable region. */
-export const DisclosureRoot = forwardRef(function DisclosureRoot({ children, className, color, defaultExpanded, disabled = false, expanded, onChange, radius = "medium", size = "medium", style, ...properties }, ref) {
-    const theme = useControlTheme({ color, radius, size });
-    const resolved = useResolvedAppearance();
-    const context = useMemo(() => ({
-        motion: transitionTiming(resolved.transaction, resolved.preferences.animations),
-        theme
-    }), [resolved.preferences.animations, resolved.transaction, theme]);
-    return _jsx(DisclosureThemeContext.Provider, { value: context, children: _jsx(AriaDisclosure, { ...properties, ...(expanded === undefined ? {} : { isExpanded: expanded }), ...(defaultExpanded === undefined ? {} : { defaultExpanded }), ref: ref, className: className, isDisabled: disabled, onExpandedChange: onChange, style: {
-                display: "grid",
-                minWidth: 0,
-                fontFamily: "inherit",
-                fontSize: theme.fontSize,
-                ...style
-            }, children: children }) });
+export const DisclosureRoot = forwardRef(function Disclosure({ children, className, color = "transparent", defaultExpanded, disabled = false, expanded, onExpandedChange, radius, size, style, ...properties }, ref) {
+    const metrics = useControlMetrics(size, radius);
+    const context = useMemo(() => ({ color, metrics }), [color, metrics]);
+    return _jsx(DisclosureStyleContext.Provider, { value: context, children: _jsx(AriaDisclosure, { ...properties, ...(expanded === undefined ? {} : { isExpanded: expanded }), ...(defaultExpanded === undefined ? {} : { defaultExpanded }), ref: ref, className: className, isDisabled: disabled, onExpandedChange: onExpandedChange, style: { display: "grid", minWidth: 0, fontFamily: "inherit", fontSize: metrics.fontSize, ...style }, children: children }) });
 });
 /** The control that changes the Disclosure's expansion state. */
 export const DisclosureTrigger = forwardRef(function DisclosureTrigger({ children, className, style, ...properties }, ref) {
-    const { motion, theme } = useDisclosureTheme();
+    const { color, metrics } = useDisclosureStyle();
     const disclosure = useDisclosureState();
-    return _jsxs(AriaButton, { ...properties, ref: ref, slot: "trigger", className: className, style: state => ({
-            ...theme.transition,
+    return _jsxs(AriaButton, { ...properties, ref: ref, slot: "trigger", className: className, render: surfaceRender("button", state => ({
+            color,
+            radius: metrics.radius,
+            shadow: false,
+            interaction: { hovered: state.isHovered, pressed: state.isPressed, focusVisible: state.isFocusVisible, disabled: state.isDisabled }
+        })), style: {
             appearance: "none",
             display: "grid",
             gridTemplateColumns: "minmax(0, 1fr) auto",
             alignItems: "center",
-            gap: theme.gap,
+            gap: metrics.gap,
             width: "100%",
             minWidth: 0,
-            minHeight: theme.height,
-            paddingBlock: theme.gap,
-            paddingInline: Math.max(8, theme.spacing),
+            minHeight: metrics.height,
+            paddingBlock: metrics.gap / 2,
+            paddingInline: metrics.inset,
             boxSizing: "border-box",
             border: 0,
-            borderRadius: theme.radius,
-            outline: state.isFocusVisible ? `1px solid ${theme.focusColor}` : "none",
-            outlineOffset: 1,
-            cursor: state.isDisabled ? "not-allowed" : "pointer",
-            opacity: state.isDisabled ? controlOpacity.disabled : 1,
+            background: "none",
+            cursor: "pointer",
             font: "inherit",
-            lineHeight: 1.5,
+            fontWeight: 500,
+            lineHeight: 1.45,
             textAlign: "start",
             userSelect: "none",
             WebkitTapHighlightColor: "transparent",
-            ...(disclosure.isExpanded
-                ? state.isPressed ? theme.paints.palette.pressed : state.isHovered ? theme.paints.palette.hover : theme.paints.palette.rest
-                : state.isPressed ? theme.paints.subtle.pressed : state.isHovered ? theme.paints.subtle.hover : { background: "transparent", color: "inherit" }),
             ...style
-        }), children: [_jsx("span", { style: { minWidth: 0 }, children: children }), _jsx("span", { "aria-hidden": "true", style: {
-                    ...motion,
-                    transitionProperty: "transform",
-                    width: "0.5em",
-                    height: "0.5em",
-                    marginInline: "0.25em",
-                    borderInlineEnd: "1px solid currentColor",
-                    borderBlockEnd: "1px solid currentColor",
-                    transform: disclosure.isExpanded ? "rotate(225deg)" : "rotate(45deg)"
-                } })] });
+        }, children: [_jsx("span", { style: { minWidth: 0 }, children: children }), _jsx(ChevronDown, { ...iconProps(14), style: { ...transition(metrics.visual, "rotate"), rotate: disclosure.isExpanded ? "180deg" : "0deg" } })] });
 });
 /** Content revealed by a Disclosure trigger. */
 export const DisclosureContent = forwardRef(function DisclosureContent({ children, className, padding = "small", style, ...properties }, ref) {
-    const { motion } = useDisclosureTheme();
+    const { metrics } = useDisclosureStyle();
     const disclosure = useDisclosureState();
-    const { appearance } = useResolvedAppearance();
     return _jsx(AriaDisclosurePanel, { ...properties, ref: ref, className: className, style: {
-            ...motion,
-            transitionProperty: "height, opacity",
+            ...transition(metrics.visual, "height, opacity"),
             height: "var(--disclosure-panel-height)",
             overflow: "clip",
             opacity: disclosure.isExpanded ? 1 : 0,
             ...style
-        }, children: _jsx("div", { style: { minHeight: 0, overflow: "hidden" }, children: _jsx("div", { style: { padding: resolveSpacing(padding, appearance) }, children: children }) }) });
+        }, children: _jsx("div", { style: { minHeight: 0, overflow: "hidden" }, children: _jsx("div", { style: { padding: resolveSpacing(padding, metrics.visual.spacing) }, children: children }) }) });
 });
 function useDisclosureState() {
     const state = useContext(DisclosureStateContext);
@@ -85,8 +64,8 @@ function useDisclosureState() {
         throw new Error("Disclosure parts must be used inside Disclosure");
     return state;
 }
-function useDisclosureTheme() {
-    const context = useContext(DisclosureThemeContext);
+function useDisclosureStyle() {
+    const context = useContext(DisclosureStyleContext);
     if (context == null)
         throw new Error("Disclosure parts must be used inside Disclosure");
     return context;

package/dist/drop-zone.d.ts

@@ -0,0 +1,18 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { DropZoneProps as AriaDropZoneProps } from "react-aria-components";
+import { type RadiusProps } from "./foundation/radius.js";
+import type { MaterialOverrides } from "./surface/material-options.js";
+export interface DropZoneProps extends Omit<AriaDropZoneProps, "onDrop" | "getDropOperation" | "isDisabled" | "className" | "style" | "children">, RadiusProps, MaterialOverrides {
+    readonly children?: ReactNode;
+    /** MIME types it accepts, such as `image/png`, or a family such as `image/*`. Anything, when absent. */
+    readonly accept?: readonly string[];
+    readonly onDrop?: (files: File[]) => void;
+    readonly disabled?: boolean;
+    readonly className?: string;
+    readonly style?: CSSProperties;
+}
+/**
+ * An area that takes files dragged onto it. It recesses like every value
+ * holder, and takes the subtle `primary` level while files hover it.
+ */
+export declare const DropZone: import("react").ForwardRefExoticComponent<DropZoneProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/drop-zone.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef } from "react";
+import { DropZone as AriaDropZone } from "react-aria-components";
+import { useControlMetrics } from "./control/control.js";
+import { surfaceRender } from "./control/surface-render.js";
+import { colorLevel } from "./foundation/color.js";
+import { resolveRadius } from "./foundation/radius.js";
+import { dimmedClass } from "./surface/surface.js";
+/**
+ * An area that takes files dragged onto it. It recesses like every value
+ * holder, and takes the subtle `primary` level while files hover it.
+ */
+export const DropZone = forwardRef(function DropZone({ children, accept, onDrop, disabled, radius, material, className, style, ...properties }, ref) {
+    const metrics = useControlMetrics();
+    const { colors } = metrics.visual;
+    const accepts = (type) => accept === undefined || accept.some(pattern => pattern.endsWith("/*") ? type.startsWith(pattern.slice(0, -1)) : type === pattern);
+    return _jsx(AriaDropZone, { ...properties, ref: ref, isDisabled: disabled, 
+        // A drag names exact types only, so a family such as `image/*` is checked on drop.
+        getDropOperation: types => accept === undefined || accept.some(pattern => pattern.endsWith("/*") || types.has(pattern)) ? "copy" : "cancel", onDrop: async (event) => {
+            const files = await Promise.all(event.items
+                .filter((item) => item.kind === "file" && accepts(item.type))
+                .map(item => item.getFile()));
+            if (files.length > 0)
+                onDrop?.(files);
+        }, className: state => dimmedClass(state.isDisabled, className ?? state.defaultClassName) ?? "", render: surfaceRender("div", state => ({
+            color: state.isDropTarget ? colorLevel(colors.primary, "subtle", colors) : "background",
+            depth: "recessed",
+            material,
+            radius: resolveRadius(radius ?? "medium", metrics.visual.radius),
+            interaction: { hovered: false, focusVisible: state.isFocusVisible || state.isDropTarget, disabled: state.isDisabled }
+        })), style: { display: "grid", placeItems: "center", gap: metrics.gap, padding: metrics.spacing * 2, textAlign: "center", ...style }, children: children });
+});

package/dist/dropdown-menu.d.ts

@@ -1,17 +1,20 @@
 import type { ComponentProps } from "react";
 import type { MenuTriggerProps as AriaMenuTriggerProps } from "react-aria-components";
 import { type ButtonProps } from "./button.js";
-export type DropdownMenuRootProps = AriaMenuTriggerProps;
-export declare function DropdownMenuRoot(properties: DropdownMenuRootProps): import("react").JSX.Element;
+import { type OverlayRootProps } from "./control/open-state.js";
+export type DropdownMenuRootProps = OverlayRootProps & Readonly<Pick<AriaMenuTriggerProps, "trigger">>;
+export declare function DropdownMenuRoot({ children, trigger, ...state }: DropdownMenuRootProps): import("react").JSX.Element;
 export type DropdownMenuTriggerProps = ButtonProps;
 export declare const DropdownMenuTrigger: import("react").ForwardRefExoticComponent<ButtonProps & import("react").RefAttributes<HTMLButtonElement>>;
 /** A button-triggered overlay. Its Content owns positioning; Menu owns commands and selection. */
 export declare const DropdownMenu: typeof DropdownMenuRoot & {
     Trigger: import("react").ForwardRefExoticComponent<ButtonProps & import("react").RefAttributes<HTMLButtonElement>>;
-    Content: import("react").ForwardRefExoticComponent<import("./popover.js").PopoverContentProps & import("react").RefAttributes<HTMLElement>>;
+    Content: import("react").ForwardRefExoticComponent<import("./popover.js").PopoverContentProps & Readonly<{
+        nonModal?: boolean;
+    }> & import("react").RefAttributes<HTMLElement>>;
     Menu: import("./menu.js").MenuRootComponent & {
         Item: import("./menu.js").MenuItemComponent;
-        Section: <T>(props: import("react-aria-components").MenuSectionProps<T> & React.RefAttributes<HTMLElement>) => import("react").ReactElement<unknown, string | React.JSXElementConstructor<any>> | null;
+        Section: <T extends object = object>(properties: import("./menu.js").MenuSectionProps<T>) => import("react").ReactElement | null;
         Header: import("react").ForwardRefExoticComponent<import("react-aria-components").HeaderProps & import("react").RefAttributes<HTMLElement>>;
         Separator: import("react").ForwardRefExoticComponent<import("react-aria-components").SeparatorProps & import("react").RefAttributes<HTMLElement>>;
     };

package/dist/dropdown-menu.js

@@ -2,10 +2,11 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { forwardRef } from "react";
 import { MenuTrigger as AriaMenuTrigger } from "react-aria-components";
 import { Button } from "./button.js";
+import { ariaOpenState } from "./control/open-state.js";
 import { Menu } from "./menu.js";
-import { PopoverContent } from "./popover.js";
-export function DropdownMenuRoot(properties) {
-    return _jsx(AriaMenuTrigger, { ...properties });
+import { MenuContent } from "./popover.js";
+export function DropdownMenuRoot({ children, trigger, ...state }) {
+    return _jsx(AriaMenuTrigger, { ...ariaOpenState(state), trigger: trigger, children: children });
 }
 export const DropdownMenuTrigger = forwardRef(function DropdownMenuTrigger(properties, ref) {
     return _jsx(Button, { ...properties, ref: ref });
@@ -13,6 +14,6 @@ export const DropdownMenuTrigger = forwardRef(function DropdownMenuTrigger(prope
 /** A button-triggered overlay. Its Content owns positioning; Menu owns commands and selection. */
 export const DropdownMenu = Object.assign(DropdownMenuRoot, {
     Trigger: DropdownMenuTrigger,
-    Content: PopoverContent,
+    Content: MenuContent,
     Menu
 });

package/dist/fieldset.d.ts

@@ -0,0 +1,13 @@
+import type { FieldsetHTMLAttributes, ReactNode } from "react";
+export interface FieldsetProps extends Omit<FieldsetHTMLAttributes<HTMLFieldSetElement>, "title"> {
+    /** Names the group for everyone, including assistive technology. */
+    readonly title: ReactNode;
+    readonly description?: ReactNode;
+    readonly children: ReactNode;
+}
+/**
+ * A titled group of related fields, such as one section of settings. Each
+ * field keeps its own label; the group adds only its title, its description,
+ * and the spacing between fields.
+ */
+export declare const Fieldset: import("react").ForwardRefExoticComponent<FieldsetProps & import("react").RefAttributes<HTMLFieldSetElement>>;

package/dist/fieldset.js

@@ -0,0 +1,26 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useId } from "react";
+import { controlFontSizes, controlFontWeight, controlOpacity, useControlMetrics } from "./control/control.js";
+import { resolveSpacing } from "./foundation/spacing.js";
+/**
+ * A titled group of related fields, such as one section of settings. Each
+ * field keeps its own label; the group adds only its title, its description,
+ * and the spacing between fields.
+ */
+export const Fieldset = forwardRef(function Fieldset({ title, description, children, style, ...properties }, ref) {
+    const metrics = useControlMetrics();
+    const { spacing } = metrics.visual;
+    const titleId = useId();
+    const descriptionId = useId();
+    // The title names the group through aria-labelledby: a styled legend loses
+    // its naming role in some browsers.
+    return _jsxs("fieldset", { "aria-labelledby": titleId, "aria-describedby": description != null ? descriptionId : undefined, ...properties, ref: ref, style: {
+            display: "grid",
+            gap: resolveSpacing("large", spacing),
+            minWidth: 0,
+            margin: 0,
+            padding: 0,
+            border: 0,
+            ...style
+        }, children: [_jsxs("div", { style: { display: "grid", gap: resolveSpacing("xsmall", spacing) }, children: [_jsx("span", { id: titleId, style: { fontSize: controlFontSizes.large, fontWeight: controlFontWeight }, children: title }), description != null && _jsx("span", { id: descriptionId, style: { fontSize: controlFontSizes.medium, opacity: controlOpacity.secondary }, children: description })] }), _jsx("div", { style: { display: "grid", gap: resolveSpacing("large", spacing), minWidth: 0 }, children: children })] });
+});

package/dist/file-trigger.d.ts

@@ -0,0 +1,13 @@
+import type { ReactNode } from "react";
+export interface FileTriggerProps {
+    /** A Button, or any pressable React UI control, that opens the file chooser. */
+    readonly children: ReactNode;
+    /** MIME types or extensions the chooser offers, such as `image/*` or `.html`. */
+    readonly accept?: readonly string[];
+    readonly multiple?: boolean;
+    /** Choose a directory instead of files. */
+    readonly directory?: boolean;
+    readonly onSelect?: (files: File[]) => void;
+}
+/** Opens the system file chooser from the control it wraps. It draws nothing of its own. */
+export declare function FileTrigger({ children, accept, multiple, directory, onSelect }: FileTriggerProps): import("react").JSX.Element;

package/dist/file-trigger.js

@@ -0,0 +1,6 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { FileTrigger as AriaFileTrigger } from "react-aria-components";
+/** Opens the system file chooser from the control it wraps. It draws nothing of its own. */
+export function FileTrigger({ children, accept, multiple, directory, onSelect }) {
+    return _jsx(AriaFileTrigger, { acceptedFileTypes: accept, allowsMultiple: multiple, acceptDirectory: directory, onSelect: files => onSelect?.(files === null ? [] : [...files]), children: children });
+}

package/dist/flex.d.ts

@@ -1,5 +1,5 @@
 import type { ComponentPropsWithoutRef } from "react";
-import type { LayoutAlignment, LayoutGap, LayoutJustification } from "./layout.js";
+import type { LayoutAlignment, LayoutGap, LayoutJustification } from "./foundation/layout.js";
 /** Properties accepted by the Flex layout primitive. */
 export interface FlexProps extends ComponentPropsWithoutRef<"div"> {
     /** Main-axis direction. The browser default is `row`. */

package/dist/flex.js

@@ -1,17 +1,18 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { forwardRef } from "react";
-import { alignment, justification, resolveGap } from "./layout.js";
-import { useAppearance } from "./ui-provider.js";
+import { alignment, justification } from "./foundation/layout.js";
+import { resolveSpacing } from "./foundation/spacing.js";
+import { useVisual } from "./foundation/visual.js";
 /** A predictable Flexbox container with no visual appearance of its own. */
 export const Flex = forwardRef(function Flex({ align, direction, gap, inline = false, justify, style, wrap, ...properties }, ref) {
-    const appearance = useAppearance();
+    const { spacing } = useVisual();
     return _jsx("div", { ...properties, ref: ref, style: {
             ...style,
             display: inline ? "inline-flex" : "flex",
             alignItems: alignment(align) ?? style?.alignItems,
             flexDirection: direction ?? style?.flexDirection,
             flexWrap: wrap === undefined ? style?.flexWrap : wrap === "reverse" ? "wrap-reverse" : wrap ? "wrap" : "nowrap",
-            gap: gap === undefined ? style?.gap : resolveGap(gap, appearance),
+            gap: gap === undefined ? style?.gap : resolveSpacing(gap, spacing),
             justifyContent: justification(justify) ?? style?.justifyContent
         } });
 });

package/dist/foundation/appearance.d.ts

@@ -0,0 +1,83 @@
+import { type Appearance as SystemAppearance, type AppearanceColors, type AppearanceMaterial, type AppearanceShadow, type AppearanceTransaction } from "@phreshos/core";
+export type { AppearanceColor, AppearanceColors, AppearanceMaterial, AppearanceRange, AppearanceShadow, AppearanceTransaction, Easing, ThemedValue } from "@phreshos/core";
+/** The System Appearance fields consumed by React UI. */
+export type Appearance = Pick<SystemAppearance, "colors" | "spacing" | "radius" | "shadow" | "material" | "transaction">;
+type Themed<Value> = Readonly<{
+    light?: Readonly<Partial<Value>>;
+    dark?: Readonly<Partial<Value>>;
+}>;
+type AppearanceUpdateFields = Readonly<{
+    colors?: Themed<AppearanceColors>;
+    spacing?: number;
+    radius?: number;
+    shadow?: Themed<AppearanceShadow>;
+    material?: Themed<AppearanceMaterial>;
+    transaction?: Readonly<Partial<AppearanceTransaction>>;
+}>;
+/** At least one partial visual field merged recursively with the nearest UIProvider. */
+export type AppearanceUpdate = {
+    [Field in keyof AppearanceUpdateFields]-?: Readonly<Required<Pick<AppearanceUpdateFields, Field>> & Omit<AppearanceUpdateFields, Field>>;
+}[keyof AppearanceUpdateFields];
+/** Bounds for the visual Appearance fields consumed by React UI. */
+export declare const appearanceLimits: Readonly<{
+    spacing: Readonly<{
+        minimum: 6;
+        maximum: 18;
+    }>;
+    radius: Readonly<{
+        minimum: 6;
+        maximum: 18;
+    }>;
+    shadow: Readonly<{
+        x: Readonly<{
+            minimum: -48;
+            maximum: 48;
+        }>;
+        y: Readonly<{
+            minimum: -48;
+            maximum: 48;
+        }>;
+        blur: Readonly<{
+            minimum: 0;
+            maximum: 96;
+        }>;
+        spread: Readonly<{
+            minimum: -24;
+            maximum: 24;
+        }>;
+        opacity: Readonly<{
+            minimum: 0;
+            maximum: 1;
+        }>;
+    }>;
+    material: Readonly<{
+        grain: Readonly<{
+            minimum: 0;
+            maximum: 1;
+        }>;
+        grainAmount: Readonly<{
+            minimum: 0;
+            maximum: 1;
+        }>;
+        backdrop: Readonly<{
+            minimum: 0;
+            maximum: 24;
+        }>;
+        opacity: Readonly<{
+            minimum: 0;
+            maximum: 1;
+        }>;
+        distortion: Readonly<{
+            minimum: 0;
+            maximum: 140;
+        }>;
+        saturation: Readonly<{
+            minimum: 1;
+            maximum: 2.6;
+        }>;
+    }>;
+}>;
+/** The visual portion of the System's default Appearance. */
+export declare const defaultAppearance: Appearance;
+/** Applies one partial update; omitted leaves continue to inherit. */
+export declare function mergeAppearance(appearance: Appearance, update: AppearanceUpdate): Appearance;

package/dist/foundation/appearance.js

@@ -0,0 +1,38 @@
+import { appearanceLimits as coreAppearanceLimits, defaultAppearance as systemDefaultAppearance } from "@phreshos/core";
+/** Bounds for the visual Appearance fields consumed by React UI. */
+export const appearanceLimits = Object.freeze({
+    spacing: coreAppearanceLimits.spacing,
+    radius: coreAppearanceLimits.radius,
+    shadow: coreAppearanceLimits.shadow,
+    material: coreAppearanceLimits.material
+});
+/** The visual portion of the System's default Appearance. */
+export const defaultAppearance = Object.freeze({
+    colors: systemDefaultAppearance.colors,
+    spacing: systemDefaultAppearance.spacing,
+    radius: systemDefaultAppearance.radius,
+    shadow: systemDefaultAppearance.shadow,
+    material: systemDefaultAppearance.material,
+    transaction: systemDefaultAppearance.transaction
+});
+/** Applies one partial update; omitted leaves continue to inherit. */
+export function mergeAppearance(appearance, update) {
+    return Object.freeze({
+        colors: mergeThemed(appearance.colors, update.colors),
+        spacing: update.spacing ?? appearance.spacing,
+        radius: update.radius ?? appearance.radius,
+        shadow: mergeThemed(appearance.shadow, update.shadow),
+        material: mergeThemed(appearance.material, update.material),
+        transaction: update.transaction === undefined
+            ? appearance.transaction
+            : Object.freeze({ ...appearance.transaction, ...update.transaction })
+    });
+}
+function mergeThemed(current, update) {
+    if (update === undefined)
+        return current;
+    return Object.freeze({
+        light: update.light === undefined ? current.light : Object.freeze({ ...current.light, ...update.light }),
+        dark: update.dark === undefined ? current.dark : Object.freeze({ ...current.dark, ...update.dark })
+    });
+}

package/dist/{aria-direction.js → foundation/aria-direction.js}

@@ -3,6 +3,8 @@ import { useMemo } from "react";
 import { useLocale } from "react-aria/I18nProvider";
 const ariaDirectionBoundary = "data-phreshos-ui-aria-direction";
 const redirectedEvents = new WeakSet();
+// Text entry keeps native caret movement; choice inputs move selection by direction.
+const directionalInputTypes = new Set(["radio", "checkbox", "range"]);
 /** Aligns React Aria's directional keyboard behavior with the React UI direction contract. */
 export function useAriaDirectionBridge(direction) {
     const { direction: ariaDirection } = useLocale();
@@ -18,7 +20,7 @@ export function useAriaDirectionBridge(direction) {
             if (!(target instanceof Element) || target.closest(`[${ariaDirectionBoundary}]`) !== event.currentTarget)
                 return;
             const editable = target.closest("[contenteditable=true]");
-            if (target instanceof HTMLInputElement || target instanceof HTMLTextAreaElement || target instanceof HTMLSelectElement || (editable && editable.getAttribute("role") !== "spinbutton"))
+            if ((target instanceof HTMLInputElement && !directionalInputTypes.has(target.type)) || target instanceof HTMLTextAreaElement || target instanceof HTMLSelectElement || (editable && editable.getAttribute("role") !== "spinbutton"))
                 return;
             event.preventDefault();
             event.stopPropagation();

package/dist/foundation/color.d.ts

@@ -0,0 +1,61 @@
+import type { AppearanceColor, AppearanceColors } from "./appearance.js";
+/** A treatment derived from one base color relative to the canvas and content. */
+export type ColorLevel = "subtle" | "soft" | "base" | "strong" | "intense";
+/** Every treatment derived from one base color. */
+export type ColorScale = Readonly<Record<ColorLevel, string>>;
+/** An Appearance color, an Appearance color at one level, or a direct CSS color. */
+export type Color = AppearanceColor | `${AppearanceColor}:${ColorLevel}` | (string & {});
+/** Returns an opaque sRGB serialization, or `null` when the value is not a concrete CSS color. */
+export declare function concreteColor(value: string): string | null;
+/** WCAG relative luminance of a concrete color, or `null` when it cannot be evaluated. */
+export declare function luminance(value: string): number | null;
+/** WCAG contrast ratio between two colors, or `null` when either cannot be evaluated. */
+export declare function contrast(first: string, second: string): number | null;
+/**
+ * Mixes `amount` of `target` into `base` in OKLab, concretely when possible.
+ * OKLab keeps the hue while moving toward a near-neutral canvas or text color;
+ * OKLCH would rotate the hue toward the neutral's meaningless angle.
+ */
+export declare function mixColor(base: string, target: string, amount: number): string;
+/** Applies transparency without restricting the source CSS color syntax. */
+export declare function colorOpacity(value: string, opacity: number): string;
+/** Resolves one Color against the active Appearance colors. */
+export declare function resolveColor(value: Color, colors: AppearanceColors): string;
+/** Derives one level from a concrete base color. */
+export declare function colorLevel(base: string, level: ColorLevel, colors: AppearanceColors): string;
+/** Every level derived from one base color. */
+export declare function colorScale(base: string, colors: AppearanceColors): ColorScale;
+/**
+ * Perceived lightness contrast (APCA Lc magnitude) of `text` drawn on `fill`,
+ * or `null` when either cannot be evaluated. Unlike the WCAG 2 ratio, it is
+ * polarity-aware: the WCAG ratio overrates dark text on saturated mid-tone
+ * fills such as blue or green, where light text actually reads better.
+ */
+export declare function readability(fill: string, text: string): number | null;
+/**
+ * Returns the Appearance text color, `foreground`, unless `background` reads
+ * clearly better on the fill: better by at least one APCA step.
+ */
+export declare function readableColor(fill: string, colors: AppearanceColors): string;
+/** Whether the canvas is darker than its content, derived from the colors themselves. */
+export declare function darkCanvas(colors: AppearanceColors): boolean;
+/**
+ * How dark the canvas is, from 0 (a light canvas) to 1 (a dark canvas), read
+ * from the perceptual lightness of the background itself. Treatments that
+ * depend on the canvas interpolate along it instead of switching at a threshold,
+ * so a mid-tone canvas receives a mid-tone treatment.
+ */
+export declare function canvasDarkness(colors: AppearanceColors): number;
+/**
+ * The paint of a recess in `base`: the same color moved just far enough toward
+ * whichever extreme has more room to reach one constant perceptual difference.
+ * Depth therefore reads the same on a light, mid-tone, or dark canvas.
+ */
+export declare function recessColor(base: string): string;
+/** The lighter Appearance content candidate: the paint of anything lit from above, such as a thumb. */
+export declare function lightColor(colors: AppearanceColors): string;
+export declare function isColorLevel(value: string): value is ColorLevel;
+/** Every level derived from one color in the active Appearance. */
+export declare function useColor(value: Color): ColorScale;
+/** The readable content color for one fill in the active Appearance. */
+export declare function useContrastingColor(value: Color): string;