@calliopelabs/ui 0.7.0 → 0.12.0

package/dist/shell/BrandMark.d.ts

@@ -1,14 +1,36 @@
 import type * as React from "react";
+import type { Product } from "../appearance/product.js";
+import type { Mode } from "../theme/tokens.js";
+/** A deployment's logo as `withBrand` puts it on the product: validated image URLs. */
+export type BrandLogo = NonNullable<Product["logo"]>;
 export interface BrandMarkProps {
     /** Where the mark leads: the product's home. */
     href: string;
-    /** The product's logo mark (an <img> or SVG). Decorative: the name or the label carries the meaning. */
+    /** The product's logo mark (an <img> or SVG). Decorative: the name or the label carries the meaning. Defaults to the product's `logo.mark`. */
     mark?: React.ReactNode;
     /** Defaults to the product's name from AppearanceProvider. */
     name?: string;
+    /**
+     * Image URLs in place of the product's runtime logo (a brand admin's draft).
+     * `mark` is the square mark; `onDark` and `onLight` are the full logo, drawn
+     * in place of the name on a dark or a light sidebar.
+     */
+    logo?: BrandLogo;
+    /** Shown in the collapsed sidebar when there is no mark. Defaults to the product's `shortName`. */
+    shortName?: string;
+    /** A line under the name: an environment, an edition, a customer. Hidden when collapsed. */
+    tagline?: React.ReactNode;
     /** The mark alone, for the collapsed sidebar. */
     collapsed?: boolean;
     className?: string;
 }
-/** The product's mark and name, heading the sidebar. */
-export declare function BrandMark({ href, mark, name, collapsed, className }: BrandMarkProps): React.JSX.Element;
+/** The full logo for the sidebar of one mode: the variant made for its lightness, else the other. */
+export declare function logoForSidebar(logo: BrandLogo | undefined, product: Product | null, mode: Mode): string | undefined;
+/**
+ * The product's mark and name, heading the sidebar. A runtime brand's logo
+ * (`withBrand`) replaces them: its mark in the tile, its full logo in place of
+ * the name, the `onDark` or `onLight` variant chosen by the sidebar's
+ * lightness in each mode. Both variants are in the markup and CSS shows the
+ * one for the current mode, so the first paint is already right.
+ */
+export declare function BrandMark({ href, mark, name, logo, shortName, tagline, collapsed, className, }: BrandMarkProps): React.JSX.Element;

package/dist/shell/BrandMark.js

@@ -1,14 +1,44 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { inkFor } from "../appearance/appearance.js";
 import { useProduct } from "../appearance/AppearanceProvider.js";
 import { cn } from "../lib/cn.js";
 import { useUI } from "../provider/UIProvider.js";
-/** The product's mark and name, heading the sidebar. */
-export function BrandMark({ href, mark, name, collapsed = false, className }) {
+/** True when the sidebar of `mode` is dark, so a logo drawn on it is the `onDark` one. */
+function sidebarIsDark(product, mode) {
+    const sidebar = mode === "dark" ? product?.sidebar : product?.sidebarLight;
+    // Unbranded light grounds keep a neutral, light sidebar.
+    if (!sidebar)
+        return mode === "dark";
+    return inkFor(sidebar) === "#ffffff";
+}
+/** The full logo for the sidebar of one mode: the variant made for its lightness, else the other. */
+export function logoForSidebar(logo, product, mode) {
+    if (!logo)
+        return undefined;
+    return sidebarIsDark(product, mode)
+        ? (logo.onDark ?? logo.onLight)
+        : (logo.onLight ?? logo.onDark);
+}
+/**
+ * The product's mark and name, heading the sidebar. A runtime brand's logo
+ * (`withBrand`) replaces them: its mark in the tile, its full logo in place of
+ * the name, the `onDark` or `onLight` variant chosen by the sidebar's
+ * lightness in each mode. Both variants are in the markup and CSS shows the
+ * one for the current mode, so the first paint is already right.
+ */
+export function BrandMark({ href, mark, name, logo, shortName, tagline, collapsed = false, className, }) {
     const { Link } = useUI();
     const product = useProduct();
     const title = name ?? product?.name;
     if (!title)
         throw new Error("BrandMark needs a name, or an AppearanceProvider with a product");
-    return (_jsxs(Link, { href: href, "aria-label": collapsed ? title : undefined, className: cn("flex min-w-0 items-center gap-2 rounded-lg focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none", collapsed && "justify-center", className), children: [mark && (_jsx("span", { "aria-hidden": true, className: "flex size-7 shrink-0 items-center justify-center rounded-lg bg-sidebar-primary/10 ring-1 ring-sidebar-primary/30 [&_img]:size-4.5 [&_svg]:size-4.5", children: mark })), !collapsed && (_jsx("span", { className: "truncate font-head text-sm font-semibold tracking-tight", children: title }))] }));
+    const brandLogo = logo ?? product?.logo;
+    const tile = mark ?? (brandLogo?.mark ? _jsx("img", { src: brandLogo.mark, alt: "", draggable: false }) : null);
+    const onDark = logoForSidebar(brandLogo, product, "dark");
+    const onLight = logoForSidebar(brandLogo, product, "light");
+    const full = !collapsed && (onDark || onLight);
+    const short = collapsed && !tile ? (shortName ?? product?.shortName) : undefined;
+    const logoClass = "h-6 w-auto max-w-full min-w-0 object-contain object-left";
+    return (_jsxs(Link, { href: href, "aria-label": collapsed || full ? title : undefined, className: cn("flex min-w-0 items-center gap-2 rounded-lg focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none", collapsed && "justify-center", className), children: [tile && (_jsx("span", { "aria-hidden": true, className: "flex size-7 shrink-0 items-center justify-center rounded-lg bg-sidebar-primary/10 ring-1 ring-sidebar-primary/30 [&_img]:size-4.5 [&_svg]:size-4.5", children: tile })), short && (_jsx("span", { "aria-hidden": true, className: "truncate font-head text-xs font-semibold tracking-tight", children: short })), !collapsed && (_jsxs("span", { className: "grid min-w-0", children: [full ? (onDark === onLight ? (_jsx("img", { src: onDark, alt: "", draggable: false, className: logoClass })) : (_jsxs(_Fragment, { children: [onDark && (_jsx("img", { src: onDark, alt: "", draggable: false, className: cn(logoClass, "in-data-[mode=light]:hidden") })), onLight && (_jsx("img", { src: onLight, alt: "", draggable: false, className: cn(logoClass, "hidden in-data-[mode=light]:block") }))] }))) : (_jsx("span", { className: "truncate font-head text-sm font-semibold tracking-tight", children: title })), tagline && " ", tagline && (_jsx("span", { className: "truncate text-2xs text-sidebar-muted-foreground", children: tagline }))] }))] }));
 }

package/dist/shell/RailPanel.js

@@ -19,10 +19,10 @@ export function RailPanel({ label, title, actions, footer, children, collapsed,
     if (collapsed && !inDrawer) {
         if (collapsedMode === "hidden")
             return null;
-        return (_jsxs("aside", { "aria-label": label, "data-slot": "rail-panel", "data-collapsed": true, className: cn("flex h-full w-8 shrink-0 flex-col items-center gap-2 border-l border-sidebar-border bg-sidebar py-2 text-muted-foreground", className), children: [_jsx("button", { type: "button", onClick: () => onCollapsedChange(false), "aria-label": messages.rail.show(label), title: `${messages.rail.show(label)} (])`, className: "flex size-7 items-center justify-center rounded-lg hover:bg-sidebar-accent hover:text-sidebar-foreground focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none", children: _jsx(ChevronsLeftIcon, { className: "size-4", "aria-hidden": true }) }), collapsedIcon && (_jsx("span", { "aria-hidden": true, className: "[&_svg]:size-4", children: collapsedIcon }))] }));
+        return (_jsxs("aside", { "aria-label": label, "data-slot": "rail-panel", "data-collapsed": true, className: cn("flex h-full w-8 shrink-0 flex-col items-center gap-2 border-l border-sidebar-border bg-sidebar py-2 text-sidebar-muted-foreground", className), children: [_jsx("button", { type: "button", onClick: () => onCollapsedChange(false), "aria-label": messages.rail.show(label), title: `${messages.rail.show(label)} (])`, className: "flex size-7 items-center justify-center rounded-lg hover:bg-sidebar-accent hover:text-sidebar-foreground focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none", children: _jsx(ChevronsLeftIcon, { className: "size-4", "aria-hidden": true }) }), collapsedIcon && (_jsx("span", { "aria-hidden": true, className: "[&_svg]:size-4", children: collapsedIcon }))] }));
     }
     const resizable = Boolean(onWidthChange) && !inDrawer && !expanded;
-    const iconButton = "flex size-7 shrink-0 items-center justify-center rounded-lg text-muted-foreground hover:bg-sidebar-accent hover:text-sidebar-foreground focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none";
+    const iconButton = "flex size-7 shrink-0 items-center justify-center rounded-lg text-sidebar-muted-foreground hover:bg-sidebar-accent hover:text-sidebar-foreground focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none";
     return (_jsxs("aside", { "aria-label": label, "data-slot": "rail-panel", "data-expanded": expanded || undefined, style: inDrawer || expanded ? undefined : { width }, className: cn("relative flex h-full min-h-0 shrink-0 flex-col border-l border-sidebar-border bg-sidebar text-sidebar-foreground", (inDrawer || expanded) && "w-full min-w-0 flex-1", inDrawer && "border-l-0", className), children: [resizable && (_jsx(ResizeHandle, { label: messages.rail.resize(label), width: width, minWidth: minWidth, maxWidth: maxWidth, onWidthChange: (next) => onWidthChange?.(clamp(next)) })), _jsxs("div", { className: "flex min-w-0 items-center gap-2 border-b border-sidebar-border px-3 py-2", children: [_jsx("div", { className: "min-w-0 flex-1 truncate text-sm font-semibold", children: title ?? label }), actions, onExpandedChange && !inDrawer && (_jsx("button", { type: "button", onClick: () => onExpandedChange(!expanded), "aria-label": expanded ? messages.rail.restore(label) : messages.rail.expand(label), title: expanded ? messages.rail.restore(label) : messages.rail.expand(label), className: iconButton, children: expanded ? (_jsx(Minimize2Icon, { className: "size-4", "aria-hidden": true })) : (_jsx(Maximize2Icon, { className: "size-4", "aria-hidden": true })) })), !inDrawer && (_jsx("button", { type: "button", onClick: () => onCollapsedChange(true), "aria-label": messages.rail.hide(label), title: `${messages.rail.hide(label)} (])`, className: iconButton, children: _jsx(ChevronsRightIcon, { className: "size-4", "aria-hidden": true }) }))] }), _jsx("div", { className: "min-h-0 flex-1 overflow-y-auto", children: children }), footer && _jsx("div", { className: "border-t border-sidebar-border px-3 py-2", children: footer })] }));
 }
 /* A focusable separator is the WAI-ARIA window splitter, an interactive

package/dist/shell/RailTree.js

@@ -14,7 +14,7 @@ import { StatusDot } from "../status/StatusDot.js";
  */
 export function RailTree({ label, groups, activeHref, loading = false, emptyText, className, }) {
     const headingId = React.useId();
-    return (_jsxs("div", { className: cn("flex min-w-0 flex-col", className), children: [_jsx("div", { id: headingId, className: "px-3 pt-3 pb-1 text-2xs font-semibold tracking-wider text-muted-foreground uppercase", children: label }), _jsx("div", { className: "px-2 pb-2", children: loading ? (_jsx("div", { className: "flex flex-col gap-2 px-1 pt-1", "aria-busy": true, children: Array.from({ length: 4 }, (_, i) => (_jsx(Skeleton, { className: "h-6 w-full" }, i))) })) : groups.length === 0 ? (_jsx("p", { className: "px-2 py-2 text-xs text-muted-foreground", children: emptyText })) : (_jsx("ul", { "aria-labelledby": headingId, className: "flex flex-col gap-0.5", children: groups.map((group) => (_jsx(Branch, { group: group, activeHref: activeHref }, group.key))) })) })] }));
+    return (_jsxs("div", { className: cn("flex min-w-0 flex-col", className), children: [_jsx("div", { id: headingId, className: "px-3 pt-3 pb-1 text-2xs font-semibold tracking-wider text-sidebar-muted-foreground uppercase", children: label }), _jsx("div", { className: "px-2 pb-2", children: loading ? (_jsx("div", { className: "flex flex-col gap-2 px-1 pt-1", "aria-busy": true, children: Array.from({ length: 4 }, (_, i) => (_jsx(Skeleton, { className: "h-6 w-full" }, i))) })) : groups.length === 0 ? (_jsx("p", { className: "px-2 py-2 text-xs text-sidebar-muted-foreground", children: emptyText })) : (_jsx("ul", { "aria-labelledby": headingId, className: "flex flex-col gap-0.5", children: groups.map((group) => (_jsx(Branch, { group: group, activeHref: activeHref }, group.key))) })) })] }));
 }
 function Branch({ group, activeHref }) {
     const { Link } = useUI();
@@ -22,7 +22,7 @@ function Branch({ group, activeHref }) {
     const [open, setOpen] = React.useState(holdsActive);
     const listId = React.useId();
     const Chevron = open ? ChevronDownIcon : ChevronRightIcon;
-    return (_jsxs("li", { children: [_jsxs("button", { type: "button", onClick: () => setOpen((o) => !o), "aria-expanded": open, "aria-controls": listId, className: "flex h-7 w-full min-w-0 items-center gap-1.5 rounded-lg px-1.5 text-left text-sm hover:bg-sidebar-accent/60 focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none", children: [_jsx(Chevron, { className: "size-3.5 shrink-0 text-muted-foreground", "aria-hidden": true }), _jsx("span", { className: "truncate font-medium", title: group.label, children: group.label }), " ", _jsx("span", { className: "ml-auto font-mono text-2xs text-muted-foreground", children: group.items.length })] }), _jsx("ul", { id: listId, hidden: !open, className: "ml-3 flex flex-col gap-0.5 border-l border-current/10 pl-2", children: group.items.map((item) => {
+    return (_jsxs("li", { children: [_jsxs("button", { type: "button", onClick: () => setOpen((o) => !o), "aria-expanded": open, "aria-controls": listId, className: "flex h-7 w-full min-w-0 items-center gap-1.5 rounded-lg px-1.5 text-left text-sm hover:bg-sidebar-accent/60 focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none", children: [_jsx(Chevron, { className: "size-3.5 shrink-0 text-sidebar-muted-foreground", "aria-hidden": true }), _jsx("span", { className: "truncate font-medium", title: group.label, children: group.label }), " ", _jsx("span", { className: "ml-auto font-mono text-2xs text-sidebar-muted-foreground", children: group.items.length })] }), _jsx("ul", { id: listId, hidden: !open, className: "ml-3 flex flex-col gap-0.5 border-l border-current/10 pl-2", children: group.items.map((item) => {
                     const Icon = item.icon;
                     const isActive = item.href === activeHref;
                     return (_jsx("li", { children: _jsxs(Link, { href: item.href, "aria-current": isActive ? "page" : undefined, className: cn("flex h-7 min-w-0 items-center gap-2 rounded-lg px-1.5 text-sm focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none", isActive

package/dist/shell/Sidebar.d.ts

@@ -1,4 +1,4 @@
-import type * as React from "react";
+import * as React from "react";
 import type { NavActive, NavModel } from "../nav/model.js";
 export interface SidebarProps {
     /** The model, filtered to what the viewer may open (`visibleNav`). */
@@ -15,6 +15,13 @@ export interface SidebarProps {
     footer?: React.ReactNode;
     /** The navigation landmark's name. Defaults to "Main". */
     label?: string;
+    /**
+     * The `name` of a `RailBoot` passed to `AppearanceScript rails`: until React
+     * hydrates, the sidebar renders both its folded and open bodies and the
+     * stamped `data-rail-<name>` shows the right one, so the first paint is
+     * already the person's choice.
+     */
+    railName?: string;
     className?: string;
 }
 /**
@@ -23,4 +30,4 @@ export interface SidebarProps {
  * row and the collapsed state are the caller's; `[` toggles it through the
  * AppShell.
  */
-export declare function Sidebar({ nav, active, collapsed: collapsedProp, onCollapsedChange, header, headerCollapsed, footer, label, className, }: SidebarProps): React.JSX.Element;
+export declare function Sidebar({ nav, active, collapsed: collapsedProp, onCollapsedChange, header, headerCollapsed, footer, label, railName, className, }: SidebarProps): React.JSX.Element;

package/dist/shell/Sidebar.js

@@ -1,21 +1,27 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { ChevronsLeftIcon, ChevronsRightIcon } from "lucide-react";
+import * as React from "react";
 import { cn } from "../lib/cn.js";
 import { Nav } from "../nav/Nav.js";
 import { useUI } from "../provider/UIProvider.js";
 import { useRailPlacement } from "./placement.js";
+const noSubscription = () => () => { };
 /**
  * The main rail, on the left (Astrolift layout D): the one brand surface.
  * 220px with labels, 48px with icons. Pure: the filtered model, the active
  * row and the collapsed state are the caller's; `[` toggles it through the
  * AppShell.
  */
-export function Sidebar({ nav, active, collapsed: collapsedProp, onCollapsedChange, header, headerCollapsed, footer, label, className, }) {
+export function Sidebar({ nav, active, collapsed: collapsedProp, onCollapsedChange, header, headerCollapsed, footer, label, railName, className, }) {
     const { messages } = useUI();
     const inDrawer = useRailPlacement() === "drawer";
+    // True on the server and while hydrating, false once React owns the page.
+    const hydrating = React.useSyncExternalStore(noSubscription, () => false, () => true);
+    const pending = Boolean(railName) && hydrating && !inDrawer;
     const collapsed = collapsedProp && !inDrawer;
-    return (_jsxs("div", { "data-slot": "sidebar", "data-collapsed": collapsed || undefined, className: cn("flex h-full min-h-0 shrink-0 flex-col border-r border-sidebar-border bg-sidebar text-sidebar-foreground", inDrawer ? "w-full border-r-0" : "transition-[width] duration-(--motion-base)", !inDrawer && (collapsed ? "w-12" : "w-55"), className), children: [collapsed
+    const body = (folded) => (_jsxs(_Fragment, { children: [folded
                 ? headerCollapsed && _jsx("div", { className: "flex justify-center py-3", children: headerCollapsed })
-                : header && _jsx("div", { className: "flex min-w-0 items-center px-3 py-3", children: header }), _jsx("nav", { "aria-label": label ?? messages.nav.label, className: "min-h-0 flex-1 overflow-y-auto px-2 py-1", children: _jsx(Nav, { nav: nav, active: active, collapsed: collapsed }) }), (footer || !inDrawer) && (_jsxs("div", { className: "flex flex-col gap-1 border-t border-sidebar-border px-2 py-2", children: [!collapsed && footer, !inDrawer && (_jsx("button", { type: "button", onClick: () => onCollapsedChange(!collapsed), "aria-label": collapsed ? messages.nav.expand : messages.nav.collapse, title: collapsed ? messages.nav.expandTitle : messages.nav.collapseTitle, className: "flex h-8 items-center justify-center rounded-lg text-muted-foreground hover:bg-sidebar-accent hover:text-sidebar-foreground focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none", children: collapsed ? (_jsx(ChevronsRightIcon, { className: "size-4", "aria-hidden": true })) : (_jsx(ChevronsLeftIcon, { className: "size-4", "aria-hidden": true })) }))] }))] }));
+                : header && _jsx("div", { className: "flex min-w-0 items-center px-3 py-3", children: header }), _jsx("nav", { "aria-label": label ?? messages.nav.label, className: "min-h-0 flex-1 overflow-y-auto px-2 py-1", children: _jsx(Nav, { nav: nav, active: active, collapsed: folded }) }), (footer || !inDrawer) && (_jsxs("div", { className: "flex flex-col gap-1 border-t border-sidebar-border px-2 py-2", children: [!folded && footer, !inDrawer && (_jsx("button", { type: "button", onClick: () => onCollapsedChange(!folded), "aria-label": folded ? messages.nav.expand : messages.nav.collapse, title: folded ? messages.nav.expandTitle : messages.nav.collapseTitle, className: "flex h-8 items-center justify-center rounded-lg text-sidebar-muted-foreground hover:bg-sidebar-accent hover:text-sidebar-foreground focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none", children: folded ? (_jsx(ChevronsRightIcon, { className: "size-4", "aria-hidden": true })) : (_jsx(ChevronsLeftIcon, { className: "size-4", "aria-hidden": true })) }))] }))] }));
+    return (_jsx("div", { "data-slot": "sidebar", "data-collapsed": collapsed || undefined, "data-rail": pending ? railName : undefined, "data-rail-pending": pending || undefined, className: cn("flex h-full min-h-0 shrink-0 flex-col border-r border-sidebar-border bg-sidebar text-sidebar-foreground", inDrawer ? "w-full border-r-0" : "transition-[width] duration-(--motion-base)", !inDrawer && (collapsed ? "w-12" : "w-55"), className), children: pending ? (_jsxs(_Fragment, { children: [_jsx("div", { "data-rail-body": "expanded", className: "contents", children: body(false) }), _jsx("div", { "data-rail-body": "collapsed", className: "contents", children: body(true) })] })) : (body(collapsed)) }));
 }

package/dist/shell/UserMenu.d.ts

@@ -11,6 +11,8 @@ export interface UserMenuItem {
 export interface UserMenuProps {
     name: string;
     email: string;
+    /** The person's picture; their initials show without it, and while it loads. */
+    avatar?: string;
     /** Groups of items, separated by rules: account pages, then help. */
     groups?: readonly (readonly UserMenuItem[])[];
     onSignOut: () => void;
@@ -19,4 +21,4 @@ export interface UserMenuProps {
     className?: string;
 }
 /** The signed-in person's menu, at the foot of the sidebar. Pure: the person, the items and sign-out are the app's. */
-export declare function UserMenu({ name, email, groups, onSignOut, collapsed, className, }: UserMenuProps): React.JSX.Element;
+export declare function UserMenu({ name, email, avatar, groups, onSignOut, collapsed, className, }: UserMenuProps): React.JSX.Element;

package/dist/shell/UserMenu.js

@@ -2,25 +2,17 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { LogOutIcon } from "lucide-react";
 import { cn } from "../lib/cn.js";
+import { Avatar, initials } from "../primitives/Avatar.js";
 import { DropdownMenu, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuLabel, DropdownMenuSeparator, DropdownMenuTrigger, } from "../primitives/DropdownMenu.js";
 import { useUI } from "../provider/UIProvider.js";
-function initialsOf(name) {
-    return (name
-        .split(/\s+/)
-        .map((part) => part[0])
-        .filter(Boolean)
-        .slice(0, 2)
-        .join("")
-        .toUpperCase() || "?");
-}
 /** The signed-in person's menu, at the foot of the sidebar. Pure: the person, the items and sign-out are the app's. */
-export function UserMenu({ name, email, groups = [], onSignOut, collapsed = false, className, }) {
+export function UserMenu({ name, email, avatar, groups = [], onSignOut, collapsed = false, className, }) {
     const { Link, messages } = useUI();
     return (_jsxs(DropdownMenu, { children: [_jsxs(DropdownMenuTrigger
             // Expanded, the visible name and email are the trigger's name (WCAG
             // 2.5.3, label in name); collapsed, only the initials show, so it
             // needs one.
-            , { "aria-label": collapsed ? messages.user.accountMenu(name, initialsOf(name)) : undefined, className: cn("flex h-10 w-full min-w-0 items-center gap-2 rounded-lg px-1.5 text-left hover:bg-sidebar-accent/60 focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none", collapsed && "justify-center px-0", className), children: [_jsx("span", { "aria-hidden": true, className: "flex size-7 shrink-0 items-center justify-center rounded-full bg-muted font-mono text-xs font-medium text-foreground", children: initialsOf(name) }), !collapsed && (_jsxs("span", { className: "grid min-w-0 flex-1 leading-tight", children: [_jsx("span", { className: "truncate text-sm font-medium", children: name }), " ", _jsx("span", { className: "truncate text-xs text-muted-foreground", children: email })] }))] }), _jsxs(DropdownMenuContent, { side: "right", align: "end", className: "min-w-56", children: [_jsxs(DropdownMenuLabel, { className: "grid font-normal", children: [_jsx("span", { className: "truncate text-sm font-medium text-popover-foreground", children: name }), _jsx("span", { className: "truncate text-xs text-muted-foreground", children: email })] }), groups.map((items, i) => (_jsx(MenuGroup, { items: items, Link: Link }, i))), _jsx(DropdownMenuSeparator, {}), _jsxs(DropdownMenuItem, { onSelect: onSignOut, children: [_jsx(LogOutIcon, { "aria-hidden": true }), " ", messages.user.signOut] })] })] }));
+            , { "aria-label": collapsed ? messages.user.accountMenu(name, initials(name)) : undefined, className: cn("flex h-10 w-full min-w-0 items-center gap-2 rounded-lg px-1.5 text-left hover:bg-sidebar-accent/60 focus-visible:ring-2 focus-visible:ring-ring focus-visible:outline-none", collapsed && "justify-center px-0", className), children: [_jsx(Avatar, { name: name, src: avatar, decorative: true }), !collapsed && (_jsxs("span", { className: "grid min-w-0 flex-1 leading-tight", children: [_jsx("span", { className: "truncate text-sm font-medium", children: name }), " ", _jsx("span", { className: "truncate text-xs text-sidebar-muted-foreground", children: email })] }))] }), _jsxs(DropdownMenuContent, { side: "right", align: "end", className: "min-w-56", children: [_jsxs(DropdownMenuLabel, { className: "grid font-normal", children: [_jsx("span", { className: "truncate text-sm font-medium text-popover-foreground", children: name }), _jsx("span", { className: "truncate text-xs text-muted-foreground", children: email })] }), groups.map((items, i) => (_jsx(MenuGroup, { items: items, Link: Link }, i))), _jsx(DropdownMenuSeparator, {}), _jsxs(DropdownMenuItem, { onSelect: onSignOut, children: [_jsx(LogOutIcon, { "aria-hidden": true }), " ", messages.user.signOut] })] })] }));
 }
 function MenuGroup({ items, Link, }) {
     return (_jsxs(_Fragment, { children: [_jsx(DropdownMenuSeparator, {}), _jsx(DropdownMenuGroup, { children: items.map((item) => {

package/dist/shell/rail-boot.d.ts

@@ -0,0 +1,28 @@
+/**
+ * A rail whose fold is applied before first paint. `AppearanceScript` (with
+ * `rails`) reads the same localStorage entry `useRailState` writes and stamps
+ * `data-rail-<name>="collapsed" | "expanded"` on <html>; a Sidebar given
+ * `railName` paints from that attribute until React has hydrated, so a
+ * person who folded the rail never sees it open first. Pure, so a Server
+ * Component can build the list.
+ */
+export interface RailBoot {
+    /** The localStorage key, the same one passed to `useRailState`. */
+    key: string;
+    /** A lowercase slug: the attribute is `data-rail-<name>` and a Sidebar's `railName`. */
+    name: string;
+    /** Folded by default (until the person chooses) on viewports narrower than this many px. */
+    collapsedBelow?: number;
+}
+/** The rails, checked: a name lands in a CSS selector and an attribute name. */
+export declare function checkRails(rails: readonly RailBoot[]): RailBoot[];
+/** The media query for "narrower than `width`px", shared by the boot script and the hook. */
+export declare function narrowerThan(width: number): string;
+/** The attribute a rail's fold is stamped under on <html>. */
+export declare function railAttribute(name: string): `data-rail-${string}`;
+/**
+ * The CSS that paints a pending Sidebar (rendered on the server, not yet
+ * hydrated) from the stamped attribute: its width, and which of its two
+ * bodies shows.
+ */
+export declare function railStyles(rails: readonly RailBoot[]): string;

package/dist/shell/rail-boot.js

@@ -0,0 +1,45 @@
+const SLUG = /^[a-z][a-z0-9-]*$/;
+/** The rails, checked: a name lands in a CSS selector and an attribute name. */
+export function checkRails(rails) {
+    return rails.map((rail) => {
+        if (!SLUG.test(rail.name))
+            throw new Error(`@calliopelabs/ui: rail name must be a lowercase slug, got ${rail.name}`);
+        if (typeof rail.key !== "string" || !rail.key)
+            throw new Error(`@calliopelabs/ui: rail ${rail.name} needs a storage key`);
+        if (rail.collapsedBelow !== undefined &&
+            !(Number.isFinite(rail.collapsedBelow) && rail.collapsedBelow > 0))
+            throw new Error(`@calliopelabs/ui: rail ${rail.name} collapsedBelow must be a positive width`);
+        const out = { key: rail.key, name: rail.name };
+        if (rail.collapsedBelow !== undefined)
+            out.collapsedBelow = rail.collapsedBelow;
+        return out;
+    });
+}
+/** The media query for "narrower than `width`px", shared by the boot script and the hook. */
+export function narrowerThan(width) {
+    return `(max-width: ${width - 0.02}px)`;
+}
+/** The attribute a rail's fold is stamped under on <html>. */
+export function railAttribute(name) {
+    return `data-rail-${name}`;
+}
+/** Widths of the Sidebar, matching its `w-12` and `w-55`. */
+const SIDEBAR_WIDTH = { collapsed: "3rem", expanded: "13.75rem" };
+/**
+ * The CSS that paints a pending Sidebar (rendered on the server, not yet
+ * hydrated) from the stamped attribute: its width, and which of its two
+ * bodies shows.
+ */
+export function railStyles(rails) {
+    return checkRails(rails)
+        .map(({ name }) => {
+        const folded = `html[${railAttribute(name)}="collapsed"]`;
+        const open = `html:not([${railAttribute(name)}="collapsed"])`;
+        const pending = `[data-rail="${name}"][data-rail-pending]`;
+        return (`${folded} ${pending}{width:${SIDEBAR_WIDTH.collapsed}}` +
+            `${open} ${pending}{width:${SIDEBAR_WIDTH.expanded}}` +
+            `${folded} ${pending} [data-rail-body="expanded"],` +
+            `${open} ${pending} [data-rail-body="collapsed"]{display:none}`);
+    })
+        .join("");
+}

package/dist/shell/rail-state.d.ts

@@ -1,11 +1,16 @@
+import { type RailBoot } from "./rail-boot.js";
 /**
  * One rail's collapsed state, remembered per person in this browser.
  * `defaultCollapsed` applies until they choose: Astrolift's projects rail
  * passes "narrower than 1280px". The server renders the rail expanded and the
  * client applies the saved choice without a hydration mismatch; a change in
  * one tab reaches the others.
+ *
+ * Given a `RailBoot` (the one passed to `AppearanceScript rails`) instead of a
+ * key, the default is its `collapsedBelow` width, and the state is kept on
+ * <html> as `data-rail-<name>`, which the boot script stamped before paint.
  */
-export declare function useRailState(storageKey: string, defaultCollapsed?: () => boolean): readonly [boolean, (collapsed: boolean) => void];
+export declare function useRailState(rail: string | RailBoot, defaultCollapsed?: () => boolean): readonly [boolean, (collapsed: boolean) => void];
 /** A resizable rail's width in px, remembered like its collapsed state and held to its range. */
 export declare function useRailWidth(storageKey: string, defaultWidth: number, range: {
     min: number;

package/dist/shell/rail-state.js

@@ -1,18 +1,34 @@
 "use client";
 import * as React from "react";
 import { readLocal, subscribeLocal, writeLocal } from "../lib/local-store.js";
+import { narrowerThan, railAttribute } from "./rail-boot.js";
+function narrowerThanNow(width) {
+    return typeof window.matchMedia === "function" && window.matchMedia(narrowerThan(width)).matches;
+}
 /**
  * One rail's collapsed state, remembered per person in this browser.
  * `defaultCollapsed` applies until they choose: Astrolift's projects rail
  * passes "narrower than 1280px". The server renders the rail expanded and the
  * client applies the saved choice without a hydration mismatch; a change in
  * one tab reaches the others.
+ *
+ * Given a `RailBoot` (the one passed to `AppearanceScript rails`) instead of a
+ * key, the default is its `collapsedBelow` width, and the state is kept on
+ * <html> as `data-rail-<name>`, which the boot script stamped before paint.
  */
-export function useRailState(storageKey, defaultCollapsed = () => false) {
+export function useRailState(rail, defaultCollapsed) {
+    const storageKey = typeof rail === "string" ? rail : rail.key;
+    const name = typeof rail === "string" ? undefined : rail.name;
+    const below = typeof rail === "string" ? undefined : rail.collapsedBelow;
+    const fallback = React.useCallback(() => (defaultCollapsed ? defaultCollapsed() : below ? narrowerThanNow(below) : false), [defaultCollapsed, below]);
     const collapsed = React.useSyncExternalStore(subscribeLocal, () => {
         const saved = readLocal(storageKey);
-        return saved === "1" ? true : saved === "0" ? false : defaultCollapsed();
+        return saved === "1" ? true : saved === "0" ? false : fallback();
     }, () => false);
+    React.useEffect(() => {
+        if (name)
+            document.documentElement.setAttribute(railAttribute(name), collapsed ? "collapsed" : "expanded");
+    }, [name, collapsed]);
     const set = React.useCallback((next) => writeLocal(storageKey, next ? "1" : "0"), [storageKey]);
     return [collapsed, set];
 }

package/dist/styles/preset.css

@@ -10,6 +10,9 @@
  */
 @import "./theme.css";
 
+/* The workflow canvas's structural styles (@xyflow/react), under the utilities so tokens win. */
+@import "@xyflow/react/dist/base.css" layer(base);
+
 /* The package's own components: their classes are generated with the app's. */
 @source "../";
 
@@ -44,6 +47,7 @@
   --color-sidebar-foreground: var(--sidebar-foreground);
   --color-sidebar-primary: var(--sidebar-primary);
   --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-muted-foreground: var(--sidebar-muted-foreground, var(--muted-foreground));
   --color-sidebar-accent: var(--sidebar-accent);
   --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
   --color-sidebar-border: var(--sidebar-border);

package/dist/styles/theme.css

@@ -35,6 +35,9 @@
   --border: rgba(255, 255, 255, 0.1);
   --input: rgba(255, 255, 255, 0.1);
   --sidebar: var(--brand-sidebar, #0a0a0a);
+  --sidebar-foreground: var(--brand-sidebar-foreground, #f0f2f1);
+  --sidebar-primary: var(--brand-sidebar-primary, var(--brand-primary));
+  --sidebar-muted-foreground: var(--brand-sidebar-muted-foreground, #848b88);
   --sidebar-accent: color-mix(in oklab, var(--primary) 16%, transparent);
   --sidebar-border: rgba(255, 255, 255, 0.08);
   --foreground: #f0f2f1;
@@ -53,8 +56,6 @@
   --chart-3: #cbf39d;
   --chart-4: #e0b34a;
   --chart-5: #0b6644;
-  --sidebar-foreground: #f0f2f1;
-  --sidebar-primary: var(--brand-primary);
   --sidebar-primary-foreground: var(--brand-on-primary);
   --sidebar-accent-foreground: #f0f2f1;
   --sidebar-ring: var(--brand-primary);
@@ -91,9 +92,12 @@
   --muted-foreground: #5c5b58;
   --border: #dfdedc;
   --input: #dfdedc;
-  --sidebar: #f4f3f1;
-  --sidebar-accent: #f3ebe5;
-  --sidebar-border: #dfdedc;
+  --sidebar: var(--brand-sidebar-light, #f4f3f1);
+  --sidebar-foreground: var(--brand-sidebar-foreground, #1e1d1b);
+  --sidebar-primary: var(--brand-sidebar-primary, var(--brand-primary));
+  --sidebar-muted-foreground: var(--brand-sidebar-muted-foreground, #5c5b58);
+  --sidebar-accent: var(--brand-sidebar-accent, #f3ebe5);
+  --sidebar-border: var(--brand-sidebar-border, #dfdedc);
   --foreground: #1e1d1b;
   --card-foreground: #1e1d1b;
   --popover-foreground: #1e1d1b;
@@ -110,8 +114,6 @@
   --chart-3: #8a7a5c;
   --chart-4: #b8860b;
   --chart-5: #26803f;
-  --sidebar-foreground: #1e1d1b;
-  --sidebar-primary: var(--brand-primary);
   --sidebar-primary-foreground: var(--brand-on-primary);
   --sidebar-accent-foreground: #1e1d1b;
   --sidebar-ring: var(--brand-primary);
@@ -148,6 +150,9 @@
   --border: rgba(255, 255, 255, 0.1);
   --input: rgba(255, 255, 255, 0.1);
   --sidebar: var(--brand-sidebar, #0a0a0a);
+  --sidebar-foreground: var(--brand-sidebar-foreground, #f0f2f1);
+  --sidebar-primary: var(--brand-sidebar-primary, var(--brand-primary));
+  --sidebar-muted-foreground: var(--brand-sidebar-muted-foreground, #848b88);
   --sidebar-accent: color-mix(in oklab, var(--primary) 16%, transparent);
   --sidebar-border: rgba(255, 255, 255, 0.08);
 }
@@ -164,6 +169,9 @@
   --border: rgba(255, 255, 255, 0.1);
   --input: rgba(255, 255, 255, 0.1);
   --sidebar: var(--brand-sidebar, #161819);
+  --sidebar-foreground: var(--brand-sidebar-foreground, #f0f2f1);
+  --sidebar-primary: var(--brand-sidebar-primary, var(--brand-primary));
+  --sidebar-muted-foreground: var(--brand-sidebar-muted-foreground, #8b9194);
   --sidebar-accent: color-mix(in oklab, var(--primary) 16%, transparent);
   --sidebar-border: rgba(255, 255, 255, 0.08);
 }
@@ -180,6 +188,9 @@
   --border: rgba(255, 255, 255, 0.09);
   --input: rgba(255, 255, 255, 0.1);
   --sidebar: #161719;
+  --sidebar-foreground: #f0f2f1;
+  --sidebar-primary: var(--brand-primary);
+  --sidebar-muted-foreground: #8e9296;
   --sidebar-accent: color-mix(in oklab, var(--primary) 14%, transparent);
   --sidebar-border: rgba(255, 255, 255, 0.07);
 }
@@ -196,6 +207,9 @@
   --border: rgba(255, 255, 255, 0.1);
   --input: rgba(255, 255, 255, 0.1);
   --sidebar: var(--brand-sidebar, #0a1310);
+  --sidebar-foreground: var(--brand-sidebar-foreground, #f0f2f1);
+  --sidebar-primary: var(--brand-sidebar-primary, var(--brand-primary));
+  --sidebar-muted-foreground: var(--brand-sidebar-muted-foreground, #8ba199);
   --sidebar-accent: color-mix(in oklab, var(--primary) 16%, transparent);
   --sidebar-border: rgba(255, 255, 255, 0.08);
 }
@@ -212,6 +226,9 @@
   --border: rgba(255, 255, 255, 0.1);
   --input: rgba(255, 255, 255, 0.1);
   --sidebar: var(--brand-sidebar, #152141);
+  --sidebar-foreground: var(--brand-sidebar-foreground, #f0f2f1);
+  --sidebar-primary: var(--brand-sidebar-primary, var(--brand-primary));
+  --sidebar-muted-foreground: var(--brand-sidebar-muted-foreground, #97a6c2);
   --sidebar-accent: color-mix(in oklab, var(--primary) 16%, transparent);
   --sidebar-border: rgba(255, 255, 255, 0.08);
 }
@@ -227,9 +244,12 @@
   --muted-foreground: #5c5b58;
   --border: #dedad2;
   --input: #dedad2;
-  --sidebar: #f5f0e4;
-  --sidebar-accent: #f0e6da;
-  --sidebar-border: #dedad2;
+  --sidebar: var(--brand-sidebar-light, #f5f0e4);
+  --sidebar-foreground: var(--brand-sidebar-foreground, #1e1d1b);
+  --sidebar-primary: var(--brand-sidebar-primary, var(--brand-primary));
+  --sidebar-muted-foreground: var(--brand-sidebar-muted-foreground, #5c5b58);
+  --sidebar-accent: var(--brand-sidebar-accent, #f0e6da);
+  --sidebar-border: var(--brand-sidebar-border, #dedad2);
 }
 
 /* Ground: Mist (light) */
@@ -243,9 +263,12 @@
   --muted-foreground: #5c5b58;
   --border: #d6dcdf;
   --input: #d6dcdf;
-  --sidebar: #e9f1f5;
-  --sidebar-accent: #dfeaf0;
-  --sidebar-border: #d6dcdf;
+  --sidebar: var(--brand-sidebar-light, #e9f1f5);
+  --sidebar-foreground: var(--brand-sidebar-foreground, #1e1d1b);
+  --sidebar-primary: var(--brand-sidebar-primary, var(--brand-primary));
+  --sidebar-muted-foreground: var(--brand-sidebar-muted-foreground, #5c5b58);
+  --sidebar-accent: var(--brand-sidebar-accent, #dfeaf0);
+  --sidebar-border: var(--brand-sidebar-border, #d6dcdf);
 }
 
 /* Accent: Green (dark) */

package/dist/theme/css-layer.d.ts

@@ -0,0 +1,19 @@
+import { type Product } from "../appearance/product.js";
+/**
+ * The CSS layer: the same tokens and the same boot script, for pages that
+ * cannot render React (Django, Jinja, HTMX, Rails, Laravel, Phoenix). Both
+ * files are generated here from the token table and the boot source by
+ * `npm run theme`, and shipped as `@calliopelabs/ui/css/*`.
+ */
+/** The products the CSS layer knows by name (`data-product`): the family's brands. */
+export declare const CSS_LAYER_PRODUCTS: readonly Product[];
+/** The whole of css/tokens.css. */
+export declare function renderTokensCss(): string;
+/**
+ * The whole of css/appearance.js: the boot script AppearanceScript renders
+ * (the same source text), the boot configs of the built-in products, and a
+ * small API over them. `set` stores the merged preference and runs the boot
+ * script again, so first paint and every later change resolve through one
+ * code path. Plain ES5, like the boot script.
+ */
+export declare function renderAppearanceJs(): string;