@phreshos/react-ui 0.1.38 → 0.1.40

package/dist/alert.js

@@ -1,12 +1,11 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { forwardRef } from "react";
-import { CircleAlert, CircleCheck, Info, TriangleAlert } from "lucide-react";
 import { controlFontSizes, controlFontWeight, useControlMetrics } from "./control/control.js";
 import { iconProps } from "./control/icon.js";
+import { meaningIcon, urgentMeaning } from "./control/meaning.js";
 import { colorLevel, resolveColor } from "./foundation/color.js";
 import { resolveRadius } from "./foundation/radius.js";
 import { Surface } from "./surface/surface.js";
-const meaningIcons = { danger: CircleAlert, warning: TriangleAlert, success: CircleCheck };
 /**
  * A message that stays in place, such as a failed save. It is painted in the
  * subtle level of its color, like a selection, and leads with the icon of its
@@ -15,8 +14,8 @@ const meaningIcons = { danger: CircleAlert, warning: TriangleAlert, success: Cir
 export const Alert = forwardRef(function Alert({ color = "info", title, icon, children, radius, style, ...properties }, ref) {
     const metrics = useControlMetrics();
     const { colors } = metrics.visual;
-    const urgent = color === "danger" || color === "warning";
-    const MeaningIcon = meaningIcons[color] ?? Info;
+    const urgent = urgentMeaning(color);
+    const MeaningIcon = meaningIcon(color);
     return _jsxs(Surface, { ...properties, ref: ref, role: urgent ? "alert" : "status", color: colorLevel(resolveColor(color, colors), "subtle", colors), depth: "flat", radius: radius ?? resolveRadius("medium", metrics.visual.radius), style: {
             display: "grid",
             gridTemplateColumns: icon === false ? "minmax(0, 1fr)" : "auto minmax(0, 1fr)",

package/dist/app-layout.d.ts

@@ -5,7 +5,9 @@ export interface AppLayoutProps extends HTMLAttributes<HTMLDivElement> {
     readonly sidebarWidth?: CSSProperties["width"];
 }
 export type AppLayoutRegionProps = HTMLAttributes<HTMLElement>;
+export type AppLayoutTitleProps = HTMLAttributes<HTMLHeadingElement>;
 export declare const AppLayout: import("react").ForwardRefExoticComponent<AppLayoutProps & import("react").RefAttributes<HTMLDivElement>> & {
+    Title: import("react").ForwardRefExoticComponent<AppLayoutTitleProps & import("react").RefAttributes<HTMLHeadingElement>>;
     Sidebar: import("react").ForwardRefExoticComponent<AppLayoutRegionProps & import("react").RefAttributes<HTMLElement>>;
     Header: import("react").ForwardRefExoticComponent<AppLayoutRegionProps & import("react").RefAttributes<HTMLElement>>;
     Content: import("react").ForwardRefExoticComponent<AppLayoutRegionProps & import("react").RefAttributes<HTMLElement>>;

package/dist/app-layout.js

@@ -1,42 +1,66 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { createContext, forwardRef, useContext } from "react";
-import { useControlMetrics } from "./control/control.js";
-import { separatorColor } from "./control/field.js";
+import { controlFontSizes, controlFontWeight } from "./control/control.js";
 import { headerHeight } from "./foundation/layout.js";
+import { resolveRadius } from "./foundation/radius.js";
 import { scale } from "./foundation/scale.js";
+import { useVisual } from "./foundation/visual.js";
 import { ScrollArea } from "./scroll-area.js";
-const AppLayoutContext = createContext(null);
+import { Surface } from "./surface/surface.js";
+const AppLayoutContext = createContext(false);
 /**
- * The frame of a program's interface: a sidebar beside a header, the content,
- * and an optional footer. It owns only the regions, their scrolling, and the
- * hairlines between them; the program places its own components inside.
+ * The frame of a program's interface: a title above a sidebar, and a header,
+ * the content, and an optional footer beside them. Only the content is a
+ * Surface, the same inset region as a Panel's content; the other regions sit
+ * on whatever holds the layout, separated by spacing alone.
  */
 const AppLayoutRoot = forwardRef(function AppLayout({ children, sidebarWidth, style, ...properties }, ref) {
-    const metrics = useControlMetrics();
-    const { spacing } = metrics.visual;
-    return _jsx(AppLayoutContext.Provider, { value: { separator: separatorColor(metrics), spacing }, children: _jsx("div", { ...properties, ref: ref, style: {
+    const visual = useVisual();
+    const inset = scale(visual.spacing, "small");
+    return _jsx(AppLayoutContext.Provider, { value: true, children: _jsx("div", { ...properties, ref: ref, style: {
                 display: "grid",
-                gridTemplateColumns: `${typeof sidebarWidth === "number" ? `${sidebarWidth}px` : sidebarWidth ?? `${spacing * 18}px`} minmax(0, 1fr)`,
+                gridTemplateColumns: `${typeof sidebarWidth === "number" ? `${sidebarWidth}px` : sidebarWidth ?? `${visual.spacing * 18}px`} minmax(0, 1fr)`,
                 gridTemplateRows: "auto minmax(0, 1fr) auto",
-                gridTemplateAreas: `"sidebar header" "sidebar content" "sidebar footer"`,
+                gridTemplateAreas: `"title header" "sidebar content" "sidebar footer"`,
+                columnGap: inset,
+                // The header row supplies the space above the content, as in a Panel.
+                padding: inset,
+                paddingTop: 0,
+                boxSizing: "border-box",
                 width: "100%",
                 height: "100%",
                 minWidth: 0,
                 minHeight: 0,
                 // The frame of a program: its text takes the Appearance text color.
-                color: metrics.visual.colors.foreground,
+                color: visual.colors.foreground,
                 fontFamily: "inherit",
                 ...style
             }, children: children }) });
 });
+/** The program's title above the sidebar, in the header row. */
+const AppLayoutTitle = forwardRef(function AppLayoutTitle({ style, ...properties }, ref) {
+    const { spacing } = useLayout();
+    return _jsx("h1", { ...properties, ref: ref, style: {
+            gridArea: "title",
+            display: "flex",
+            alignItems: "center",
+            minWidth: 0,
+            minHeight: headerHeight(spacing),
+            margin: 0,
+            paddingInline: scale(spacing, "small"),
+            fontSize: controlFontSizes.large,
+            fontWeight: controlFontWeight,
+            ...style
+        } });
+});
 /** The sidebar, such as a program's navigation. It scrolls on its own. */
 const AppLayoutSidebar = forwardRef(function AppLayoutSidebar({ children, style, ...properties }, ref) {
-    const { separator, spacing } = useLayout();
-    return _jsx("aside", { ...properties, ref: ref, style: { gridArea: "sidebar", minHeight: 0, boxSizing: "border-box", borderInlineEnd: `1px solid ${separator}`, ...style }, children: _jsx(ScrollArea, { style: { height: "100%" }, children: _jsx("div", { style: { padding: scale(spacing, "small") }, children: children }) }) });
+    const { spacing } = useLayout();
+    return _jsx("aside", { ...properties, ref: ref, style: { gridArea: "sidebar", minHeight: 0, ...style }, children: _jsx(ScrollArea, { style: { height: "100%" }, children: _jsx("div", { style: { padding: scale(spacing, "small") }, children: children }) }) });
 });
 /** The header row above the content, as tall as a Window or Panel header. */
 const AppLayoutHeader = forwardRef(function AppLayoutHeader({ style, ...properties }, ref) {
-    const { separator, spacing } = useLayout();
+    const { spacing } = useLayout();
     return _jsx("header", { ...properties, ref: ref, style: {
             gridArea: "header",
             display: "flex",
@@ -44,20 +68,24 @@ const AppLayoutHeader = forwardRef(function AppLayoutHeader({ style, ...properti
             gap: scale(spacing, "small"),
             minWidth: 0,
             minHeight: headerHeight(spacing),
-            paddingInline: spacing,
-            boxSizing: "border-box",
-            borderBlockEnd: `1px solid ${separator}`,
             ...style
         } });
 });
-/** The content. It scrolls on its own, padded by the Appearance spacing. */
+/** The content, on its Surface. It scrolls on its own, padded by the Appearance spacing. */
 const AppLayoutContent = forwardRef(function AppLayoutContent({ children, style, ...properties }, ref) {
-    const { spacing } = useLayout();
-    return _jsx("main", { ...properties, ref: ref, style: { gridArea: "content", minWidth: 0, minHeight: 0, ...style }, children: _jsx(ScrollArea, { style: { height: "100%" }, children: _jsx("div", { style: { padding: spacing }, children: children }) }) });
+    const { spacing, radius } = useLayout();
+    return _jsx(Surface, { as: "main", ...properties, ref: ref, material: "extended", radius: resolveRadius("medium", radius), style: {
+            gridArea: "content",
+            minWidth: 0,
+            minHeight: 0,
+            // The Surface owns its shape: what scrolls inside stays within its corners.
+            overflow: "clip",
+            ...style
+        }, children: _jsx(ScrollArea, { style: { height: "100%" }, children: _jsx("div", { style: { padding: spacing }, children: children }) }) });
 });
 /** An optional row below the content, such as the actions that apply to it. */
 const AppLayoutFooter = forwardRef(function AppLayoutFooter({ style, ...properties }, ref) {
-    const { separator, spacing } = useLayout();
+    const { spacing } = useLayout();
     return _jsx("footer", { ...properties, ref: ref, style: {
             gridArea: "footer",
             display: "flex",
@@ -65,18 +93,17 @@ const AppLayoutFooter = forwardRef(function AppLayoutFooter({ style, ...properti
             justifyContent: "flex-end",
             gap: scale(spacing, "small"),
             minWidth: 0,
-            padding: `${scale(spacing, "small")}px ${spacing}px`,
-            borderBlockStart: `1px solid ${separator}`,
+            paddingTop: scale(spacing, "small"),
             ...style
         } });
 });
 function useLayout() {
-    const context = useContext(AppLayoutContext);
-    if (context == null)
+    if (!useContext(AppLayoutContext))
         throw new Error("AppLayout parts must be used inside AppLayout");
-    return context;
+    return useVisual();
 }
 export const AppLayout = Object.assign(AppLayoutRoot, {
+    Title: AppLayoutTitle,
     Sidebar: AppLayoutSidebar,
     Header: AppLayoutHeader,
     Content: AppLayoutContent,

package/dist/avatar.d.ts

@@ -0,0 +1,23 @@
+import type { CSSProperties, ReactNode } from "react";
+import { type Color } from "./foundation/color.js";
+import type { ScaleLevel } from "./foundation/scale.js";
+export interface AvatarProps {
+    /** Who it shows. It names the Avatar for assistive technology and supplies the initials. */
+    readonly name: string;
+    /** A picture that replaces the initials. */
+    readonly src?: string;
+    /** Replaces the initials, for example with an icon for an agent. */
+    readonly children?: ReactNode;
+    /** Otherwise one of the Appearance roles, chosen from the name so a person keeps one color. */
+    readonly color?: Color;
+    /** The Avatar is as tall as a control of this size. */
+    readonly size?: ScaleLevel;
+    readonly className?: string;
+    readonly style?: CSSProperties;
+}
+/**
+ * A person or an agent, drawn as a circle as tall as a control: a picture, or
+ * initials on the soft level of a color. The text color follows from the
+ * paint like any Surface.
+ */
+export declare const Avatar: import("react").ForwardRefExoticComponent<AvatarProps & import("react").RefAttributes<HTMLSpanElement>>;

package/dist/avatar.js

@@ -0,0 +1,42 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef } from "react";
+import { controlFontWeight, useControlMetrics } from "./control/control.js";
+import { colorLevel, resolveColor } from "./foundation/color.js";
+import { Surface } from "./surface/surface.js";
+const roles = ["primary", "secondary", "success", "warning", "info", "danger"];
+/** The same name always lands on the same role. */
+function nameRole(name) {
+    let hash = 0;
+    for (const character of name)
+        hash = (hash * 31 + character.codePointAt(0)) >>> 0;
+    return roles[hash % roles.length];
+}
+function initials(name) {
+    const words = name.trim().split(/\s+/).filter(Boolean);
+    return words.slice(0, 2).map(word => [...word][0].toLocaleUpperCase()).join("");
+}
+/**
+ * A person or an agent, drawn as a circle as tall as a control: a picture, or
+ * initials on the soft level of a color. The text color follows from the
+ * paint like any Surface.
+ */
+export const Avatar = forwardRef(function Avatar({ name, src, children, color, size, className, style }, ref) {
+    const metrics = useControlMetrics(size);
+    const { colors } = metrics.visual;
+    const fill = colorLevel(resolveColor(color ?? nameRole(name), colors), "soft", colors);
+    return _jsx(Surface, { as: "span", ref: ref, role: "img", "aria-label": name, className: className, color: fill, depth: "flat", radius: "full", style: {
+            display: "inline-grid",
+            placeItems: "center",
+            flexShrink: 0,
+            width: metrics.height,
+            height: metrics.height,
+            overflow: "hidden",
+            fontSize: metrics.fontSize,
+            fontWeight: controlFontWeight,
+            lineHeight: 1,
+            userSelect: "none",
+            ...style
+        }, children: src !== undefined
+            ? _jsx("img", { src: src, alt: "", style: { width: "100%", height: "100%", objectFit: "cover", borderRadius: "inherit" } })
+            : children ?? initials(name) });
+});

package/dist/badge.d.ts

@@ -0,0 +1,20 @@
+import type { CSSProperties, ReactNode } from "react";
+import { type Color } from "./foundation/color.js";
+import type { ScaleLevel } from "./foundation/scale.js";
+export interface BadgeProps {
+    readonly children?: ReactNode;
+    /** The color role of the state it names. Omitted, the Badge is neutral: the content color. */
+    readonly color?: Color;
+    /** Leads with a dot in the full color, for a live state such as `running`. */
+    readonly dot?: boolean;
+    /** The badge sizes its text one control step below this level. */
+    readonly size?: ScaleLevel;
+    readonly className?: string;
+    readonly style?: CSSProperties;
+}
+/**
+ * A short label for a state, such as `running` or `stopped`. It is not a
+ * control: it is painted in the subtle level of its color, like a selection,
+ * with its text in the strong level so the color stays readable.
+ */
+export declare const Badge: import("react").ForwardRefExoticComponent<BadgeProps & import("react").RefAttributes<HTMLSpanElement>>;

package/dist/badge.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef } from "react";
+import { controlFontSizes, controlFontWeight, useControlMetrics } from "./control/control.js";
+import { colorLevel, resolveColor } from "./foundation/color.js";
+import { Surface } from "./surface/surface.js";
+const smaller = Object.freeze({ xsmall: "xsmall", small: "xsmall", medium: "small", large: "medium", xlarge: "large" });
+/**
+ * A short label for a state, such as `running` or `stopped`. It is not a
+ * control: it is painted in the subtle level of its color, like a selection,
+ * with its text in the strong level so the color stays readable.
+ */
+export const Badge = forwardRef(function Badge({ children, color = "foreground", dot = false, size, className, style }, ref) {
+    const metrics = useControlMetrics(size);
+    const { colors } = metrics.visual;
+    const base = resolveColor(color, colors);
+    const fill = colorLevel(base, "subtle", colors);
+    return _jsxs(Surface, { as: "span", ref: ref, className: className, color: fill, depth: "flat", radius: "full", style: {
+            display: "inline-flex",
+            alignItems: "center",
+            gap: metrics.gap / 2,
+            paddingInline: metrics.gap,
+            paddingBlock: metrics.gap / 4,
+            color: colorLevel(base, "strong", colors),
+            fontSize: controlFontSizes[smaller[size ?? "medium"]],
+            fontWeight: controlFontWeight,
+            lineHeight: 1.45,
+            whiteSpace: "nowrap",
+            verticalAlign: "middle",
+            ...style
+        }, children: [dot && _jsx("span", { "aria-hidden": "true", style: { width: "0.5em", height: "0.5em", borderRadius: "50%", background: base, flexShrink: 0 } }), children] });
+});

package/dist/breadcrumbs.d.ts

@@ -0,0 +1,20 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { BreadcrumbsProps as AriaBreadcrumbsProps } from "react-aria-components";
+import type { ScaleLevel } from "./foundation/scale.js";
+export interface BreadcrumbsProps extends Omit<AriaBreadcrumbsProps<object>, "className" | "style" | "children"> {
+    readonly children?: ReactNode;
+    readonly size?: ScaleLevel;
+    readonly className?: string;
+    readonly style?: CSSProperties;
+}
+export interface BreadcrumbsItemProps {
+    readonly children?: ReactNode;
+    readonly href?: string;
+    readonly id?: string;
+}
+/** One step of the path. Its separator follows it, except after the current page. */
+declare function BreadcrumbsItem({ children, href, id }: BreadcrumbsItemProps): import("react").JSX.Element;
+export declare const Breadcrumbs: import("react").ForwardRefExoticComponent<BreadcrumbsProps & import("react").RefAttributes<HTMLOListElement>> & {
+    Item: typeof BreadcrumbsItem;
+};
+export {};

package/dist/breadcrumbs.js

@@ -0,0 +1,43 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, forwardRef, useContext } from "react";
+import { Breadcrumb as AriaBreadcrumb, Breadcrumbs as AriaBreadcrumbs, Link as AriaLink } from "react-aria-components";
+import { ChevronRight } from "lucide-react";
+import { controlFontWeight, controlOpacity, transition, useControlMetrics } from "./control/control.js";
+import { iconProps } from "./control/icon.js";
+import { surfacePaint } from "./surface/surface.js";
+const BreadcrumbsContext = createContext(null);
+/** Where a page sits in a hierarchy: each ancestor is a link, the last entry is the current page. */
+const BreadcrumbsRoot = forwardRef(function Breadcrumbs({ children, size, style, ...properties }, ref) {
+    const metrics = useControlMetrics(size);
+    return _jsx(BreadcrumbsContext.Provider, { value: metrics, children: _jsx(AriaBreadcrumbs, { ...properties, ref: ref, style: {
+                display: "flex",
+                flexWrap: "wrap",
+                alignItems: "center",
+                gap: metrics.gap / 2,
+                margin: 0,
+                padding: 0,
+                listStyle: "none",
+                fontSize: metrics.fontSize,
+                lineHeight: 1.45,
+                ...style
+            }, children: children }) });
+});
+/** One step of the path. Its separator follows it, except after the current page. */
+function BreadcrumbsItem({ children, href, id }) {
+    const metrics = useContext(BreadcrumbsContext);
+    if (metrics === null)
+        throw new Error("Breadcrumbs.Item must be inside Breadcrumbs");
+    const ring = surfacePaint(metrics.visual, metrics.visual.colors.foreground, "flat", "none", false, { focusVisible: true }).ring;
+    return _jsx(AriaBreadcrumb, { id: id, style: { display: "flex", alignItems: "center", gap: metrics.gap / 2 }, children: ({ isCurrent }) => _jsxs(_Fragment, { children: [_jsx(AriaLink, { href: isCurrent ? undefined : href, style: state => ({
+                        ...transition(metrics.visual, "opacity, outline-color"),
+                        color: "inherit",
+                        textDecoration: "none",
+                        borderRadius: "0.2em",
+                        fontWeight: isCurrent ? controlFontWeight : undefined,
+                        opacity: isCurrent || state.isHovered ? 1 : controlOpacity.secondary,
+                        outline: `3px solid ${state.isFocusVisible ? ring : "transparent"}`,
+                        outlineOffset: 1,
+                        cursor: isCurrent ? "default" : "pointer"
+                    }), children: children }), !isCurrent && _jsx(ChevronRight, { ...iconProps(Math.round(metrics.height / 2)), style: { opacity: controlOpacity.placeholder } })] }) });
+}
+export const Breadcrumbs = Object.assign(BreadcrumbsRoot, { Item: BreadcrumbsItem });

package/dist/control/control.d.ts

@@ -27,6 +27,8 @@ export interface FieldProps {
 export type ControlOverrides = keyof ControlProps | keyof FieldProps | "children" | "isDisabled" | "isRequired" | "isInvalid" | "isReadOnly";
 /** Relative text scale for control content. Only a component's root applies it. */
 export declare const controlFontSizes: Readonly<Record<ScaleLevel, string>>;
+/** A control text size relative to an element that already applies another level. */
+export declare function relativeFontSize(level: ScaleLevel, within: ScaleLevel): string;
 export declare const controlFontWeight = 600;
 /** Attenuation shared by every control family. */
 export declare const controlOpacity: Readonly<{

package/dist/control/control.js

@@ -10,6 +10,10 @@ export const controlFontSizes = Object.freeze({
     large: "0.875em",
     xlarge: "0.9375em"
 });
+/** A control text size relative to an element that already applies another level. */
+export function relativeFontSize(level, within) {
+    return `${Number.parseFloat(controlFontSizes[level]) / Number.parseFloat(controlFontSizes[within])}em`;
+}
 export const controlFontWeight = 600;
 /** Attenuation shared by every control family. */
 export const controlOpacity = Object.freeze({

package/dist/control/meaning.d.ts

@@ -0,0 +1,5 @@
+import type { Color } from "../foundation/color.js";
+/** The icon of a message's meaning: its color role, or `i` for anything else. */
+export declare function meaningIcon(color: Color): import("lucide-react").LucideIcon;
+/** Whether a message of this meaning interrupts, and is announced as it appears. */
+export declare function urgentMeaning(color: Color): boolean;

package/dist/control/meaning.js

@@ -0,0 +1,10 @@
+import { CircleAlert, CircleCheck, Info, TriangleAlert } from "lucide-react";
+const meaningIcons = { danger: CircleAlert, warning: TriangleAlert, success: CircleCheck };
+/** The icon of a message's meaning: its color role, or `i` for anything else. */
+export function meaningIcon(color) {
+    return meaningIcons[color] ?? Info;
+}
+/** Whether a message of this meaning interrupts, and is announced as it appears. */
+export function urgentMeaning(color) {
+    return color === "danger" || color === "warning";
+}

package/dist/dialog.js

@@ -6,7 +6,7 @@ import { controlFontSizes, controlFontWeight, controlOpacity } from "./control/c
 import { ariaOpenState } from "./control/open-state.js";
 import { colorOpacity, darkCanvas } from "./foundation/color.js";
 import { resolveDirection, useDirection } from "./foundation/direction.js";
-import MotionStyle, { backdropMotionClass, overlayMotionClass, overlayTransition } from "./foundation/motion-style.js";
+import MotionStyle, { backdropMotionClass, overlayLayer, overlayMotionClass, overlayTransition } from "./foundation/motion-style.js";
 import { scale } from "./foundation/scale.js";
 import { useVisual } from "./foundation/visual.js";
 import { floatingShadow } from "./surface/shadow-options.js";
@@ -34,7 +34,7 @@ export const DialogBackdrop = forwardRef(function DialogBackdrop({ children, cla
                     ...transition,
                     position: "fixed",
                     inset: 0,
-                    zIndex: 1_000,
+                    zIndex: overlayLayer,
                     display: "grid",
                     placeItems: "center",
                     boxSizing: "border-box",

package/dist/foundation/motion-style.d.ts

@@ -2,6 +2,14 @@ import type { CSSProperties } from "react";
 import type { Visual } from "./visual.js";
 /** Per-overlay variables consumed by the shared entrance keyframes. */
 export declare function overlayTransition(visual: Visual): CSSProperties;
+/**
+ * How long one pass of a repeating motion takes, such as an indeterminate
+ * progress sweep or a skeleton pulse: eight Appearance transactions, and never
+ * quicker than a calm breath.
+ */
+export declare function loopDuration(visual: Visual): number;
+/** The stacking layer of content above an interface: dialogs and notifications. */
+export declare const overlayLayer = 1000;
 export declare const overlayMotionClass = "phreshos-ui-overlay";
 export declare const backdropMotionClass = "phreshos-ui-backdrop";
 /** React hoists and deduplicates this stylesheet, including inside portals. */

package/dist/foundation/motion-style.js

@@ -6,6 +6,16 @@ export function overlayTransition(visual) {
         "--phreshos-ui-motion-easing": visual.easing
     };
 }
+/**
+ * How long one pass of a repeating motion takes, such as an indeterminate
+ * progress sweep or a skeleton pulse: eight Appearance transactions, and never
+ * quicker than a calm breath.
+ */
+export function loopDuration(visual) {
+    return Math.max(900, visual.appearance.transaction.duration * 8);
+}
+/** The stacking layer of content above an interface: dialogs and notifications. */
+export const overlayLayer = 1_000;
 export const overlayMotionClass = "phreshos-ui-overlay";
 export const backdropMotionClass = "phreshos-ui-backdrop";
 const stylesheet = `
@@ -38,6 +48,9 @@ const stylesheet = `
 @keyframes phreshos-ui-spin {
   to { rotate: 360deg; }
 }
+@keyframes phreshos-ui-pulse {
+  50% { opacity: 0.55; }
+}
 @keyframes phreshos-ui-sweep {
   from { inset-inline-start: -40%; }
   to { inset-inline-start: 100%; }

package/dist/link.d.ts

@@ -0,0 +1,18 @@
+import type { CSSProperties, ReactNode } from "react";
+import { type LinkProps as AriaLinkProps } from "react-aria-components";
+import { type Color } from "./foundation/color.js";
+export interface LinkProps extends Omit<AriaLinkProps, "children" | "className" | "style" | "isDisabled"> {
+    readonly children?: ReactNode;
+    /** The link's color role. Its text takes the strong level, so it reads on the canvas. */
+    readonly color?: Color;
+    readonly disabled?: boolean;
+    readonly className?: string;
+    readonly style?: CSSProperties;
+}
+/**
+ * A link inside text. Links inside the app go through the `navigate` given to
+ * UIProvider, like a Button with an href. Its underline rests at the
+ * placeholder strength and fills in on hover; focus draws the same ring as
+ * every other control.
+ */
+export declare const Link: import("react").ForwardRefExoticComponent<LinkProps & import("react").RefAttributes<HTMLAnchorElement>>;

package/dist/link.js

@@ -0,0 +1,32 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef } from "react";
+import { Link as AriaLink } from "react-aria-components";
+import { controlOpacity, transition } from "./control/control.js";
+import { colorLevel, colorOpacity, resolveColor } from "./foundation/color.js";
+import { useVisual } from "./foundation/visual.js";
+import { surfacePaint } from "./surface/surface.js";
+/**
+ * A link inside text. Links inside the app go through the `navigate` given to
+ * UIProvider, like a Button with an href. Its underline rests at the
+ * placeholder strength and fills in on hover; focus draws the same ring as
+ * every other control.
+ */
+export const Link = forwardRef(function Link({ color = "primary", disabled, className, style, children, ...properties }, ref) {
+    const visual = useVisual();
+    const paint = colorLevel(resolveColor(color, visual.colors), "strong", visual.colors);
+    const ring = surfacePaint(visual, paint, "flat", "none", false, { focusVisible: true }).ring;
+    return _jsx(AriaLink, { ...properties, ref: ref, className: className, isDisabled: disabled, style: state => ({
+            ...transition(visual, "text-decoration-color, outline-color"),
+            color: paint,
+            textDecorationLine: "underline",
+            textDecorationThickness: "from-font",
+            textUnderlineOffset: "0.2em",
+            textDecorationColor: state.isHovered ? paint : colorOpacity(paint, controlOpacity.placeholder),
+            borderRadius: "0.2em",
+            outline: `3px solid ${state.isFocusVisible ? ring : "transparent"}`,
+            outlineOffset: 1,
+            cursor: state.isDisabled ? "not-allowed" : "pointer",
+            opacity: state.isDisabled ? controlOpacity.secondary : undefined,
+            ...style
+        }), children: children });
+});

package/dist/loading.d.ts

@@ -0,0 +1,20 @@
+import type { CSSProperties } from "react";
+import { type ReadinessProps } from "./readiness.js";
+import { type SurfaceOwnProps } from "./surface/surface.js";
+/** The cover is a Surface: its own props set its color, depth, material, and radius. */
+export interface LoadingProps extends Pick<ReadinessProps, "children" | "delay">, SurfaceOwnProps {
+    readonly className?: string;
+    readonly style?: CSSProperties;
+    /** Lists every requirement with a message, each with its own progress, instead of one message. */
+    readonly steps?: boolean;
+}
+/**
+ * A Readiness boundary drawn the way the System draws loading: a Surface that
+ * covers the waiting interface, with a Spinner and the message of the first
+ * waiting requirement, or every step. A requirement's detail is its message
+ * when it is a string; other requirements are waited for without being shown.
+ *
+ * The cover fills the nearest positioned ancestor, which owns its shape. It appears at once and
+ * fades out with the Appearance transaction when everything is ready.
+ */
+export declare function Loading({ children, delay, steps, ...surface }: LoadingProps): import("react").JSX.Element;

package/dist/loading.js

@@ -0,0 +1,66 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from "react";
+import { Check } from "lucide-react";
+import { useControlMetrics } from "./control/control.js";
+import { iconProps } from "./control/icon.js";
+import { Readiness } from "./readiness.js";
+import { Spinner, spinnerDiameter } from "./spinner.js";
+import { Surface } from "./surface/surface.js";
+import { Text } from "./typography.js";
+/**
+ * A Readiness boundary drawn the way the System draws loading: a Surface that
+ * covers the waiting interface, with a Spinner and the message of the first
+ * waiting requirement, or every step. A requirement's detail is its message
+ * when it is a string; other requirements are waited for without being shown.
+ *
+ * The cover fills the nearest positioned ancestor, which owns its shape. It appears at once and
+ * fades out with the Appearance transaction when everything is ready.
+ */
+export function Loading({ children, delay, steps = false, ...surface }) {
+    return _jsx(Readiness, { delay: delay, status: state => _jsx(LoadingCover, { state: state, steps: steps, surface: surface }), children: children });
+}
+function LoadingCover({ state, steps, surface }) {
+    const metrics = useControlMetrics();
+    const { duration, easing } = metrics.visual;
+    const { ready } = state;
+    const [gone, setGone] = useState(false);
+    if (!ready && gone)
+        setGone(false);
+    // Leaves the tree once faded, so it stops being a layer that repaints over the interface.
+    useEffect(() => {
+        if (!ready)
+            return;
+        const timer = setTimeout(() => setGone(true), duration);
+        return () => clearTimeout(timer);
+    }, [ready, duration]);
+    // What was shown stays in place while fading out.
+    const shown = useRef([]);
+    if (!ready)
+        shown.current = state.requirements.flatMap(requirement => typeof requirement.detail === "string" ? [{ message: requirement.detail, ready: requirement.ready }] : []);
+    if (gone)
+        return null;
+    const { depth = "flat", radius = 0, style, ...paint } = surface;
+    const cover = {
+        position: "absolute",
+        inset: 0,
+        display: "grid",
+        placeItems: "center",
+        opacity: ready ? 0 : 1,
+        // New waiting covers at once; only readiness fades.
+        transition: ready ? `opacity ${duration}ms ${easing}` : "none",
+        pointerEvents: ready ? "none" : undefined,
+        ...style
+    };
+    const progress = steps ? _jsx(StepList, { steps: shown.current }) : _jsx(Message, { message: shown.current.find(step => !step.ready)?.message });
+    // Flat and without a shape of its own by default: the container it fills owns its shape.
+    return _jsx(Surface, { ...paint, depth: depth, radius: radius, role: "status", "aria-hidden": ready || undefined, style: cover, children: progress });
+}
+function Message({ message }) {
+    const metrics = useControlMetrics();
+    return _jsxs("div", { style: { display: "grid", justifyItems: "center", gap: metrics.gap * 2 }, children: [_jsx(Spinner, { decorative: true }), message !== undefined && _jsx(Text, { tone: "secondary", size: "small", children: message })] });
+}
+function StepList({ steps }) {
+    const metrics = useControlMetrics();
+    const indicator = spinnerDiameter(metrics.visual.spacing, "small");
+    return _jsx("ul", { style: { listStyle: "none", margin: 0, padding: 0, display: "grid", gap: metrics.gap * 2 }, children: steps.map((step, index) => _jsxs("li", { "data-ready": step.ready, style: { display: "flex", alignItems: "center", gap: metrics.gap * 2 }, children: [step.ready ? _jsx(Check, { ...iconProps(indicator) }) : _jsx(Spinner, { decorative: true, size: "small" }), _jsx(Text, { tone: step.ready ? "secondary" : "default", size: "small", children: step.message })] }, index)) });
+}

package/dist/main.d.ts

@@ -41,10 +41,22 @@ export { Spinner, type SpinnerProps } from "./spinner.js";
 export { NumberField, type NumberFieldProps } from "./number-field.js";
 export { SegmentedControl, type SegmentedControlProps, type SegmentedControlItemProps } from "./segmented-control.js";
 export { Alert, type AlertProps } from "./alert.js";
+export { Link, type LinkProps } from "./link.js";
+export { Heading, Text, Kbd, Code, type HeadingProps, type TextProps, type KbdProps, type CodeProps } from "./typography.js";
+export { Badge, type BadgeProps } from "./badge.js";
+export { Meter, type MeterProps } from "./meter.js";
+export { SearchField, type SearchFieldProps } from "./search-field.js";
+export { Breadcrumbs, type BreadcrumbsProps, type BreadcrumbsItemProps } from "./breadcrumbs.js";
+export { Avatar, type AvatarProps } from "./avatar.js";
+export { TagGroup, type TagGroupProps, type TagGroupTagProps } from "./tag-group.js";
+export { Skeleton, type SkeletonProps } from "./skeleton.js";
+export { toast, ToastRegion, type ToastContent, type ToastOptions, type ToastRegionProps } from "./toast.js";
+export { Readiness, useReadiness, useRequirement, type ReadinessProps, type ReadinessState, type Requirement } from "./readiness.js";
+export { Loading, type LoadingProps } from "./loading.js";
 export { FileTrigger, type FileTriggerProps } from "./file-trigger.js";
 export { DropZone, type DropZoneProps } from "./drop-zone.js";
 export { Fieldset, type FieldsetProps } from "./fieldset.js";
-export { AppLayout, type AppLayoutProps, type AppLayoutRegionProps } from "./app-layout.js";
+export { AppLayout, type AppLayoutProps, type AppLayoutRegionProps, type AppLayoutTitleProps } from "./app-layout.js";
 export { ColorSwatch, type ColorSwatchProps } from "./color-swatch.js";
 export { ColorSwatchPicker, type ColorSwatchPickerProps, type ColorSwatchPickerItemProps } from "./color-swatch-picker.js";
 export { ColorSlider, type ColorSliderProps } from "./color-slider.js";