@phreshos/react-ui 0.1.34 → 0.1.35

package/dist/main.d.ts

@@ -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";

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";

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@phreshos/react-ui",
-  "version": "0.1.34",
+  "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",