@phreshos/react-ui 0.1.0

package/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2026 Zohayr SLILEH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,214 @@
+# `@phreshos/react-ui`
+
+A React component library for coherent PhreshOS Program interfaces.
+
+## Installation
+
+```bash
+bun add @phreshos/react-ui @phreshos/core react react-dom
+```
+
+React UI accepts an explicit `ThemeProperties` snapshot and does not require a
+running PhreshOS environment:
+
+```tsx
+import { standardTheme } from "@phreshos/core"
+import { Button, Flex, ThemeProvider } from "@phreshos/react-ui"
+
+function Example() {
+  return <ThemeProvider theme={standardTheme}>
+    <Flex align="center" gap="small">
+      <Button onPress={() => console.log("save")}>Save</Button>
+    </Flex>
+  </ThemeProvider>
+}
+```
+
+## Package status
+
+This package is one component of a larger architecture that remains under
+active testing. Its public surface is intentionally small and will grow only
+as component contracts are established. It is usable outside a running
+system, though its standard Theme contract comes from `@phreshos/core`.
+
+The library is being built up from behavior contracts rather than from a
+primitive dependency's component catalog. `Button` uses React Aria Components
+for normalized pointer, keyboard, focus, disabled, and pending behavior,
+without exposing that library as the public design language. Components still
+under evaluation may compare React Aria Components against Base UI privately,
+in tests.
+
+The library's future icon language has a tree-shakeable public subpath,
+`@phreshos/react-ui/icons`. That subpath deliberately exports nothing until an
+icon source and its contracts have been selected.
+
+`Grid` and `Flex` are appearance-neutral layout primitives. They preserve
+native element properties, styles, and refs while naming the layout decisions
+that recur throughout an interface:
+
+```tsx
+<Grid columns="repeat(auto-fit, minmax(12rem, 1fr))" gap="1rem">
+  ...
+</Grid>
+
+<Flex align="center" justify="between" gap={12} wrap>
+  ...
+</Flex>
+```
+
+Numeric gaps are expressed in pixels. Grid dimensions may be positive integer
+counts or native CSS track expressions, leaving responsive behavior to CSS
+rather than introducing a second breakpoint system.
+
+Inside a `ThemeProvider`, React UI derives its own spacing levels from the
+Theme's concrete default spacing:
+
+```tsx
+<Flex gap="small">...</Flex>
+<Grid gap="large">...</Grid>
+```
+
+Structures that own native spacing pass the explicit Theme value to the
+general React SDK hook instead:
+
+```tsx
+import { useScale } from "@phreshos/react"
+
+const spacing = useScale(theme.spacing)
+
+<section style={{ gap: spacing.large }} />
+```
+
+Explicit values such as `4rem` are used directly — passing them through a
+Theme hook would perform no additional work.
+
+The Theme stores unrestricted CSS background, foreground, and accent sources.
+Core derives the fixed `subtle`, `soft`, `base`, `strong`, and `intense`
+treatments from any supplied color, preserving the value exactly at `base`.
+`useColor(value)` in the React SDK memoizes that calculation without
+implicitly choosing a Theme property. CSS performs the nearby mixing in
+OKLCH, so React UI does not own or persist a parallel palette of its own:
+
+```tsx
+import { useColor } from "@phreshos/react"
+
+const colors = useColor(theme.accent)
+
+<strong style={{ color: colors.strong }} />
+```
+
+`GlassSurface` is the shared translucent material. The Theme supplies its
+background, foreground, and concrete default values for distortion, blur,
+saturation, brightness, and material opacity. The component derives its tint
+from the background and applies the foreground to its content, while accent
+remains independent for emphasis and interaction. The surface may also derive
+a small or large treatment from each numeric default without turning those
+levels into system state.
+
+Derived opacity is capped at thirty percent and never fades the surface's
+content. Layout, spacing, radius, and external elevation remain ordinary
+container concerns:
+
+```tsx
+<GlassSurface className="rounded-xl p-3">
+  ...
+</GlassSurface>
+
+<GlassSurface color="soft" distortion="large" blur="small" opacity="medium">
+  ...
+</GlassSurface>
+```
+
+Shape-owning components accept the shared `Radius` value directly. Semantic
+levels are derived from the Theme's concrete radius through the same
+`scale()` rule used for spacing, while numbers and CSS values remain explicit
+overrides:
+
+```tsx
+<GlassSurface radius="large">...</GlassSurface>
+<GlassSurface radius="2rem">...</GlassSurface>
+```
+
+Structures whose native element owns the shape derive from the explicit
+radius value through the same general React SDK hook:
+
+```tsx
+import { useScale } from "@phreshos/react"
+
+const radius = useScale(theme.radius)
+
+<section style={{ borderRadius: radius.large }} />
+```
+
+`Button` is the library's first interactive primitive. Its translucent
+control treatment matches the desktop's Start and sign-out controls, letting
+the surrounding Theme material remain visible. It derives spacing and radius
+from the Theme while keeping a single activation path across pointer, Enter,
+and Space input:
+
+```tsx
+<Button onPress={save}>Save</Button>
+<Button size="large" pending>Saving</Button>
+<Button disabled>Unavailable</Button>
+```
+
+Pending Buttons remain focusable but cannot activate. Disabled Buttons leave
+the focus order entirely. The native element defaults to `type="button"`, so
+placing it inside a form never triggers an accidental submission.
+
+`ThemeProvider` accepts a plain `ThemeProperties` snapshot, so the library
+remains usable without either environment SDK. A Program can adapt its
+observable Host value at the application boundary:
+
+```tsx
+import { HostProvider, useHostTheme } from "@phreshos/react"
+import { ThemeProvider } from "@phreshos/react-ui"
+
+function ThemedApplication({ children }) {
+  const theme = useHostTheme()
+
+  return <ThemeProvider theme={theme}>{children}</ThemeProvider>
+}
+
+<HostProvider provide={["theme"]} fallback={null}>
+  <ThemedApplication>{children}</ThemedApplication>
+</HostProvider>
+```
+
+## Standing requirements
+
+- Components preserve one recognizable visual identity.
+- Props that select a semantic treatment accept only the values documented by
+  that component. Explicit native styles and supported CSS spacing, radius,
+  and color values remain available where the component contract allows them.
+- `ThemeProvider` requires an explicit `theme` prop; it never discovers an
+  environment SDK or silently selects a global theme.
+- The provider applies a replacement `theme` value immediately to its
+  descendants.
+- Providers are scoped and nestable. The nearest `ThemeProvider` supplies the
+  complete theme for its descendants without affecting its parent or
+  siblings.
+- Accessibility, keyboard behavior, focus, and form behavior are contractual.
+- Components must work inside structurally isolated Program iframes.
+- Public types and JSDoc are part of the product.
+
+## Development
+
+```bash
+bun install --frozen-lockfile
+bun run verify
+```
+
+`verify` type-checks the source and tests, runs the behavior suite, rebuilds the
+package, packs the publication artifact, installs it into a temporary consumer,
+and checks its runtime, TypeScript, and public subpath entry points.
+
+`Button` is the only interactive component currently exported. Private
+acceptance suites also compare Field, Select, Dialog, and Context Menu
+candidates against the same implementation-independent behaviors; those
+candidates are not part of the package's public surface. Field covers labeling,
+descriptions, validation, native states, and value changes. Select covers
+collections, keyboard input, disabled options, form submission, and cleanup.
+Dialog covers modal semantics, focus, dismissal, nesting, state changes, and
+cleanup. Context Menu covers invocation, focus, actions, disabled items,
+dismissal, and cleanup.

package/dist/button.d.ts

@@ -0,0 +1,25 @@
+import type { CSSProperties, ReactNode } from "react";
+import type { ButtonProps as AriaButtonProps } from "react-aria-components";
+import { type ScaleLevel } from "@phreshos/core";
+import { type RadiusProps } from "./radius.js";
+type NativeButtonProps = Omit<AriaButtonProps, "children" | "className" | "isDisabled" | "isPending" | "onClick" | "onPress" | "style">;
+/** Properties accepted by the shared interactive button. */
+export interface ButtonProps extends NativeButtonProps, RadiusProps {
+    /** Visible Button content. */
+    readonly children?: ReactNode;
+    /** Native class name applied without replacing the component contract. */
+    readonly className?: string;
+    /** Prevents focus and activation. */
+    readonly disabled?: boolean;
+    /** Prevents activation while keeping the Button focusable. */
+    readonly pending?: boolean;
+    /** Runs once for a normalized pointer, Enter, or Space activation. */
+    readonly onPress?: () => void;
+    /** Derives the Button's spacing from the Theme's concrete default. */
+    readonly size?: ScaleLevel;
+    /** Additional native styles that do not replace the Button's identity. */
+    readonly style?: CSSProperties;
+}
+/** A Theme-aware action with normalized pointer and keyboard behavior. */
+export declare const Button: import("react").ForwardRefExoticComponent<ButtonProps & import("react").RefAttributes<HTMLButtonElement>>;
+export {};

package/dist/button.js

@@ -0,0 +1,69 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef } from "react";
+import { Button as AriaButton } from "react-aria-components";
+import { scale } from "@phreshos/core";
+import { resolveRadius } from "./radius.js";
+import { useTheme } from "./theme-provider.js";
+/** A Theme-aware action with normalized pointer and keyboard behavior. */
+export const Button = forwardRef(function Button({ children, disabled = false, pending = false, onPress, radius = "medium", size = "medium", style, type = "button", ...properties }, ref) {
+    const theme = useTheme();
+    const spacing = scale(theme.spacing, size);
+    const borderRadius = resolveRadius(radius, theme);
+    return _jsx(AriaButton, { ...properties, ref: ref, type: type, isDisabled: disabled, isPending: pending, onPress: onPress, style: ({ isFocusVisible, isHovered, isPressed }) => buttonStyle({
+            borderRadius,
+            disabled,
+            isFocusVisible,
+            isHovered,
+            isPressed,
+            pending,
+            size,
+            spacing,
+            foreground: theme.foreground,
+            style
+        }), children: children });
+});
+function buttonStyle({ borderRadius, disabled, isFocusVisible, isHovered, isPressed, pending, size, spacing, foreground, style }) {
+    const fontSize = buttonFontSizes[size];
+    const height = Math.max(size === "xsmall" ? 24 : 28, 20 + spacing);
+    return {
+        ...style,
+        appearance: "none",
+        display: "inline-grid",
+        gridAutoFlow: "column",
+        gridAutoColumns: "max-content",
+        placeItems: "center",
+        flexShrink: 0,
+        minWidth: 0,
+        height,
+        paddingBlock: 0,
+        paddingInline: Math.max(8, spacing * 2 / 3),
+        gap: Math.max(4, spacing / 2),
+        border: "1px solid rgba(255, 255, 255, 0.45)",
+        borderRadius,
+        outline: "none",
+        color: foreground,
+        backgroundColor: `rgba(255, 255, 255, ${isPressed ? 0.42 : isHovered ? 0.5 : 0.3})`,
+        boxShadow: isFocusVisible
+            ? "0 0 0 2px rgba(255, 255, 255, 0.85), inset 0 1px 0 rgba(255, 255, 255, 0.8)"
+            : "inset 0 1px 0 rgba(255, 255, 255, 0.8)",
+        opacity: disabled ? 0.46 : pending ? 0.68 : 1,
+        transform: isPressed ? "scale(0.95)" : "scale(1)",
+        transition: "background-color 100ms ease, box-shadow 100ms ease, opacity 100ms ease, transform 100ms ease",
+        cursor: disabled ? "not-allowed" : pending ? "progress" : "pointer",
+        font: "inherit",
+        fontSize,
+        fontWeight: 650,
+        lineHeight: 1,
+        textAlign: "center",
+        textDecoration: "none",
+        userSelect: "none",
+        WebkitTapHighlightColor: "transparent"
+    };
+}
+const buttonFontSizes = Object.freeze({
+    xsmall: 10,
+    small: 11,
+    medium: 12,
+    large: 13,
+    xlarge: 14
+});

package/dist/color.d.ts

@@ -0,0 +1,2 @@
+/** Applies material opacity without restricting the source CSS color syntax. */
+export declare function colorOpacity(value: string, opacity: number): string;

package/dist/color.js

@@ -0,0 +1,5 @@
+/** Applies material opacity without restricting the source CSS color syntax. */
+export function colorOpacity(value, opacity) {
+    const percentage = Math.round(opacity * 10_000) / 100;
+    return `color-mix(in srgb, ${value} ${percentage}%, transparent)`;
+}

package/dist/flex.d.ts

@@ -0,0 +1,19 @@
+import type { ComponentPropsWithoutRef } from "react";
+import type { LayoutAlignment, LayoutGap, LayoutJustification } from "./layout.js";
+/** Properties accepted by the Flex layout primitive. */
+export interface FlexProps extends ComponentPropsWithoutRef<"div"> {
+    /** Main-axis direction. The browser default is `row`. */
+    readonly direction?: "row" | "row-reverse" | "column" | "column-reverse";
+    /** Cross-axis alignment of the children. */
+    readonly align?: LayoutAlignment;
+    /** Distribution of children along the main axis. */
+    readonly justify?: LayoutJustification;
+    /** Space between children. Numbers are pixels. */
+    readonly gap?: LayoutGap;
+    /** Enables wrapping, or reverses the wrapped cross-axis order. */
+    readonly wrap?: boolean | "reverse";
+    /** Uses `inline-flex` instead of `flex`. */
+    readonly inline?: boolean;
+}
+/** A predictable Flexbox container with no visual appearance of its own. */
+export declare const Flex: import("react").ForwardRefExoticComponent<FlexProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/flex.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef } from "react";
+import { alignment, justification, resolveGap } from "./layout.js";
+import { useThemeIfAvailable } from "./theme-provider.js";
+/** A predictable Flexbox container with no visual appearance of its own. */
+export const Flex = forwardRef(function Flex({ align, direction, gap, inline = false, justify, style, wrap, ...properties }, ref) {
+    const theme = useThemeIfAvailable();
+    return _jsx("div", { ...properties, ref: ref, style: {
+            ...style,
+            display: inline ? "inline-flex" : "flex",
+            alignItems: alignment(align) ?? style?.alignItems,
+            flexDirection: direction ?? style?.flexDirection,
+            flexWrap: wrap === undefined ? style?.flexWrap : wrap === "reverse" ? "wrap-reverse" : wrap ? "wrap" : "nowrap",
+            gap: gap === undefined ? style?.gap : resolveGap(gap, theme),
+            justifyContent: justification(justify) ?? style?.justifyContent
+        } });
+});

package/dist/glass-surface.d.ts

@@ -0,0 +1,34 @@
+import type { ComponentPropsWithoutRef } from "react";
+import { type Colorable, type ColorLevel, type ScaleLevel } from "@phreshos/core";
+import { type RadiusProps } from "./radius.js";
+/** Native properties accepted by the shared glass container. */
+export type GlassSurfaceProps = ComponentPropsWithoutRef<"div"> & Colorable<ColorLevel> & RadiusProps & Readonly<{
+    /** Distortion derived from the Theme's concrete default. */
+    distortion?: ScaleLevel;
+    /** Blur derived from the Theme's concrete default. */
+    blur?: ScaleLevel;
+    /** Saturation derived from the Theme's concrete default. */
+    saturation?: ScaleLevel;
+    /** Brightness derived from the Theme's concrete default. */
+    brightness?: ScaleLevel;
+    /** Material opacity derived from the Theme's concrete default. */
+    opacity?: ScaleLevel;
+}>;
+/**
+ * Contains content within the shared refracted glass material.
+ *
+ * Layout, spacing, radius, and external elevation remain the responsibility of
+ * the containing interface. Only the material itself is owned here.
+ */
+export declare const GlassSurface: import("react").ForwardRefExoticComponent<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & Colorable<ColorLevel> & RadiusProps & Readonly<{
+    /** Distortion derived from the Theme's concrete default. */
+    distortion?: ScaleLevel;
+    /** Blur derived from the Theme's concrete default. */
+    blur?: ScaleLevel;
+    /** Saturation derived from the Theme's concrete default. */
+    saturation?: ScaleLevel;
+    /** Brightness derived from the Theme's concrete default. */
+    brightness?: ScaleLevel;
+    /** Material opacity derived from the Theme's concrete default. */
+    opacity?: ScaleLevel;
+}> & import("react").RefAttributes<HTMLDivElement>>;

package/dist/glass-surface.js

@@ -0,0 +1,40 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { forwardRef, useId } from "react";
+import { color as deriveColor, scale, scaleMultiplier, themeLimits } from "@phreshos/core";
+import { colorOpacity } from "./color.js";
+import { resolveRadius } from "./radius.js";
+import { useTheme } from "./theme-provider.js";
+const shell = "inset 1px 1px 0 rgba(255, 255, 255, 0.7), inset -1px -1px 0 rgba(255, 255, 255, 0.28)";
+/**
+ * Contains content within the shared refracted glass material.
+ *
+ * Layout, spacing, radius, and external elevation remain the responsibility of
+ * the containing interface. Only the material itself is owned here.
+ */
+export const GlassSurface = forwardRef(function GlassSurface({ blur = "medium", brightness = "medium", children, color = "base", distortion = "medium", opacity = "medium", radius, saturation = "medium", style, ...properties }, ref) {
+    const theme = useTheme();
+    const filter = `phresh-glass-${useId().replaceAll(":", "")}`;
+    const backdrop = glassBackdrop(theme.glass, { blur, brightness, saturation });
+    const alpha = boundedOpacity(scale(theme.glass.opacity, opacity));
+    const tint = deriveColor(theme.background)[color];
+    const borderRadius = resolveRadius(radius, theme);
+    return _jsxs("div", { ...properties, ref: ref, style: {
+            ...style,
+            ...(borderRadius === undefined ? {} : { borderRadius }),
+            color: theme.foreground,
+            backgroundColor: colorOpacity(tint, alpha),
+            backgroundImage: `linear-gradient(to bottom, ${colorOpacity(tint, boundedOpacity(alpha * 5 / 3))}, ${colorOpacity(tint, boundedOpacity(alpha / 2))})`,
+            boxShadow: shell,
+            backdropFilter: `url(#${filter}) ${backdrop}`,
+            WebkitBackdropFilter: backdrop,
+            isolation: "isolate",
+            overflow: "hidden"
+        }, children: [_jsx("svg", { "aria-hidden": "true", width: "0", height: "0", style: { position: "absolute" }, children: _jsxs("filter", { id: filter, x: "0%", y: "0%", width: "100%", height: "100%", children: [_jsx("feTurbulence", { type: "fractalNoise", baseFrequency: "0.008 0.008", numOctaves: "2", seed: "92", result: "noise" }), _jsx("feGaussianBlur", { in: "noise", stdDeviation: "2", result: "blurred" }), _jsx("feDisplacementMap", { in: "SourceGraphic", in2: "blurred", scale: scale(theme.glass.distortion, distortion), xChannelSelector: "R", yChannelSelector: "G" })] }) }), children] });
+});
+function glassBackdrop(glass, levels) {
+    return `blur(${scale(glass.blur, levels.blur)}px) saturate(${scaleMultiplier(glass.saturation, levels.saturation)}) brightness(${scaleMultiplier(glass.brightness, levels.brightness)})`;
+}
+/** Keeps every derived tint within the system's maximum glass opacity. */
+function boundedOpacity(value) {
+    return Math.round(Math.min(themeLimits.glass.opacity.maximum, Math.max(0, value)) * 10_000) / 10_000;
+}

package/dist/grid.d.ts

@@ -0,0 +1,21 @@
+import type { ComponentPropsWithoutRef, CSSProperties } from "react";
+import type { LayoutAlignment, LayoutGap, LayoutJustification } from "./layout.js";
+/** Properties accepted by the Grid layout primitive. */
+export interface GridProps extends ComponentPropsWithoutRef<"div"> {
+    /** Equal-width column count or native CSS column-track expression. */
+    readonly columns?: number | string;
+    /** Equal-height row count or native CSS row-track expression. */
+    readonly rows?: number | string;
+    /** Automatic placement direction. */
+    readonly flow?: CSSProperties["gridAutoFlow"];
+    /** Cross-axis alignment of items inside their grid areas. */
+    readonly align?: LayoutAlignment;
+    /** Distribution of the grid tracks along the inline axis. */
+    readonly justify?: LayoutJustification;
+    /** Space between rows and columns. Numbers are pixels. */
+    readonly gap?: LayoutGap;
+    /** Uses `inline-grid` instead of `grid`. */
+    readonly inline?: boolean;
+}
+/** A predictable CSS Grid container with no visual appearance of its own. */
+export declare const Grid: import("react").ForwardRefExoticComponent<GridProps & import("react").RefAttributes<HTMLDivElement>>;

package/dist/grid.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef } from "react";
+import { alignment, justification, resolveGap, tracks } from "./layout.js";
+import { useThemeIfAvailable } from "./theme-provider.js";
+/** A predictable CSS Grid container with no visual appearance of its own. */
+export const Grid = forwardRef(function Grid({ align, columns, flow, gap, inline = false, justify, rows, style, ...properties }, ref) {
+    const theme = useThemeIfAvailable();
+    return _jsx("div", { ...properties, ref: ref, style: {
+            ...style,
+            display: inline ? "inline-grid" : "grid",
+            alignItems: alignment(align) ?? style?.alignItems,
+            gap: gap === undefined ? style?.gap : resolveGap(gap, theme),
+            gridAutoFlow: flow ?? style?.gridAutoFlow,
+            gridTemplateColumns: tracks(columns, "columns") ?? style?.gridTemplateColumns,
+            gridTemplateRows: tracks(rows, "rows") ?? style?.gridTemplateRows,
+            justifyContent: justification(justify) ?? style?.justifyContent
+        } });
+});

package/dist/icons/main.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Public entry point for icons that belong to the React UI visual language.
+ *
+ * Icons enter this surface only after their source, accessibility behavior,
+ * and customization contract have been established.
+ */
+export {};

package/dist/icons/main.js

@@ -0,0 +1,7 @@
+/**
+ * Public entry point for icons that belong to the React UI visual language.
+ *
+ * Icons enter this surface only after their source, accessibility behavior,
+ * and customization contract have been established.
+ */
+export {};

package/dist/layout.d.ts

@@ -0,0 +1,14 @@
+import type { CSSProperties } from "react";
+import type { ThemeProperties } from "@phreshos/core";
+import { type Spacing } from "./spacing.js";
+/** Cross-axis alignment shared by layout containers. */
+export type LayoutAlignment = "start" | "center" | "end" | "stretch" | "baseline";
+/** Main-axis distribution shared by layout containers. */
+export type LayoutJustification = "start" | "center" | "end" | "between" | "around" | "evenly";
+/** A spacing value applied between layout children. */
+export type LayoutGap = Spacing;
+export declare function alignment(value: LayoutAlignment | undefined): CSSProperties["alignItems"] | undefined;
+export declare function justification(value: LayoutJustification | undefined): CSSProperties["justifyContent"] | undefined;
+/** Resolves semantic spacing while preserving explicit CSS gap values. */
+export declare function resolveGap(value: LayoutGap | undefined, theme: ThemeProperties | null): CSSProperties["gap"];
+export declare function tracks(value: number | string | undefined, property: "columns" | "rows"): string | undefined;

package/dist/layout.js

@@ -0,0 +1,34 @@
+import { resolveSpacing } from "./spacing.js";
+const alignments = {
+    start: "flex-start",
+    center: "center",
+    end: "flex-end",
+    stretch: "stretch",
+    baseline: "baseline"
+};
+const justifications = {
+    start: "flex-start",
+    center: "center",
+    end: "flex-end",
+    between: "space-between",
+    around: "space-around",
+    evenly: "space-evenly"
+};
+export function alignment(value) {
+    return value === undefined ? undefined : alignments[value];
+}
+export function justification(value) {
+    return value === undefined ? undefined : justifications[value];
+}
+/** Resolves semantic spacing while preserving explicit CSS gap values. */
+export function resolveGap(value, theme) {
+    return resolveSpacing(value, theme);
+}
+export function tracks(value, property) {
+    if (value === undefined || typeof value === "string")
+        return value;
+    if (!Number.isInteger(value) || value < 1) {
+        throw new TypeError(`Grid ${property} must be a positive integer or CSS track expression`);
+    }
+    return `repeat(${value}, minmax(0, 1fr))`;
+}

package/dist/main.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Public entry point for the React UI library.
+ *
+ * Components enter this surface only after their implementation-independent
+ * behavior contract has been established by the package's tests.
+ */
+export { ThemeProvider, useTheme, type ThemeProviderProps } from "./theme-provider.js";
+export { Flex, type FlexProps } from "./flex.js";
+export { Grid, type GridProps } from "./grid.js";
+export { GlassSurface, type GlassSurfaceProps } from "./glass-surface.js";
+export { Button, type ButtonProps } from "./button.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";

package/dist/main.js

@@ -0,0 +1,13 @@
+/**
+ * Public entry point for the React UI library.
+ *
+ * Components enter this surface only after their implementation-independent
+ * behavior contract has been established by the package's tests.
+ */
+export { ThemeProvider, useTheme } from "./theme-provider.js";
+export { Flex } from "./flex.js";
+export { Grid } from "./grid.js";
+export { GlassSurface } from "./glass-surface.js";
+export { Button } from "./button.js";
+export { resolveRadius } from "./radius.js";
+export { resolveSpacing } from "./spacing.js";

package/dist/radius.d.ts

@@ -0,0 +1,10 @@
+import type { CSSProperties } from "react";
+import type { Shapeable, ThemeProperties } from "@phreshos/core";
+import { type ScaleLevel } from "@phreshos/core";
+/** A Theme-derived level, pixel value, or explicit CSS corner radius. */
+export type Radius = ScaleLevel | number | (string & {});
+/** Shared semantic corner-radius capability for React UI components. */
+export interface RadiusProps extends Shapeable<Radius> {
+}
+/** Resolves a Radius while preserving explicit CSS and pixel values. */
+export declare function resolveRadius(value: Radius | undefined, theme: ThemeProperties | null): CSSProperties["borderRadius"];

package/dist/radius.js

@@ -0,0 +1,9 @@
+import { isScaleLevel, scale } from "@phreshos/core";
+/** Resolves a Radius while preserving explicit CSS and pixel values. */
+export function resolveRadius(value, theme) {
+    if (!isScaleLevel(value))
+        return value;
+    if (!theme)
+        throw new Error("A semantic radius requires a ThemeProvider");
+    return scale(theme.radius, value);
+}

package/dist/spacing.d.ts

@@ -0,0 +1,8 @@
+import type { CSSProperties } from "react";
+import type { ThemeProperties } from "@phreshos/core";
+import { type ScaleLevel } from "@phreshos/core";
+/** A Theme-derived level, pixel value, or explicit CSS spacing value. */
+export type Spacing = ScaleLevel | number | (string & {});
+/** Resolves spacing while preserving explicit CSS and pixel values. */
+export declare function resolveSpacing(value: ScaleLevel, theme: ThemeProperties | null): number;
+export declare function resolveSpacing(value: Spacing | undefined, theme: ThemeProperties | null): CSSProperties["gap"];

package/dist/spacing.js

@@ -0,0 +1,8 @@
+import { isScaleLevel, scale } from "@phreshos/core";
+export function resolveSpacing(value, theme) {
+    if (!isScaleLevel(value))
+        return value;
+    if (!theme)
+        throw new Error("Semantic spacing requires a ThemeProvider");
+    return scale(theme.spacing, value);
+}

package/dist/theme-provider.d.ts

@@ -0,0 +1,29 @@
+import type { ReactNode } from "react";
+import type { ThemeProperties } from "@phreshos/core";
+/** Provides the nearest Theme value to one React subtree. */
+export declare function ThemeProvider({ children, theme }: ThemeProviderProps): import("react").JSX.Element;
+/** Returns the complete snapshot supplied by the nearest ThemeProvider. */
+export declare function useTheme(): Readonly<{
+    background: string;
+    foreground: string;
+    accent: string;
+    spacing: number;
+    radius: number;
+    glass: import("@phreshos/core").ThemeGlass;
+}>;
+/** Internal optional read used by primitives with both raw and themed values. */
+export declare function useThemeIfAvailable(): Readonly<{
+    background: string;
+    foreground: string;
+    accent: string;
+    spacing: number;
+    radius: number;
+    glass: import("@phreshos/core").ThemeGlass;
+}> | null;
+/** Properties accepted by ThemeProvider. */
+export interface ThemeProviderProps {
+    /** Content that receives this Theme instead of any outer Theme. */
+    readonly children: ReactNode;
+    /** Complete Theme value for this subtree. */
+    readonly theme: ThemeProperties;
+}

package/dist/theme-provider.js

@@ -0,0 +1,20 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext } from "react";
+const missing = Symbol("ThemeProvider");
+const ThemeContext = createContext(missing);
+/** Provides the nearest Theme value to one React subtree. */
+export function ThemeProvider({ children, theme }) {
+    return _jsx(ThemeContext.Provider, { value: theme, children: children });
+}
+/** Returns the complete snapshot supplied by the nearest ThemeProvider. */
+export function useTheme() {
+    const properties = useContext(ThemeContext);
+    if (properties === missing)
+        throw new Error("useTheme() requires a ThemeProvider");
+    return properties;
+}
+/** Internal optional read used by primitives with both raw and themed values. */
+export function useThemeIfAvailable() {
+    const properties = useContext(ThemeContext);
+    return properties === missing ? null : properties;
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@phreshos/react-ui",
+  "version": "0.1.0",
+  "description": "React components for coherent PhreshOS Program interfaces.",
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/main.js",
+  "types": "dist/main.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/main.d.ts",
+      "default": "./dist/main.js"
+    },
+    "./icons": {
+      "types": "./dist/icons/main.d.ts",
+      "default": "./dist/icons/main.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "author": "Zohayr SLILEH",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/PhreshOS/react-ui.git"
+  },
+  "bugs": {
+    "url": "https://github.com/PhreshOS/react-ui/issues"
+  },
+  "homepage": "https://github.com/PhreshOS/react-ui#readme",
+  "keywords": [
+    "phreshos",
+    "react",
+    "components",
+    "ui"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "packageManager": "bun@1.3.14",
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "check": "tsc --noEmit && tsc -p tsconfig.test.json",
+    "test": "vitest run --environment jsdom",
+    "build": "node --run clean && tsc --noEmit false --outDir dist --rootDir source",
+    "verify:package": "node scripts/verify-package.mjs",
+    "verify": "node --run check && node --run test && node --run build && node --run verify:package",
+    "prepack": "node --run test && node --run build"
+  },
+  "peerDependencies": {
+    "@phreshos/core": "^0.1.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0"
+  },
+  "dependencies": {
+    "react-aria-components": "^1.20.0"
+  },
+  "devDependencies": {
+    "@base-ui/react": "^1.7.0",
+    "@phreshos/core": "^0.1.1",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.2.18",
+    "@types/react-dom": "^19.2.4",
+    "jsdom": "^30.0.1",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.1"
+  }
+}