@calliopelabs/ui 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Calliope Labs Inc
+
+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

@@ -1,3 +1,333 @@
-# Temporary Holding Version
+# @calliopelabs/ui
 
-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.
+The shared operator UI of Calliope AI: the app shell, navigation, page frame, data table and list patterns, status colours, design tokens and appearance settings that Astrolift AI and Zentinelle AI both run on. Extracted from the Astrolift AI frontend and generalized with a per-product config, so each console keeps its own name, accent, sidebar colour and navigation while sharing everything else.
+
+It is built Storybook first: every component and every screen pattern is built and reviewed in the catalog before an app uses it. The catalog is published at **https://calliopeai.github.io/calliope-ui/**.
+
+- React 19 and TypeScript, shipped as per-file ESM with types. No Next-only APIs: the app hands the package its link component.
+- Tailwind CSS 4: the theme tokens as CSS, plus a preset.
+- Radix underneath the overlays and menus; lucide icons.
+
+## Install
+
+```sh
+npm i @calliopelabs/ui
+```
+
+Peer dependencies: `react` and `react-dom` 19, and `tailwindcss` 4 for styling.
+
+## Styles
+
+In the app's global stylesheet, after Tailwind:
+
+```css
+@import "tailwindcss";
+@import "@calliopelabs/ui/preset.css";
+```
+
+The preset brings the theme tokens (`@calliopelabs/ui/theme.css`), maps them onto Tailwind's colour, radius, font, type and motion scales (`bg-primary`, `text-success-fg`, `bg-sidebar`, `rounded-lg`, `text-2xs`, `font-mono`), adds the family's base layer, and points Tailwind at the package's components so their classes are generated with the app's. `dark:` follows the ground (`data-mode` on `<html>`), not the operating system.
+
+The fonts are the app's to load: IBM Plex Sans for the interface, IBM Plex Mono for anything technical, DM Sans for headings. Set `--font-plex-sans`, `--font-plex-mono` and `--font-dm-sans` (with `next/font`, as their `variable`), or install the families under those names.
+
+A non-Tailwind app can import `@calliopelabs/ui/theme.css` alone for the CSS variables.
+
+## Define the product
+
+A product is a brand plus a navigation model. The two consoles' brands ship with the package; each app adds its navigation:
+
+```ts
+// lib/product.ts
+import { astroliftBrand, defineProduct, type NavModel } from "@calliopelabs/ui";
+import { BotIcon, HomeIcon, PackageIcon, RocketIcon } from "lucide-react";
+
+const NAV: NavModel = [
+  {
+    key: "home",
+    label: "Home",
+    icon: HomeIcon,
+    flat: true,
+    groups: [{ functions: [{ key: "home", label: "Home", href: "/dashboard", icon: HomeIcon }] }],
+  },
+  {
+    key: "apps",
+    label: "Apps",
+    icon: PackageIcon,
+    groups: [
+      {
+        functions: [
+          { key: "apps", label: "Apps", href: "/apps", icon: PackageIcon, requires: "apps" },
+          {
+            key: "deployments",
+            label: "Deployments",
+            href: "/deployments",
+            icon: RocketIcon,
+            requires: "apps",
+          },
+        ],
+      },
+    ],
+  },
+  // agents, admin, ...
+];
+
+export const astrolift = defineProduct({ ...astroliftBrand, nav: NAV });
+```
+
+Astrolift AI: leaf green on the deep planet green sidebar (`#04231a`), all six grounds, graphite by default (mist when the system runs light), and its eight named themes.
+
+Zentinelle AI: teal (`#37efed`, `#0d7470` on light grounds) on the navy sidebar (`#0b0b19`), a true black ground by default, the family accents beside teal, and no emerald ground. Its seven areas gate rows by role:
+
+```ts
+import { defineProduct, zentinelleBrand, type NavModel } from "@calliopelabs/ui";
+import { LayoutDashboardIcon, ScaleIcon, ShieldCheckIcon } from "lucide-react";
+
+const NAV: NavModel = [
+  {
+    key: "overview",
+    label: "Overview",
+    icon: LayoutDashboardIcon,
+    flat: true,
+    groups: [{ functions: [{ key: "overview", label: "Overview", href: "/dashboard" }] }],
+  },
+  {
+    key: "policies",
+    label: "Policies",
+    icon: ShieldCheckIcon,
+    groups: [{ functions: [{ key: "policies", label: "Policies", href: "/policies" }] }],
+  },
+  {
+    key: "risk",
+    label: "Risk & compliance",
+    icon: ScaleIcon,
+    groups: [
+      {
+        functions: [
+          { key: "risks", label: "Risks", href: "/risks" },
+          { key: "evidence", label: "Evidence", href: "/evidence", requires: "admin" },
+        ],
+      },
+    ],
+  },
+  // agents, activity, models & usage, settings
+];
+
+export const zentinelle = defineProduct({ ...zentinelleBrand, nav: NAV });
+```
+
+`defineProduct` validates the config and throws on anything that would paint wrong: a colour that is not lowercase `#rrggbb`, a default ground the product does not offer, a brand accent key the family already uses.
+
+## Wire the shell
+
+The example is a Next.js App Router app; any React app works the same way with its own router's link.
+
+The root layout renders the appearance script in `<head>`, so the stored ground, accent, density and corners are on `<html>` before first paint:
+
+```tsx
+// app/layout.tsx (a Server Component)
+import { AppearanceScript } from "@calliopelabs/ui";
+
+import { astrolift } from "@/lib/product";
+import { Providers } from "./providers";
+import "./globals.css";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    // The script stamps <html> before React hydrates.
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <AppearanceScript product={astrolift} />
+      </head>
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}
+```
+
+The providers live in a client module, because the product holds component references (its navigation icons) that cannot cross from a Server Component into a Client Component as props:
+
+```tsx
+// app/providers.tsx
+"use client";
+
+import { AppearanceProvider, UIProvider } from "@calliopelabs/ui";
+import Link from "next/link";
+
+import { astrolift } from "@/lib/product";
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <UIProvider link={Link}>
+      <AppearanceProvider product={astrolift}>{children}</AppearanceProvider>
+    </UIProvider>
+  );
+}
+```
+
+The signed-in layout draws the shell. Everything it shows comes from the app; the components are pure:
+
+```tsx
+// app/(app)/shell.tsx
+"use client";
+
+import {
+  AppShell,
+  BrandMark,
+  RailPanel,
+  RailTree,
+  Sidebar,
+  UserMenu,
+  activeFor,
+  useRailState,
+  visibleNav,
+} from "@calliopelabs/ui";
+import { usePathname } from "next/navigation";
+import * as React from "react";
+
+import { astrolift } from "@/lib/product";
+
+export function Shell({ children, can, projects, me }: ShellProps) {
+  const pathname = usePathname() ?? "/";
+  const nav = React.useMemo(() => visibleNav(astrolift.nav, can), [can]);
+  const [sidebarCollapsed, setSidebarCollapsed] = useRailState("astrolift.shell.main");
+  const [railCollapsed, setRailCollapsed] = useRailState(
+    "astrolift.shell.projects",
+    () => window.innerWidth < 1280
+  );
+
+  return (
+    <AppShell
+      onToggleSidebar={() => setSidebarCollapsed(!sidebarCollapsed)}
+      onToggleRightRail={() => setRailCollapsed(!railCollapsed)}
+      sidebar={
+        <Sidebar
+          nav={nav}
+          active={activeFor(nav, pathname)}
+          collapsed={sidebarCollapsed}
+          onCollapsedChange={setSidebarCollapsed}
+          header={<BrandMark href="/dashboard" mark={<img src="/logo.svg" alt="" />} />}
+          headerCollapsed={
+            <BrandMark href="/dashboard" mark={<img src="/logo.svg" alt="" />} collapsed />
+          }
+          footer={<UserMenu name={me.name} email={me.email} onSignOut={signOut} />}
+        />
+      }
+      rightRail={
+        <RailPanel
+          label="Projects"
+          title={me.orgName}
+          collapsed={railCollapsed}
+          onCollapsedChange={setRailCollapsed}
+        >
+          <RailTree
+            label="My projects"
+            groups={projects}
+            activeHref={pathname}
+            emptyText="You are not in a project yet."
+          />
+        </RailPanel>
+      }
+      rightRailLabel="Projects"
+    >
+      {children}
+    </AppShell>
+  );
+}
+```
+
+`[` folds the sidebar and `]` the right rail. Below `md` both rails open as drawers from a top bar. Zentinelle docks its assistant in the same slot: a `RailPanel` with `collapsedMode="hidden"`, `width` from `useRailWidth(key, 400, { min: 320, max: 560 })` with `onWidthChange`, and `expanded` with `onExpandedChange` for the full-width view. Keep the conversation in state above the shell: on narrow screens a rail renders in its drawer as well as its hidden desktop place.
+
+A page is a `PageFrame`: breadcrumbs from the navigation model (`areaSwitcher`), the title row with its status, context and one primary action, at most one row of tabs, then the body.
+
+```tsx
+<PageFrame
+  crumbs={[areaSwitcher(nav, "apps", "deployments")]}
+  title="Deployments"
+  primaryAction={<Button size="sm">New deployment</Button>}
+  tabs={views}
+  tabsLabel="Views"
+>
+  <DataTable
+    label="Deployments"
+    controller={table}
+    columns={columns}
+    getRowId={(d) => d.id}
+    rowHref={(d) => `/deployments/${d.id}`}
+    empty={{ title: "No deployments yet", actionHref: "/apps", actionLabel: "Deploy an app" }}
+  />
+</PageFrame>
+```
+
+The package fetches nothing. `DataTable` reads a `TableController`: rows, state, paging, search and sort, all done by the server. An app implements it over its own data layer; Astrolift's `useCursorTable` already returns one.
+
+## Appearance
+
+The person sets four axes, per product: the **ground** (black, charcoal, graphite, emerald, paper, mist; it decides light or dark), the **accent** (the product's own, a family accent, or any colour that stands 3:1 off the ground), the **density** (`compact` hairline rows or boxed `cards`) and the **corners** (0, 2, 4 or 10 px). `AppearancePicker` is the settings UI for all four.
+
+- Precedence: a locked org theme, then the person's choice, then the org default, then the product default. Until someone picks a ground, light or dark follows the system.
+- An org policy that arrives after sign-in goes in through `useAppearance().setPolicy`. An app that keeps the preference on its server passes `onChange` and hands the server's copy back through `applyServerAppearance`.
+- Status colours never move: lime ok, amber warn, red error, green info, whatever the accent or ground. Tests hold the generated CSS to that, and check WCAG contrast for every ground with every accent.
+
+## Copy and languages
+
+Every string the package renders is English by default and overridable, one group at a time:
+
+```tsx
+<UIProvider link={Link} messages={{ table: { retry: t("retry"), loadFailed: (label) => t("loadFailed", { label }) } }}>
+```
+
+Messages that take a value are functions, so the app's own i18n formats them. Navigation labels come from the model; `localizeNav(nav, translate)` maps them through a catalog.
+
+## Develop
+
+Node 24 (`.nvmrc`).
+
+| Command                                                     | Does                                                                             |
+| ----------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `npm run storybook`                                         | The catalog, on port 6006                                                        |
+| `npm test`                                                  | Every test, including one that renders every story and runs the a11y addon on it |
+| `npm run lint`, `npm run typecheck`, `npm run format:check` | The gates CI runs                                                                |
+| `npm run theme`                                             | Regenerates `src/styles/theme.css` after a change to `src/theme/tokens.ts`       |
+| `npm run build`, `npm run pack:check`                       | Builds `dist/` and checks the package a consumer receives                        |
+| `npm run build-storybook`                                   | The static catalog                                                               |
+
+Conventions for contributors and agents are in [`bootstrap.md`](bootstrap.md).
+
+## Releasing
+
+`publish.yml` publishes to npm as `@calliopelabs/ui` through npm trusted publishing: there is no npm token, the job's GitHub OIDC identity stands in for one, and the package carries provenance. It runs when a GitHub release is published, or by hand on an existing version tag; it refuses a branch. Before anything is published, `release-checks.yml` checks that the tag names the `package.json` version and points at the commit being built, then runs every CI gate on that commit. A prerelease version (`0.2.0-alpha.1`) goes out under the `alpha` dist-tag, and a version already on npm is left alone. Nothing in the workflows bumps a version or creates a tag.
+
+### The first publish
+
+A brand new package cannot use trusted publishing: npm attaches a trusted publisher to a package that already exists. So `0.1.0` is published once by hand, by an npm account in the `calliopelabs` organization with two-factor authentication on. In a fresh clone of `main`, tag it (a tag push starts no workflow) and publish that clean checkout of the tag:
+
+```sh
+git clone https://github.com/calliopeai/calliope-ui.git calliope-ui-v0.1.0 && cd calliope-ui-v0.1.0
+git tag v0.1.0 && git push origin v0.1.0
+nvm use
+npm login
+npm ci && npm run build && npm publish --access public
+```
+
+Then add the trusted publisher on npmjs.com, in the package's settings under Trusted publishing: GitHub Actions, organization or user `calliopeai`, repository `calliope-ui`, workflow filename `publish.yml`, no environment. Under allowed actions, allow `npm publish`: a configuration created after 2026-09-03 allows only staged publishing (`npm stage publish`) by default, and this workflow publishes directly. The same from the command line (npm 11.15 or later):
+
+```sh
+npm trust github @calliopelabs/ui --repo calliopeai/calliope-ui --file publish.yml --allow-publish
+```
+
+A new trusted publisher expires unless a publish through it succeeds within 2 days, so add it shortly before the next release; if it expired, delete it and add it again. From then on, a published GitHub release publishes automatically. Once a release has gone out that way, setting Publishing access to "Require two-factor authentication and disallow tokens" turns token publishing off.
+
+### Every release after
+
+Bump the version in a pull request (`npm version 0.2.0 --no-git-tag-version` changes `package.json` and `package-lock.json`). Once it merges, publish a release whose tag names that version:
+
+```sh
+gh release create v0.2.0 --target main --generate-notes
+```
+
+Add `--prerelease` for a prerelease version. A failed run can be re-run, or dispatched again on the tag with `gh workflow run publish.yml --ref v0.2.0`.
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

package/dist/appearance/AppearancePicker.d.ts

@@ -0,0 +1,10 @@
+import * as React from "react";
+/**
+ * The person's appearance for the product in context: theme presets, accent
+ * (including any colour that stands 3:1 off the ground), ground, density and
+ * corners. Read-only while the org locks the theme. Choosing a ground also
+ * chooses light or dark. Status colours are not offered: they never change.
+ */
+export declare function AppearancePicker({ className }: {
+    className?: string;
+}): React.JSX.Element;

package/dist/appearance/AppearancePicker.js

@@ -0,0 +1,75 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { LockIcon } from "lucide-react";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+import { Button } from "../primitives/Button.js";
+import { useUI } from "../provider/UIProvider.js";
+import { MIN_NON_TEXT_CONTRAST } from "../theme/contrast.js";
+import { DENSITY_KEYS, GROUNDS, SURFACES } from "../theme/tokens.js";
+import { accentContrast, isCustomAccent, modeFor, parseCustomAccent, } from "./appearance.js";
+import { useAppearance } from "./AppearanceProvider.js";
+import { CORNERS } from "./product.js";
+/** The sidebar a ground paints for this product, for the theme previews. */
+function sidebarFor(product, ground) {
+    const sidebar = SURFACES[ground].sidebar;
+    return sidebar === "brand" ? product.sidebar : sidebar;
+}
+function accentOn(accent, ground) {
+    if (!accent)
+        return "transparent";
+    return modeFor(ground) === "dark" ? accent.dark : accent.light;
+}
+/** A miniature of the chrome: sidebar, ground and accent, in the exact colours. */
+function ThemePreview({ product, ground, accent, }) {
+    return (_jsxs("span", { "aria-hidden": true, className: "flex h-9 overflow-hidden rounded-lg border", style: { background: SURFACES[ground].background }, children: [_jsx("span", { style: { background: sidebarFor(product, ground), width: "26%" } }), _jsx("span", { className: "flex flex-1 items-center px-1.5", children: _jsx("span", { style: { background: accentOn(accent, ground), height: 4, width: "58%", borderRadius: 1 } }) })] }));
+}
+const choice = "relative flex cursor-pointer items-center gap-2 rounded-lg border px-2.5 py-1.5 text-sm transition-colors hover:border-primary has-checked:border-primary has-checked:ring-1 has-checked:ring-primary has-disabled:cursor-not-allowed has-disabled:opacity-60 has-focus-visible:ring-2 has-focus-visible:ring-ring";
+function Choice({ name, checked, disabled, onSelect, className, children, }) {
+    return (_jsxs("label", { className: cn(choice, className), children: [_jsx("input", { type: "radio", name: name, checked: checked, disabled: disabled, onChange: onSelect, className: "sr-only" }), children] }));
+}
+function Group({ legend, children }) {
+    return (_jsxs("fieldset", { className: "flex min-w-0 flex-col gap-2", children: [_jsx("legend", { className: "mb-2 text-2xs font-semibold tracking-[0.08em] text-muted-foreground uppercase", children: legend }), children] }));
+}
+/**
+ * The person's appearance for the product in context: theme presets, accent
+ * (including any colour that stands 3:1 off the ground), ground, density and
+ * corners. Read-only while the org locks the theme. Choosing a ground also
+ * chooses light or dark. Status colours are not offered: they never change.
+ */
+export function AppearancePicker({ className }) {
+    const { product, appearance, locked, setAppearance, reset } = useAppearance();
+    const { messages } = useUI();
+    const t = messages.appearance;
+    const id = React.useId();
+    const accents = product.accents;
+    const activeTheme = product.themes.find((th) => th.ground === appearance.ground && th.accent === appearance.accent);
+    return (_jsxs("div", { "data-slot": "appearance-picker", className: cn("flex min-w-0 flex-col gap-6", className), children: [locked && (_jsxs("p", { className: "flex items-center gap-2 rounded-lg border border-info-border bg-info-bg px-3 py-2 text-sm text-info-fg", children: [_jsx(LockIcon, { className: "size-4 shrink-0", "aria-hidden": true }), t.locked] })), product.themes.length > 0 && (_jsx(Group, { legend: t.themes, children: _jsx("div", { className: "grid grid-cols-[repeat(auto-fill,minmax(9rem,1fr))] gap-2", children: product.themes.map((theme) => (_jsxs(Choice, { name: `${id}-theme`, checked: activeTheme?.id === theme.id, disabled: locked, onSelect: () => setAppearance({ ground: theme.ground, accent: theme.accent }), className: "flex-col items-stretch gap-2 p-2", children: [_jsx(ThemePreview, { product: product, ground: theme.ground, accent: accents.find((a) => a.key === theme.accent) }), _jsxs("span", { children: [_jsx("span", { className: "block text-sm font-semibold", children: theme.name }), _jsx("span", { className: "block text-xs text-muted-foreground", children: theme.hint })] })] }, theme.id))) }) })), _jsxs(Group, { legend: t.accent, children: [_jsx("div", { className: "flex flex-wrap gap-2", children: accents.map((accent) => (_jsxs(Choice, { name: `${id}-accent`, checked: appearance.accent === accent.key, disabled: locked, onSelect: () => setAppearance({ accent: accent.key }), children: [_jsx("span", { "aria-hidden": true, className: "size-3.5 rounded-full", style: { background: accentOn(accent, appearance.ground) } }), t.accentLabel(accent.key, accent.label)] }, accent.key))) }), _jsx(CustomAccent, { id: `${id}-custom`, value: isCustomAccent(appearance.accent) ? appearance.accent : null, ground: appearance.ground, disabled: locked, onChange: (accent) => setAppearance({ accent }) })] }), _jsx(Group, { legend: t.ground, children: _jsx("div", { className: "flex flex-wrap gap-2", children: product.grounds.map((ground) => (_jsxs(Choice, { name: `${id}-ground`, checked: appearance.ground === ground, disabled: locked, onSelect: () => setAppearance({ ground }), children: [_jsx("span", { "aria-hidden": true, className: "size-3.5 rounded-full border", style: { background: SURFACES[ground].background } }), t.groundLabel(ground, GROUNDS[ground].label), _jsx("span", { className: "text-xs text-muted-foreground", children: t.mode(GROUNDS[ground].mode) })] }, ground))) }) }), _jsx(Group, { legend: t.density, children: _jsx("div", { className: "grid gap-2 sm:grid-cols-2", children: DENSITY_KEYS.map((density) => (_jsxs(Choice, { name: `${id}-density`, checked: appearance.density === density, disabled: locked, onSelect: () => setAppearance({ density }), className: "flex-col items-start gap-0.5 px-3 py-2", children: [_jsx("span", { className: "text-sm font-semibold", children: t.densityLabel(density) }), _jsx("span", { className: "text-xs text-muted-foreground", children: t.densityHint(density) })] }, density))) }) }), _jsx(Group, { legend: t.corners, children: _jsx("div", { className: "flex flex-wrap gap-2", children: CORNERS.map((corners) => (_jsxs(Choice, { name: `${id}-corners`, checked: appearance.corners === corners, disabled: locked, onSelect: () => setAppearance({ corners }), children: [_jsx("span", { "aria-hidden": true, className: "size-3.5 border-t-2 border-l-2 border-current", style: { borderTopLeftRadius: corners } }), t.cornersLabel(corners)] }, corners))) }) }), !locked && (_jsx("div", { children: _jsx(Button, { variant: "outline", size: "sm", onClick: reset, children: t.reset }) }))] }));
+}
+/**
+ * Any colour as the accent (Astrolift palette option A). It applies only once
+ * it stands 3:1 off the ground (WCAG 2.2 §1.4.11); until then the draft stays
+ * in the field with the reason.
+ */
+function CustomAccent({ id, value, ground, disabled, onChange, }) {
+    const { messages } = useUI();
+    const t = messages.appearance;
+    const [draft, setDraft] = React.useState(value ?? "");
+    const parsed = parseCustomAccent(draft);
+    const check = parsed ? accentContrast(parsed, ground) : null;
+    const helpId = `${id}-help`;
+    function update(next) {
+        setDraft(next);
+        const hex = parseCustomAccent(next);
+        if (hex && accentContrast(hex, ground).ok)
+            onChange(hex);
+    }
+    const help = !draft
+        ? t.customAccentHelp
+        : !parsed
+            ? t.customAccentInvalid
+            : check?.ok
+                ? t.customAccentOk(check.ratio.toFixed(1))
+                : t.customAccentFaint((check?.ratio ?? 1).toFixed(1), MIN_NON_TEXT_CONTRAST, modeFor(ground));
+    return (_jsxs("div", { className: "mt-1 flex min-w-0 flex-col gap-1.5", children: [_jsx("label", { htmlFor: id, className: "text-sm font-medium", children: t.customAccent }), _jsxs("div", { className: "flex min-w-0 flex-wrap items-center gap-2", children: [_jsx("input", { type: "color", "aria-label": t.customAccentPick, disabled: disabled, value: parsed ?? "#2f9e52", onChange: (event) => update(event.target.value), className: "size-8 shrink-0 cursor-pointer rounded-lg border bg-transparent disabled:cursor-not-allowed" }), _jsx("input", { id: id, type: "text", inputMode: "text", spellCheck: false, disabled: disabled, value: draft, placeholder: "#2f9e52", onChange: (event) => update(event.target.value), "aria-invalid": Boolean(draft) && !check?.ok, "aria-describedby": helpId, className: "h-8 w-32 rounded-lg border border-input bg-transparent px-2.5 font-mono text-sm outline-none placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:opacity-50 aria-invalid:border-destructive" }), value && _jsx("span", { className: "text-xs text-muted-foreground", children: t.customAccentInUse })] }), _jsx("p", { id: helpId, "aria-live": "polite", className: cn("text-xs [overflow-wrap:anywhere]", draft && !check?.ok ? "text-danger-fg" : "text-muted-foreground"), children: help })] }));
+}

package/dist/appearance/AppearanceProvider.d.ts

@@ -0,0 +1,53 @@
+import * as React from "react";
+import type { Density, Mode } from "../theme/tokens.js";
+import { type Appearance, type OrgAppearancePolicy } from "./appearance.js";
+import type { Product } from "./product.js";
+export interface AppearanceContextValue {
+    product: Product;
+    /** What applies now: the org lock, the person's choice, the org default or the product default. */
+    appearance: Appearance;
+    mode: Mode;
+    /** True when an org policy locks the theme; the picker renders read-only. */
+    locked: boolean;
+    /** The person's own choice; null when they follow the org or the product. */
+    personal: Partial<Appearance> | null;
+    setAppearance: (patch: Partial<Appearance>) => void;
+    /** Forget the person's choice ("use the default"), not "choose the defaults". */
+    reset: () => void;
+    /** Supply the org policy once it is known, from inside the signed-in layout. */
+    setPolicy: (policy: OrgAppearancePolicy | null) => void;
+    /** Take the person's preference from the app's server, without echoing it back through onChange. */
+    applyServerAppearance: (personal: unknown) => void;
+}
+export interface AppearanceProviderProps {
+    product: Product;
+    /** The org policy, when the caller already has it; `setPolicy` supplies it later otherwise. */
+    policy?: OrgAppearancePolicy | null;
+    /** Called with the person's new preference (null on reset), for an app that keeps it on its server. */
+    onChange?: (personal: Partial<Appearance> | null) => void;
+    /**
+     * Controlled: the person's preference comes from here instead of
+     * localStorage, and changes only reach `onChange`. For a catalog toolbar
+     * or a test; an app leaves it out.
+     */
+    value?: Partial<Appearance> | null;
+    children: React.ReactNode;
+}
+/**
+ * Holds the person's appearance for one product and keeps <html> in step.
+ * The preference is read from localStorage as an external store, so the
+ * server render and hydration use the product default (AppearanceScript has
+ * already painted the stored choice), other tabs follow through the storage
+ * event, and nothing is set from an effect.
+ *
+ * The product config carries component references (navigation icons), so
+ * create this provider in a client module rather than passing the product
+ * across from a Server Component.
+ */
+export declare function AppearanceProvider({ product, policy, onChange, value: controlled, children, }: AppearanceProviderProps): React.JSX.Element;
+/** The appearance context. Throws outside an AppearanceProvider. */
+export declare function useAppearance(): AppearanceContextValue;
+/** The product in context, or null outside an AppearanceProvider. */
+export declare function useProduct(): Product | null;
+/** The density in context, or compact outside an AppearanceProvider. */
+export declare function useDensity(): Density;

package/dist/appearance/AppearanceProvider.js

@@ -0,0 +1,113 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import * as React from "react";
+import { subscribeLocal } from "../lib/local-store.js";
+import { appearanceFromServer, applyAppearance, clearAppearance, normalizePartial, parseStoredAppearance, readAppearance, readStoredAppearance, resolveAppearance, writeAppearance, } from "./appearance.js";
+const AppearanceContext = React.createContext(null);
+const LIGHT_QUERY = "(prefers-color-scheme: light)";
+function subscribeScheme(onChange) {
+    if (typeof window.matchMedia !== "function")
+        return () => { };
+    const query = window.matchMedia(LIGHT_QUERY);
+    query.addEventListener("change", onChange);
+    return () => query.removeEventListener("change", onChange);
+}
+function systemMode() {
+    return typeof window.matchMedia === "function" && window.matchMedia(LIGHT_QUERY).matches
+        ? "light"
+        : "dark";
+}
+const noSubscription = () => () => { };
+/**
+ * Holds the person's appearance for one product and keeps <html> in step.
+ * The preference is read from localStorage as an external store, so the
+ * server render and hydration use the product default (AppearanceScript has
+ * already painted the stored choice), other tabs follow through the storage
+ * event, and nothing is set from an effect.
+ *
+ * The product config carries component references (navigation icons), so
+ * create this provider in a client module rather than passing the product
+ * across from a Server Component.
+ */
+export function AppearanceProvider({ product, policy = null, onChange, value: controlled, children, }) {
+    const isControlled = controlled !== undefined;
+    const raw = React.useSyncExternalStore(subscribeLocal, () => readStoredAppearance(product), () => null);
+    const scheme = React.useSyncExternalStore(subscribeScheme, systemMode, () => "dark");
+    const isClient = React.useSyncExternalStore(noSubscription, () => true, () => false);
+    const [orgPolicy, setOrgPolicy] = React.useState(policy);
+    const personal = React.useMemo(() => isControlled
+        ? controlled && Object.keys(normalizePartial(controlled, product)).length > 0
+            ? normalizePartial(controlled, product)
+            : null
+        : parseStoredAppearance(raw, product), [isControlled, controlled, raw, product]);
+    const { value, mode, locked } = React.useMemo(() => resolveAppearance(personal, orgPolicy, product, scheme), [personal, orgPolicy, product, scheme]);
+    React.useEffect(() => {
+        // While hydrating, the store reads above return their server snapshots,
+        // so `value` is the product default rather than what the boot script
+        // applied from storage; stamping it would flash. The client render that
+        // follows hydration applies the real value.
+        if (isClient)
+            applyAppearance(value, product);
+    }, [isClient, value, product]);
+    const onChangeRef = React.useRef(onChange);
+    React.useEffect(() => {
+        onChangeRef.current = onChange;
+    }, [onChange]);
+    const setAppearance = React.useCallback((patch) => {
+        if (locked)
+            return;
+        if (isControlled) {
+            onChangeRef.current?.(normalizePartial({ ...(personal ?? {}), ...patch }, product));
+            return;
+        }
+        // Read the stored value rather than the rendered one, so two changes
+        // in one tick both land.
+        const next = normalizePartial({ ...(readAppearance(product) ?? {}), ...patch }, product);
+        writeAppearance(product, next);
+        onChangeRef.current?.(next);
+    }, [locked, isControlled, personal, product]);
+    const reset = React.useCallback(() => {
+        if (locked)
+            return;
+        if (!isControlled)
+            clearAppearance(product);
+        onChangeRef.current?.(null);
+    }, [locked, isControlled, product]);
+    const applyServerAppearance = React.useCallback((next) => {
+        if (isControlled)
+            return;
+        const parsed = appearanceFromServer(next, product);
+        if (parsed)
+            writeAppearance(product, parsed);
+        else
+            clearAppearance(product);
+    }, [isControlled, product]);
+    const setPolicy = React.useCallback((next) => setOrgPolicy(next), []);
+    const context = React.useMemo(() => ({
+        product,
+        appearance: value,
+        mode,
+        locked,
+        personal,
+        setAppearance,
+        reset,
+        setPolicy,
+        applyServerAppearance,
+    }), [product, value, mode, locked, personal, setAppearance, reset, setPolicy, applyServerAppearance]);
+    return _jsx(AppearanceContext.Provider, { value: context, children: children });
+}
+/** The appearance context. Throws outside an AppearanceProvider. */
+export function useAppearance() {
+    const context = React.useContext(AppearanceContext);
+    if (!context)
+        throw new Error("useAppearance must be used inside <AppearanceProvider>");
+    return context;
+}
+/** The product in context, or null outside an AppearanceProvider. */
+export function useProduct() {
+    return React.useContext(AppearanceContext)?.product ?? null;
+}
+/** The density in context, or compact outside an AppearanceProvider. */
+export function useDensity() {
+    return React.useContext(AppearanceContext)?.appearance.density ?? "compact";
+}

package/dist/appearance/AppearanceScript.d.ts

@@ -0,0 +1,16 @@
+import type { Product } from "./product.js";
+export interface AppearanceScriptProps {
+    product: Product;
+    /** The page's CSP nonce, when inline style and script need one. */
+    nonce?: string;
+}
+/**
+ * Render in <head>, before anything paints: the product's brand tokens (its
+ * sidebar and its own accent) and the script that stamps the person's ground,
+ * accent, density and corners on <html> from localStorage. Without it the page
+ * paints the defaults and swaps once React hydrates, which reads as a flash.
+ *
+ * Not a client component: it renders the same markup on the server and needs
+ * no hooks, so a Next root layout can render it directly.
+ */
+export declare function AppearanceScript({ product, nonce }: AppearanceScriptProps): import("react").JSX.Element;

package/dist/appearance/AppearanceScript.js

@@ -0,0 +1,14 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { appearanceScript, productStyles } from "./boot.js";
+/**
+ * Render in <head>, before anything paints: the product's brand tokens (its
+ * sidebar and its own accent) and the script that stamps the person's ground,
+ * accent, density and corners on <html> from localStorage. Without it the page
+ * paints the defaults and swaps once React hydrates, which reads as a flash.
+ *
+ * Not a client component: it renders the same markup on the server and needs
+ * no hooks, so a Next root layout can render it directly.
+ */
+export function AppearanceScript({ product, nonce }) {
+    return (_jsxs(_Fragment, { children: [_jsx("style", { nonce: nonce, "data-calliope-ui": "product", dangerouslySetInnerHTML: { __html: productStyles(product) } }), _jsx("script", { nonce: nonce, "data-calliope-ui": "appearance", dangerouslySetInnerHTML: { __html: appearanceScript(product) } })] }));
+}