@phreshos/react-ui 0.1.15 → 0.1.17

package/README.md

@@ -2,8 +2,19 @@
 
 Environment-neutral React components and the visual language of PhreshOS.
 
-React UI interprets Core Appearance and Theme contracts. It does not depend on a
-Client or Server runtime and does not own authoritative application state.
+[Appearance](https://docs.phreshos.com/system/appearance) ·
+[React SDK](https://docs.phreshos.com/sdks/react) ·
+[Source](https://github.com/PhreshOS/react-ui)
+
+## Role
+
+React UI interprets Core Appearance and Theme contracts as reusable visual
+primitives. The Desktop and Programs compose those primitives instead of
+reimplementing material, spacing, color, radius, or interaction behavior.
+
+The package does not depend on a Client or Server runtime and does not own
+authoritative application state. React owns runtime-neutral state adaptation;
+applications own composition.
 
 ## Installation
 
@@ -14,45 +25,192 @@ Client or Server runtime and does not own authoritative application state.
 | Bun | `bun add @phreshos/react-ui` |
 | Yarn | `yarn add @phreshos/react-ui` |
 
-`@phreshos/core`, React, and React DOM are peer dependencies.
+Core is a built-in runtime dependency. React and React DOM remain peer
+dependencies because the application and React UI must share one React
+runtime.
 
-## Appearance
+```tsx
+import { Button, Surface } from "@phreshos/react-ui"
+
+<Surface>
+  <Button>Continue</Button>
+</Surface>
+```
+
+Without a provider, components use Core's `defaultAppearance` and reactively
+follow the browser color scheme. `AppearanceProvider` independently overrides
+either value for a subtree; omitted values inherit from the nearest provider.
+React UI also exports that same canonical `defaultAppearance` value for callers
+that need it explicitly.
+See [Appearance](https://docs.phreshos.com/system/appearance) for the contract
+interpreted by the provider and components.
 
 ```tsx
-import { standardAppearance } from "@phreshos/core"
-import {
-  AppearanceProvider,
-  Button,
-  Surface,
-} from "@phreshos/react-ui"
-
-<AppearanceProvider appearance={standardAppearance} theme="light">
-  <Surface>
-    <Button>Continue</Button>
-  </Surface>
+import { AppearanceProvider, Button } from "@phreshos/react-ui"
+
+<AppearanceProvider theme="dark">
+  <Button>Dark subtree</Button>
 </AppearanceProvider>
 ```
 
-`AppearanceProvider` provides the unresolved Appearance and one effective
-`"light" | "dark"` Theme. `useAppearance()` reads the unresolved value,
-`useTheme()` reads the effective mode, and `useResolveTheme()` resolves one
-themed property where it is consumed.
+`Button`, `Input`, `Textarea`, `Select`, `Checkbox`, `Switch`, and `Radio`
+host the shared Material while retaining their native behavior. Color and material
+are independent inputs. `color` accepts an Appearance color and resting level such
+as `background:base` or `primary:soft`, or a direct CSS color. Material and neutral
+surface hosts default to `background:base`; a component may select a semantic
+default required by its own behavior, such as `primary:base` for selection.
+Hover and press derive shades of that fill. The resting fill chooses the
+higher-contrast text from Appearance's background and foreground once; interaction
+shades keep that choice.
+`size` accepts `xsmall`, `small`, `medium` (default), `large`, or `xlarge`;
+spacing and radius follow Appearance. `disabled` prevents activation and focus;
+`pending` prevents activation while retaining focus.
 
-The provider also applies the shared document scrollbar treatment without
-adding a rendered container.
+```tsx
+<Button>Cancel</Button>
+<Button color="primary:base" onPress={save}>Save</Button>
+<Button color="danger:soft" size="small">Delete</Button>
+```
+
+`Material` is the raw visual substance: paint, opacity, frost, refraction, and
+grain. It fills the geometry of its nearest positioned container,
+inherits that container's radius, and adds no content, layout, interaction, or
+shadow. The container must establish its own geometry and isolation.
+
+```tsx
+<div style={{ position: "relative", isolation: "isolate", width: 240, height: 120, borderRadius: 18 }}>
+  <Material color="background:soft" material={{ opacity: 0.4 }} />
+</div>
+```
 
-## Components
+`Surface` is the standard geometric host for a `Material`. It establishes the
+required positioning and isolation on a `div`, resolves radius, renders Material,
+and then renders its content. It never creates or consumes a shadow. Shadow remains
+an independent visual concern. `radius` accepts a size level, a number in pixels,
+or a CSS radius and defaults to `medium`.
 
-The package owns the reusable visual primitives used across the desktop and
-official Programs:
+```tsx
+<Surface color="background:soft" radius="large">Derived values</Surface>
+<Surface color="#345678" radius={18}>Direct values</Surface>
+```
 
-- `Surface` and `SurfaceMaterial`
-- `Button`
-- `Flex` and `Grid`
-- spacing, scale, radius, color, and icon utilities
+`MaterialOptions` defines `opacity`, `backdrop`, `grain`, `grainAmount`,
+`distortion`, and `saturation`. It contains no color. `MaterialProps` keeps
+`color` beside `material?: MaterialOptions`, so paint selection never becomes a
+physical-material setting. Omitted material values follow `appearance.material`.
+Effect options accept a scale level or a direct number; opacity affects material
+only, never the host's children.
 
-These primitives form one visual language. Desktop and Program Views compose
-them rather than reimplementing their material or layout behavior.
+Radius belongs to host geometry, while Surface's border belongs to its geometric
+boundary. Material may determine the border treatment, but it neither owns nor
+renders that border.
+
+Material-bearing controls expose the same separate `color` and `material` props.
+For text fields and Select, `material` targets the field or trigger; for Checkbox,
+Switch, and Radio, it targets the indicator. RadioGroup supplies material defaults
+to its options, and a Radio can override them.
+
+```tsx
+<Button color="primary:base" material={{ opacity: 0.6, backdrop: 0 }}>Save</Button>
+<Input label="Name" radius="large" material={{ grain: "small" }} />
+```
+
+`Panel` composes an outer `Surface`, an optional header, and an inset content
+`Surface`. Both materials retain Surface defaults; the content inset follows
+Appearance spacing. Positioning, modality, and lifecycle belong to the caller.
+
+```tsx
+import { Panel } from "@phreshos/react-ui"
+
+<Panel header={<h2>Title</h2>} contentProps={{ style: { padding: 16 } }}>
+  Content
+</Panel>
+```
+
+Native properties and the forwarded ref target the outer Surface.
+`contentProps` targets the inner Surface; `children` supplies its content.
+
+## Inputs
+
+Every input uses Appearance colors and the same five `size` levels as Button.
+`color` selects the fill independently from material. Input, Textarea, Select,
+and Button use `background:base` when it is omitted; selection indicators use
+`primary:base`. Invalid
+fields use danger instead. Text fields share Surface's glass edge. Interaction shades
+derive from the base color's lightness, and text or selection marks use whichever
+Appearance background or foreground has higher contrast against the base fill.
+That text or mark color stays unchanged across interaction shades.
+These are component-owned derivations, not additional Appearance settings.
+Theme names never imply particular colors. No component requires a Client or
+Server SDK.
+
+Fields distinguish hover, pointer focus, keyboard focus, and invalid state.
+Shared CSS transitions use a fixed 120ms ease-out timing for colors and corner
+radius. Material fill and opacity transition on the painted layers, not on the
+Surface host. Select menus combine a small placement-aware slide with an overlay
+opacity fade for entry and exit, using React Aria's animation lifecycle. Reduced-motion preferences make
+these changes immediate. No Appearance configuration is added for motion yet.
+Blur, distortion, geometry, and Surface host opacity are not transitioned; gradients
+and structurally removed effects change directly rather than adding extra
+layers or keeping disabled effects alive.
+
+Motion animates toggle presses, selection marks, switch travel, the Select
+chevron, and Slider thumb feedback. Reduced-motion preferences remove spatial
+feedback and make state transitions immediate. Slider values and native input
+behavior are never delayed by visual animation.
+
+| Component | Value contract | Purpose |
+| --- | --- | --- |
+| `Input` | `value`, `defaultValue`, `onChange(string)` | Single-line text; supports text, email, password, search, URL, and telephone types |
+| `Textarea` | `value`, `defaultValue`, `onChange(string)` | Multiline text; four rows by default, vertically resizable |
+| `Checkbox` | `checked`, `defaultChecked`, `onChange(boolean)` | Independent selection; `indeterminate` represents a mixed state |
+| `Switch` | `checked`, `defaultChecked`, `onChange(boolean)` | An on/off setting |
+| `RadioGroup` / `Radio` | Group `value`, `defaultValue`, `onChange(string)`; Radio `value` | One exclusive choice; vertical by default, optionally horizontal |
+| `Select` | `value: string \| null`, `defaultValue`, `onChange(string \| null)` | One choice from `options: { value, label, disabled? }[]` |
+| `Slider` | `value`, `defaultValue`, `onChange(number)` | One numeric value; `minValue`, `maxValue`, `step`, and `onChangeEnd`; horizontal by default |
+
+Use `label` for visible labels, or `aria-label` / `aria-labelledby` for an
+accessible name without visible text. `description` provides associated help.
+`disabled` prevents interaction and removes the control from keyboard focus.
+`name` participates in native form submission. Controlled values remain owned
+by the caller; omit them and use defaults for internal state and form reset.
+
+Text fields, Checkbox, Switch, and RadioGroup also support `readOnly`: the
+value cannot change, but the control remains focusable. These fields and
+Select support `required`, `invalid`, `errorMessage`, and React Aria's native
+or ARIA validation behavior. A Radio's selection and validation belong to its
+group. Slider represents a bounded number rather than a required text or
+choice field, and has no read-only or validation-error mode. Select has no
+read-only mode; disable it when selection must be unavailable.
+
+`Input`, `Textarea`, and `Select` accept `radius`. Other inputs retain their
+intrinsic indicator shapes. `className` and `style` address the field's root;
+default visual properties remain component-owned. Input and Textarea refs
+target their native text controls; other refs target the root div. Checkbox,
+Switch, and Radio additionally accept `inputRef` for their native input.
+
+```tsx
+import { Input, Textarea, Checkbox, Radio, RadioGroup, Switch, Select, Slider } from "@phreshos/react-ui"
+
+<Input label="Name" name="name" required />
+<Textarea label="Description" name="description" />
+<Checkbox label="Remember this choice" name="remember" />
+<Switch label="Notifications" name="notifications" defaultChecked />
+<RadioGroup label="Layout" name="layout" defaultValue="grid">
+  <Radio label="Grid" value="grid" />
+  <Radio label="List" value="list" />
+</RadioGroup>
+<Select label="Sort" name="sort" options={[
+  { value: "name", label: "Name" },
+  { value: "date", label: "Date" }
+]} />
+<Slider label="Volume" name="volume" defaultValue={50} minValue={0} maxValue={100} step={1} />
+```
+
+React Aria owns focus, keyboard, form, and selection behavior. Select's popup
+uses Surface defaults. Toggle indicators use Motion internally and respect
+reduced-motion preferences. The preview Program demonstrates each input's
+sizes, colors, state, and interaction without overriding its visual defaults.
 
 ## Development
 
@@ -62,13 +220,20 @@ bun run verify
 ```
 
 `verify` checks the contracts, tests the components, builds the package, and
-validates its public artifact.
+validates its published shape.
 
-## Repository boundary
+## Related repositories
 
-This repository owns visual interpretation and reusable React components. Core
-owns Appearance contracts, React owns runtime-neutral state adaptation, and
-applications own composition.
+- [`@phreshos/core`](https://github.com/PhreshOS/core) owns Appearance, Theme,
+  and the shared values interpreted here.
+- [`@phreshos/react`](https://github.com/PhreshOS/react) owns runtime-neutral
+  React state adaptation.
+- [PhreshOS System](https://github.com/PhreshOS/system) composes the visual
+  language into the Desktop.
+- [Settings](https://github.com/PhreshOS/settings-program) presents owner-facing
+  Appearance controls.
+
+## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for the repository workflow and
 [SECURITY.md](SECURITY.md) for private vulnerability reporting.

package/dist/appearance-provider.d.ts

@@ -1,17 +1,15 @@
 import type { ReactNode } from "react";
-import type { Appearance, Theme, ThemedValue } from "@phreshos/core";
-/** Provides unresolved Appearance and one effective Theme to a React subtree. */
+import { type Appearance, type Theme, type ThemedValue } from "@phreshos/core";
+/** Optionally overrides unresolved Appearance and effective Theme for a React subtree. */
 export declare function AppearanceProvider({ appearance, children, theme }: AppearanceProviderProps): import("react").JSX.Element;
-/** Returns the complete unresolved Appearance supplied by the nearest provider. */
+/** Returns the nearest unresolved Appearance, or Core's complete default. */
 export declare function useAppearance(): Appearance;
-/** Returns the effective Theme supplied by the nearest provider. */
+/** Returns the nearest explicit Theme, or reactively follows the browser. */
 export declare function useTheme(): Theme;
 /** Resolves one themed value only where it is consumed. */
 export declare function useResolveTheme<Value, DarkValue extends Value = never>(value: ThemedValue<Value, DarkValue>): Exclude<Value, undefined>;
-/** Internal optional read for primitives that also accept direct values. */
-export declare function useAppearanceIfAvailable(): Appearance | null;
 export interface AppearanceProviderProps {
-    readonly appearance: Appearance;
+    readonly appearance?: Appearance;
     readonly children: ReactNode;
-    readonly theme: Theme;
+    readonly theme?: Theme;
 }

package/dist/appearance-provider.js

@@ -1,34 +1,49 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { createContext, useContext } from "react";
+import { createContext, useContext, useSyncExternalStore } from "react";
+import { defaultAppearance } from "@phreshos/core";
 import DocumentScrollbars from "./document-scrollbars.js";
-const missing = Symbol("AppearanceProvider");
-const AppearanceContext = createContext(missing);
-const ThemeContext = createContext(missing);
-/** Provides unresolved Appearance and one effective Theme to a React subtree. */
+import MotionStyle from "./motion-style.js";
+const AppearanceContext = createContext(defaultAppearance);
+const ThemeContext = createContext(null);
+/** Optionally overrides unresolved Appearance and effective Theme for a React subtree. */
 export function AppearanceProvider({ appearance, children, theme }) {
-    return _jsx(AppearanceContext.Provider, { value: appearance, children: _jsxs(ThemeContext.Provider, { value: theme, children: [_jsx(DocumentScrollbars, { appearance: appearance, theme: theme }), children] }) });
+    const inheritedAppearance = useAppearance();
+    const inheritedTheme = useTheme();
+    const resolvedAppearance = appearance ?? inheritedAppearance;
+    const resolvedTheme = theme ?? inheritedTheme;
+    return _jsx(AppearanceContext.Provider, { value: resolvedAppearance, children: _jsxs(ThemeContext.Provider, { value: resolvedTheme, children: [_jsx(MotionStyle, {}), _jsx(DocumentScrollbars, { appearance: resolvedAppearance, theme: resolvedTheme }), children] }) });
 }
-/** Returns the complete unresolved Appearance supplied by the nearest provider. */
+/** Returns the nearest unresolved Appearance, or Core's complete default. */
 export function useAppearance() {
-    const appearance = useContext(AppearanceContext);
-    if (appearance === missing)
-        throw new Error("useAppearance() requires an AppearanceProvider");
-    return appearance;
+    return useContext(AppearanceContext);
 }
-/** Returns the effective Theme supplied by the nearest provider. */
+/** Returns the nearest explicit Theme, or reactively follows the browser. */
 export function useTheme() {
     const theme = useContext(ThemeContext);
-    if (theme === missing)
-        throw new Error("useTheme() requires an AppearanceProvider");
-    return theme;
+    const browserTheme = useBrowserTheme();
+    return theme ?? browserTheme;
 }
 /** Resolves one themed value only where it is consumed. */
 export function useResolveTheme(value) {
     const theme = useTheme();
     return (theme === "dark" && "dark" in value ? value.dark : value.light);
 }
-/** Internal optional read for primitives that also accept direct values. */
-export function useAppearanceIfAvailable() {
-    const appearance = useContext(AppearanceContext);
-    return appearance === missing ? null : appearance;
+function useBrowserTheme() {
+    return useSyncExternalStore(subscribeBrowserTheme, browserTheme, serverTheme);
 }
+function subscribeBrowserTheme(change) {
+    if (typeof window === "undefined" || typeof window.matchMedia !== "function")
+        return () => undefined;
+    const preference = window.matchMedia(darkThemeQuery);
+    preference.addEventListener("change", change);
+    return () => preference.removeEventListener("change", change);
+}
+function browserTheme() {
+    return typeof window !== "undefined"
+        && typeof window.matchMedia === "function"
+        && window.matchMedia(darkThemeQuery).matches
+        ? "dark"
+        : "light";
+}
+function serverTheme() { return "light"; }
+const darkThemeQuery = "(prefers-color-scheme: dark)";

package/dist/button.d.ts

@@ -1,12 +1,18 @@
 import type { CSSProperties, ReactNode } from "react";
 import type { ButtonProps as AriaButtonProps } from "react-aria-components";
-import { type ScaleLevel } from "./scale.js";
-import { type RadiusProps } from "./radius.js";
-type NativeButtonProps = Omit<AriaButtonProps, "children" | "className" | "isDisabled" | "isPending" | "onClick" | "onPress" | "style">;
+import type { ScaleLevel } from "./scale.js";
+import type { RadiusProps } from "./radius.js";
+import { type ControlColor } from "./control.js";
+import type { MaterialOverrides } from "./material.js";
+type NativeButtonProps = Omit<AriaButtonProps, "children" | "className" | "color" | "isDisabled" | "isPending" | "onClick" | "onPress" | "style">;
+/** A semantic color from Appearance; omission uses background and foreground. */
+export type ButtonColor = ControlColor;
 /** Properties accepted by the shared interactive button. */
-export interface ButtonProps extends NativeButtonProps, RadiusProps {
+export interface ButtonProps extends NativeButtonProps, RadiusProps, MaterialOverrides {
     /** Visible Button content. */
     readonly children?: ReactNode;
+    /** Base color for the material. Omission keeps the Button neutral. */
+    readonly color?: ButtonColor;
     /** Native class name applied without replacing the component contract. */
     readonly className?: string;
     /** Prevents focus and activation. */
@@ -17,7 +23,7 @@ export interface ButtonProps extends NativeButtonProps, RadiusProps {
     readonly onPress?: () => void;
     /** Derives the Button's spacing from Appearance's concrete default. */
     readonly size?: ScaleLevel;
-    /** Additional native styles that do not replace the Button's identity. */
+    /** Native styles applied after Button defaults. */
     readonly style?: CSSProperties;
 }
 /** An Appearance-aware action with normalized pointer and keyboard behavior. */

package/dist/button.js

@@ -1,34 +1,33 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { forwardRef } from "react";
 import { Button as AriaButton } from "react-aria-components";
-import { scale } from "./scale.js";
-import { resolveRadius } from "./radius.js";
-import { useAppearance, useResolveTheme } from "./appearance-provider.js";
+import { controlFontSizes, useControlTheme } from "./control.js";
+import { MaterialButton } from "./control-material.js";
+import { visualTransition } from "./motion-style.js";
 /** An Appearance-aware action with normalized pointer and keyboard behavior. */
-export const Button = forwardRef(function Button({ children, disabled = false, pending = false, onPress, radius = "medium", size = "medium", style, type = "button", ...properties }, ref) {
-    const appearance = useAppearance();
-    const spacing = scale(useResolveTheme(appearance.spacing), size);
-    const borderRadius = resolveRadius(radius, appearance);
-    const foreground = useResolveTheme(appearance.foreground);
-    return _jsx(AriaButton, { ...properties, ref: ref, type: type, isDisabled: disabled, isPending: pending, onPress: onPress, style: ({ isFocusVisible, isHovered, isPressed }) => buttonStyle({
-            borderRadius,
+export const Button = forwardRef(function Button({ children, color, disabled = false, pending = false, onPress, radius = "medium", size = "medium", style, material, type = "button", ...properties }, ref) {
+    const theme = useControlTheme({ color, radius, size });
+    return _jsx(AriaButton, { ...properties, ref: ref, type: type, isDisabled: disabled, isPending: pending, onPress: onPress, render: (native, state) => _jsx(MaterialButton, { native: native, material: material, paint: buttonPaint(theme, !disabled && !pending, state.isHovered, state.isPressed) }), style: ({ isFocusVisible, isHovered, isPressed }) => buttonStyle({
+            theme,
             disabled,
             isFocusVisible,
             isHovered,
             isPressed,
             pending,
             size,
-            spacing,
-            foreground,
             style
         }), children: children });
 });
-function buttonStyle({ borderRadius, disabled, isFocusVisible, isHovered, isPressed, pending, size, spacing, foreground, style }) {
-    const fontSize = buttonFontSizes[size];
-    const height = Math.max(size === "xsmall" ? 24 : 28, 20 + spacing);
+function buttonStyle({ theme, disabled, isFocusVisible, isHovered, isPressed, pending, size, style }) {
+    const fontSize = controlFontSizes[size];
+    const { spacing, foreground } = theme;
+    const height = Math.max(24, 24 + spacing);
+    const interactive = !disabled && !pending;
+    const paint = buttonPaint(theme, interactive, isHovered, isPressed);
     return {
-        ...style,
+        ...visualTransition,
         appearance: "none",
+        boxSizing: "border-box",
         display: "inline-grid",
         gridAutoFlow: "column",
         gridAutoColumns: "max-content",
@@ -37,34 +36,27 @@ function buttonStyle({ borderRadius, disabled, isFocusVisible, isHovered, isPres
         minWidth: 0,
         height,
         paddingBlock: 0,
-        paddingInline: Math.max(8, spacing * 2 / 3),
+        paddingInline: Math.max(8, spacing),
         gap: Math.max(4, spacing / 2),
-        border: "1px solid rgba(255, 255, 255, 0.45)",
-        borderRadius,
-        outline: "none",
-        color: foreground,
-        backgroundColor: `rgba(255, 255, 255, ${isPressed ? 0.42 : isHovered ? 0.5 : 0.3})`,
-        boxShadow: isFocusVisible
-            ? "0 0 0 2px rgba(255, 255, 255, 0.85), inset 0 1px 0 rgba(255, 255, 255, 0.8)"
-            : "inset 0 1px 0 rgba(255, 255, 255, 0.8)",
+        border: "none",
+        borderRadius: theme.radius,
+        outline: isFocusVisible ? `2px solid ${foreground}` : "none",
+        outlineOffset: 2,
+        ...paint,
         opacity: disabled ? 0.46 : pending ? 0.68 : 1,
-        transform: isPressed ? "scale(0.95)" : "scale(1)",
-        transition: "background-color 100ms ease, box-shadow 100ms ease, opacity 100ms ease, transform 100ms ease",
         cursor: disabled ? "not-allowed" : pending ? "progress" : "pointer",
         font: "inherit",
         fontSize,
-        fontWeight: 650,
+        fontWeight: 550,
         lineHeight: 1,
         textAlign: "center",
         textDecoration: "none",
         userSelect: "none",
-        WebkitTapHighlightColor: "transparent"
+        WebkitTapHighlightColor: "transparent",
+        ...style
     };
 }
-const buttonFontSizes = Object.freeze({
-    xsmall: 10,
-    small: 11,
-    medium: 12,
-    large: 13,
-    xlarge: 14
-});
+function buttonPaint(theme, interactive, hovered, pressed) {
+    const paints = theme.colored ? theme.paints.palette : theme.paints.neutral;
+    return interactive && pressed ? paints.pressed : interactive && hovered ? paints.hover : paints.rest;
+}

package/dist/checkbox.d.ts

@@ -0,0 +1,11 @@
+import type { CheckboxFieldProps } from "react-aria-components";
+import type { ControlOverrides, ControlProps, FieldProps } from "./control.js";
+import type { MaterialOverrides } from "./material.js";
+export interface CheckboxProps extends Omit<CheckboxFieldProps, ControlOverrides | "isReadOnly" | "isSelected" | "defaultSelected" | "isIndeterminate">, ControlProps, FieldProps, MaterialOverrides {
+    readonly checked?: boolean;
+    readonly defaultChecked?: boolean;
+    readonly indeterminate?: boolean;
+    readonly readOnly?: boolean;
+}
+/** An independent boolean field with optional mixed-state presentation. */
+export declare const Checkbox: import("react").ForwardRefExoticComponent<CheckboxProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/checkbox.js

@@ -0,0 +1,10 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef } from "react";
+import { CheckboxField, CheckboxButton } from "react-aria-components";
+import { FieldFeedback, fieldStyle, useControlTheme } from "./control.js";
+import { ToggleIndicator, toggleStyle } from "./toggle-indicator.js";
+/** An independent boolean field with optional mixed-state presentation. */
+export const Checkbox = forwardRef(function Checkbox({ label, description, errorMessage, disabled, required, invalid, readOnly, checked, defaultChecked, indeterminate, size, color, style, material, ...properties }, ref) {
+    const theme = useControlTheme({ size, color });
+    return _jsxs(CheckboxField, { ...properties, ref: ref, isDisabled: disabled, isRequired: required, isInvalid: invalid, isReadOnly: readOnly, isSelected: checked, defaultSelected: defaultChecked, isIndeterminate: indeterminate, style: state => fieldStyle(theme, state.isDisabled, style), children: [_jsx(CheckboxButton, { style: state => toggleStyle(theme, state.isDisabled, state.isReadOnly), children: state => _jsxs(_Fragment, { children: [_jsx(ToggleIndicator, { kind: "checkbox", material: material, theme: theme, selected: state.isSelected, indeterminate: state.isIndeterminate, focused: state.isFocusVisible, invalid: state.isInvalid, hovered: !state.isDisabled && !state.isReadOnly && state.isHovered, pressed: !state.isDisabled && !state.isReadOnly && state.isPressed }), label] }) }), _jsx(FieldFeedback, { theme: theme, description: description, errorMessage: errorMessage })] });
+});

package/dist/color.d.ts

@@ -1,10 +1,50 @@
+import type { AppearanceColor } from "@phreshos/core";
 /** A visual treatment derived from one concrete CSS color. */
 export type ColorLevel = "subtle" | "soft" | "base" | "strong" | "intense";
 /** Every visual treatment derived from one concrete CSS color. */
 export type ColorScale = Readonly<Record<ColorLevel, string>>;
+/** One Appearance color and resting level, or a direct CSS color. */
+export type Color = `${AppearanceColor}:${ColorLevel}` | (string & {});
+export declare const defaultColor = "background:base";
+/** Distinguishes derived color levels from direct CSS colors. */
+export declare function isColorLevel(value: string | undefined): value is ColorLevel;
 /** Derives visual treatments while preserving the concrete value at `base`. */
 export declare function color(value: string): ColorScale;
+/** Resolves the same named treatment for solid paint and contrast calculations. */
+export declare function resolveColorLevel(value: string, level: ColorLevel): string;
 /** Returns the complete visual treatments derived from one concrete color. */
 export declare function useColor(value: string): ColorScale;
+/** Resolves a semantic Appearance color or preserves a direct CSS color. */
+export declare function useResolveColor(value?: Color): string;
+/** Resolves a color to concrete opaque paint for solid interactive states. */
+export declare function useResolveSolidColor(value: Color): string;
 /** Applies material opacity without restricting the source CSS color syntax. */
 export declare function colorOpacity(value: string, opacity: number): string;
+/** Reads perceptual lightness from a resolved CSS color. */
+export declare function colorLightness(value: string): number;
+/** Orders resolved CSS colors by perceptual lightness, never by their role. */
+export declare function orderColors(first: string, second: string): {
+    lighter: string;
+    darker: string;
+};
+/** Solid controls use opaque, gamut-mapped colors for both paint and contrast. */
+export declare function opaqueColor(value: string): string;
+/** Changes only perceptual lightness; theme names never determine direction. */
+export declare function colorShade(value: string, amount: number): string;
+/** Chooses only from the two Appearance colors, against the actual painted fill. */
+export declare function onColor(fill: string, background: string, foreground: string): string;
+/** Solid controls start at base; interaction shades preserve its text choice. */
+export declare function solidColors(base: string, background: string, foreground: string): {
+    rest: {
+        background: string;
+        color: string;
+    };
+    hover: {
+        background: string;
+        color: string;
+    };
+    pressed: {
+        background: string;
+        color: string;
+    };
+};