@phreshos/react-ui 0.1.49 → 0.1.51

package/README.md

@@ -231,7 +231,7 @@ component-owned.
 Text fields, Select, ComboBox, and the date fields recess the `background` by
 default. Checkbox, Switch, and RadioGroup indicators are recessed beds that rise
 in their color when selected. Slider and ProgressBar fill a recessed rail with
-their color. Motion follows `appearance.transaction`; Preferences with
+their color. Motion is derived from what moves, how far, and `appearance.tempo` (`timing`, `useTiming`); Preferences with
 animations disabled make every change immediate without changing Appearance.
 
 | Component | Value contract | Purpose |

package/dist/button.d.ts

@@ -25,7 +25,10 @@ interface ButtonOwnProps extends ControlProps, RadiusProps, MaterialOverrides, S
 /** A Button that acts: a native `<button>`. */
 export interface ButtonActionProps extends NativeButtonProps, ButtonOwnProps {
     readonly href?: undefined;
-    /** Prevents activation while keeping the Button focusable. */
+    /**
+     * Work the Button started is under way: a Spinner shows in its place, the Button keeps its size
+     * and its name, and it stays focusable without activating.
+     */
     readonly pending?: boolean;
 }
 /**

package/dist/button.js

@@ -1,8 +1,9 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { forwardRef } from "react";
 import { Button as AriaButton, Link as AriaLink } from "react-aria-components";
-import { controlOpacity, transition, useControlMetrics } from "./control/control.js";
+import { transition, useControlMetrics } from "./control/control.js";
 import { surfaceRender } from "./control/surface-render.js";
+import { Spinner } from "./spinner.js";
 /** A raised Surface you act on, or follow when it has an `href`. */
 export const Button = forwardRef(function Button(properties, ref) {
     const { children, color = "default", depth, disabled, iconOnly = false, radius, size, style, className, material, shadow, ...rest } = properties;
@@ -33,7 +34,7 @@ export const Button = forwardRef(function Button(properties, ref) {
     const { pending = false, type = "button", ...action } = rest;
     // Disabled state is read from React Aria, so a Button placed in a slot, such
     // as a calendar's month buttons, follows the owner that disables it.
-    return _jsx(AriaButton, { ...action, ref: ref, type: type, className: className, isDisabled: disabled, isPending: pending, render: surfaceRender("button", state => surface(state, pending)), style: state => buttonStyle(metrics, iconOnly, !state.isDisabled && !pending && state.isPressed, state.isDisabled, pending, style), children: children });
+    return _jsx(AriaButton, { ...action, ref: ref, type: type, className: className, isDisabled: disabled, isPending: pending, render: surfaceRender("button", state => surface(state, pending)), style: state => buttonStyle(metrics, iconOnly, !state.isDisabled && !pending && state.isPressed, state.isDisabled, pending, style), children: pending ? _jsxs(_Fragment, { children: [_jsx("span", { style: { display: "inline-flex", alignItems: "center", gap: metrics.gap, opacity: 0 }, children: children }), _jsx("span", { style: { position: "absolute", inset: 0, display: "grid", placeItems: "center" }, children: _jsx(Spinner, { decorative: true, color: "currentColor", style: { width: metrics.indicator, height: metrics.indicator } }) })] }) : children });
 });
 function buttonStyle(metrics, iconOnly, pressed, disabled, pending, style) {
     return {
@@ -62,7 +63,7 @@ function buttonStyle(metrics, iconOnly, pressed, disabled, pending, style) {
         WebkitTapHighlightColor: "transparent",
         cursor: disabled ? "not-allowed" : pending ? "progress" : "pointer",
         scale: pressed ? "0.97" : "1",
-        ...(pending ? { opacity: controlOpacity.pending } : {}),
+        ...(pending ? { position: "relative" } : {}),
         ...style
     };
 }

package/dist/control/control.d.ts

@@ -36,7 +36,6 @@ export declare const controlLineHeight = 1.45;
 export declare const controlFontWeight = 600;
 /** Attenuation shared by every control family. */
 export declare const controlOpacity: Readonly<{
-    pending: 0.68;
     secondary: 0.66;
     placeholder: 0.55;
 }>;
@@ -62,5 +61,5 @@ export declare function controlMetrics(visual: Visual, size: ScaleLevel, radius:
  * Appearance radius itself.
  */
 export declare function proportionalRadius(visual: Visual, height: number, level?: ScaleLevel): number;
-/** A CSS transition for the given properties using the Appearance transaction. */
+/** A CSS transition for the given properties moving as a change in place. */
 export declare function transition(visual: Visual, properties: string, factor?: number): CSSProperties;

package/dist/control/control.js

@@ -21,7 +21,6 @@ export const controlLineHeight = 1.45;
 export const controlFontWeight = 600;
 /** Attenuation shared by every control family. */
 export const controlOpacity = Object.freeze({
-    pending: 0.68,
     secondary: 0.66,
     placeholder: 0.55
 });
@@ -70,7 +69,7 @@ export function proportionalRadius(visual, height, level = "medium") {
     const medium = controlHeight(visual.spacing);
     return Math.round(scale(visual.radius, level) * height / medium * 100) / 100;
 }
-/** A CSS transition for the given properties using the Appearance transaction. */
+/** A CSS transition for the given properties moving as a change in place. */
 export function transition(visual, properties, factor = 1) {
     return {
         transitionProperty: properties,

package/dist/drawer.d.ts

@@ -0,0 +1,21 @@
+import { type CSSProperties, type ReactNode } from "react";
+export interface DrawerProps {
+    readonly open: boolean;
+    /** Called for a press outside the Drawer or for Escape. */
+    readonly onClose: () => void;
+    /** Shown at its top, such as the name of what it belongs to. */
+    readonly title?: ReactNode;
+    readonly "aria-label"?: string;
+    readonly className?: string;
+    readonly style?: CSSProperties;
+    readonly children: ReactNode;
+}
+/**
+ * A narrow layout's sidebar, over its content from the start side, such as the navigation a narrow
+ * window gives up to its content. It is placed in its nearest positioned container. A press
+ * outside or Escape closes it. It slides in and back out along the same path, timed by the
+ * motion of a change in place, the way out its own animation so its end is seen; without motion it
+ * simply shows and goes. Only its position moves:
+ * fading it would switch off the blur it draws of what is behind it.
+ */
+export declare function Drawer({ open, onClose, title, className, style, children, ...properties }: DrawerProps): import("react").JSX.Element | null;

package/dist/drawer.js

@@ -0,0 +1,53 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import { controlFontSizes, controlFontWeight } from "./control/control.js";
+import MotionStyle, { overlayTransition } from "./foundation/motion-style.js";
+import { scale } from "./foundation/scale.js";
+import { useVisual } from "./foundation/visual.js";
+import { Surface } from "./surface/surface.js";
+/**
+ * A narrow layout's sidebar, over its content from the start side, such as the navigation a narrow
+ * window gives up to its content. It is placed in its nearest positioned container. A press
+ * outside or Escape closes it. It slides in and back out along the same path, timed by the
+ * motion of a change in place, the way out its own animation so its end is seen; without motion it
+ * simply shows and goes. Only its position moves:
+ * fading it would switch off the blur it draws of what is behind it.
+ */
+export function Drawer({ open, onClose, title, className, style, children, ...properties }) {
+    const visual = useVisual();
+    const animated = visual.duration > 0;
+    const inset = scale(visual.spacing, "small");
+    // It stays while it slides out, and leaves once the slide ends.
+    const [present, setPresent] = useState(open);
+    useEffect(() => { if (open)
+        setPresent(true);
+    else if (!animated)
+        setPresent(false); }, [open, animated]);
+    useEffect(() => {
+        if (!open)
+            return;
+        // Escape closes the Drawer alone, not a surface that holds it.
+        const close = (event) => { if (event.key === "Escape") {
+            event.preventDefault();
+            event.stopPropagation();
+            onClose();
+        } };
+        addEventListener("keydown", close, true);
+        return () => removeEventListener("keydown", close, true);
+    }, [open, onClose]);
+    if (!present)
+        return null;
+    return _jsxs(_Fragment, { children: [_jsx(MotionStyle, {}), open && _jsx("div", { "data-drawer-scrim": "", style: { position: "absolute", inset: 0, zIndex: 10 }, onPointerDown: onClose }), _jsxs(Surface, { ...properties, "data-drawer": "", "data-state": animated ? open ? "opening" : "closing" : undefined, material: "full", className: ["phreshos-ui-drawer", className].filter(Boolean).join(" "), onAnimationEnd: () => { if (!open)
+                    setPresent(false); }, style: {
+                    ...overlayTransition(visual),
+                    position: "absolute",
+                    insetBlock: inset,
+                    insetInlineStart: inset,
+                    zIndex: 11,
+                    boxSizing: "border-box",
+                    width: `min(${visual.spacing * 20}px, calc(100% - ${visual.spacing * 4}px))`,
+                    padding: inset,
+                    overflow: "auto",
+                    ...style
+                }, children: [title != null && _jsx("div", { style: { padding: `${inset}px ${inset}px ${visual.spacing}px`, fontSize: controlFontSizes.xlarge, fontWeight: controlFontWeight }, children: title }), children] })] });
+}

package/dist/foundation/appearance.d.ts

@@ -1,7 +1,7 @@
-import { type Appearance as SystemAppearance, type AppearanceColors, type AppearanceMaterial, type AppearanceShadow, type AppearanceTransaction } from "@phreshos/core";
-export type { AppearanceColor, AppearanceColors, AppearanceMaterial, AppearanceRange, AppearanceShadow, AppearanceTransaction, Easing, ThemedValue } from "@phreshos/core";
+import { type Appearance as SystemAppearance, type AppearanceColors, type AppearanceMaterial, type AppearanceShadow } from "@phreshos/core";
+export type { AppearanceColor, AppearanceColors, AppearanceMaterial, AppearanceRange, AppearanceShadow, Transaction, Easing, ThemedValue } from "@phreshos/core";
 /** The System Appearance fields consumed by React UI. */
-export type Appearance = Pick<SystemAppearance, "colors" | "spacing" | "radius" | "shadow" | "material" | "transaction">;
+export type Appearance = Pick<SystemAppearance, "colors" | "spacing" | "radius" | "shadow" | "material" | "tempo">;
 type Themed<Value> = Readonly<{
     light?: Readonly<Partial<Value>>;
     dark?: Readonly<Partial<Value>>;
@@ -12,7 +12,7 @@ type AppearanceUpdateFields = Readonly<{
     radius?: number;
     shadow?: Themed<AppearanceShadow>;
     material?: Themed<AppearanceMaterial>;
-    transaction?: Readonly<Partial<AppearanceTransaction>>;
+    tempo?: number;
 }>;
 /** At least one partial visual field merged recursively with the nearest UIProvider. */
 export type AppearanceUpdate = {
@@ -76,6 +76,10 @@ export declare const appearanceLimits: Readonly<{
             maximum: 2.6;
         }>;
     }>;
+    tempo: Readonly<{
+        minimum: number;
+        maximum: 4;
+    }>;
 }>;
 /** The visual portion of the System's default Appearance. */
 export declare const defaultAppearance: Appearance;

package/dist/foundation/appearance.js

@@ -4,7 +4,8 @@ export const appearanceLimits = Object.freeze({
     spacing: coreAppearanceLimits.spacing,
     radius: coreAppearanceLimits.radius,
     shadow: coreAppearanceLimits.shadow,
-    material: coreAppearanceLimits.material
+    material: coreAppearanceLimits.material,
+    tempo: coreAppearanceLimits.tempo
 });
 /** The visual portion of the System's default Appearance. */
 export const defaultAppearance = Object.freeze({
@@ -13,7 +14,7 @@ export const defaultAppearance = Object.freeze({
     radius: systemDefaultAppearance.radius,
     shadow: systemDefaultAppearance.shadow,
     material: systemDefaultAppearance.material,
-    transaction: systemDefaultAppearance.transaction
+    tempo: systemDefaultAppearance.tempo
 });
 /** Applies one partial update; omitted leaves continue to inherit. */
 export function mergeAppearance(appearance, update) {
@@ -23,9 +24,7 @@ export function mergeAppearance(appearance, update) {
         radius: update.radius ?? appearance.radius,
         shadow: mergeThemed(appearance.shadow, update.shadow),
         material: mergeThemed(appearance.material, update.material),
-        transaction: update.transaction === undefined
-            ? appearance.transaction
-            : Object.freeze({ ...appearance.transaction, ...update.transaction })
+        tempo: update.tempo ?? appearance.tempo
     });
 }
 function mergeThemed(current, update) {

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

@@ -4,7 +4,7 @@ import type { Visual } from "./visual.js";
 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
+ * progress sweep or a skeleton pulse: eight changes in place, and never
  * quicker than a calm breath.
  */
 export declare function loopDuration(visual: Visual): number;

package/dist/foundation/motion-style.js

@@ -1,4 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
+import { timing } from "./timing.js";
 /** Per-overlay variables consumed by the shared entrance keyframes. */
 export function overlayTransition(visual) {
     return {
@@ -8,11 +9,11 @@ export function overlayTransition(visual) {
 }
 /**
  * How long one pass of a repeating motion takes, such as an indeterminate
- * progress sweep or a skeleton pulse: eight Appearance transactions, and never
+ * progress sweep or a skeleton pulse: eight changes in place, and never
  * quicker than a calm breath.
  */
 export function loopDuration(visual) {
-    return Math.max(900, visual.appearance.transaction.duration * 8);
+    return Math.max(900, timing("change", { tempo: visual.appearance.tempo }).duration * 8);
 }
 /** The stacking layer of content above an interface: dialogs and notifications. */
 export const overlayLayer = 1_000;
@@ -45,6 +46,22 @@ const stylesheet = `
   color: inherit;
   opacity: 0.55;
 }
+.phreshos-ui-text-control::-webkit-search-cancel-button,
+.phreshos-ui-text-control::-webkit-search-decoration {
+  display: none;
+}
+.phreshos-ui-drawer[data-state="opening"] {
+  animation: phreshos-ui-drawer-in var(--phreshos-ui-motion-duration) var(--phreshos-ui-motion-easing);
+}
+.phreshos-ui-drawer[data-state="closing"] {
+  animation: phreshos-ui-drawer-out var(--phreshos-ui-motion-duration) var(--phreshos-ui-motion-easing) forwards;
+}
+:dir(rtl).phreshos-ui-drawer[data-state="opening"] { animation-name: phreshos-ui-drawer-in-rtl; }
+:dir(rtl).phreshos-ui-drawer[data-state="closing"] { animation-name: phreshos-ui-drawer-out-rtl; }
+@keyframes phreshos-ui-drawer-in { from { translate: calc(-100% - 1rem) 0; } }
+@keyframes phreshos-ui-drawer-out { to { translate: calc(-100% - 1rem) 0; } }
+@keyframes phreshos-ui-drawer-in-rtl { from { translate: calc(100% + 1rem) 0; } }
+@keyframes phreshos-ui-drawer-out-rtl { to { translate: calc(100% + 1rem) 0; } }
 @keyframes phreshos-ui-spin {
   to { rotate: 360deg; }
 }

package/dist/foundation/timing.d.ts

@@ -0,0 +1,30 @@
+import type { Transaction } from "@phreshos/core";
+/**
+ * What moves, which decides how it moves:
+ *
+ * - `change`: something changing in its place, such as a color, a control's state, or an overlay
+ *   appearing. It is short, and the same whatever the size of what changes.
+ * - `window`: a box carried across a distance, such as a Window moving or resizing. A light body
+ *   answering a hand: it sets off at once and settles softly.
+ * - `view`: a whole scene carried across a distance, such as the view over the plane. It moves as
+ *   a body on a spring: it arrives without passing its place, and a move taken on the way carries
+ *   on at the speed it already has.
+ */
+export type MotionKind = "change" | "window" | "view";
+export type TimingOptions = Readonly<{
+    /** How far it goes, in pixels; nothing for a change in place. */
+    distance?: number;
+    /** Whether it leaves the person's sight: then it sets off softly, or it is gone in the first frames. */
+    leaving?: boolean;
+    /** The Appearance tempo, or a tempo made from it; 1 by default. */
+    tempo?: number;
+}>;
+/**
+ * The motion of one change: how long it takes and how it moves, from what moves, how far, and the
+ * tempo. The shape of every motion is the System's own; the tempo only stretches or shortens time,
+ * so every motion keeps its shape and its length beside every other.
+ *
+ * Across a distance, the time grows with the distance, gently, as the square root, within bounds:
+ * a fixed short time would cross a far distance so fast that frames show as jumps.
+ */
+export declare function timing(kind: MotionKind, options?: TimingOptions): Transaction;

package/dist/foundation/timing.js

@@ -0,0 +1,36 @@
+/**
+ * The motion of one change: how long it takes and how it moves, from what moves, how far, and the
+ * tempo. The shape of every motion is the System's own; the tempo only stretches or shortens time,
+ * so every motion keeps its shape and its length beside every other.
+ *
+ * Across a distance, the time grows with the distance, gently, as the square root, within bounds:
+ * a fixed short time would cross a far distance so fast that frames show as jumps.
+ */
+export function timing(kind, options = {}) {
+    const tempo = options.tempo ?? 1;
+    // A change in place is the same for one tempo, so it is one value that effects can depend on. Only
+    // the few tempos in use are kept: a tempo dragged across its range leaves none of its steps behind.
+    if (kind === "change") {
+        let cached = changes.get(tempo);
+        if (!cached) {
+            if (changes.size >= 8)
+                changes.delete(changes.keys().next().value);
+            changes.set(tempo, cached = Object.freeze({ duration: Math.round(change.duration * tempo), easing: change.easing }));
+        }
+        return cached;
+    }
+    const pace = paces[kind];
+    const distance = options.distance ?? 0;
+    // Near, the time grows as the square root; a long crossing adds a little more for each pixel
+    // past a first stretch, so a far journey is not crossed at a rush.
+    const designed = Math.min(pace.maximum, Math.max(pace.minimum, pace.base + pace.growth * Math.sqrt(distance) + pace.far * Math.max(0, distance - 1000)));
+    return Object.freeze({ duration: Math.round(designed * tempo), easing: options.leaving ? departure : pace.easing });
+}
+const change = Object.freeze({ duration: 102, easing: "ease-out" });
+const changes = new Map();
+/** The curve of something leaving the view: soft to start, gathering speed as it goes. */
+const departure = Object.freeze([0.65, 0, 0.35, 1]);
+const paces = {
+    view: { base: 187, growth: 8.5, far: 0, minimum: 255, maximum: 850, easing: Object.freeze({ spring: Object.freeze({ bounce: 0 }) }) },
+    window: { base: 72, growth: 3.4, far: 0.0425, minimum: 110, maximum: 553, easing: Object.freeze([0.22, 1, 0.36, 1]) }
+};

package/dist/foundation/visual.d.ts

@@ -1,4 +1,6 @@
-import { type Appearance, type AppearanceColors, type AppearanceMaterial, type AppearanceShadow, type Easing, type ThemedValue } from "./appearance.js";
+import { type Transaction } from "@phreshos/core";
+import { type MotionKind, type TimingOptions } from "./timing.js";
+import { type Appearance, type AppearanceColors, type AppearanceMaterial, type AppearanceShadow, type ThemedValue } from "./appearance.js";
 import type { Preferences } from "./preferences.js";
 /**
  * One Appearance resolved for one set of Preferences. Every component reads
@@ -13,9 +15,9 @@ export interface Visual {
     readonly shadow: AppearanceShadow;
     readonly spacing: number;
     readonly radius: number;
-    /** Duration in milliseconds, already zero when animations are disabled. */
+    /** Duration in milliseconds of a change in place, already zero when animations are disabled. */
     readonly duration: number;
-    /** CSS timing function for the Appearance transaction. */
+    /** CSS timing function of a change in place. */
     readonly easing: string;
 }
 /** Resolves and memoizes one Visual per Appearance, Theme, and animation preference. */
@@ -32,11 +34,15 @@ export declare function useAppearance(): Appearance;
 export declare function usePreferences(): Preferences;
 /** Returns the shared resolved Visual for the nearest Appearance and Preferences. */
 export declare function useVisual(): Visual;
+/**
+ * Derives the motion of a change from the nearest Appearance's tempo: what moves, how far, and
+ * whether it leaves sight. With animations off, every motion takes no time.
+ */
+export declare function useTiming(): (kind: MotionKind, options?: Omit<TimingOptions, "tempo">) => Transaction;
 /** Selects the active branch of one themed value. */
 export declare function useThemedValue<Value>(value: ThemedValue<Value>): Value;
 /** Reactively reads the browser's complete visual preferences. */
 export declare function useBrowserPreferences(): Preferences;
 /** Creates a stable source for one explicitly supplied Preferences value. */
 export declare function fixedPreferencesSource(preferences: Preferences): PreferencesSource;
-export declare function cssEasing(easing: Easing): string;
 export declare const PreferencesContext: import("react").Context<PreferencesSource>;

package/dist/foundation/visual.js

@@ -1,4 +1,6 @@
-import { createContext, useContext, useSyncExternalStore } from "react";
+import { createContext, useCallback, useContext, useSyncExternalStore } from "react";
+import { cssEasing } from "@phreshos/core";
+import { timing } from "./timing.js";
 import { defaultAppearance } from "./appearance.js";
 const visuals = new WeakMap();
 /** Resolves and memoizes one Visual per Appearance, Theme, and animation preference. */
@@ -10,7 +12,8 @@ export function resolveVisual(appearance, preferences) {
     const cached = resolved.get(key);
     if (cached !== undefined)
         return cached;
-    const duration = preferences.animations ? appearance.transaction.duration : 0;
+    const change = timing("change", { tempo: appearance.tempo });
+    const duration = preferences.animations ? change.duration : 0;
     const visual = Object.freeze({
         appearance,
         preferences,
@@ -20,7 +23,7 @@ export function resolveVisual(appearance, preferences) {
         spacing: appearance.spacing,
         radius: appearance.radius,
         duration,
-        easing: cssEasing(appearance.transaction.easing)
+        easing: cssEasing(change.easing)
     });
     resolved.set(key, visual);
     return visual;
@@ -39,6 +42,18 @@ export function usePreferences() {
 export function useVisual() {
     return resolveVisual(useAppearance(), usePreferences());
 }
+/**
+ * Derives the motion of a change from the nearest Appearance's tempo: what moves, how far, and
+ * whether it leaves sight. With animations off, every motion takes no time.
+ */
+export function useTiming() {
+    const visual = useVisual();
+    return useCallback(function (kind, options = {}) {
+        if (!visual.preferences.animations)
+            return still;
+        return timing(kind, { ...options, tempo: visual.appearance.tempo });
+    }, [visual]);
+}
 /** Selects the active branch of one themed value. */
 export function useThemedValue(value) {
     return value[usePreferences().theme];
@@ -55,9 +70,8 @@ export function fixedPreferencesSource(preferences) {
         subscribe: () => () => undefined
     };
 }
-export function cssEasing(easing) {
-    return typeof easing === "string" ? easing : `cubic-bezier(${easing.join(", ")})`;
-}
+// Every motion with animations off: it takes no time, so its curve never shows.
+const still = Object.freeze({ duration: 0, easing: "linear" });
 const defaultPreferences = Object.freeze({ theme: "light", animations: true });
 const subscribers = new Set();
 let darkPreference;

package/dist/grid-list.d.ts

@@ -8,6 +8,8 @@ type GridListRootBaseProps<T extends object> = Omit<AriaGridListProps<T>, "class
     className?: string;
     /** Color laid beneath selected Items. */
     color?: Color;
+    /** Color of Items that are not selected: `default` unless given. */
+    restColor?: Color;
     /** The narrowest an Item may be; the grid fits as many columns as that allows. Sixteen times the spacing by default. */
     itemWidth?: CSSProperties["width"];
     size?: ScaleLevel;
@@ -29,6 +31,8 @@ export interface GridListItemProps<T = object> extends Omit<AriaGridListItemProp
     readonly className?: string;
     /** Color laid beneath this Item when it is selected. */
     readonly color?: Color;
+    /** Color of this Item while it is not selected; the GridList's unless given. */
+    readonly restColor?: Color;
     readonly disabled?: boolean;
     readonly style?: CSSProperties;
 }

package/dist/grid-list.js

@@ -10,12 +10,12 @@ import { resolveDirection, useDirection } from "./foundation/direction.js";
 import { collectionHeaderStyle } from "./list-box.js";
 const GridListStyleContext = createContext(null);
 const GridListRootImplementation = forwardRef(function GridList(properties, ref) {
-    const { className, color = "primary", defaultValue: _defaultValue, itemWidth, onChange: _onChange, radius, selectionMode: _selectionMode, size, style, value: _value, ...native } = properties;
+    const { className, color = "primary", restColor = "default", defaultValue: _defaultValue, itemWidth, onChange: _onChange, radius, selectionMode: _selectionMode, size, style, value: _value, ...native } = properties;
     const metrics = useControlMetrics(size, radius);
     const width = itemWidth ?? metrics.visual.spacing * 16;
     // As many columns as fit, each at least the Item width; a Section repeats the same columns.
     const columns = `repeat(auto-fill, minmax(min(${typeof width === "number" ? `${width}px` : width}, 100%), 1fr))`;
-    const context = useMemo(() => ({ color, metrics, columns }), [color, metrics, columns]);
+    const context = useMemo(() => ({ color, restColor, metrics, columns }), [color, restColor, metrics, columns]);
     const direction = resolveDirection(native.dir, useDirection());
     return _jsx(GridListStyleContext.Provider, { value: context, children: _jsx(AriaDirectionBoundary, { direction: direction, children: _jsx(AriaGridList, { ...native, ...ariaSelection(properties, "single"), ref: ref, dir: direction, layout: "grid", className: className, style: state => ({
                     display: "grid",
@@ -33,7 +33,7 @@ const GridListRootImplementation = forwardRef(function GridList(properties, ref)
                 }) }) }) });
 });
 /** One card. It holds whatever it is given, and shows a check in its corner when selected. */
-const GridListItemImplementation = forwardRef(function GridListItem({ children, className, color, disabled = false, style, textValue, ...properties }, ref) {
+const GridListItemImplementation = forwardRef(function GridListItem({ children, className, color, restColor, disabled = false, style, textValue, ...properties }, ref) {
     const inherited = useGridListStyle();
     const itemColor = color ?? inherited.color;
     const { metrics } = inherited;
@@ -46,9 +46,9 @@ const GridListItemImplementation = forwardRef(function GridListItem({ children,
                 focusVisible: state.isFocusVisible,
                 disabled: state.isDisabled
             }, metrics.radius),
-            // Unlike a list row, a card is a whole Surface: flat, in the default color at rest, in its
-            // selection color once selected, with the default material in both.
-            ...(state.isSelected || state.isDropTarget === true ? {} : { color: "default" }),
+            // Unlike a list row, a card is a whole Surface: flat, in its rest color, in its selection
+            // color once selected, with the default material in both.
+            ...(state.isSelected || state.isDropTarget === true ? {} : { color: restColor ?? inherited.restColor }),
             material: undefined
         })), style: {
             position: "relative",

package/dist/loading.d.ts

@@ -17,7 +17,7 @@ export interface LoadingProps extends Pick<ReadinessProps, "children" | "delay">
  * requirements are waited for without being shown.
  *
  * The loading fills the nearest positioned ancestor. It appears at once; when
- * everything is ready it fades out with the Appearance transaction and the
+ * everything is ready it fades out as a change in place and the
  * interface appears whole at once.
  */
 export declare function Loading({ children, delay, steps, className, style }: LoadingProps): import("react").JSX.Element;

package/dist/loading.js

@@ -15,7 +15,7 @@ import { Text } from "./typography.js";
  * requirements are waited for without being shown.
  *
  * The loading fills the nearest positioned ancestor. It appears at once; when
- * everything is ready it fades out with the Appearance transaction and the
+ * everything is ready it fades out as a change in place and the
  * interface appears whole at once.
  */
 export function Loading({ children, delay, steps = false, className, style }) {

package/dist/main.d.ts

@@ -4,10 +4,11 @@
  * Components enter this surface only after their implementation-independent
  * behavior contract has been established by the package's tests.
  */
-export { appearanceLimits, defaultAppearance, type Appearance, type AppearanceColor, type AppearanceColors, type AppearanceMaterial, type AppearanceRange, type AppearanceShadow, type AppearanceTransaction, type AppearanceUpdate, type Easing, type ThemedValue } from "./foundation/appearance.js";
+export { appearanceLimits, defaultAppearance, type Appearance, type AppearanceColor, type AppearanceColors, type AppearanceMaterial, type AppearanceRange, type AppearanceShadow, type Transaction, type AppearanceUpdate, type Easing, type ThemedValue } from "./foundation/appearance.js";
 export { UIProvider, type UIProviderProps } from "./foundation/provider.js";
 export { DocumentTheme } from "./document-theme.js";
-export { useAppearance, useBrowserPreferences, usePreferences, useThemedValue } from "./foundation/visual.js";
+export { useAppearance, useBrowserPreferences, usePreferences, useThemedValue, useTiming } from "./foundation/visual.js";
+export { timing, type MotionKind, type TimingOptions } from "./foundation/timing.js";
 export { useDirection, useDocumentDirection, type Direction } from "./foundation/direction.js";
 export type { Preferences, PreferencesUpdate, Theme } from "./foundation/preferences.js";
 export { Flex, type FlexProps } from "./flex.js";
@@ -17,6 +18,7 @@ export { resolveColor, useColor, useContrastingColor, type Color, type ColorLeve
 export { Panel, type PanelProps, type PanelHeaderProps, type PanelContentProps } from "./panel.js";
 export { Window, type WindowProps, type WindowContentProps, type WindowHeaderProps, type WindowIdentityProps, type WindowCenterProps, type WindowActionsProps, type WindowActionProps, type WindowControlProps, type WindowMaximizeProps, type WindowCloseProps, type WindowMoveCaptureProps } from "./window.js";
 export { default as useWindowMoveHandle, type WindowMoveHandle } from "./use-window-move-handle.js";
+export { Drawer, type DrawerProps } from "./drawer.js";
 export { Button, type ButtonActionProps, type ButtonColor, type ButtonLinkProps, type ButtonProps } from "./button.js";
 export { Input, type InputProps } from "./input.js";
 export { Textarea, type TextareaProps } from "./textarea.js";

package/dist/main.js

@@ -7,7 +7,8 @@
 export { appearanceLimits, defaultAppearance } from "./foundation/appearance.js";
 export { UIProvider } from "./foundation/provider.js";
 export { DocumentTheme } from "./document-theme.js";
-export { useAppearance, useBrowserPreferences, usePreferences, useThemedValue } from "./foundation/visual.js";
+export { useAppearance, useBrowserPreferences, usePreferences, useThemedValue, useTiming } from "./foundation/visual.js";
+export { timing } from "./foundation/timing.js";
 export { useDirection, useDocumentDirection } from "./foundation/direction.js";
 export { Flex } from "./flex.js";
 export { Grid } from "./grid.js";
@@ -17,6 +18,7 @@ export { resolveColor, useColor, useContrastingColor } from "./foundation/color.
 export { Panel } from "./panel.js";
 export { Window } from "./window.js";
 export { default as useWindowMoveHandle } from "./use-window-move-handle.js";
+export { Drawer } from "./drawer.js";
 export { Button } from "./button.js";
 export { Input } from "./input.js";
 export { Textarea } from "./textarea.js";

package/dist/spinner.js

@@ -1,9 +1,9 @@
-import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { forwardRef } from "react";
 import { ProgressBar as AriaProgressBar } from "react-aria-components";
 import { useControlMetrics } from "./control/control.js";
-import { colorOpacity, resolveColor } from "./foundation/color.js";
-import MotionStyle from "./foundation/motion-style.js";
+import { resolveColor } from "./foundation/color.js";
+import MotionStyle, { loopDuration } 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) {
@@ -25,7 +25,7 @@ export const Spinner = forwardRef(function Spinner({ className, color = "primary
         verticalAlign: "middle",
         ...style
     };
-    const indicator = _jsxs(_Fragment, { children: [_jsx(MotionStyle, {}), _jsxs("svg", { "data-spinner-indicator": "", "aria-hidden": "true", focusable: "false", viewBox: "0 0 24 24", width: "100%", height: "100%", fill: "none", style: { display: "block", animation: metrics.visual.duration > 0 ? `phreshos-ui-spin ${Math.max(600, metrics.visual.appearance.transaction.duration * 5)}ms linear infinite` : undefined }, children: [_jsx("circle", { "data-spinner-track": "", cx: "12", cy: "12", r: "9", stroke: colorOpacity(arc, 0.2), strokeWidth: "3" }), _jsx("circle", { "data-spinner-fill": "", cx: "12", cy: "12", r: "9", pathLength: "100", stroke: arc, strokeWidth: "3", strokeLinecap: "round", strokeDasharray: "30 70" })] })] });
+    const indicator = _jsxs(_Fragment, { children: [_jsx(MotionStyle, {}), _jsx("svg", { "data-spinner-indicator": "", "aria-hidden": "true", focusable: "false", viewBox: "0 0 24 24", width: "100%", height: "100%", fill: "none", style: { display: "block", animation: metrics.visual.duration > 0 ? `phreshos-ui-spin ${loopDuration(metrics.visual)}ms linear infinite` : undefined }, children: _jsx("circle", { "data-spinner-fill": "", cx: "12", cy: "12", r: "11", pathLength: "100", stroke: arc, strokeWidth: "2", strokeDasharray: "75 25", transform: "rotate(-90 12 12)" }) })] });
     if (decorative)
         return _jsx("div", { ...properties, ref: ref, "aria-hidden": "true", className: className, style: rootStyle, children: indicator });
     return _jsx(AriaProgressBar, { ...properties, ref: ref, "aria-label": label, className: className, isIndeterminate: true, style: rootStyle, children: indicator });

package/dist/tooltip.d.ts

@@ -4,7 +4,9 @@ import { type ButtonActionProps } from "./button.js";
 import { type AriaOverlayInternals, type OverlayRootProps } from "./control/open-state.js";
 import { type Direction } from "./foundation/direction.js";
 import { type SurfaceOwnProps } from "./surface/surface.js";
-export type TooltipRootProps = OverlayRootProps & Readonly<Pick<AriaTooltipTriggerProps, "delay" | "closeDelay" | "trigger">> & Readonly<{
+export type TooltipRootProps = OverlayRootProps & Readonly<Pick<AriaTooltipTriggerProps, "closeDelay" | "trigger">> & Readonly<{
+    /** Milliseconds the pointer rests on the trigger before the Tooltip opens: four changes in place by default. */
+    delay?: number;
     /** Whether the Tooltip is prevented from opening. */
     disabled?: boolean;
     /** Whether pressing the trigger closes the Tooltip. Defaults to `true`. */
@@ -18,6 +20,8 @@ export interface TooltipContentProps extends Omit<AriaTooltipProps, AriaOverlayI
     readonly children?: ReactNode;
     readonly className?: string;
     readonly dir?: Direction;
+    /** DOM container that owns the positioned overlay's coordinate space. */
+    readonly portalContainer?: Element;
     readonly style?: CSSProperties;
 }
 export declare const TooltipContent: import("react").ForwardRefExoticComponent<TooltipContentProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/tooltip.js

@@ -9,20 +9,23 @@ import MotionStyle, { overlayMotionClass, overlayTransition } from "./foundation
 import { resolveDirectionalPlacement } from "./foundation/overlay-placement.js";
 import { scale } from "./foundation/scale.js";
 import { useVisual } from "./foundation/visual.js";
+import { timing } from "./foundation/timing.js";
 import { floatingShadow } from "./surface/shadow-options.js";
 import { Surface } from "./surface/surface.js";
 export function TooltipRoot({ children, delay, closeDelay, trigger, disabled, closeOnPress, ...state }) {
-    return _jsx(AriaTooltipTrigger, { ...ariaOpenState(state), delay: delay, closeDelay: closeDelay, trigger: trigger, isDisabled: disabled, shouldCloseOnPress: closeOnPress, children: children });
+    // A pointer resting on a trigger for four changes in place is asking what it is.
+    const rest = timing("change", { tempo: useVisual().appearance.tempo }).duration * 4;
+    return _jsx(AriaTooltipTrigger, { ...ariaOpenState(state), delay: delay ?? rest, closeDelay: closeDelay, trigger: trigger, isDisabled: disabled, shouldCloseOnPress: closeOnPress, children: children });
 }
 export const TooltipTrigger = forwardRef(function TooltipTrigger(properties, ref) {
     return _jsx(Button, { ...properties, ref: ref });
 });
-export const TooltipContent = forwardRef(function TooltipContent({ children, className, color, material, radius, shadow, style, offset, placement = "top", dir, ...attributes }, ref) {
+export const TooltipContent = forwardRef(function TooltipContent({ children, className, color, material, radius, shadow, style, offset, placement = "top", dir, portalContainer, ...attributes }, ref) {
     const visual = useVisual();
     const inset = scale(visual.spacing, "small");
     const transition = overlayTransition(visual);
     const direction = resolveDirection(dir, useDirection());
-    return _jsxs(_Fragment, { children: [_jsx(MotionStyle, {}), _jsx(AriaTooltip, { ...attributes, ref: ref, dir: direction, offset: offset ?? inset, placement: resolveDirectionalPlacement(placement, direction), className: overlayMotionClass, style: transition, children: _jsx(Surface, { dir: direction, className: className, color: color ?? "foreground", material: material, radius: radius, shadow: shadow ?? floatingShadow(visual.shadow), style: {
+    return _jsxs(_Fragment, { children: [_jsx(MotionStyle, {}), _jsx(AriaTooltip, { ...attributes, ref: ref, dir: direction, offset: offset ?? inset, placement: resolveDirectionalPlacement(placement, direction), UNSTABLE_portalContainer: portalContainer, className: overlayMotionClass, style: transition, children: _jsx(Surface, { dir: direction, className: className, color: color ?? "foreground", material: material, radius: radius, shadow: shadow ?? floatingShadow(visual.shadow), style: {
                         boxSizing: "border-box",
                         maxWidth: "28em",
                         paddingBlock: inset,

package/dist/use-window-move-handle.d.ts

@@ -1,4 +1,4 @@
-import type { BeginWindowMoveGesture } from "@phreshos/core";
+import type { BeginPresentationMoveGesture } from "@phreshos/core";
 import { type PointerEventHandler } from "react";
 export interface WindowMoveHandle {
     onPointerDown: PointerEventHandler<HTMLElement>;
@@ -8,4 +8,4 @@ export interface WindowMoveHandle {
     onLostPointerCapture: PointerEventHandler<HTMLElement>;
 }
 /** Turns one DOM element into a move handle for any compatible host gesture. */
-export default function useWindowMoveHandle(beginMoveGesture?: BeginWindowMoveGesture, onError?: (error: unknown) => void): WindowMoveHandle;
+export default function useWindowMoveHandle(beginMoveGesture?: BeginPresentationMoveGesture, onError?: (error: unknown) => void): WindowMoveHandle;

package/dist/window.d.ts

@@ -1,5 +1,5 @@
 import type { HTMLAttributes, ReactNode } from "react";
-import type { BeginWindowMoveGesture } from "@phreshos/core";
+import type { BeginPresentationMoveGesture } from "@phreshos/core";
 import { type ButtonActionProps } from "./button.js";
 import { type Color } from "./foundation/color.js";
 import { type SurfaceProps } from "./surface/surface.js";
@@ -16,7 +16,7 @@ export interface WindowHeaderProps extends Omit<HTMLAttributes<HTMLDivElement>,
     /** Base color inherited by header-owned text and icons. */
     readonly color?: Color;
     /** Hands an intentional header drag to its host after the pointer threshold. */
-    readonly beginMoveGesture?: BeginWindowMoveGesture;
+    readonly beginMoveGesture?: BeginPresentationMoveGesture;
     /** Whether the represented window is currently maximized. */
     readonly maximized?: boolean;
     /** Toggles the represented window between maximized and restored states. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/react-ui",
-  "version": "0.1.49",
+  "version": "0.1.51",
   "description": "React components for coherent PhreshOS Program interfaces.",
   "type": "module",
   "sideEffects": false,
@@ -57,7 +57,7 @@
   "dependencies": {
     "@base-ui/react": "^1.7.0",
     "@internationalized/date": "^3.12.3",
-    "@phreshos/core": "^0.1.66",
+    "@phreshos/core": "^0.1.69",
     "colorjs.io": "^0.7.1",
     "lucide-react": "^1.48.0",
     "react-aria": "^3.51.0",