@phreshos/react-ui 0.1.39 → 0.1.41

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/grain.d.ts

@@ -4,6 +4,15 @@
  * without also fading that layer's backdrop.
  */
 export declare function grainImage(seed: number, amount: number, opacity: number): string;
+/**
+ * One grain texture as a shared class. Its name comes from the texture's own
+ * parameters, so server and browser rendering agree on it, and the rule is
+ * written once however many Surfaces use it instead of inline on each.
+ */
+export declare function grainTexture(seed: number, amount: number, opacity: number): Readonly<{
+    name: string;
+    rule: string;
+}>;
 /**
  * One texture serves every Surface. Each Surface tiles it from its own origin,
  * so neighbours never align, and equal paints can share one generated class.

package/dist/surface/grain.js

@@ -20,6 +20,15 @@ export function grainImage(seed, amount, opacity) {
     resources.set(key, resource);
     return resource;
 }
+/**
+ * One grain texture as a shared class. Its name comes from the texture's own
+ * parameters, so server and browser rendering agree on it, and the rule is
+ * written once however many Surfaces use it instead of inline on each.
+ */
+export function grainTexture(seed, amount, opacity) {
+    const name = `phreshos-grain-${seed}-${amount}-${Math.round(opacity * 1_000)}`.replace(/[^a-z0-9-]/gi, "_");
+    return { name, rule: `:where(.${name}) { --phreshos-surface-grain: ${grainImage(seed, amount, opacity)} }` };
+}
 /**
  * One texture serves every Surface. Each Surface tiles it from its own origin,
  * so neighbours never align, and equal paints can share one generated class.

package/dist/surface/surface.d.ts

@@ -76,6 +76,10 @@ export declare function surfacePaint(visual: Visual, color: Color, depth: Surfac
     ring: string;
     shadow: string;
     distortion: number;
+    grain: Readonly<{
+        name: string;
+        rule: string;
+    }> | null;
     variables: CSSProperties;
 };
 /**

package/dist/surface/surface.js

@@ -3,7 +3,7 @@ import { createElement, forwardRef, useId, useInsertionEffect } from "react";
 import { canvasDarkness, colorOpacity, contrast, mixColor, readableColor, recessColor, resolveColor } from "../foundation/color.js";
 import { resolveRadius } from "../foundation/radius.js";
 import { useVisual } from "../foundation/visual.js";
-import { grainImage, grainSeed, grainSize } from "./grain.js";
+import { grainSeed, grainSize, grainTexture } from "./grain.js";
 import { flushPaintRules, paintClass, usePaintClasses } from "./paint-class.js";
 import { resolveMaterialOptions } from "./material-options.js";
 import { resolveShadowOptions, shadowStyle } from "./shadow-options.js";
@@ -35,10 +35,10 @@ export const SurfaceView = forwardRef(function Surface({ as: Element = "div", co
     return createElement(Element, {
         ...properties,
         ref,
-        className: [surfaceClass, painted, dimmedClass(interaction?.disabled ?? false), className].filter(Boolean).join(" "),
+        className: [surfaceClass, paint.grain?.name, painted, dimmedClass(interaction?.disabled ?? false), className].filter(Boolean).join(" "),
         // Without a document (server rendering), the same declarations travel inline.
         style: painted === undefined ? { ...inlineDeclarations(declarations), ...style } : style
-    }, _jsx(SurfaceStyle, {}), paint.distortion > 0 && _jsx(Refraction, { identity: identity, distortion: paint.distortion }), children);
+    }, _jsx(SurfaceStyle, {}), paint.grain && _jsx(GrainStyle, { grain: paint.grain }), paint.distortion > 0 && _jsx(Refraction, { identity: identity, distortion: paint.distortion }), children);
 });
 function inlineDeclarations(declarations) {
     const result = {};
@@ -94,8 +94,8 @@ export function surfacePaint(visual, color, depth, options, shadowOptions, inter
         ? [material.backdrop > 0 ? `blur(${material.backdrop}px)` : "", material.saturation !== 1 ? `saturate(${material.saturation})` : ""].filter(Boolean).join(" ")
         : "";
     const grain = level >= materialLevel.basic && material.grain > 0 && material.grainAmount > 0
-        ? grainImage(grainSeed, material.grainAmount, level === materialLevel.basic ? material.grain * material.opacity : material.grain)
-        : "none";
+        ? grainTexture(grainSeed, material.grainAmount, level === materialLevel.basic ? material.grain * material.opacity : material.grain)
+        : null;
     const ringBase = interaction?.invalid
         ? colors.danger
         : !clear && (contrast(base, colors.background) ?? 1) >= 1.6 ? base : colors.primary;
@@ -135,9 +135,11 @@ export function surfacePaint(visual, color, depth, options, shadowOptions, inter
         ring: colorOpacity(ringBase, 0.34),
         shadow: [hairline, outer === "none" ? null : outer].filter(Boolean).join(", ") || "none",
         distortion: level >= materialLevel.full && translucent ? material.distortion : 0,
+        grain,
         variables: {
             "--phreshos-surface-paint": translucent ? colorOpacity(fill, opacity) : fill,
-            "--phreshos-surface-grain": grain,
+            // A grain texture arrives through its shared class; without one the layer is empty.
+            ...(grain === null ? { "--phreshos-surface-grain": "none" } : {}),
             "--phreshos-surface-frost": frost || "none",
             "--phreshos-surface-rim": rim,
             "--phreshos-surface-spill-top": spill("top"),
@@ -243,6 +245,10 @@ const stylesheet = `
   mask: linear-gradient(#000 0 0) content-box exclude, linear-gradient(#000 0 0);
 }
 `;
+/** One rule per grain texture, hoisted and deduplicated by React like the stylesheet below. */
+function GrainStyle({ grain }) {
+    return _jsx("style", { href: grain.name, precedence: "phreshos", children: grain.rule });
+}
 /** React hoists and deduplicates this stylesheet, including inside portals. */
 function SurfaceStyle() {
     return _jsx("style", { href: "phreshos-react-ui-surface", precedence: "phreshos", children: stylesheet });

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;