@phreshos/react-ui 0.1.38 → 0.1.40

package/dist/main.js

@@ -40,6 +40,18 @@ export { Spinner } from "./spinner.js";
 export { NumberField } from "./number-field.js";
 export { SegmentedControl } from "./segmented-control.js";
 export { Alert } from "./alert.js";
+export { Link } from "./link.js";
+export { Heading, Text, Kbd, Code } from "./typography.js";
+export { Badge } from "./badge.js";
+export { Meter } from "./meter.js";
+export { SearchField } from "./search-field.js";
+export { Breadcrumbs } from "./breadcrumbs.js";
+export { Avatar } from "./avatar.js";
+export { TagGroup } from "./tag-group.js";
+export { Skeleton } from "./skeleton.js";
+export { toast, ToastRegion } from "./toast.js";
+export { Readiness, useReadiness, useRequirement } from "./readiness.js";
+export { Loading } from "./loading.js";
 export { FileTrigger } from "./file-trigger.js";
 export { DropZone } from "./drop-zone.js";
 export { Fieldset } from "./fieldset.js";

package/dist/meter.d.ts

@@ -0,0 +1,26 @@
+import type { CSSProperties, ReactNode } from "react";
+import { type MeterProps as AriaMeterProps } from "react-aria-components";
+import { type Color } from "./foundation/color.js";
+import type { ScaleLevel } from "./foundation/scale.js";
+import type { MaterialOverrides } from "./surface/material-options.js";
+type NativeMeterProps = Omit<AriaMeterProps, "children" | "className" | "style">;
+export interface MeterProps extends NativeMeterProps, MaterialOverrides {
+    readonly className?: string;
+    /** Color of the measured portion while no threshold is reached. */
+    readonly color?: Color;
+    /** From this share of the range, between 0 and 1, the measure turns `warning`. */
+    readonly warning?: number;
+    /** From this share of the range, between 0 and 1, the measure turns `danger`. */
+    readonly danger?: number;
+    /** Visible label associated with the measured value. */
+    readonly label?: ReactNode;
+    readonly size?: ScaleLevel;
+    readonly style?: CSSProperties;
+}
+/**
+ * A quantity within a known range, such as disk usage. Unlike a ProgressBar it
+ * does not move toward an end: it reads a level, and turns `warning` or
+ * `danger` once it crosses the thresholds it is given.
+ */
+export declare const Meter: import("react").ForwardRefExoticComponent<MeterProps & import("react").RefAttributes<HTMLDivElement>>;
+export {};

package/dist/meter.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { forwardRef } from "react";
+import { Label, Meter as AriaMeter } from "react-aria-components";
+import { controlFontWeight, controlOpacity, transition, useControlMetrics } from "./control/control.js";
+import { fieldStyle } from "./control/field.js";
+import { resolveColor } from "./foundation/color.js";
+import { railThickness } from "./progress-bar.js";
+import { SurfaceView } from "./surface/surface.js";
+/**
+ * A quantity within a known range, such as disk usage. Unlike a ProgressBar it
+ * does not move toward an end: it reads a level, and turns `warning` or
+ * `danger` once it crosses the thresholds it is given.
+ */
+export const Meter = forwardRef(function Meter({ className, color = "info", warning, danger, label, material, size, style, value = 0, minValue = 0, maxValue = 100, ...properties }, ref) {
+    const metrics = useControlMetrics(size);
+    const share = maxValue === minValue ? 0 : (value - minValue) / (maxValue - minValue);
+    const role = danger !== undefined && share >= danger ? "danger" : warning !== undefined && share >= warning ? "warning" : color;
+    const fill = resolveColor(role, metrics.visual.colors);
+    return _jsx(AriaMeter, { ...properties, ref: ref, className: className, value: value, minValue: minValue, maxValue: maxValue, style: fieldStyle(metrics, { width: "100%", ...style }), children: state => _jsxs(_Fragment, { children: [(label != null || state.valueText != null) && _jsxs("span", { style: { display: "flex", alignItems: "baseline", justifyContent: "space-between", gap: metrics.gap }, children: [label != null && _jsx(Label, { style: { fontWeight: controlFontWeight }, children: label }), state.valueText != null && _jsx("span", { style: { fontVariantNumeric: "tabular-nums", opacity: controlOpacity.secondary }, children: state.valueText })] }), _jsx(SurfaceView, { as: "span", "aria-hidden": "true", "data-meter-track": "", color: "background", depth: "recessed", material: material, radius: "full", style: { display: "block", height: railThickness(metrics), overflow: "hidden" }, children: _jsx("span", { "data-meter-fill": "", style: {
+                            ...transition(metrics.visual, "width, background-color", 1.5),
+                            position: "absolute",
+                            insetBlock: 0,
+                            insetInlineStart: 0,
+                            display: "block",
+                            width: `${state.percentage}%`,
+                            borderRadius: "inherit",
+                            background: fill
+                        } }) })] }) });
+});

package/dist/progress-bar.d.ts

@@ -1,5 +1,6 @@
 import type { CSSProperties, ReactNode } from "react";
 import type { ProgressBarProps as AriaProgressBarProps } from "react-aria-components";
+import { useControlMetrics } from "./control/control.js";
 import { type Color } from "./foundation/color.js";
 import type { ScaleLevel } from "./foundation/scale.js";
 import type { MaterialOverrides } from "./surface/material-options.js";
@@ -15,6 +16,8 @@ export interface ProgressBarProps extends NativeProgressBarProps, MaterialOverri
     readonly size?: ScaleLevel;
     readonly style?: CSSProperties;
 }
+/** The thickness of a recessed value rail, shared by ProgressBar and Meter. */
+export declare function railThickness(metrics: ReturnType<typeof useControlMetrics>): number;
 /** Progress over time: a recessed rail filled in the owner's color. */
 export declare const ProgressBar: import("react").ForwardRefExoticComponent<ProgressBarProps & import("react").RefAttributes<HTMLDivElement>>;
 export {};

package/dist/progress-bar.js

@@ -4,12 +4,16 @@ import { Label, ProgressBar as AriaProgressBar } from "react-aria-components";
 import { controlFontWeight, controlOpacity, transition, useControlMetrics } from "./control/control.js";
 import { fieldStyle } from "./control/field.js";
 import { resolveColor } from "./foundation/color.js";
-import MotionStyle from "./foundation/motion-style.js";
+import MotionStyle, { loopDuration } from "./foundation/motion-style.js";
 import { SurfaceView } from "./surface/surface.js";
+/** The thickness of a recessed value rail, shared by ProgressBar and Meter. */
+export function railThickness(metrics) {
+    return Math.max(4, Math.round(metrics.spacing / 2));
+}
 /** Progress over time: a recessed rail filled in the owner's color. */
 export const ProgressBar = forwardRef(function ProgressBar({ className, color = "primary", indeterminate = false, label, material, size, style, value, minValue = 0, maxValue = 100, ...properties }, ref) {
     const metrics = useControlMetrics(size);
-    const thickness = Math.max(4, Math.round(metrics.spacing / 2));
+    const thickness = railThickness(metrics);
     const fill = resolveColor(color, metrics.visual.colors);
     const moving = indeterminate && metrics.visual.duration > 0;
     return _jsx(AriaProgressBar, { ...properties, ref: ref, className: className, value: value, minValue: minValue, maxValue: maxValue, isIndeterminate: indeterminate, style: fieldStyle(metrics, { width: "100%", ...style }), children: state => {
@@ -24,7 +28,7 @@ export const ProgressBar = forwardRef(function ProgressBar({ className, color =
                                 width: state.isIndeterminate ? "40%" : `${state.percentage ?? 0}%`,
                                 borderRadius: "inherit",
                                 background: fill,
-                                animation: moving ? `phreshos-ui-sweep ${Math.max(900, metrics.visual.appearance.transaction.duration * 8)}ms ${metrics.visual.easing} infinite` : undefined
+                                animation: moving ? `phreshos-ui-sweep ${loopDuration(metrics.visual)}ms ${metrics.visual.easing} infinite` : undefined
                             } }) })] });
         } });
 });

package/dist/readiness.d.ts

@@ -0,0 +1,46 @@
+import type { ReactNode } from "react";
+/** One requirement of a boundary, as it is now. */
+export interface Requirement<Detail = unknown> {
+    readonly ready: boolean;
+    readonly detail: Detail;
+}
+/** What a boundary knows: whether it is ready, and every requirement declared in it. */
+export interface ReadinessState<Detail = unknown> {
+    readonly ready: boolean;
+    readonly requirements: readonly Requirement<Detail>[];
+}
+export interface ReadinessProps<Detail = unknown> {
+    /** The interface that waits. Held while the boundary is not ready. */
+    readonly children?: ReactNode;
+    /**
+     * Interface that shows the waiting. Rendered next to the children, outside
+     * the held area, so it stays interactive. A function receives the same
+     * value `useReadiness()` returns.
+     */
+    readonly status?: ReactNode | ((readiness: ReadinessState<Detail>) => ReactNode);
+    /** Milliseconds the boundary stays held after its requirements are ready, for work they do not see. */
+    readonly delay?: number;
+}
+/**
+ * Holds interaction with its children until every requirement declared in it
+ * is ready. It draws nothing: the children are wrapped in one
+ * `display: contents` element that carries `inert` while waiting.
+ *
+ * A requirement belongs to its nearest boundary only, so a boundary that
+ * starts waiting inside a ready one holds just its own part.
+ *
+ * The boundary starts held and is released only after the first commit, once
+ * every requirement mounted with it has registered. Server HTML is held too.
+ */
+export declare function Readiness<Detail = unknown>({ children, status, delay }: ReadinessProps<Detail>): import("react").JSX.Element;
+/**
+ * Declares one requirement of the nearest boundary for as long as the calling
+ * component is mounted. It follows `ready` both ways. `detail` is carried as-is
+ * and compared by identity, so pass a stable value such as a string.
+ */
+export declare function useRequirement(ready: boolean, detail?: unknown): void;
+/**
+ * Reads the nearest boundary. Inside `status`, that is the boundary the status
+ * belongs to. `Detail` states what the boundary's requirements pass as detail.
+ */
+export declare function useReadiness<Detail = unknown>(): ReadinessState<Detail>;

package/dist/readiness.js

@@ -0,0 +1,78 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useContext, useEffect, useLayoutEffect, useMemo, useReducer, useRef, useState } from "react";
+/** Where `useRequirement` declares. Status content sees the parent's, not its own boundary's. */
+const RegistryContext = createContext(null);
+/** What `useReadiness` reads. */
+const StateContext = createContext(null);
+/**
+ * Holds interaction with its children until every requirement declared in it
+ * is ready. It draws nothing: the children are wrapped in one
+ * `display: contents` element that carries `inert` while waiting.
+ *
+ * A requirement belongs to its nearest boundary only, so a boundary that
+ * starts waiting inside a ready one holds just its own part.
+ *
+ * The boundary starts held and is released only after the first commit, once
+ * every requirement mounted with it has registered. Server HTML is held too.
+ */
+export function Readiness({ children, status, delay = 0 }) {
+    const entries = useRef(new Map());
+    const [revision, invalidate] = useReducer((value) => value + 1, 0);
+    const [mounted, setMounted] = useState(false);
+    const [delayed, setDelayed] = useState(false);
+    const registry = useMemo(() => ({
+        set(identity, requirement) {
+            const current = entries.current.get(identity);
+            if (current !== undefined && current.ready === requirement.ready && Object.is(current.detail, requirement.detail))
+                return;
+            entries.current.set(identity, requirement);
+            invalidate();
+        },
+        delete(identity) {
+            if (entries.current.delete(identity))
+                invalidate();
+        }
+    }), []);
+    // Descendant layout effects run first, so every requirement mounted with the boundary is known here.
+    useLayoutEffect(() => setMounted(true), []);
+    const requirements = useMemo(() => [...entries.current.values()], [revision]);
+    const met = mounted && requirements.every(requirement => requirement.ready);
+    // The delay starts again whenever a requirement stops being ready.
+    if (!met && delayed)
+        setDelayed(false);
+    useEffect(() => {
+        if (!met || delay === 0)
+            return;
+        const timer = setTimeout(() => setDelayed(true), delay);
+        return () => clearTimeout(timer);
+    }, [met, delay]);
+    const ready = met && (delay === 0 || delayed);
+    const state = useMemo(() => ({ ready, requirements }), [ready, requirements]);
+    return _jsxs(StateContext.Provider, { value: state, children: [_jsx(RegistryContext.Provider, { value: registry, children: _jsx("div", { "data-readiness": "", inert: !ready, style: { display: "contents" }, children: children }) }), typeof status === "function" ? status(state) : status] });
+}
+/**
+ * Declares one requirement of the nearest boundary for as long as the calling
+ * component is mounted. It follows `ready` both ways. `detail` is carried as-is
+ * and compared by identity, so pass a stable value such as a string.
+ */
+export function useRequirement(ready, detail) {
+    const registry = useContext(RegistryContext);
+    if (registry === null)
+        throw new Error("useRequirement must be called inside a Readiness boundary.");
+    // The call site is the identity: one object for this mounted component.
+    const [identity] = useState(() => ({}));
+    useLayoutEffect(() => {
+        registry.set(identity, { ready, detail });
+    }, [registry, identity, ready, detail]);
+    useLayoutEffect(() => () => registry.delete(identity), [registry, identity]);
+}
+/**
+ * Reads the nearest boundary. Inside `status`, that is the boundary the status
+ * belongs to. `Detail` states what the boundary's requirements pass as detail.
+ */
+export function useReadiness() {
+    const state = useContext(StateContext);
+    if (state === null)
+        throw new Error("useReadiness must be called inside a Readiness boundary.");
+    return state;
+}

package/dist/search-field.d.ts

@@ -0,0 +1,13 @@
+import type { SearchFieldProps as AriaSearchFieldProps } from "react-aria-components";
+import { type ControlOverrides, type ControlProps, type FieldProps } from "./control/control.js";
+import type { RadiusProps } from "./foundation/radius.js";
+import type { MaterialOverrides } from "./surface/material-options.js";
+export interface SearchFieldProps extends Omit<AriaSearchFieldProps, ControlOverrides | "className" | "style">, ControlProps, FieldProps, RadiusProps, MaterialOverrides {
+    readonly placeholder?: string;
+    readonly readOnly?: boolean;
+}
+/**
+ * A text field for searching. It leads with a search mark, and a clear button
+ * appears once it holds text; Escape clears it too, and Enter calls `onSubmit`.
+ */
+export declare const SearchField: import("react").ForwardRefExoticComponent<SearchFieldProps & import("react").RefAttributes<HTMLInputElement>>;

package/dist/search-field.js

@@ -0,0 +1,27 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { forwardRef } from "react";
+import { Group, Input as AriaInput, SearchField as AriaSearchField } from "react-aria-components";
+import { Search, X } from "lucide-react";
+import { controlOpacity, useControlMetrics } from "./control/control.js";
+import { FieldButton } from "./control/field-button.js";
+import { FieldFeedback, FieldLabel, fieldStyle } from "./control/field.js";
+import { iconProps } from "./control/icon.js";
+import { surfaceRender } from "./control/surface-render.js";
+import { nativeTextStyle } from "./control/text-control.js";
+import MotionStyle, { textControlClass } from "./foundation/motion-style.js";
+import { dimmedClass } from "./surface/surface.js";
+/**
+ * A text field for searching. It leads with a search mark, and a clear button
+ * appears once it holds text; Escape clears it too, and Enter calls `onSubmit`.
+ */
+export const SearchField = forwardRef(function SearchField({ label, description, errorMessage, disabled, readOnly, required, invalid, size, color = "background", radius, style, className, placeholder, material, ...properties }, ref) {
+    const metrics = useControlMetrics(size, radius);
+    const icon = Math.round(metrics.height / 2);
+    return _jsx(AriaSearchField, { ...properties, className: dimmedClass(disabled ?? false, className), isDisabled: disabled, isReadOnly: readOnly, isRequired: required, isInvalid: invalid, style: fieldStyle(metrics, style), children: field => _jsxs(_Fragment, { children: [_jsx(MotionStyle, {}), _jsx(FieldLabel, { label: label }), _jsxs(Group, { render: surfaceRender("div", group => ({
+                        color,
+                        depth: "recessed",
+                        material,
+                        radius: metrics.radius,
+                        interaction: { hovered: group.isHovered, focusVisible: group.isFocusWithin, invalid: group.isInvalid, disabled: group.isDisabled }
+                    })), style: { display: "grid", gridTemplateColumns: "auto minmax(0, 1fr) auto", alignItems: "center", minWidth: 0, height: metrics.height, paddingInlineEnd: 4 }, children: [_jsx(Search, { ...iconProps(icon), style: { marginInlineStart: metrics.inset, opacity: controlOpacity.placeholder } }), _jsx(AriaInput, { ref: ref, placeholder: placeholder, className: textControlClass, style: { ...nativeTextStyle(metrics, false), paddingInlineStart: metrics.gap, WebkitAppearance: "none" } }), _jsx(FieldButton, { metrics: metrics, "aria-label": "Clear search", style: { visibility: field.isEmpty ? "hidden" : "visible" }, children: _jsx(X, { ...iconProps(icon) }) })] }), _jsx(FieldFeedback, { metrics: metrics, description: description, errorMessage: errorMessage })] }) });
+});

package/dist/skeleton.d.ts

@@ -0,0 +1,15 @@
+import type { CSSProperties } from "react";
+import { type Radius } from "./foundation/radius.js";
+export interface SkeletonProps {
+    /** Lines of text to hold the place of. Omitted, the Skeleton is one block sized by `style`. */
+    readonly lines?: number;
+    readonly radius?: Radius;
+    readonly className?: string;
+    readonly style?: CSSProperties;
+}
+/**
+ * The place of content that is still loading, in the separator paint so it
+ * sits quietly on any Surface. It pulses at the pace of every repeating motion
+ * and stands still when animations are off.
+ */
+export declare function Skeleton({ lines, radius, className, style }: SkeletonProps): import("react").JSX.Element;

package/dist/skeleton.js

@@ -0,0 +1,29 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useControlMetrics } from "./control/control.js";
+import { separatorColor } from "./control/field.js";
+import MotionStyle, { loopDuration } from "./foundation/motion-style.js";
+import { resolveRadius } from "./foundation/radius.js";
+/** The last line of a paragraph ends short, at the golden ratio of the others. */
+const lastLine = `${(1 / 1.618) * 100}%`;
+/**
+ * The place of content that is still loading, in the separator paint so it
+ * sits quietly on any Surface. It pulses at the pace of every repeating motion
+ * and stands still when animations are off.
+ */
+export function Skeleton({ lines, radius, className, style }) {
+    const metrics = useControlMetrics();
+    const visual = metrics.visual;
+    const paint = {
+        display: "block",
+        background: separatorColor(metrics),
+        borderRadius: resolveRadius(radius ?? "small", visual.radius),
+        animation: visual.duration > 0 ? `phreshos-ui-pulse ${loopDuration(visual)}ms ${visual.easing} infinite` : undefined
+    };
+    if (lines === undefined)
+        return _jsxs(_Fragment, { children: [_jsx(MotionStyle, {}), _jsx("span", { "aria-hidden": "true", className: className, style: { ...paint, height: metrics.height, ...style } })] });
+    return _jsxs(_Fragment, { children: [_jsx(MotionStyle, {}), _jsx("span", { "aria-hidden": "true", className: className, style: { display: "grid", gap: "0.5lh", ...style }, children: Array.from({ length: lines }, (_, index) => _jsx("span", { style: {
+                        ...paint,
+                        height: "1em",
+                        width: index === lines - 1 && lines > 1 ? lastLine : "100%"
+                    } }, index)) })] });
+}

package/dist/spinner.d.ts

@@ -21,6 +21,8 @@ type DecorativeSpinnerProps = Readonly<{
     label?: never;
 }>;
 export type SpinnerProps = SpinnerVisualProps & (NamedSpinnerProps | DecorativeSpinnerProps);
+/** A standalone status stays visibly distinct from the compact control indicator. */
+export declare function spinnerDiameter(spacing: number, size: ScaleLevel): number;
 /** Compact indeterminate progress, either named or explicitly decorative. */
 export declare const Spinner: import("react").ForwardRefExoticComponent<SpinnerProps & import("react").RefAttributes<HTMLDivElement>>;
 export {};

package/dist/spinner.js

@@ -5,12 +5,15 @@ import { useControlMetrics } from "./control/control.js";
 import { colorOpacity, resolveColor } from "./foundation/color.js";
 import MotionStyle from "./foundation/motion-style.js";
 import { scale } from "./foundation/scale.js";
+/** A standalone status stays visibly distinct from the compact control indicator. */
+export function spinnerDiameter(spacing, size) {
+    return spacing + scale(spacing, size);
+}
 /** Compact indeterminate progress, either named or explicitly decorative. */
 export const Spinner = forwardRef(function Spinner({ className, color = "primary", decorative = false, label, size = "medium", style, ...properties }, ref) {
     const metrics = useControlMetrics(size);
     const { colors } = metrics.visual;
-    // A standalone status stays visibly distinct from the compact control indicator.
-    const diameter = metrics.visual.spacing + scale(metrics.visual.spacing, size);
+    const diameter = spinnerDiameter(metrics.visual.spacing, size);
     const arc = color === "currentColor" ? "currentColor" : resolveColor(color, colors);
     const rootStyle = {
         display: "inline-grid",

package/dist/surface/surface.d.ts

@@ -78,3 +78,14 @@ export declare function surfacePaint(visual: Visual, color: Color, depth: Surfac
     distortion: number;
     variables: CSSProperties;
 };
+/**
+ * How far the inward spill reaches: at most a fixed depth, and less on short
+ * Surfaces. At a fixed depth a small button was lit through nearly half its
+ * height and read as swollen, while a large panel barely changes.
+ *
+ * The limit is the height of the spill's background layer, not the gradient's
+ * size: browsers reject a size that mixes pixels and percentages inside
+ * radial-gradient(), and one rejected layer drops the whole background,
+ * grain included.
+ */
+export declare const spillDepth = "min(6px, 12%)";

package/dist/surface/surface.js

@@ -111,11 +111,10 @@ export function surfacePaint(visual, color, depth, options, shadowOptions, inter
     const rim = edged
         ? `linear-gradient(to right, transparent, ${colorOpacity(light, lit.side)} 18%, ${colorOpacity(light, lit.edge)} 50%, ${colorOpacity(light, lit.side)} 82%, transparent)`
         : "none";
-    // The spill reaches at most a fixed depth, and less on short Surfaces: at a
-    // fixed depth, a small button was lit through nearly half its height and
-    // read as swollen, while a large panel barely changes.
+    // The spill fills its own background layer, whose height the stylesheet
+    // limits (see spillDepth).
     const spill = (edge) => edged && lit.spill > 0
-        ? `radial-gradient(50% ${spillDepth} at 50% ${edge === "top" ? "0" : "100%"}, ${colorOpacity(light, lit.spill)}, transparent)`
+        ? `radial-gradient(50% 100% at 50% ${edge === "top" ? "0" : "100%"}, ${colorOpacity(light, lit.spill)}, transparent)`
         : "none";
     // A recessed Surface holds a value, so focus and validity also claim its hairline.
     const claimed = interaction?.invalid || (depth === "recessed" && interaction?.focusVisible);
@@ -148,8 +147,17 @@ export function surfacePaint(visual, color, depth, options, shadowOptions, inter
         }
     };
 }
-/** How far the inward spill reaches: a fixed depth, or a share of a short Surface's height. */
-const spillDepth = "min(6px, 12%)";
+/**
+ * How far the inward spill reaches: at most a fixed depth, and less on short
+ * Surfaces. At a fixed depth a small button was lit through nearly half its
+ * height and read as swollen, while a large panel barely changes.
+ *
+ * The limit is the height of the spill's background layer, not the gradient's
+ * size: browsers reject a size that mixes pixels and percentages inside
+ * radial-gradient(), and one rejected layer drops the whole background,
+ * grain included.
+ */
+export const spillDepth = "min(6px, 12%)";
 /** How much light each part of the rim receives, interpolated along the canvas darkness. */
 function edgeLight(depth, darkness) {
     const { light, dark } = edgeLightEnds[depth];
@@ -219,7 +227,9 @@ const stylesheet = `
   z-index: -1;
   background-color: var(--phreshos-surface-paint);
   background-image: var(--phreshos-surface-spill-top), var(--phreshos-surface-spill-bottom), var(--phreshos-surface-grain);
-  background-size: auto, auto, ${grainSize}px ${grainSize}px;
+  background-size: 100% ${spillDepth}, 100% ${spillDepth}, ${grainSize}px ${grainSize}px;
+  background-position: center top, center bottom, 0 0;
+  background-repeat: no-repeat, no-repeat, repeat;
   -webkit-backdrop-filter: var(--phreshos-surface-frost);
   backdrop-filter: var(--phreshos-surface-frost);
   transition: background-color var(--phreshos-surface-duration) var(--phreshos-surface-easing);

package/dist/tag-group.d.ts

@@ -0,0 +1,21 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { TagGroupProps as AriaTagGroupProps, TagProps as AriaTagProps } from "react-aria-components";
+import { type FieldProps } from "./control/control.js";
+import { type Color } from "./foundation/color.js";
+import type { ScaleLevel } from "./foundation/scale.js";
+export interface TagGroupProps extends Omit<AriaTagGroupProps, "className" | "style" | "children">, Omit<FieldProps, "required" | "invalid"> {
+    readonly children?: ReactNode;
+    /** The paint of every Tag, in its subtle level; selection uses the selection color. */
+    readonly color?: Color;
+    readonly size?: ScaleLevel;
+    readonly className?: string;
+    readonly style?: CSSProperties;
+}
+export interface TagGroupTagProps extends Omit<AriaTagProps, "className" | "style" | "children"> {
+    readonly children?: ReactNode;
+}
+declare function TagGroupTag({ children, ...properties }: TagGroupTagProps): import("react").JSX.Element;
+export declare const TagGroup: import("react").ForwardRefExoticComponent<TagGroupProps & import("react").RefAttributes<HTMLDivElement>> & {
+    Tag: typeof TagGroupTag;
+};
+export {};

package/dist/tag-group.js

@@ -0,0 +1,52 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { createContext, forwardRef, useContext } from "react";
+import { Tag as AriaTag, TagGroup as AriaTagGroup, TagList } from "react-aria-components";
+import { X } from "lucide-react";
+import { controlFontWeight, relativeFontSize, useControlMetrics } from "./control/control.js";
+import { FieldButton } from "./control/field-button.js";
+import { FieldFeedback, FieldLabel, fieldStyle } from "./control/field.js";
+import { iconProps } from "./control/icon.js";
+import { selectionColor } from "./control/item.js";
+import { surfaceRender } from "./control/surface-render.js";
+import { colorLevel, resolveColor } from "./foundation/color.js";
+const TagGroupContext = createContext(null);
+/** Tags sit one control step below the size of their group, like Badges. */
+const smaller = Object.freeze({ xsmall: "xsmall", small: "xsmall", medium: "small", large: "medium", xlarge: "large" });
+/**
+ * A set of short labels, such as applied filters. Tags can be selected like
+ * collection items, and with `onRemove` each one gains a remove button.
+ */
+const TagGroupRoot = forwardRef(function TagGroup({ label, description, errorMessage, children, color = "default", size = "medium", style, ...properties }, ref) {
+    const group = useControlMetrics(size);
+    const metrics = useControlMetrics(smaller[size]);
+    return _jsx(TagGroupContext.Provider, { value: { metrics, color, size }, children: _jsxs(AriaTagGroup, { ...properties, ref: ref, style: fieldStyle(group, style), children: [_jsx(FieldLabel, { label: label }), _jsx(TagList, { style: { display: "flex", flexWrap: "wrap", gap: group.gap }, children: children }), _jsx(FieldFeedback, { metrics: group, description: description, errorMessage: errorMessage })] }) });
+});
+function TagGroupTag({ children, ...properties }) {
+    const context = useContext(TagGroupContext);
+    if (context === null)
+        throw new Error("TagGroup.Tag must be inside TagGroup");
+    const { metrics, color, size } = context;
+    const { colors } = metrics.visual;
+    const base = resolveColor(color, colors);
+    return _jsx(AriaTag, { ...properties, textValue: properties.textValue ?? (typeof children === "string" ? children : undefined), render: surfaceRender("div", state => ({
+            color: state.isSelected ? selectionColor(base, colors) : colorLevel(base, "subtle", colors),
+            depth: "flat",
+            radius: "full",
+            interaction: { hovered: state.isHovered, pressed: state.isPressed, focusVisible: state.isFocusVisible, disabled: state.isDisabled }
+        })), style: state => ({
+            display: "inline-flex",
+            alignItems: "center",
+            gap: metrics.gap / 2,
+            height: metrics.height,
+            paddingInlineStart: metrics.inset,
+            paddingInlineEnd: state.allowsRemoving ? 4 : metrics.inset,
+            boxSizing: "border-box",
+            // The group root already applies its own text level.
+            fontSize: relativeFontSize(smaller[size], size),
+            fontWeight: controlFontWeight,
+            whiteSpace: "nowrap",
+            cursor: state.selectionMode === "none" ? "default" : "pointer",
+            outlineOffset: -1
+        }), children: state => _jsxs(_Fragment, { children: [children, state.allowsRemoving && _jsx(FieldButton, { slot: "remove", metrics: metrics, "aria-label": "Remove", children: _jsx(X, { ...iconProps(Math.round(metrics.height / 2)) }) })] }) });
+}
+export const TagGroup = Object.assign(TagGroupRoot, { Tag: TagGroupTag });

package/dist/toast.d.ts

@@ -0,0 +1,32 @@
+import type { CSSProperties, ReactNode } from "react";
+import { type Color } from "./foundation/color.js";
+export interface ToastContent {
+    readonly title: ReactNode;
+    readonly description?: ReactNode;
+    /** The meaning, as a color role: `info` by default. It sets the icon. */
+    readonly color?: Color;
+}
+export interface ToastOptions {
+    /**
+     * Milliseconds before the Toast closes itself. Omitted, it stays until
+     * closed. Keep at least five seconds, so it can be read.
+     */
+    readonly timeout?: number;
+}
+/**
+ * Shows a brief message that does not interrupt, such as "Saved". It appears
+ * in the ToastRegion and returns a key that closes it early.
+ */
+export declare const toast: Readonly<{
+    show(content: ToastContent, options?: ToastOptions): string;
+    close(key: string): void;
+}>;
+export interface ToastRegionProps {
+    readonly className?: string;
+    readonly style?: CSSProperties;
+}
+/**
+ * Where Toasts appear: stacked at the end of the viewport bottom, above the
+ * interface, at the large spacing step from its edges. Render it once.
+ */
+export declare function ToastRegion({ className, style }: ToastRegionProps): import("react").JSX.Element;

package/dist/toast.js

@@ -0,0 +1,62 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Text, UNSTABLE_Toast as AriaToast, UNSTABLE_ToastContent as AriaToastContent, UNSTABLE_ToastQueue as AriaToastQueue, UNSTABLE_ToastRegion as AriaToastRegion } from "react-aria-components";
+import { X } from "lucide-react";
+import { controlFontSizes, controlFontWeight, controlOpacity, useControlMetrics } from "./control/control.js";
+import { FieldButton } from "./control/field-button.js";
+import { iconProps } from "./control/icon.js";
+import { meaningIcon } from "./control/meaning.js";
+import { colorLevel, resolveColor } from "./foundation/color.js";
+import MotionStyle, { overlayLayer, overlayTransition } from "./foundation/motion-style.js";
+import { resolveRadius } from "./foundation/radius.js";
+import { scale } from "./foundation/scale.js";
+import { Surface } from "./surface/surface.js";
+import { floatingShadow } from "./surface/shadow-options.js";
+const queue = new AriaToastQueue({ maxVisibleToasts: 5 });
+/**
+ * Shows a brief message that does not interrupt, such as "Saved". It appears
+ * in the ToastRegion and returns a key that closes it early.
+ */
+export const toast = Object.freeze({
+    show(content, options = {}) {
+        return queue.add(content, options.timeout === undefined ? {} : { timeout: options.timeout });
+    },
+    close(key) {
+        queue.close(key);
+    }
+});
+/**
+ * Where Toasts appear: stacked at the end of the viewport bottom, above the
+ * interface, at the large spacing step from its edges. Render it once.
+ */
+export function ToastRegion({ className, style }) {
+    const metrics = useControlMetrics();
+    const visual = metrics.visual;
+    const inset = scale(visual.spacing, "large");
+    return _jsxs(_Fragment, { children: [_jsx(MotionStyle, {}), _jsx(AriaToastRegion, { queue: queue, className: className, style: {
+                    position: "fixed",
+                    insetBlockEnd: inset,
+                    insetInlineEnd: inset,
+                    zIndex: overlayLayer,
+                    display: "flex",
+                    flexDirection: "column-reverse",
+                    // Each Toast is as wide as its message, up to the width of a readable line.
+                    alignItems: "end",
+                    gap: metrics.gap,
+                    maxWidth: `min(28em, calc(100vw - ${inset * 2}px))`,
+                    outline: "none",
+                    ...style
+                }, children: ({ toast: item }) => {
+                    const color = item.content.color ?? "info";
+                    const Icon = meaningIcon(color);
+                    return _jsx(AriaToast, { toast: item, style: { outline: "none", ...overlayTransition(visual), animation: `phreshos-ui-overlay-enter var(--phreshos-ui-motion-duration) var(--phreshos-ui-motion-easing) both` }, children: _jsxs(Surface, { material: "full", shadow: floatingShadow(visual.shadow), radius: resolveRadius("medium", visual.radius), style: {
+                                display: "grid",
+                                gridTemplateColumns: "auto minmax(0, 1fr) auto",
+                                alignItems: "start",
+                                gap: metrics.gap * 2,
+                                padding: metrics.spacing,
+                                paddingInlineEnd: metrics.spacing / 2,
+                                fontSize: controlFontSizes.medium,
+                                lineHeight: 1.45
+                            }, children: [_jsx("span", { style: { display: "grid", height: "1.45em", alignItems: "center", color: colorLevel(resolveColor(color, visual.colors), "strong", visual.colors) }, children: _jsx(Icon, { ...iconProps(Math.round(metrics.height / 2)) }) }), _jsxs(AriaToastContent, { style: { display: "grid", gap: 2, minWidth: 0 }, children: [_jsx(Text, { slot: "title", style: { fontWeight: controlFontWeight }, children: item.content.title }), item.content.description != null && _jsx(Text, { slot: "description", style: { opacity: controlOpacity.secondary }, children: item.content.description })] }), _jsx(FieldButton, { slot: "close", metrics: metrics, "aria-label": "Close", children: _jsx(X, { ...iconProps(Math.round(metrics.height / 2)) }) })] }) });
+                } })] });
+}