@phreshos/react-ui 0.1.33 → 0.1.35

package/dist/color.d.ts

@@ -14,6 +14,8 @@ export declare function color(value: string): ColorScale;
 export declare function resolveColorLevel(value: string, level: ColorLevel): string;
 /** Returns the complete visual treatments derived from one concrete color. */
 export declare function useColor(value: string): ColorScale;
+/** Returns the readable Appearance content color for one semantic or CSS fill. */
+export declare function useContrastingColor(value: Color): string;
 /** Resolves a semantic color from an already selected Appearance branch. */
 export declare function resolveColor(value: Color | undefined, colors: AppearanceColors): string;
 /** Resolves opaque control paint from an already selected Appearance branch. */

package/dist/color.js

@@ -1,4 +1,5 @@
 import { useMemo } from "react";
+import { useResolvedAppearance } from "./appearance-context.js";
 import ColorSpace from "colorjs.io/src/ColorSpace.js";
 import { mix } from "colorjs.io/src/interpolation.js";
 import parse from "colorjs.io/src/parse.js";
@@ -61,6 +62,11 @@ export function resolveColorLevel(value, level) {
 export function useColor(value) {
     return useMemo(() => color(value), [value]);
 }
+/** Returns the readable Appearance content color for one semantic or CSS fill. */
+export function useContrastingColor(value) {
+    const { colors } = useResolvedAppearance();
+    return useMemo(() => contrastingColor(value, colors), [value, colors]);
+}
 /** Resolves a semantic color from an already selected Appearance branch. */
 export function resolveColor(value, colors) {
     const resolved = value ?? defaultColor;

package/dist/main.d.ts

@@ -13,7 +13,7 @@ export { Grid, type GridProps } from "./grid.js";
 export { Surface, type MaterialMode, type MaterialOptions, type ShadowOptions, type SurfaceComponent, type SurfaceHost, type SurfaceHostProps, type SurfaceOwnProps, type SurfaceProps } from "./surface.js";
 export { defaultColor, type Color, type ColorLevel, type ColorScale } from "./color.js";
 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 } from "./window.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 { Button, type ButtonColor, type ButtonProps } from "./button.js";
 export { Input, type InputProps } from "./input.js";
@@ -36,6 +36,8 @@ export { Table, type TableProps, type TableNoSelectionProps, type TableSingleSel
 export { Tree, type TreeProps, type TreeNoSelectionProps, type TreeSingleSelectionProps, type TreeMultipleSelectionProps, type TreeMultipleValue, type TreeItemProps, type TreeContentProps, type TreeCollectionProps } from "./tree.js";
 export { Slider, type SliderProps } from "./slider.js";
 export { ProgressBar, type ProgressBarProps } from "./progress-bar.js";
+export { Spinner, type SpinnerProps } from "./spinner.js";
+export { Readiness, useReadiness, useRequirement, type ReadinessFallback, type ReadinessProps, type ReadinessRequirement, type ReadinessRequirementProps } from "./readiness.js";
 export { ScrollArea, type ScrollAreaAxis, type ScrollAreaProps } from "./scroll-area.js";
 export { Toolbar, type ToolbarProps, type ToolbarGroupProps, type ToolbarSeparatorProps } from "./toolbar.js";
 export { Disclosure, type DisclosureProps, type DisclosureTriggerProps, type DisclosureContentProps } from "./disclosure.js";
@@ -51,5 +53,5 @@ export type { ControlColor } from "./control.js";
 export type { LayoutAlignment, LayoutGap, LayoutJustification } from "./layout.js";
 export { resolveRadius, type Radius, type RadiusProps } from "./radius.js";
 export { resolveSpacing, type Spacing } from "./spacing.js";
-export { useColor } from "./color.js";
+export { useColor, useContrastingColor } from "./color.js";
 export { useScale, type NumericScale, type ScaleLevel } from "./scale.js";

package/dist/main.js

@@ -34,6 +34,8 @@ export { Table } from "./table.js";
 export { Tree } from "./tree.js";
 export { Slider } from "./slider.js";
 export { ProgressBar } from "./progress-bar.js";
+export { Spinner } from "./spinner.js";
+export { Readiness, useReadiness, useRequirement } from "./readiness.js";
 export { ScrollArea } from "./scroll-area.js";
 export { Toolbar } from "./toolbar.js";
 export { Disclosure } from "./disclosure.js";
@@ -47,5 +49,5 @@ export { AlertDialog } from "./alert-dialog.js";
 export { Tooltip } from "./tooltip.js";
 export { resolveRadius } from "./radius.js";
 export { resolveSpacing } from "./spacing.js";
-export { useColor } from "./color.js";
+export { useColor, useContrastingColor } from "./color.js";
 export { useScale } from "./scale.js";

package/dist/readiness.d.ts

@@ -0,0 +1,37 @@
+import type { ReactElement, ReactNode } from "react";
+/** One requirement observed during the boundary's initial readiness cycle. */
+export interface ReadinessRequirement {
+    readonly message: string;
+    readonly createdAt: Date;
+    readonly readyAt: Date | null;
+}
+export interface ReadinessProps {
+    /** Interface prepared behind this initial readiness boundary. */
+    readonly children: ReactNode;
+    /** Optional presentation rendered while initial requirements remain pending. */
+    readonly fallback?: (requirements: readonly ReadinessRequirement[]) => ReactNode;
+    /** Message used when the oldest pending requirement has none of its own. */
+    readonly message?: string;
+}
+/** Prevents interaction with one React subtree until its initial requirements are ready. */
+export declare function ReadinessRoot({ children, fallback, message }: ReadinessProps): import("react").JSX.Element;
+export interface ReadinessRequirementProps {
+    /** Message exposed while this mounted requirement remains pending. */
+    readonly message?: string;
+}
+/** One declarative requirement whose pending lifetime matches this component's mount. */
+export declare function ReadinessRequirement({ message }: ReadinessRequirementProps): null;
+/** Registers one requirement and returns its stable, idempotent completion. */
+export declare function useRequirement(message?: string): () => void;
+/** Reads the nearest boundary's current initial-readiness state. */
+export declare function useReadiness(): Readonly<{
+    ready: boolean;
+    requirements: readonly ReadinessRequirement[];
+}>;
+interface ReadinessComponent {
+    (properties: ReadinessProps): ReactElement | null;
+    readonly Requirement: typeof ReadinessRequirement;
+}
+export declare const Readiness: ReadinessComponent;
+export type ReadinessFallback = NonNullable<ReadinessProps["fallback"]>;
+export {};

package/dist/readiness.js

@@ -0,0 +1,134 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useLayoutEffect, useMemo, useReducer, useRef, useState } from "react";
+const ReadinessContext = createContext(null);
+/** Prevents interaction with one React subtree until its initial requirements are ready. */
+export function ReadinessRoot({ children, fallback, message = "Loading…" }) {
+    const parent = useContext(ReadinessContext);
+    const requirements = useRef(new Map());
+    const revealedRef = useRef(false);
+    const [revealed, setRevealed] = useState(false);
+    const [revision, invalidate] = useReducer(value => value + 1, 0);
+    const registry = useMemo(() => ({
+        register(identity, nextMessage) {
+            if (revealedRef.current)
+                return;
+            const current = requirements.current.get(identity);
+            if (current != null) {
+                if (current.readyAt == null)
+                    return;
+                // React Strict Mode restores mounted effects before the initial tree settles.
+                requirements.current.set(identity, {
+                    ...current,
+                    message: nextMessage,
+                    readyAt: null
+                });
+                invalidate();
+                return;
+            }
+            requirements.current.set(identity, {
+                message: nextMessage,
+                createdAt: new Date(),
+                readyAt: null
+            });
+            invalidate();
+        },
+        update(identity, nextMessage) {
+            if (revealedRef.current)
+                return;
+            const current = requirements.current.get(identity);
+            if (current == null || current.message === nextMessage)
+                return;
+            requirements.current.set(identity, { ...current, message: nextMessage });
+            invalidate();
+        },
+        complete(identity) {
+            if (revealedRef.current)
+                return;
+            const current = requirements.current.get(identity);
+            if (current == null || current.readyAt != null)
+                return;
+            requirements.current.set(identity, { ...current, readyAt: new Date() });
+            invalidate();
+        },
+        release(identity) {
+            if (revealedRef.current)
+                return;
+            const current = requirements.current.get(identity);
+            if (current == null || current.readyAt != null)
+                return;
+            requirements.current.set(identity, { ...current, readyAt: new Date() });
+            invalidate();
+        }
+    }), []);
+    const currentRequirements = useMemo(() => {
+        return [...requirements.current.values()].map(requirement => ({
+            message: requirement.message ?? message,
+            createdAt: new Date(requirement.createdAt),
+            readyAt: requirement.readyAt == null ? null : new Date(requirement.readyAt)
+        }));
+    }, [message, revision]);
+    const currentMessage = currentRequirements.find(requirement => requirement.readyAt == null)?.message ?? message;
+    const completeParent = useManagedRequirement(parent?.registry ?? null, currentMessage);
+    useLayoutEffect(() => {
+        if (revealedRef.current
+            || [...requirements.current.values()].some(requirement => requirement.readyAt == null))
+            return;
+        // Descendant layout effects register first, so an empty set here represents a settled commit.
+        revealedRef.current = true;
+        setRevealed(true);
+    }, [revision]);
+    useLayoutEffect(() => {
+        if (revealed)
+            completeParent();
+    }, [completeParent, revealed]);
+    const context = useMemo(() => ({
+        ready: revealed,
+        requirements: currentRequirements,
+        registry
+    }), [currentRequirements, registry, revealed]);
+    return _jsxs(ReadinessContext.Provider, { value: context, children: [_jsx("div", { "data-readiness": "", "data-ready": revealed ? "true" : "false", inert: revealed ? undefined : true, style: { display: "contents" }, children: children }), !revealed && fallback?.(currentRequirements)] });
+}
+/** One declarative requirement whose pending lifetime matches this component's mount. */
+export function ReadinessRequirement({ message }) {
+    useRequirement(message);
+    return null;
+}
+/** Registers one requirement and returns its stable, idempotent completion. */
+export function useRequirement(message) {
+    const context = useContext(ReadinessContext);
+    if (context == null)
+        throw new Error("useRequirement must be used inside Readiness");
+    return useManagedRequirement(context.registry, message);
+}
+/** Reads the nearest boundary's current initial-readiness state. */
+export function useReadiness() {
+    const context = useContext(ReadinessContext);
+    if (context == null)
+        throw new Error("useReadiness must be used inside Readiness");
+    return useMemo(() => ({
+        ready: context.ready,
+        requirements: context.requirements
+    }), [context.ready, context.requirements]);
+}
+function useManagedRequirement(registry, message) {
+    const identity = useRef({});
+    const completed = useRef(false);
+    useLayoutEffect(() => {
+        if (!completed.current)
+            registry?.register(identity.current, message);
+        return () => registry?.release(identity.current);
+    }, [registry]);
+    useLayoutEffect(() => {
+        if (!completed.current)
+            registry?.update(identity.current, message);
+    }, [message, registry]);
+    return useCallback(() => {
+        if (completed.current)
+            return;
+        completed.current = true;
+        registry?.complete(identity.current);
+    }, [registry]);
+}
+export const Readiness = Object.assign(ReadinessRoot, {
+    Requirement: ReadinessRequirement
+});

package/dist/spinner.d.ts

@@ -0,0 +1,29 @@
+import type { CSSProperties } from "react";
+import type { ProgressBarProps as AriaProgressBarProps } from "react-aria-components";
+import type { ControlColor } from "./control.js";
+import { type ScaleLevel } from "./scale.js";
+type NativeSpinnerProps = Omit<AriaProgressBarProps, "aria-hidden" | "aria-label" | "aria-labelledby" | "children" | "className" | "formatOptions" | "isIndeterminate" | "maxValue" | "minValue" | "slot" | "style" | "value" | "valueLabel">;
+interface SpinnerVisualProps extends NativeSpinnerProps {
+    /** Native class name applied without replacing the component contract. */
+    readonly className?: string;
+    /** Color of the moving indicator. */
+    readonly color?: ControlColor;
+    /** Derives the indicator diameter from Appearance. */
+    readonly size?: ScaleLevel;
+    /** Native styles applied after Spinner defaults. */
+    readonly style?: CSSProperties;
+}
+type NamedSpinnerProps = Readonly<{
+    /** Accessible operation name announced with indeterminate progress semantics. */
+    label: string;
+    decorative?: false;
+}>;
+type DecorativeSpinnerProps = Readonly<{
+    /** Hides the Spinner when surrounding content already communicates progress. */
+    decorative: true;
+    label?: never;
+}>;
+export type SpinnerProps = SpinnerVisualProps & (NamedSpinnerProps | DecorativeSpinnerProps);
+/** 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

@@ -0,0 +1,42 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef } from "react";
+import { ProgressBar as AriaProgressBar } from "react-aria-components";
+import { motion } from "motion/react";
+import { useAppearance } from "./appearance-context.js";
+import { colorOpacity } from "./color.js";
+import { useControlTheme } from "./control.js";
+import { scale } from "./scale.js";
+/** Compact indeterminate progress, either named or explicitly decorative. */
+export const Spinner = forwardRef(function Spinner({ className, color = "default:base", decorative = false, label, size = "medium", style, ...properties }, ref) {
+    const appearance = useAppearance();
+    const theme = useControlTheme({ color, size });
+    // Spinner is a standalone status, so its scale must remain visibly distinct
+    // instead of inheriting the compact indicator size used inside controls.
+    const diameter = appearance.spacing + scale(appearance.spacing, size);
+    const rootStyle = {
+        display: "inline-grid",
+        placeItems: "center",
+        boxSizing: "border-box",
+        flexShrink: 0,
+        width: diameter,
+        height: diameter,
+        verticalAlign: "middle",
+        ...style
+    };
+    const indicator = _jsx(SpinnerIndicator, { contextualColor: color === "currentColor", theme: theme });
+    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 });
+});
+function SpinnerIndicator({ contextualColor, theme }) {
+    const duration = typeof theme.motionTransition.duration === "number"
+        ? Math.max(0.6, theme.motionTransition.duration * 4)
+        : 0.8;
+    // currentColor belongs to the surrounding surface, whose canvas is not the
+    // Appearance canvas. Alpha preserves contrast against that actual owner.
+    const track = contextualColor
+        ? colorOpacity("currentColor", 0.25)
+        : theme.paints.subtle.rest.background;
+    const fill = contextualColor ? "currentColor" : theme.paints.palette.rest.background;
+    return _jsxs(motion.svg, { "data-spinner-indicator": "", "aria-hidden": "true", focusable: "false", viewBox: "0 0 24 24", width: "100%", height: "100%", fill: "none", initial: false, animate: { rotate: theme.animations ? [0, 360] : 0 }, transition: theme.animations ? { duration, repeat: Infinity, ease: "linear" } : { duration: 0 }, style: { display: "block", transformOrigin: "center" }, children: [_jsx("circle", { "data-spinner-track": "", cx: "12", cy: "12", r: "9", stroke: track, strokeWidth: "3" }), _jsx("circle", { "data-spinner-fill": "", cx: "12", cy: "12", r: "9", pathLength: "100", stroke: fill, strokeWidth: "3", strokeLinecap: "round", strokeDasharray: "68 32" })] });
+}

package/dist/toggle-indicator.js

@@ -35,6 +35,10 @@ export function ToggleIndicator({ kind, direction = "ltr", selected, indetermina
 }
 export function toggleStyle(theme, disabled, readOnly) {
     return {
+        // React Aria's focusable native input is visually hidden with absolute
+        // positioning. Anchor it here so focus cannot scroll an ancestor viewport
+        // toward a position outside the visible toggle.
+        position: "relative",
         display: "flex",
         alignItems: "center",
         gap: theme.gap,

package/dist/window.d.ts

@@ -14,6 +14,10 @@ export interface WindowHeaderProps extends Omit<HTMLAttributes<HTMLDivElement>,
     readonly color?: Color;
     /** Hands an intentional header drag to its host after the pointer threshold. */
     readonly beginMoveGesture?: BeginWindowMoveGesture;
+    /** Whether the represented window is currently maximized. */
+    readonly maximized?: boolean;
+    /** Toggles the represented window between maximized and restored states. */
+    readonly onMaximize?: () => void;
     /** Receives a synchronous or asynchronous move handoff failure. */
     readonly onMoveError?: (error: unknown) => void;
 }
@@ -29,6 +33,7 @@ export interface WindowMaximizeProps extends WindowControlProps {
     readonly maximized?: boolean;
 }
 export type WindowCloseProps = WindowControlProps;
+export type WindowMoveCaptureProps = HTMLAttributes<HTMLDivElement>;
 /** One Surface with a ready-to-use header-and-content composition. */
 export declare const Window: import("react").ForwardRefExoticComponent<Omit<WindowProps, "ref"> & import("react").RefAttributes<HTMLDivElement>> & {
     Header: import("react").ForwardRefExoticComponent<WindowHeaderProps & import("react").RefAttributes<HTMLDivElement>> & {
@@ -41,4 +46,5 @@ export declare const Window: import("react").ForwardRefExoticComponent<Omit<Wind
         Close: import("react").ForwardRefExoticComponent<WindowControlProps & import("react").RefAttributes<HTMLButtonElement>>;
     };
     Content: import("react").ForwardRefExoticComponent<WindowContentProps & import("react").RefAttributes<HTMLDivElement>>;
+    MoveCapture: import("react").ForwardRefExoticComponent<WindowMoveCaptureProps & import("react").RefAttributes<HTMLDivElement>>;
 };

package/dist/window.js

@@ -33,7 +33,7 @@ const WindowContent = forwardRef(function WindowContent({ style, ...properties }
         } });
 });
 /** The composable top region of a window; its enclosing Surface owns the material. */
-const HeaderRoot = forwardRef(function HeaderRoot({ active = true, beginMoveGesture, children, color, onLostPointerCapture, onMoveError, onPointerCancel, onPointerDown, onPointerMove, onPointerUp, style, ...properties }, ref) {
+const HeaderRoot = forwardRef(function HeaderRoot({ active = true, beginMoveGesture, children, color, maximized = false, onDoubleClick, onLostPointerCapture, onMaximize, onMoveError, onPointerCancel, onPointerDown, onPointerMove, onPointerUp, style, ...properties }, ref) {
     const resolved = useResolvedAppearance();
     const spacing = resolved.appearance.spacing;
     const foreground = style?.color ?? resolveColor(color ?? "foreground:base", resolved.colors);
@@ -41,6 +41,8 @@ const HeaderRoot = forwardRef(function HeaderRoot({ active = true, beginMoveGest
         active,
         foreground,
         iconRadius: scale(resolved.appearance.radius, "xsmall"),
+        maximized,
+        onMaximize,
         spacing,
         transition: transitionTiming(resolved.transaction, resolved.preferences.animations)
     };
@@ -49,7 +51,11 @@ const HeaderRoot = forwardRef(function HeaderRoot({ active = true, beginMoveGest
                 onPointerDown?.(event);
                 if (!event.defaultPrevented)
                     move.onPointerDown(event);
-            }, onPointerMove: event => { onPointerMove?.(event); move.onPointerMove(event); }, onPointerUp: event => { onPointerUp?.(event); move.onPointerUp(event); }, onPointerCancel: event => { onPointerCancel?.(event); move.onPointerCancel(event); }, onLostPointerCapture: event => { onLostPointerCapture?.(event); move.onLostPointerCapture(event); }, style: {
+            }, onPointerMove: event => { onPointerMove?.(event); move.onPointerMove(event); }, onPointerUp: event => { onPointerUp?.(event); move.onPointerUp(event); }, onPointerCancel: event => { onPointerCancel?.(event); move.onPointerCancel(event); }, onLostPointerCapture: event => { onLostPointerCapture?.(event); move.onLostPointerCapture(event); }, onDoubleClick: event => {
+                onDoubleClick?.(event);
+                if (!event.defaultPrevented)
+                    onMaximize?.();
+            }, style: {
                 boxSizing: "border-box",
                 display: "flex",
                 alignItems: "center",
@@ -118,8 +124,10 @@ const WindowAction = forwardRef(function WindowAction({ ...properties }, ref) {
 const WindowMinimize = forwardRef(function WindowMinimize({ "aria-label": label = "Minimize", preventFocusOnPress = true, ...properties }, ref) {
     return _jsx(WindowAction, { ...properties, ref: ref, "aria-label": label, preventFocusOnPress: preventFocusOnPress, children: _jsx(ControlIcon, { children: _jsx("path", { d: "M1.5 7.5h7" }) }) });
 });
-const WindowMaximize = forwardRef(function WindowMaximize({ "aria-label": label, maximized = false, ...properties }, ref) {
-    return _jsx(WindowAction, { ...properties, ref: ref, "aria-label": label ?? (maximized ? "Restore" : "Maximize"), children: _jsx(ControlIcon, { children: maximized
+const WindowMaximize = forwardRef(function WindowMaximize({ "aria-label": label, maximized, onPress, ...properties }, ref) {
+    const header = useHeader();
+    const selected = maximized ?? header.maximized;
+    return _jsx(WindowAction, { ...properties, ref: ref, onPress: onPress ?? header.onMaximize, "aria-label": label ?? (selected ? "Restore" : "Maximize"), children: _jsx(ControlIcon, { children: selected
                 ? _jsx("path", { d: "M1 4h5v5H1zM4 1h5v5H6.5", strokeWidth: "1.3", strokeLinejoin: "round" })
                 : _jsx("path", { d: "M1.5 1.5h7v7h-7z", strokeWidth: "1.3", strokeLinejoin: "round" }) }) });
 });
@@ -138,8 +146,20 @@ const Header = Object.assign(HeaderRoot, {
     Maximize: WindowMaximize,
     Close: WindowClose
 });
+/** The active full-viewport side of a Window move handoff. */
+const WindowMoveCapture = forwardRef(function WindowMoveCapture({ style, ...properties }, ref) {
+    return _jsx("div", { ...properties, ref: ref, style: {
+            position: "fixed",
+            inset: 0,
+            touchAction: "none",
+            userSelect: "none",
+            cursor: "grab",
+            ...style
+        } });
+});
 /** One Surface with a ready-to-use header-and-content composition. */
 export const Window = Object.assign(WindowRoot, {
     Header,
-    Content: WindowContent
+    Content: WindowContent,
+    MoveCapture: WindowMoveCapture
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/react-ui",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "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.59",
+    "@phreshos/core": "^0.1.60",
     "colorjs.io": "^0.7.1",
     "motion": "^13.2.0",
     "react-aria": "^3.51.0",