@phreshos/react-ui 0.1.27 → 0.1.29

package/README.md

@@ -8,8 +8,8 @@ Environment-neutral React components and the visual language of PhreshOS.
 
 ## Role
 
-React UI interprets Core Appearance and Theme contracts as reusable visual
-primitives. The Desktop and Programs compose those primitives instead of
+React UI owns reusable visual contracts that accept the corresponding PhreshOS
+System values directly. The Desktop and Programs compose those primitives instead of
 reimplementing material, spacing, color, radius, or interaction behavior.
 
 The package does not depend on a Client or Server runtime and does not own
@@ -25,9 +25,8 @@ applications own composition.
 | Bun | `bun add @phreshos/react-ui` |
 | Yarn | `yarn add @phreshos/react-ui` |
 
-Core is a built-in runtime dependency. React and React DOM remain peer
-dependencies because the application and React UI must share one React
-runtime.
+React and React DOM are peer dependencies because the application and React UI
+must share one React runtime.
 
 ```tsx
 import { Button, Surface } from "@phreshos/react-ui"
@@ -37,16 +36,16 @@ import { Button, Surface } from "@phreshos/react-ui"
 </Surface>
 ```
 
-Without a provider, components use Core's `defaultAppearance` and reactively
+Without a provider, components use React UI's `defaultAppearance` and reactively
 follow the browser's complete visual preferences. `UIProvider` supplies the
 Appearance, Preferences, and direction explicitly established for a React UI
 subtree. Each omitted property inherits independently from the nearest provider
 or follows its own default resolution. A provider with no properties introduces
 no boundary or behavior.
-React UI also exports that same canonical `defaultAppearance` value for callers
-that need it explicitly.
-See [Appearance](https://docs.phreshos.com/system/appearance) for the contract
-interpreted by the provider and components.
+React UI also exports `defaultAppearance` for callers that need the value
+explicitly. A complete System Appearance can be passed directly; React UI uses
+the visual fields it owns and ignores additional System fields such as
+wallpapers.
 
 React UI is neutral between left-to-right and right-to-left interfaces.
 An explicit `UIProvider` direction creates a boundary that participates in
@@ -80,11 +79,12 @@ use the shared Surface implementation while retaining their native behavior. Col
 are independent inputs. `color` accepts an Appearance color and resting level such
 as `background:base` or `primary:soft`, or a direct CSS color. Surface defaults
 to `background:base`; solid controls default to `default:base`.
-Hover and press derive shades of that fill. The resting fill chooses the
-higher-contrast text from Appearance's background and foreground once; interaction
-shades keep that choice.
+Hover and press derive shades of that fill. Surface and solid controls choose
+the higher-contrast text from Appearance's background and foreground whenever
+their fill can be evaluated; interaction shades keep that choice.
 `size` accepts `xsmall`, `small`, `medium` (default), `large`, or `xlarge`;
-spacing and radius follow Appearance. `disabled` prevents activation and focus;
+spacing and radius follow Appearance, while typography remains inherited and
+component sizes are relative to the surrounding text. `disabled` prevents activation and focus;
 `pending` prevents activation while retaining focus.
 
 ```tsx
@@ -96,7 +96,7 @@ spacing and radius follow Appearance. `disabled` prevents activation and focus;
 `Surface` is the material- and shadow-owning element. It renders a `div` by default, while
 `as` selects another React element and preserves that element's native properties
 and ref type. Surface owns its paint, opacity, frost, refraction, grain, edge,
-outer shadow, radius, and clipping requirements. `radius` accepts a size level, `full`, a
+outer shadow, and radius. `radius` accepts a size level, `full`, a
 number in pixels, or a CSS radius and defaults to `medium`.
 
 ```tsx
@@ -154,6 +154,25 @@ Native properties and the root ref target the outer Surface. `Panel.Header`
 owns the optional leading region, while `Panel.Content` is the independently
 configurable inner Surface.
 
+`WindowHeader` provides the layout shared by Desktop-owned and application-owned
+window headers. `Identity` presents the icon and truncating title, `Center` is
+optional flexible space, and `Actions` aligns compact controls at the end. The
+header uses the enclosing Surface rather than creating another material layer.
+Its controls are React UI Buttons; callers connect them to their own window
+operations. Pointer and double-click handlers on the root can implement a drag
+area, while the center and actions keep their interactions separate.
+
+```tsx
+<WindowHeader active={active} onPointerDown={beginDrag}>
+  <WindowHeader.Identity icon={icon} title={title} />
+  <WindowHeader.Actions>
+    <WindowHeader.Minimize onPress={minimize} />
+    <WindowHeader.Maximize maximized={maximized} onPress={toggleMaximize} />
+    <WindowHeader.Close onPress={close} />
+  </WindowHeader.Actions>
+</WindowHeader>
+```
+
 ## Overlays
 
 Overlay components expose each behavioral role as a named part. Roots own open
@@ -203,8 +222,8 @@ Blur, distortion, geometry, and Surface host opacity are not transitioned; gradi
 and structurally removed effects change directly rather than adding extra
 layers or keeping disabled effects alive.
 
-Motion animates toggle presses, selection marks, switch travel, the Select
-chevron, and Slider thumb feedback. Preferences with animations disabled remove spatial
+Motion animates toggle presses, selection marks, and switch travel. CSS transitions
+animate paint and the Select chevron. Preferences with animations disabled remove spatial
 feedback and make state transitions immediate. Slider values and native input
 behavior are never delayed by visual animation.
 
@@ -256,8 +275,9 @@ import { Input, Textarea, Checkbox, Radio, RadioGroup, Switch, Select, Slider }
 <Slider label="Volume" name="volume" defaultValue={50} minValue={0} maxValue={100} step={1} />
 ```
 
-React Aria owns focus, keyboard, form, and selection behavior. Select's popup
-uses Surface defaults. Toggle indicators use Motion internally and respect
+Each control delegates focus, keyboard, form, and selection behavior to its
+accessible behavioral primitive rather than recreating those systems. Select's
+popup uses Surface defaults. Toggle indicators use Motion internally and respect
 animation preferences. The preview Program demonstrates each input's
 sizes, colors, state, and interaction without overriding its visual defaults.
 
@@ -279,8 +299,7 @@ the committed dependency graph without local package substitutions.
 
 ## Related repositories
 
-- [`@phreshos/core`](https://github.com/PhreshOS/core) owns Appearance, Theme,
-  and the shared values interpreted here.
+- [`@phreshos/core`](https://github.com/PhreshOS/core) owns the System contracts.
 - [`@phreshos/react`](https://github.com/PhreshOS/react) owns runtime-neutral
   React state adaptation.
 - [PhreshOS System](https://github.com/PhreshOS/system) composes the visual

package/dist/appearance-context.d.ts

@@ -1,19 +1,12 @@
-import { type Appearance, type DesktopPreferences as Preferences, type ThemedValue } from "@phreshos/core";
-export declare const AppearanceContext: import("react").Context<Readonly<{
-    colors: ThemedValue<import("@phreshos/core").AppearanceColors>;
-    spacing: number;
-    radius: number;
-    shadow: ThemedValue<import("@phreshos/core").AppearanceShadow>;
-    material: ThemedValue<import("@phreshos/core").AppearanceMaterial>;
-    transaction: import("@phreshos/core").AppearanceTransaction;
-    signInWallpaper: ThemedValue<string | null>;
-    desktopWallpaper: ThemedValue<string | null>;
-}>>;
-export declare const PreferencesContext: import("react").Context<Readonly<{
-    theme: import("@phreshos/core").Theme;
-    animations: boolean;
-}> | null>;
-/** Returns the nearest unresolved Appearance, or Core's complete default. */
+import { type Appearance, type ThemedValue } from "./appearance.js";
+import type { Preferences } from "./preferences.js";
+export declare const AppearanceContext: import("react").Context<Appearance>;
+export interface PreferencesSource {
+    readonly getSnapshot: () => Preferences;
+    readonly getServerSnapshot: () => Preferences;
+    readonly subscribe: (change: () => void) => () => void;
+}
+/** Returns the nearest unresolved appearance, or React UI's default. */
 export declare function useAppearance(): Appearance;
 /** Returns the nearest complete Preferences, or reactively follows the browser. */
 export declare function usePreferences(): Preferences;
@@ -21,3 +14,41 @@ export declare function usePreferences(): Preferences;
 export declare function useBrowserPreferences(): Preferences;
 /** Selects the active branch of one complete ThemedValue. */
 export declare function useThemedValue<Value>(value: ThemedValue<Value>): Value;
+/** Resolves one coherent Appearance snapshot for internal component derivation. */
+export declare function useResolvedAppearance(): {
+    appearance: Appearance;
+    preferences: Preferences;
+    colors: Readonly<{
+        background: string;
+        foreground: string;
+        default: string;
+        primary: string;
+        secondary: string;
+        success: string;
+        warning: string;
+        danger: string;
+        info: string;
+    }>;
+    material: Readonly<{
+        grain: number;
+        grainAmount: number;
+        backdrop: number;
+        opacity: number;
+        distortion: number;
+        saturation: number;
+    }>;
+    shadow: Readonly<{
+        x: number;
+        y: number;
+        blur: number;
+        spread: number;
+        opacity: number;
+    }>;
+    transaction: Readonly<{
+        duration: number;
+        easing: import("@phreshos/core").Easing;
+    }>;
+};
+/** Creates a stable source for a complete explicitly supplied Preferences value. */
+export declare function fixedPreferencesSource(preferences: Preferences): PreferencesSource;
+export declare const PreferencesContext: import("react").Context<PreferencesSource>;

package/dist/appearance-context.js

@@ -1,41 +1,91 @@
 import { createContext, useContext, useMemo, useSyncExternalStore } from "react";
-import { defaultAppearance } from "@phreshos/core";
+import { defaultAppearance } from "./appearance.js";
 export const AppearanceContext = createContext(defaultAppearance);
-export const PreferencesContext = createContext(null);
-/** Returns the nearest unresolved Appearance, or Core's complete default. */
+/** Returns the nearest unresolved appearance, or React UI's default. */
 export function useAppearance() {
     return useContext(AppearanceContext);
 }
 /** Returns the nearest complete Preferences, or reactively follows the browser. */
 export function usePreferences() {
-    const preferences = useContext(PreferencesContext);
-    const browserPreferences = useBrowserPreferences();
-    return preferences ?? browserPreferences;
+    const source = useContext(PreferencesContext);
+    return useSyncExternalStore(source.subscribe, source.getSnapshot, source.getServerSnapshot);
 }
 /** Reactively reads the browser's complete visual preferences. */
 export function useBrowserPreferences() {
-    const theme = useMediaPreference(darkThemeQuery) ? "dark" : "light";
-    const animations = !useMediaPreference(reducedMotionQuery);
-    return useMemo(() => ({ theme, animations }), [animations, theme]);
+    return useSyncExternalStore(browserPreferencesSource.subscribe, browserPreferencesSource.getSnapshot, browserPreferencesSource.getServerSnapshot);
 }
 /** Selects the active branch of one complete ThemedValue. */
 export function useThemedValue(value) {
     return value[usePreferences().theme];
 }
-function useMediaPreference(query) {
-    return useSyncExternalStore(change => subscribeMediaPreference(query, change), () => browserMediaPreference(query), () => false);
+/** Resolves one coherent Appearance snapshot for internal component derivation. */
+export function useResolvedAppearance() {
+    const appearance = useAppearance();
+    const preferences = usePreferences();
+    return useMemo(() => ({
+        appearance,
+        preferences,
+        colors: appearance.colors[preferences.theme],
+        material: appearance.material[preferences.theme],
+        shadow: appearance.shadow[preferences.theme],
+        transaction: appearance.transaction
+    }), [appearance, preferences]);
 }
-function subscribeMediaPreference(query, change) {
+/** Creates a stable source for a complete explicitly supplied Preferences value. */
+export function fixedPreferencesSource(preferences) {
+    return {
+        getSnapshot: () => preferences,
+        getServerSnapshot: () => preferences,
+        subscribe: emptySubscription
+    };
+}
+const defaultPreferences = Object.freeze({ theme: "light", animations: true });
+const subscribers = new Set();
+let darkPreference;
+let reducedMotionPreference;
+let browserSnapshot = defaultPreferences;
+function readBrowserPreferences() {
     if (typeof window === "undefined" || typeof window.matchMedia !== "function")
-        return () => undefined;
-    const preference = window.matchMedia(query);
-    preference.addEventListener("change", change);
-    return () => preference.removeEventListener("change", change);
+        return defaultPreferences;
+    darkPreference ??= window.matchMedia(darkThemeQuery);
+    reducedMotionPreference ??= window.matchMedia(reducedMotionQuery);
+    const theme = darkPreference.matches ? "dark" : "light";
+    const animations = !reducedMotionPreference.matches;
+    if (browserSnapshot.theme !== theme || browserSnapshot.animations !== animations) {
+        browserSnapshot = Object.freeze({ theme, animations });
+    }
+    return browserSnapshot;
+}
+function subscribeBrowserPreferences(change) {
+    subscribers.add(change);
+    readBrowserPreferences();
+    if (subscribers.size === 1) {
+        darkPreference?.addEventListener("change", publishBrowserPreferences);
+        reducedMotionPreference?.addEventListener("change", publishBrowserPreferences);
+    }
+    return () => {
+        subscribers.delete(change);
+        if (subscribers.size !== 0)
+            return;
+        darkPreference?.removeEventListener("change", publishBrowserPreferences);
+        reducedMotionPreference?.removeEventListener("change", publishBrowserPreferences);
+        darkPreference = undefined;
+        reducedMotionPreference = undefined;
+    };
+}
+function publishBrowserPreferences() {
+    readBrowserPreferences();
+    for (const subscriber of subscribers)
+        subscriber();
 }
-function browserMediaPreference(query) {
-    return Boolean(typeof window !== "undefined"
-        && typeof window.matchMedia === "function"
-        && window.matchMedia(query).matches);
+function emptySubscription() {
+    return () => undefined;
 }
+const browserPreferencesSource = {
+    getSnapshot: readBrowserPreferences,
+    getServerSnapshot: () => defaultPreferences,
+    subscribe: subscribeBrowserPreferences
+};
+export const PreferencesContext = createContext(browserPreferencesSource);
 const darkThemeQuery = "(prefers-color-scheme: dark)";
 const reducedMotionQuery = "(prefers-reduced-motion: reduce)";

package/dist/appearance.d.ts

@@ -0,0 +1,6 @@
+import { appearanceLimits, type Appearance as SystemAppearance, type AppearanceColor, type AppearanceColors, type AppearanceMaterial, type AppearanceRange, type AppearanceShadow, type AppearanceTransaction, type Easing, type ThemedValue } from "@phreshos/core";
+/** Complete visual input consumed by React UI. */
+export type Appearance = Pick<SystemAppearance, "colors" | "spacing" | "radius" | "shadow" | "material" | "transaction">;
+export { appearanceLimits, type AppearanceColor, type AppearanceColors, type AppearanceMaterial, type AppearanceRange, type AppearanceShadow, type AppearanceTransaction, type Easing, type ThemedValue };
+/** React UI's default visual input, derived from the System default. */
+export declare const defaultAppearance: Appearance;

package/dist/appearance.js

@@ -0,0 +1,11 @@
+import { appearanceLimits, defaultAppearance as systemDefaultAppearance } from "@phreshos/core";
+export { appearanceLimits };
+/** React UI's default visual input, derived from the System default. */
+export const defaultAppearance = Object.freeze({
+    colors: systemDefaultAppearance.colors,
+    spacing: systemDefaultAppearance.spacing,
+    radius: systemDefaultAppearance.radius,
+    shadow: systemDefaultAppearance.shadow,
+    material: systemDefaultAppearance.material,
+    transaction: systemDefaultAppearance.transaction
+});

package/dist/button.js

@@ -1,7 +1,7 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { forwardRef } from "react";
 import { Button as AriaButton } from "react-aria-components";
-import { controlFontSizes, useControlTheme } from "./control.js";
+import { controlOpacity, useControlTheme } from "./control.js";
 import { SurfaceButton } from "./control-surface.js";
 /** An Appearance-aware action with normalized pointer and keyboard behavior. */
 export const Button = forwardRef(function Button({ children, color, disabled = false, pending = false, onPress, radius = "medium", size = "medium", style, material, shadow, type = "button", ...properties }, ref) {
@@ -13,14 +13,11 @@ export const Button = forwardRef(function Button({ children, color, disabled = f
             isHovered,
             isPressed,
             pending,
-            size,
             style
         }), children: children });
 });
-function buttonStyle({ theme, disabled, isFocusVisible, isHovered, isPressed, pending, size, style }) {
-    const fontSize = controlFontSizes[size];
+function buttonStyle({ theme, disabled, isFocusVisible, isHovered, isPressed, pending, style }) {
     const { spacing, focusColor } = theme;
-    const height = Math.max(24, 24 + spacing);
     const interactive = !disabled && !pending;
     const paint = buttonPaint(theme, interactive, isHovered, isPressed);
     return {
@@ -34,20 +31,19 @@ function buttonStyle({ theme, disabled, isFocusVisible, isHovered, isPressed, pe
         justifyContent: "center",
         flexShrink: 0,
         minWidth: 0,
-        height,
+        height: theme.height,
         paddingBlock: 0,
         paddingInline: Math.max(8, spacing),
-        gap: Math.max(4, spacing / 2),
+        gap: theme.gap,
         border: "none",
         borderRadius: theme.radius,
         outline: isFocusVisible ? `1px solid ${focusColor}` : "none",
         outlineOffset: 1,
         ...paint,
-        opacity: disabled ? 0.46 : pending ? 0.68 : 1,
+        opacity: disabled ? controlOpacity.disabled : pending ? controlOpacity.pending : 1,
         cursor: disabled ? "not-allowed" : pending ? "progress" : "pointer",
         font: "inherit",
-        fontSize,
-        fontWeight: 550,
+        fontSize: theme.fontSize,
         lineHeight: 1,
         textAlign: "center",
         textDecoration: "none",

package/dist/color.d.ts

@@ -1,4 +1,4 @@
-import type { AppearanceColor } from "@phreshos/core";
+import type { AppearanceColor, AppearanceColors } from "./appearance.js";
 /** A visual treatment derived from one concrete CSS color. */
 export type ColorLevel = "subtle" | "soft" | "base" | "strong" | "intense";
 /** Every visual treatment derived from one concrete CSS color. */
@@ -14,10 +14,10 @@ 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;
-/** Resolves a semantic Appearance color or preserves a direct CSS color. */
-export declare function useResolveColor(value?: Color): string;
-/** Resolves a color to concrete opaque paint for solid interactive states. */
-export declare function useResolveSolidColor(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. */
+export declare function resolveSolidColor(value: Color, colors: AppearanceColors): string;
 /** Applies material opacity without restricting the source CSS color syntax. */
 export declare function colorOpacity(value: string, opacity: number): string;
 /** Reads perceptual lightness from a resolved CSS color. */
@@ -33,6 +33,8 @@ export declare function opaqueColor(value: string): string;
 export declare function colorShade(value: string, amount: number): string;
 /** Chooses only from the two Appearance colors, against the actual painted fill. */
 export declare function onColor(fill: string, background: string, foreground: string): string;
+/** Chooses readable content when the fill can be evaluated, otherwise preserves Appearance foreground. */
+export declare function contrastingColor(value: Color, colors: AppearanceColors): string;
 /** Solid controls start at base; interaction shades preserve its text choice. */
 export declare function solidColors(base: string, background: string, foreground: string): {
     rest: {

package/dist/color.js

@@ -1,6 +1,25 @@
 import { useMemo } from "react";
-import { ColorSpace, mix, parse, serialize, to, toGamut, contrastWCAG21, sRGB, sRGB_Linear, HSL, HWB, Lab, LCH, OKLab, OKLCH, P3, A98RGB, ProPhoto, REC_2020, XYZ_D50, XYZ_D65 } from "colorjs.io/fn";
-import { useAppearance, useThemedValue } from "./ui-provider.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";
+import serialize from "colorjs.io/src/serialize.js";
+import to from "colorjs.io/src/to.js";
+import toGamut from "colorjs.io/src/toGamut.js";
+import contrastWCAG21 from "colorjs.io/src/contrast/WCAG21.js";
+import sRGB from "colorjs.io/src/spaces/srgb.js";
+import sRGB_Linear from "colorjs.io/src/spaces/srgb-linear.js";
+import HSL from "colorjs.io/src/spaces/hsl.js";
+import HWB from "colorjs.io/src/spaces/hwb.js";
+import Lab from "colorjs.io/src/spaces/lab.js";
+import LCH from "colorjs.io/src/spaces/lch.js";
+import OKLab from "colorjs.io/src/spaces/oklab.js";
+import OKLCH from "colorjs.io/src/spaces/oklch.js";
+import P3 from "colorjs.io/src/spaces/p3.js";
+import A98RGB from "colorjs.io/src/spaces/a98rgb.js";
+import ProPhoto from "colorjs.io/src/spaces/prophoto.js";
+import REC_2020 from "colorjs.io/src/spaces/rec2020.js";
+import XYZ_D50 from "colorjs.io/src/spaces/xyz-d50.js";
+import XYZ_D65 from "colorjs.io/src/spaces/xyz-d65.js";
 // Register the CSS color spaces, without bundling unrelated color-model APIs.
 for (const space of [sRGB, sRGB_Linear, HSL, HWB, Lab, LCH, OKLab, OKLCH, P3, A98RGB, ProPhoto, REC_2020, XYZ_D50, XYZ_D65])
     ColorSpace.register(space);
@@ -40,17 +59,14 @@ export function resolveColorLevel(value, level) {
 export function useColor(value) {
     return useMemo(() => color(value), [value]);
 }
-/** Resolves a semantic Appearance color or preserves a direct CSS color. */
-export function useResolveColor(value = defaultColor) {
-    const appearance = useAppearance();
-    const colors = useThemedValue(appearance.colors);
-    const semantic = parseSemanticColor(value, colors);
-    return semantic ? color(semantic.source)[semantic.level] : value;
+/** Resolves a semantic color from an already selected Appearance branch. */
+export function resolveColor(value, colors) {
+    const resolved = value ?? defaultColor;
+    const semantic = parseSemanticColor(resolved, colors);
+    return semantic ? color(semantic.source)[semantic.level] : resolved;
 }
-/** Resolves a color to concrete opaque paint for solid interactive states. */
-export function useResolveSolidColor(value) {
-    const appearance = useAppearance();
-    const colors = useThemedValue(appearance.colors);
+/** Resolves opaque control paint from an already selected Appearance branch. */
+export function resolveSolidColor(value, colors) {
     const semantic = parseSemanticColor(value, colors);
     return semantic ? resolveColorLevel(semantic.source, semantic.level) : opaqueColor(value);
 }
@@ -88,6 +104,15 @@ export function onColor(fill, background, foreground) {
     const second = opaqueColor(foreground);
     return contrastWCAG21(fill, first) > contrastWCAG21(fill, second) ? first : second;
 }
+/** Chooses readable content when the fill can be evaluated, otherwise preserves Appearance foreground. */
+export function contrastingColor(value, colors) {
+    try {
+        return onColor(resolveSolidColor(value, colors), colors.background, colors.foreground);
+    }
+    catch {
+        return colors.foreground;
+    }
+}
 /** Solid controls start at base; interaction shades preserve its text choice. */
 export function solidColors(base, background, foreground) {
     const fill = resolveColorLevel(base, "base");

package/dist/context-menu.d.ts

@@ -1,15 +1,18 @@
 import type { ComponentProps } from "react";
 import { Pressable as AriaPressable } from "react-aria-components";
 import type { MenuTriggerProps as AriaMenuTriggerProps } from "react-aria-components";
+import { type PopoverContentProps } from "./popover.js";
 export type ContextMenuRootProps = Omit<AriaMenuTriggerProps, "trigger">;
 export declare function ContextMenuRoot(properties: ContextMenuRootProps): import("react").JSX.Element;
 export type ContextMenuTriggerProps = ComponentProps<typeof AriaPressable>;
 export declare const ContextMenuTrigger: import("react").ForwardRefExoticComponent<Omit<import("react-aria/Pressable").PressableProps & import("react").RefAttributes<import("@react-types/shared").FocusableElement>, "ref"> & import("react").RefAttributes<import("@react-types/shared").FocusableElement>>;
+export type ContextMenuContentProps = Omit<PopoverContentProps, "isNonModal">;
+export declare const ContextMenuContent: import("react").ForwardRefExoticComponent<ContextMenuContentProps & import("react").RefAttributes<HTMLElement>>;
 /** A context-requested overlay sharing the same Menu contract as DropdownMenu. */
 export declare const ContextMenu: typeof ContextMenuRoot & {
     Root: typeof ContextMenuRoot;
     Trigger: import("react").ForwardRefExoticComponent<Omit<import("react-aria/Pressable").PressableProps & import("react").RefAttributes<import("@react-types/shared").FocusableElement>, "ref"> & import("react").RefAttributes<import("@react-types/shared").FocusableElement>>;
-    Content: import("react").ForwardRefExoticComponent<import("./popover.js").PopoverContentProps & import("react").RefAttributes<HTMLElement>>;
+    Content: import("react").ForwardRefExoticComponent<ContextMenuContentProps & import("react").RefAttributes<HTMLElement>>;
     Menu: import("./menu.js").MenuRootComponent & {
         Root: import("./menu.js").MenuRootComponent;
         Item: import("./menu.js").MenuItemComponent;

package/dist/context-menu.js

@@ -1,6 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { forwardRef } from "react";
-import { MenuTrigger as AriaMenuTrigger, Pressable as AriaPressable } from "react-aria-components";
+import { forwardRef, useCallback, useContext, useEffect, useRef } from "react";
+import { MenuTrigger as AriaMenuTrigger, OverlayTriggerStateContext, Pressable as AriaPressable } from "react-aria-components";
 import { Menu } from "./menu.js";
 import { PopoverContent } from "./popover.js";
 export function ContextMenuRoot(properties) {
@@ -9,10 +9,37 @@ export function ContextMenuRoot(properties) {
 export const ContextMenuTrigger = forwardRef(function ContextMenuTrigger(properties, ref) {
     return _jsx(AriaPressable, { ...properties, ref: ref });
 });
+function setRef(ref, value) {
+    if (typeof ref === "function")
+        ref(value);
+    else if (ref)
+        ref.current = value;
+}
+export const ContextMenuContent = forwardRef(function ContextMenuContent(properties, forwardedRef) {
+    const state = useContext(OverlayTriggerStateContext);
+    const contentRef = useRef(null);
+    const ref = useCallback((element) => {
+        contentRef.current = element;
+        setRef(forwardedRef, element);
+    }, [forwardedRef]);
+    useEffect(() => {
+        if (!state?.isOpen)
+            return;
+        function dismiss(event) {
+            const target = event.target;
+            if (target instanceof Node && contentRef.current?.contains(target))
+                return;
+            state?.close();
+        }
+        document.addEventListener("pointerdown", dismiss, true);
+        return () => document.removeEventListener("pointerdown", dismiss, true);
+    }, [state]);
+    return _jsx(PopoverContent, { ...properties, ref: ref, isNonModal: true });
+});
 /** A context-requested overlay sharing the same Menu contract as DropdownMenu. */
 export const ContextMenu = Object.assign(ContextMenuRoot, {
     Root: ContextMenuRoot,
     Trigger: ContextMenuTrigger,
-    Content: PopoverContent,
+    Content: ContextMenuContent,
     Menu
 });

package/dist/control.d.ts

@@ -3,6 +3,7 @@ import { type RadiusProps } from "./radius.js";
 import { type ScaleLevel } from "./scale.js";
 import { solidColors } from "./color.js";
 import { type Color } from "./color.js";
+import type { Transition } from "motion/react";
 /** Semantic Appearance colors accepted by interactive controls. */
 export type ControlColor = Color;
 export interface ControlProps {
@@ -22,10 +23,22 @@ export interface FieldProps {
 }
 /** Names owned by our contract, not a second set of primitive-specific aliases. */
 export type ControlOverrides = keyof ControlProps | keyof FieldProps | "children" | "isDisabled" | "isRequired" | "isInvalid";
-export declare const controlFontSizes: Readonly<Record<ScaleLevel, number>>;
+export declare const controlFontSizes: Readonly<Record<ScaleLevel, CSSProperties["fontSize"]>>;
+/** Shared interaction attenuation, derived consistently across control families. */
+export declare const controlOpacity: Readonly<{
+    disabled: 0.46;
+    pending: 0.68;
+    secondary: 0.7;
+    placeholder: 0.6;
+    separator: 0.14;
+}>;
+/** Shared emphasis used by labels and control-owned headings. */
+export declare const controlFontWeight = 600;
 type SolidColors = ReturnType<typeof solidColors>;
 export interface ControlTheme {
     readonly transition: CSSProperties;
+    readonly motionTransition: Transition;
+    readonly animations: boolean;
     readonly spacing: number;
     readonly foreground: string;
     readonly background: string;
@@ -38,7 +51,8 @@ export interface ControlTheme {
         readonly danger: SolidColors;
     };
     readonly radius: CSSProperties["borderRadius"];
-    readonly fontSize: number;
+    readonly fontSize: CSSProperties["fontSize"];
+    readonly indicatorSize: number;
     readonly height: number;
     readonly gap: number;
 }