@av-pi-studio/ui-library 0.0.0-stage → 0.0.115

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+Breaking changes get a dated entry here. Versions move in lockstep with the other
+`@av-pi-studio/*` packages (0.0.x).
+
+## 2026-11-14 — 0.0.115 (initial release)
+
+Extracted from `@av-pi-studio/web-client`.
+
+### Public surface
+
+- `@av-pi-studio/ui-library` — components (`Button`, `IconButton`, `Dialog`, `Menu*`, `Popover*`,
+  `Panel`, `Select`, `Switch`, `Checkbox`, `TextInput`, `TextArea`, `Icon`, `Spinner`, `StatusDot`,
+  `StatusBadge`, `Avatar`, `EmptyState`, …), `ThemeBoundary` (`store`, `storageKey` default
+  `pi-studio-appearance`, `brandConfig`), `useAppearance`, `ToastViewport`, `Announcer`,
+  `useToastStore`, `speak`, `localStorageKvStore`.
+- `/theme` (incl. `findTokenProblems`), `/ui`, `/brand`, `/breakpoints` subpath entries.
+- CSS entries: `/styles.css` (tokens + component styles, `piui-` class prefix) and `/reset.css`.
+  Import library CSS before your own.
+- Peer dependencies: `react`, `react-dom` ^19. Targets Vite web SPAs and Electron renderers
+  (no SSR, no React Native). Dev-only console warnings rely on the consumer's bundler folding
+  `process.env.NODE_ENV`.
+- One `ThemeBoundary` per document; one copy of the library per app (toast/announcer stores are
+  module singletons).

package/README.md

@@ -1,3 +1,138 @@
-# Temporary Holding Version
+# @av-pi-studio/ui-library
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Reusable React UI primitives, theme system and global styles for Pi-Studio client apps.
+Targets Vite web SPAs and Electron renderers. No SSR, no React Native.
+
+## Install
+
+```sh
+npm i @av-pi-studio/ui-library react react-dom
+```
+
+Peer dependencies: `react` and `react-dom` `^19`. Radix (dialog, dropdown-menu, popover),
+`lucide-react`, `clsx`, `zustand` and `zod` are regular dependencies.
+
+## Quickstart
+
+Import the library CSS **before your own CSS**. Library class names carry the `piui-` prefix and
+design tokens are `--pi-*` CSS variables. `styles.css` is required; `reset.css` is an optional
+global reset.
+
+<!-- smoke:main.tsx -->
+```tsx
+import "@av-pi-studio/ui-library/reset.css";
+import "@av-pi-studio/ui-library/styles.css";
+
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import {
+  Announcer,
+  Button,
+  Switch,
+  ThemeBoundary,
+  ToastViewport,
+  useToastStore,
+} from "@av-pi-studio/ui-library";
+
+function App() {
+  const show = useToastStore((s) => s.show);
+  return (
+    <main style={{ padding: 16, display: "grid", gap: 12, justifyItems: "start" }}>
+      <Button id="smoke-button" onClick={() => show("Hello from ui-library")}>
+        Show toast
+      </Button>
+      <Switch checked onCheckedChange={() => {}} aria-label="Example switch" />
+    </main>
+  );
+}
+
+createRoot(document.getElementById("root")!).render(
+  <StrictMode>
+    <ThemeBoundary>
+      <App />
+      <ToastViewport />
+      <Announcer />
+    </ThemeBoundary>
+  </StrictMode>,
+);
+```
+<!-- /smoke:main.tsx -->
+
+- `ThemeBoundary` applies the theme (light/dark/system) to the document and provides
+  `useAppearance()`. Props (all optional):
+  - `storageKey` — key the appearance JSON is stored under (default `pi-studio-appearance`).
+  - `store` — a custom key-value store instead of `localStorage` (see `localStorageKvStore`).
+  - `brandConfig` — e.g. `{ colors: { accent: "#7c3aed" } }` to re-theme the accent.
+- `ToastViewport` and `Announcer` are **not** mounted automatically; mount them once, inside
+  `ThemeBoundary`. Fire toasts with `useToastStore.getState().show("text")` (also `copied`,
+  `error`) and screen-reader announcements with `speak()`.
+
+### Switching the theme
+
+`useAppearanceControls()` (root entry, under `ThemeBoundary`) returns `{ setMode, updateSettings }`;
+changes are applied to the document and persisted. `useAppearance()` reads the current state.
+
+```tsx
+import { Button, THEME_NAMES, useAppearance, useAppearanceControls } from "@av-pi-studio/ui-library";
+
+function ThemeSwitcher() {
+  const { mode } = useAppearance();
+  const { setMode } = useAppearanceControls();
+  return (
+    <>
+      {(["system", ...THEME_NAMES] as const).map((name) => (
+        <Button key={name} variant={name === mode ? "default" : "outline"} onClick={() => setMode(name)}>
+          {name}
+        </Button>
+      ))}
+    </>
+  );
+}
+```
+
+## Components
+
+`Button`, `IconButton`, `Dialog`, `Menu*`, `Popover*`, `Panel`, `Surface`, `Select`, `Combobox`,
+`Switch`, `Checkbox`, `TextInput`, `TextArea`, `Icon`, `Spinner`, `StatusDot`, `StatusBadge`,
+`Avatar`, `EmptyState`, `ScrollArea`, `Divider`, `ResizeHandle`, `ShortcutHint`. Types ship
+alongside (`ButtonProps`, ...).
+
+`Menu*` is half of a menu: `MenuContent`, `MenuItem`, `MenuGroup`, `MenuSeparator` and
+`MenuCursorTrigger` ship, but `Root`/`Trigger` do not — install `@radix-ui/react-dropdown-menu`
+yourself and import `DropdownMenu.Root`/`.Trigger` from it.
+
+## Entry points
+
+Only these resolve (the `exports` map); deep imports such as `.../src/...` or `.../dist/...` are
+rejected.
+
+| Specifier | Contents |
+| --- | --- |
+| `@av-pi-studio/ui-library` | Everything: components, `ThemeBoundary`, hooks, stores, and the subpaths below |
+| `.../theme` | Theme/appearance logic and token helpers (`findTokenProblems`), React-free |
+| `.../ui` | Pure UI logic (button/toast helpers), React-free |
+| `.../brand` | `BrandConfig` schema and accent derivation, React-free |
+| `.../breakpoints` | Breakpoint constants, React-free |
+| `.../styles.css` | Required global styles and `--pi-*` tokens |
+| `.../reset.css` | Optional global reset |
+
+## Constraints
+
+- One `ThemeBoundary` per document.
+- One copy of the package per app: the toast and announcer stores are module singletons.
+- React `^19`.
+- A bundler (Vite, etc.) is required: dev-only warnings read `process.env.NODE_ENV`, which the
+  bundler folds. Loading the ESM unbundled would throw `ReferenceError: process` in dev.
+- No SSR, no React Native.
+
+## Dev-only warnings
+
+In development builds the library logs a console warning when `styles.css` is not loaded, when a
+second `ThemeBoundary` mounts, or when `brandConfig` is invalid. They are stripped from
+production bundles.
+
+## Verifying a release
+
+`bash packages/ui-library/scripts/pack-smoke.sh` packs the library, installs the tarball into a
+scratch Vite app outside the repo using the Quickstart snippet above, and checks types, build,
+`exports` and CSS. `KEEP_DIR=1` keeps the scratch dir.

package/dist/brand/config.d.ts

@@ -0,0 +1,125 @@
+import { z } from "zod";
+export declare const BrandConfigSchema: z.ZodObject<{
+    productName: z.ZodOptional<z.ZodString>;
+    shortName: z.ZodOptional<z.ZodString>;
+    tagline: z.ZodOptional<z.ZodString>;
+    colors: z.ZodObject<{
+        accent: z.ZodEffects<z.ZodString, string, string>;
+        accentBright: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        accentForeground: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+        swatch: z.ZodOptional<z.ZodEffects<z.ZodString, string, string>>;
+    }, "strip", z.ZodTypeAny, {
+        accent: string;
+        accentBright?: string | undefined;
+        accentForeground?: string | undefined;
+        swatch?: string | undefined;
+    }, {
+        accent: string;
+        accentBright?: string | undefined;
+        accentForeground?: string | undefined;
+        swatch?: string | undefined;
+    }>;
+    assets: z.ZodOptional<z.ZodObject<{
+        logoLight: z.ZodString;
+        logoDark: z.ZodString;
+        logoMark: z.ZodOptional<z.ZodString>;
+        icon: z.ZodString;
+        splash: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        logoLight: string;
+        logoDark: string;
+        logoMark?: string | undefined;
+        icon: string;
+        splash?: string | undefined;
+    }, {
+        logoLight: string;
+        logoDark: string;
+        logoMark?: string | undefined;
+        icon: string;
+        splash?: string | undefined;
+    }>>;
+    links: z.ZodOptional<z.ZodObject<{
+        docs: z.ZodOptional<z.ZodString>;
+        support: z.ZodOptional<z.ZodString>;
+        issues: z.ZodOptional<z.ZodString>;
+        website: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        docs?: string | undefined;
+        support?: string | undefined;
+        issues?: string | undefined;
+        website?: string | undefined;
+    }, {
+        docs?: string | undefined;
+        support?: string | undefined;
+        issues?: string | undefined;
+        website?: string | undefined;
+    }>>;
+    legal: z.ZodOptional<z.ZodObject<{
+        copyright: z.ZodOptional<z.ZodString>;
+        companyName: z.ZodOptional<z.ZodString>;
+    }, "strip", z.ZodTypeAny, {
+        copyright?: string | undefined;
+        companyName?: string | undefined;
+    }, {
+        copyright?: string | undefined;
+        companyName?: string | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    productName?: string | undefined;
+    shortName?: string | undefined;
+    tagline?: string | undefined;
+    colors: {
+        accent: string;
+        accentBright?: string | undefined;
+        accentForeground?: string | undefined;
+        swatch?: string | undefined;
+    };
+    assets?: {
+        logoLight: string;
+        logoDark: string;
+        logoMark?: string | undefined;
+        icon: string;
+        splash?: string | undefined;
+    } | undefined;
+    links?: {
+        docs?: string | undefined;
+        support?: string | undefined;
+        issues?: string | undefined;
+        website?: string | undefined;
+    } | undefined;
+    legal?: {
+        copyright?: string | undefined;
+        companyName?: string | undefined;
+    } | undefined;
+}, {
+    productName?: string | undefined;
+    shortName?: string | undefined;
+    tagline?: string | undefined;
+    colors: {
+        accent: string;
+        accentBright?: string | undefined;
+        accentForeground?: string | undefined;
+        swatch?: string | undefined;
+    };
+    assets?: {
+        logoLight: string;
+        logoDark: string;
+        logoMark?: string | undefined;
+        icon: string;
+        splash?: string | undefined;
+    } | undefined;
+    links?: {
+        docs?: string | undefined;
+        support?: string | undefined;
+        issues?: string | undefined;
+        website?: string | undefined;
+    } | undefined;
+    legal?: {
+        copyright?: string | undefined;
+        companyName?: string | undefined;
+    } | undefined;
+}>;
+export type BrandConfig = z.infer<typeof BrandConfigSchema>;
+export type ResolvedBrandColors = Required<Pick<BrandConfig["colors"], "accent" | "accentBright" | "accentForeground" | "swatch">>;
+export declare function resolveAccentColors(colors: BrandConfig["colors"]): ResolvedBrandColors;
+//# sourceMappingURL=config.d.ts.map

package/dist/brand/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./config.js";
+export * from "./theme-injection.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/brand/index.js

@@ -0,0 +1,6 @@
+import { B as a, i as c, r as n } from "../chunks/theme-injection-BHAAhBYz.js";
+export {
+  a as BrandConfigSchema,
+  c as injectBrandAccent,
+  n as resolveAccentColors
+};

package/dist/brand/theme-injection.d.ts

@@ -0,0 +1,9 @@
+import { type ResolvedBrandColors } from "./config.js";
+import { type Theme } from "../theme/theme.js";
+/**
+ * Build a branded copy of a theme by replacing only the accent family tokens
+ * and swatch. All other tokens (surfaces, semantic status, syntax, terminal)
+ * remain unchanged — only the accent family is brand-overridable in this version.
+ */
+export declare function injectBrandAccent(theme: Theme, resolved: ResolvedBrandColors): Theme;
+//# sourceMappingURL=theme-injection.d.ts.map

package/dist/breakpoints.d.ts

@@ -0,0 +1,34 @@
+export declare const breakpoints: {
+    readonly xs: 0;
+    readonly sm: 576;
+    readonly md: 768;
+    readonly lg: 992;
+    readonly xl: 1200;
+};
+export type Breakpoint = keyof typeof breakpoints;
+/** Returns the active breakpoint name for a given container/window width. */
+export declare function getBreakpoint(width: number): Breakpoint;
+/**
+ * Compact form factor = xs or sm (phone-class layout).
+ * This is the single source of truth for "phone-class layout" —
+ * never use Platform.OS as a layout proxy.
+ */
+export declare function isCompactFormFactor(width: number): boolean;
+export declare const HEADER_INNER_HEIGHT = 48;
+export declare const HEADER_INNER_HEIGHT_MOBILE = 56;
+export declare const HEADER_TOP_PADDING_MOBILE = 8;
+export declare const WORKSPACE_SECONDARY_HEADER_HEIGHT = 36;
+export declare const FOOTER_HEIGHT = 75;
+export declare const MAX_CONTENT_WIDTH = 820;
+export declare const COMPACT_FORM_FACTOR_WIDTH = 500;
+export declare const WINDOW_CHROME: {
+    readonly macOS: {
+        readonly width: 78;
+        readonly height: 45;
+    };
+    readonly windowsLinux: {
+        readonly width: 140;
+        readonly height: 48;
+    };
+};
+//# sourceMappingURL=breakpoints.d.ts.map

package/dist/breakpoints.js

@@ -0,0 +1,32 @@
+const n = {
+  xs: 0,
+  sm: 576,
+  md: 768,
+  lg: 992,
+  xl: 1200
+};
+function s(t) {
+  return t >= n.xl ? "xl" : t >= n.lg ? "lg" : t >= n.md ? "md" : t >= n.sm ? "sm" : "xs";
+}
+function o(t) {
+  const E = s(t);
+  return E === "xs" || E === "sm";
+}
+const _ = 48, r = 56, c = 8, H = 36, O = 75, e = 820, i = 500, I = {
+  macOS: { width: 78, height: 45 },
+  // traffic-light reserve
+  windowsLinux: { width: 140, height: 48 }
+};
+export {
+  i as COMPACT_FORM_FACTOR_WIDTH,
+  O as FOOTER_HEIGHT,
+  _ as HEADER_INNER_HEIGHT,
+  r as HEADER_INNER_HEIGHT_MOBILE,
+  c as HEADER_TOP_PADDING_MOBILE,
+  e as MAX_CONTENT_WIDTH,
+  I as WINDOW_CHROME,
+  H as WORKSPACE_SECONDARY_HEADER_HEIGHT,
+  n as breakpoints,
+  s as getBreakpoint,
+  o as isCompactFormFactor
+};

package/dist/chunks/theme-injection-BHAAhBYz.js

@@ -0,0 +1,103 @@
+import { z as o } from "zod";
+function l(n) {
+  const t = n.trim().replace(/^#/, ""), a = t.length === 3 ? t.split("").map((r) => r + r).join("") : t;
+  if (a.length !== 6 || /[^0-9a-fA-F]/.test(a))
+    throw new Error(`Invalid hex color: ${n}`);
+  return {
+    r: parseInt(a.slice(0, 2), 16),
+    g: parseInt(a.slice(2, 4), 16),
+    b: parseInt(a.slice(4, 6), 16)
+  };
+}
+function h(n) {
+  return Math.max(0, Math.min(255, Math.round(n)));
+}
+function u({ r: n, g: t, b: a }) {
+  const r = (c) => h(c).toString(16).padStart(2, "0");
+  return `#${r(n)}${r(t)}${r(a)}`;
+}
+function p(n) {
+  const { r: t, g: a, b: r } = l(n), c = (e) => {
+    const g = e / 255;
+    return g <= 0.03928 ? g / 12.92 : ((g + 0.055) / 1.055) ** 2.4;
+  };
+  return 0.2126 * c(t) + 0.7152 * c(a) + 0.0722 * c(r);
+}
+function m(n, t = "#18181b", a = "#ffffff") {
+  return p(n) > 0.45 ? t : a;
+}
+function b(n, t) {
+  const { r: a, g: r, b: c } = l(n), e = Math.max(0, Math.min(1, t));
+  return u({
+    r: a + (255 - a) * e,
+    g: r + (255 - r) * e,
+    b: c + (255 - c) * e
+  });
+}
+function F(n, t) {
+  const { r: a, g: r, b: c } = l(n), e = Math.max(0, Math.min(1, t));
+  return u({ r: a * (1 - e), g: r * (1 - e), b: c * (1 - e) });
+}
+function i(n) {
+  const t = n.trim().replace(/^#/, "");
+  return (t.length === 3 || t.length === 6) && !/[^0-9a-fA-F]/.test(t);
+}
+const s = o.string().min(1, "Asset path must not be empty"), f = o.object({
+  accent: o.string().refine(i, { message: "accent must be a valid #rrggbb hex color" }),
+  accentBright: o.string().refine(i, { message: "accentBright must be a valid #rrggbb hex color" }).optional(),
+  accentForeground: o.string().refine(i, { message: "accentForeground must be a valid #rrggbb hex color" }).optional(),
+  swatch: o.string().refine(i, { message: "swatch must be a valid #rrggbb hex color" }).optional()
+}), d = o.object({
+  logoLight: s,
+  logoDark: s,
+  logoMark: s.optional(),
+  icon: s,
+  splash: s.optional()
+}), B = o.object({
+  docs: o.string().url().optional(),
+  support: o.string().url().optional(),
+  issues: o.string().url().optional(),
+  website: o.string().url().optional()
+}).optional(), x = o.object({
+  copyright: o.string().optional(),
+  companyName: o.string().optional()
+}).optional(), M = o.object({
+  productName: o.string().min(1, "productName must not be empty").optional(),
+  shortName: o.string().optional(),
+  tagline: o.string().optional(),
+  colors: f,
+  assets: d.optional(),
+  links: B,
+  legal: x
+});
+function S(n) {
+  const t = n.accent, a = n.accentBright ?? b(t, 0.35), r = n.accentForeground ?? m(t), c = n.swatch ?? t;
+  return { accent: t, accentBright: a, accentForeground: r, swatch: c };
+}
+function j(n, t) {
+  return {
+    ...n,
+    colors: {
+      ...n.colors,
+      accent: t.accent,
+      accentBright: t.accentBright,
+      accentForeground: t.accentForeground,
+      // Legacy aliases that mirror accent.
+      primary: t.accent,
+      ring: t.accent
+    },
+    swatch: t.swatch
+  };
+}
+export {
+  M as B,
+  i as a,
+  p as b,
+  m as c,
+  F as d,
+  u as e,
+  l as h,
+  j as i,
+  b as l,
+  S as r
+};