@cueplusplus/ui 0.1.0 → 0.3.0

package/dist/chrome/_edge-scroller.js

@@ -0,0 +1,149 @@
+"use client";
+import { cn } from "../lib/cn.js";
+import { computeScrollEdges, edgeFadeMask } from "./_tabs-scroll.js";
+import { useComposedRefs } from "../lib/compose.js";
+import { ChevronLeftGlyph, ChevronRightGlyph } from "./_glyphs.js";
+import * as React from "react";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+//#region src/chrome/_edge-scroller.tsx
+/** Page the strip by most of a screenful, keeping a sliver of context. */
+const NUDGE_FRACTION = .7;
+/**
+* What an overflowing element wears: the scroll axis, the fade, and no
+* scrollbar.
+*
+* A literal rather than a computed string, because Tailwind scans source text —
+* and the mask travels as a custom property so the prefixed and unprefixed
+* properties are written once here instead of twice per render.
+*
+* The property is always set, `none` when nothing overflows, and that word is
+* load-bearing: custom properties **inherit**. Leaving it unset on a strip that
+* fits does not mean "no mask", it means "whatever an ancestor said" — and a
+* `SegmentedControl` inside an overflowing `Toolbar` then wears the bar's fade
+* and loses its own last segment to it. Measured in a real browser at 320px
+* before it was written down. `none` is the initial value either way, so the
+* common case still creates no compositing layer.
+*/
+const EDGE_SCROLLER_CLASSES = "overflow-x-auto [mask-image:var(--cue-edge-fade)] [-webkit-mask-image:var(--cue-edge-fade)] [scrollbar-width:none] [&::-webkit-scrollbar]:hidden";
+/**
+* Track which edges of a horizontal scroller still hide content, and hand back
+* the mask and the pager that go with it.
+*
+* @param enabled False to keep the hook mounted but inert — a component whose
+* overflow behaviour is switched off must still call the same hooks in the same
+* order.
+*/
+function useEdgeScroll(enabled = true) {
+	const ref = React.useRef(null);
+	const [edges, setEdges] = React.useState({
+		start: false,
+		end: false
+	});
+	const sync = React.useCallback(() => {
+		const el = ref.current;
+		if (el === null) return;
+		setEdges(computeScrollEdges(el.scrollLeft, el.scrollWidth, el.clientWidth));
+	}, []);
+	React.useEffect(() => {
+		if (!enabled) return;
+		const el = ref.current;
+		if (el === null) return;
+		sync();
+		el.addEventListener("scroll", sync, { passive: true });
+		const observer = typeof ResizeObserver === "undefined" ? null : new ResizeObserver(() => sync());
+		observer?.observe(el);
+		let observedChildren = /* @__PURE__ */ new Set();
+		const syncObservedChildren = () => {
+			const nextChildren = new Set(el.children);
+			for (const child of observedChildren) if (!nextChildren.has(child)) observer?.unobserve(child);
+			for (const child of nextChildren) if (!observedChildren.has(child)) observer?.observe(child);
+			observedChildren = nextChildren;
+			sync();
+		};
+		syncObservedChildren();
+		const mutations = typeof MutationObserver === "undefined" ? null : new MutationObserver(() => syncObservedChildren());
+		mutations?.observe(el, { childList: true });
+		return () => {
+			el.removeEventListener("scroll", sync);
+			mutations?.disconnect();
+			observer?.disconnect();
+		};
+	}, [enabled, sync]);
+	const nudge = React.useCallback((direction) => {
+		const el = ref.current;
+		el?.scrollBy?.({
+			left: direction * el.clientWidth * NUDGE_FRACTION,
+			behavior: "smooth"
+		});
+	}, []);
+	const mask = enabled ? edgeFadeMask(edges) : void 0;
+	return {
+		ref,
+		edges: enabled ? edges : {
+			start: false,
+			end: false
+		},
+		style: enabled ? { "--cue-edge-fade": mask ?? "none" } : void 0,
+		nudge
+	};
+}
+/**
+* The pager buttons over an overflowing strip, drawn only for the edges that
+* actually hide something.
+*
+* Absolutely positioned, so the element they sit over must be inside a
+* `relative` frame.
+*/
+function EdgeChevrons({ edges, onNudge, previousLabel, nextLabel, className }) {
+	const base = "absolute inset-y-0 z-10 flex w-(--cue-space-5) cursor-pointer items-center justify-center text-fg-muted outline-none hover:text-fg focus-visible:outline-2 focus-visible:outline-solid focus-visible:-outline-offset-2 focus-visible:outline-accent";
+	return /* @__PURE__ */ jsxs(Fragment, { children: [edges.start ? /* @__PURE__ */ jsx("button", {
+		type: "button",
+		"data-slot": "edge-scroll-previous",
+		"aria-label": previousLabel,
+		onClick: () => onNudge(-1),
+		className: cn(base, "left-0", className),
+		children: /* @__PURE__ */ jsx(ChevronLeftGlyph, { className: "size-icon-sm" })
+	}) : null, edges.end ? /* @__PURE__ */ jsx("button", {
+		type: "button",
+		"data-slot": "edge-scroll-next",
+		"aria-label": nextLabel,
+		onClick: () => onNudge(1),
+		className: cn(base, "right-0", className),
+		children: /* @__PURE__ */ jsx(ChevronRightGlyph, { className: "size-icon-sm" })
+	}) : null] });
+}
+/**
+* A `<nav>` that scrolls its links, wrapped in the frame the chevrons need.
+*
+* A component rather than the hook that `Toolbar` and `SegmentedControl` use
+* directly, and for one specific reason: `AppBar` has to be renderable from a
+* **server component** — it is a site header, and the site header is where a
+* framework reads its data — so `app-bar.tsx` carries no `"use client"`
+* directive and cannot call a hook. The client boundary is here instead, around
+* the one part of a bar that has state.
+*/
+const EdgeScrollNav = React.forwardRef(function EdgeScrollNav({ className, frameClassName, scrolls = true, previousLabel, nextLabel, style, ...elementProps }, ref) {
+	const scroll = useEdgeScroll(scrolls);
+	const navRef = useComposedRefs(ref, scroll.ref);
+	return /* @__PURE__ */ jsxs("div", {
+		"data-slot": "app-bar-nav-frame",
+		className: cn("relative flex", frameClassName),
+		children: [/* @__PURE__ */ jsx("nav", {
+			ref: navRef,
+			className: cn(scrolls ? EDGE_SCROLLER_CLASSES : null, className),
+			...elementProps,
+			style: {
+				...style,
+				...scroll.style
+			}
+		}), /* @__PURE__ */ jsx(EdgeChevrons, {
+			edges: scroll.edges,
+			onNudge: scroll.nudge,
+			previousLabel,
+			nextLabel,
+			className: "bg-surface-1"
+		})]
+	});
+});
+//#endregion
+export { EDGE_SCROLLER_CLASSES, EdgeChevrons, EdgeScrollNav, useEdgeScroll };

package/dist/chrome/_glyphs.js

@@ -97,5 +97,23 @@ function EyeOffGlyph(props) {
 		children: [/* @__PURE__ */ jsx("path", { d: "M6.2 4A6.5 6.5 0 0 1 8 3.5C12 3.5 14.5 8 14.5 8a12 12 0 0 1-2.3 2.7M9.8 12a6.5 6.5 0 0 1-1.8.5C4 12.5 1.5 8 1.5 8A12 12 0 0 1 4.4 4.8" }), /* @__PURE__ */ jsx("path", { d: "m2.5 2.5 11 11" })]
 	});
 }
+/**
+* Three stacked strokes — the navigation trigger's mark.
+*
+* Only ever drawn below the shell's one breakpoint, where the navigation column
+* has become a drawer and the bar needs something to open it with.
+*/
+function MenuGlyph(props) {
+	return /* @__PURE__ */ jsx("svg", {
+		viewBox: "0 0 16 16",
+		fill: "none",
+		stroke: "currentColor",
+		strokeWidth: "1.75",
+		strokeLinecap: "round",
+		"aria-hidden": "true",
+		...props,
+		children: /* @__PURE__ */ jsx("path", { d: "M2.5 4h11M2.5 8h11M2.5 12h11" })
+	});
+}
 //#endregion
-export { CaretDownGlyph, ChevronLeftGlyph, ChevronRightGlyph, EyeGlyph, EyeOffGlyph, GhostGlyph };
+export { CaretDownGlyph, ChevronLeftGlyph, ChevronRightGlyph, EyeGlyph, EyeOffGlyph, GhostGlyph, MenuGlyph };

package/dist/chrome/_tabs-scroll.d.ts

@@ -1,14 +1,19 @@
 //#region src/chrome/_tabs-scroll.d.ts
 /**
- * Pure geometry for {@link ScrollableTabsList} (see `./tabs.tsx`).
+ * Pure geometry for the library's edge-scroll affordance.
  *
- * A separate module from the component on purpose. These are plain functions
+ * Written for {@link ScrollableTabsList} (see `./tabs.tsx`) and now the shared
+ * arithmetic under every strip in the system that can outgrow its container:
+ * the tab list, `Toolbar`, `SegmentedControl` and `AppBar`'s navigation all
+ * reach it through `./_edge-scroller`, which is where the React half lives.
+ *
+ * A separate module from the components on purpose. These are plain functions
  * over numbers — testable without a DOM, reusable by anything else that needs a
- * scroll-edge affordance — and keeping them out of the component file means the
- * component file can stay `"use client"` while this one has no directive at
- * all. (It is also what makes React Fast Refresh work on the component: a file
- * that exports both a component and non-component values gets a full reload
- * instead of a hot swap.)
+ * scroll-edge affordance — and keeping them out of a component file means that
+ * file can stay `"use client"` while this one has no directive at all. (It is
+ * also what makes React Fast Refresh work on the component: a file that exports
+ * both a component and non-component values gets a full reload instead of a hot
+ * swap.)
  */
 /** How far the fade reaches in from an overflowing edge, in px. */
 declare const TAB_FADE_PX = 24;
@@ -45,7 +50,7 @@ declare function computeScrollEdges(scrollLeft: number, scrollWidth: number, cli
  * an overlay would have to re-create that background as an opaque colour and
  * would drift the moment the theme changed. Masking fades the content itself
  * and lets whatever is behind show through, so it matches by construction in
- * all eight themes and both modes.
+ * every theme and both modes.
  *
  * This softens the cut; it is NOT the whole affordance. What sits at an
  * overflowing edge is often the gap between two tabs, and fading empty space is

package/dist/chrome/_tabs-scroll.js

@@ -1,14 +1,19 @@
 //#region src/chrome/_tabs-scroll.ts
 /**
-* Pure geometry for {@link ScrollableTabsList} (see `./tabs.tsx`).
+* Pure geometry for the library's edge-scroll affordance.
 *
-* A separate module from the component on purpose. These are plain functions
+* Written for {@link ScrollableTabsList} (see `./tabs.tsx`) and now the shared
+* arithmetic under every strip in the system that can outgrow its container:
+* the tab list, `Toolbar`, `SegmentedControl` and `AppBar`'s navigation all
+* reach it through `./_edge-scroller`, which is where the React half lives.
+*
+* A separate module from the components on purpose. These are plain functions
 * over numbers — testable without a DOM, reusable by anything else that needs a
-* scroll-edge affordance — and keeping them out of the component file means the
-* component file can stay `"use client"` while this one has no directive at
-* all. (It is also what makes React Fast Refresh work on the component: a file
-* that exports both a component and non-component values gets a full reload
-* instead of a hot swap.)
+* scroll-edge affordance — and keeping them out of a component file means that
+* file can stay `"use client"` while this one has no directive at all. (It is
+* also what makes React Fast Refresh work on the component: a file that exports
+* both a component and non-component values gets a full reload instead of a hot
+* swap.)
 */
 /** How far the fade reaches in from an overflowing edge, in px. */
 const TAB_FADE_PX = 24;
@@ -48,7 +53,7 @@ function computeScrollEdges(scrollLeft, scrollWidth, clientWidth) {
 * an overlay would have to re-create that background as an opaque colour and
 * would drift the moment the theme changed. Masking fades the content itself
 * and lets whatever is behind show through, so it matches by construction in
-* all eight themes and both modes.
+* every theme and both modes.
 *
 * This softens the cut; it is NOT the whole affordance. What sits at an
 * overflowing edge is often the gap between two tabs, and fading empty space is

package/dist/chrome/app-bar.d.ts

@@ -0,0 +1,103 @@
+import { BarOverflow } from "./_edge-scroller.js";
+import { LinkProps } from "../layout/link.js";
+import { SeparatorProps } from "../primitives/separator.js";
+import * as React from "react";
+//#region src/chrome/app-bar.d.ts
+interface AppBarRootProps extends React.ComponentPropsWithoutRef<"header"> {
+  /**
+   * Keep the bar at the top of the viewport as the page scrolls. Defaults to
+   * `true`.
+   *
+   * Set it `false` inside `AppShell`, where nothing scrolls the document and a
+   * sticky bar would be solving a problem the shell has already solved.
+   */
+  sticky?: boolean;
+}
+type AppBarBrandProps = Omit<LinkProps, "variant" | "external">;
+interface AppBarNavProps extends Omit<React.ComponentPropsWithoutRef<"nav">, "children"> {
+  /** Where the links sit when they are narrower than the space. Defaults to `"end"`. */
+  align?: "start" | "center" | "end";
+  /**
+   * What the navigation does when the links do not fit. Defaults to `"scroll"`.
+   *
+   * The same behaviour `Toolbar` and `SegmentedControl` have, from the same
+   * module: the links scroll inside the bar, the overflowing edge is faded and
+   * a pager chevron appears there. This is what lets the bar survive a phone
+   * without a viewport breakpoint.
+   */
+  overflow?: BarOverflow;
+  /** Accessible name for the chevron that reveals links off the leading edge. */
+  previousLabel?: string;
+  /** Accessible name for the chevron that reveals links off the trailing edge. */
+  nextLabel?: string;
+  /** Extra classes for the frame around the `<nav>`, which is what takes the remaining width. */
+  frameClassName?: string;
+  /** The links, and any separators between clusters of them. */
+  children?: React.ReactNode;
+}
+/**
+ * Which of the bar's two registers a link is set in.
+ *
+ * `muted` is furniture — the sections a reader scans past. `strong` is a
+ * destination, and the difference is the point: a run of eight identical muted
+ * words has no shape, and the one entry that matters disappears into it. Split
+ * the run with an {@link AppBarSeparator} and set the second cluster `strong`,
+ * and the bar reads as one list, differently weighted, rather than as two
+ * navigations.
+ */
+type AppBarRegister = "muted" | "strong";
+interface AppBarLinkProps extends LinkProps {
+  /** Which register the link is set in. Defaults to `"muted"`. */
+  register?: AppBarRegister;
+  /**
+   * This is the page the reader is on.
+   *
+   * Inks the link with the accent and sets `aria-current="page"` — the same
+   * bargain `Sidebar.Item` makes, so the current destination is announced and
+   * not merely coloured. Overrides `register`: a current page is never
+   * furniture.
+   */
+  active?: boolean;
+}
+type AppBarSeparatorProps = Omit<SeparatorProps, "orientation">;
+type AppBarActionsProps = React.ComponentPropsWithoutRef<"div">;
+/**
+ * The horizontal bar a site or an application wears across the top: brand slot,
+ * navigation slot, actions slot, one chrome rung tall.
+ *
+ * `AppShell` is the frame for a screen that owns the viewport; this is the bar
+ * for a document that scrolls — a marketing page, a documentation site, a
+ * console's public half. `NavigationMenu` is neither: it is the *menu* that
+ * goes inside `AppBar.Nav` when a section has children.
+ *
+ * Six parts. `Root` is the `<header>`, `Brand` the leading link, `Nav` the
+ * `<nav>` landmark that takes the remaining width and scrolls when the links
+ * outgrow it, `Link` one destination in one of two registers, `Separator` the
+ * seam between clusters, and `Actions` the trailing controls.
+ *
+ * @example
+ * <AppBar.Root>
+ *   <AppBar.Brand render={<NextLink href="/" />}>
+ *     <Eyebrow>@cueplusplus/ui</Eyebrow>
+ *   </AppBar.Brand>
+ *   <AppBar.Nav aria-label="Sections">
+ *     <AppBar.Link render={<NextLink href="/docs" />}>Docs</AppBar.Link>
+ *     <AppBar.Link render={<NextLink href="/theming" />}>Theming</AppBar.Link>
+ *     <AppBar.Separator />
+ *     <AppBar.Link render={<NextLink href="/gallery" />} register="strong">Gallery</AppBar.Link>
+ *     <AppBar.Link external render={<a href="https://skills.cueplusplus.com" />}>Skills</AppBar.Link>
+ *   </AppBar.Nav>
+ *   <AppBar.Separator />
+ *   <AppBar.Actions><ThemePicker /></AppBar.Actions>
+ * </AppBar.Root>
+ */
+declare const AppBar: {
+  Root: React.ForwardRefExoticComponent<AppBarRootProps & React.RefAttributes<HTMLElement>>;
+  Brand: React.ForwardRefExoticComponent<AppBarBrandProps & React.RefAttributes<HTMLAnchorElement>>;
+  Nav: React.ForwardRefExoticComponent<AppBarNavProps & React.RefAttributes<HTMLElement>>;
+  Link: React.ForwardRefExoticComponent<AppBarLinkProps & React.RefAttributes<HTMLAnchorElement>>;
+  Separator: React.ForwardRefExoticComponent<Omit<AppBarSeparatorProps, "ref"> & React.RefAttributes<HTMLDivElement>>;
+  Actions: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+};
+//#endregion
+export { AppBar, AppBarActionsProps, AppBarBrandProps, AppBarLinkProps, AppBarNavProps, AppBarRegister, AppBarRootProps, AppBarSeparatorProps };

package/dist/chrome/app-bar.js

@@ -0,0 +1,175 @@
+import { cn } from "../lib/cn.js";
+import { Link } from "../layout/link.js";
+import { Separator } from "../primitives/separator.js";
+import { EdgeScrollNav } from "./_edge-scroller.js";
+import * as React from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/chrome/app-bar.tsx
+/**
+* The bar across the top of a document: brand, navigation, actions.
+*
+* One rung of the chrome ladder tall, from `--cue-chrome-toolbar` — the same
+* token `Toolbar` and the docs site's hand-rolled header use, so a page that
+* stacks a bar on a toolbar gets two equal strips rather than two guesses.
+*
+* Sticky by default, and translucent because of it: a bar pinned over scrolling
+* content needs a ground, and `bg-surface-1/95` plus `backdrop-blur` says
+* "there is content under this" where an opaque fill would claim the content
+* ends here. `z-40` is above the page and below the `z-50` this library's
+* overlays float at, so a menu opened from the bar is never behind it.
+*
+* **This is a bar, not a menu.** `NavigationMenu` is the mega-menu — triggers
+* that open panels — and it goes *inside* an `AppBar.Nav` when a section has
+* children. This component is the strip it sits in.
+*
+* Static markup — no `"use client"` on this module, deliberately: a site header
+* is where a framework reads its data, so the bar has to be renderable from a
+* server component. The one part with state is the navigation's scroller, and
+* the client boundary is drawn around that alone (`_edge-scroller.tsx`).
+*
+* It adds **no viewport breakpoint**. `AppShell` holds the library's only one,
+* for navigation shape, and a horizontal bar does not need it: the brand and
+* the actions are `shrink-0`, the navigation between them takes the remaining
+* width and scrolls inside it, so a 390px viewport gets the same bar with a
+* shorter window onto the same links rather than a second layout to maintain.
+*
+* @example
+* <AppBar.Root>
+*   <AppBar.Brand render={<NextLink href="/" />}>
+*     <Eyebrow>@cueplusplus/ui</Eyebrow>
+*     <Chip tone="accent" variant="outline">0.1.0</Chip>
+*   </AppBar.Brand>
+*   <AppBar.Nav aria-label="Sections">
+*     <AppBar.Link render={<NextLink href="/docs" />}>Docs</AppBar.Link>
+*     <AppBar.Separator />
+*     <AppBar.Link render={<NextLink href="/gallery" />} register="strong">Gallery</AppBar.Link>
+*   </AppBar.Nav>
+*   <AppBar.Actions>
+*     <ThemePicker />
+*   </AppBar.Actions>
+* </AppBar.Root>
+*/
+const AppBarRoot = React.forwardRef(function AppBarRoot({ className, sticky = true, ...elementProps }, ref) {
+	return /* @__PURE__ */ jsx("header", {
+		ref,
+		"data-slot": "app-bar",
+		className: cn("flex h-(--cue-chrome-toolbar) w-full shrink-0 items-center gap-(--cue-space-4) border-b border-border bg-surface-1/95 px-(--cue-space-5) backdrop-blur", sticky ? "sticky top-0 z-40" : null, className),
+		...elementProps
+	});
+});
+/**
+* The leading slot, and the way home.
+*
+* A link rather than a box, because that is what a brand in a bar is: pass
+* `href`, or `render={<NextLink href="/" />}` to go through a router. It sets
+* the bar's own type register (mono, UI size, full-contrast ink) so a wordmark
+* and a version chip sit on one baseline without a class of their own.
+*
+* `shrink-0`: the brand is the one thing in the bar that must never be
+* compressed, because a half-drawn wordmark reads as a broken page.
+*/
+const AppBarBrand = React.forwardRef(function AppBarBrand({ className, ...linkProps }, ref) {
+	return /* @__PURE__ */ jsx(Link, {
+		ref,
+		className: cn("flex shrink-0 items-center gap-(--cue-space-3) font-mono text-(length:--cue-text-ui) text-fg", className),
+		...linkProps
+	});
+});
+/** Where a nav that does not fill its frame sits. */
+const NAV_ALIGN = {
+	start: "justify-start",
+	center: "justify-center",
+	end: "justify-end"
+};
+/**
+* The `<nav>` landmark between the brand and the actions, and the one part of
+* the bar that gives up width.
+*
+* Name it: `aria-label="Sections"`, or whatever this bar's links are. A
+* document with more than one navigation and no names on them is a screen
+* reader listing "navigation, navigation".
+*
+* The alignment sits on the frame rather than on the scrolling `<nav>` itself,
+* and that is load-bearing: `justify-content: flex-end` on a scroll container
+* pushes the overflow off the *start* edge, where several browsers cannot
+* scroll to reach it. Aligning the frame and letting the nav grow from its
+* start keeps every link reachable at every width.
+*/
+const AppBarNav = React.forwardRef(function AppBarNav({ className, frameClassName, align = "end", overflow = "scroll", previousLabel = "Show earlier links", nextLabel = "Show later links", ...elementProps }, ref) {
+	return /* @__PURE__ */ jsx(EdgeScrollNav, {
+		ref,
+		"data-slot": "app-bar-nav",
+		scrolls: overflow === "scroll",
+		previousLabel,
+		nextLabel,
+		frameClassName: cn("min-w-0 flex-1", NAV_ALIGN[align], frameClassName),
+		className: cn("flex min-w-0 items-center gap-(--cue-space-4)", className),
+		...elementProps
+	});
+});
+const REGISTERS = {
+	muted: "text-fg-muted",
+	strong: "text-fg"
+};
+/**
+* The horizontal bar a site or an application wears across the top: brand slot,
+* navigation slot, actions slot, one chrome rung tall.
+*
+* `AppShell` is the frame for a screen that owns the viewport; this is the bar
+* for a document that scrolls — a marketing page, a documentation site, a
+* console's public half. `NavigationMenu` is neither: it is the *menu* that
+* goes inside `AppBar.Nav` when a section has children.
+*
+* Six parts. `Root` is the `<header>`, `Brand` the leading link, `Nav` the
+* `<nav>` landmark that takes the remaining width and scrolls when the links
+* outgrow it, `Link` one destination in one of two registers, `Separator` the
+* seam between clusters, and `Actions` the trailing controls.
+*
+* @example
+* <AppBar.Root>
+*   <AppBar.Brand render={<NextLink href="/" />}>
+*     <Eyebrow>@cueplusplus/ui</Eyebrow>
+*   </AppBar.Brand>
+*   <AppBar.Nav aria-label="Sections">
+*     <AppBar.Link render={<NextLink href="/docs" />}>Docs</AppBar.Link>
+*     <AppBar.Link render={<NextLink href="/theming" />}>Theming</AppBar.Link>
+*     <AppBar.Separator />
+*     <AppBar.Link render={<NextLink href="/gallery" />} register="strong">Gallery</AppBar.Link>
+*     <AppBar.Link external render={<a href="https://skills.cueplusplus.com" />}>Skills</AppBar.Link>
+*   </AppBar.Nav>
+*   <AppBar.Separator />
+*   <AppBar.Actions><ThemePicker /></AppBar.Actions>
+* </AppBar.Root>
+*/
+const AppBar = {
+	Root: AppBarRoot,
+	Brand: AppBarBrand,
+	Nav: AppBarNav,
+	Link: React.forwardRef(function AppBarLink({ className, register = "muted", active = false, ...linkProps }, ref) {
+		return /* @__PURE__ */ jsx(Link, {
+			ref,
+			"data-active": active ? "" : void 0,
+			"aria-current": active ? "page" : void 0,
+			className: cn("shrink-0 font-mono text-(length:--cue-text-ui)", active ? "text-accent" : REGISTERS[register], className),
+			...linkProps
+		});
+	}),
+	Separator: React.forwardRef(function AppBarSeparator({ className, ...elementProps }, ref) {
+		return /* @__PURE__ */ jsx(Separator, {
+			ref,
+			orientation: "vertical",
+			className: cn("h-(--cue-space-5)", className),
+			...elementProps
+		});
+	}),
+	Actions: React.forwardRef(function AppBarActions({ className, ...elementProps }, ref) {
+		return /* @__PURE__ */ jsx("div", {
+			ref,
+			"data-slot": "app-bar-actions",
+			className: cn("flex shrink-0 items-center gap-(--cue-space-4)", className),
+			...elementProps
+		});
+	})
+};
+//#endregion
+export { AppBar };

package/dist/chrome/app-shell.d.ts

@@ -0,0 +1,125 @@
+import { SidebarLandmark, SidebarRootProps } from "../layout/sidebar.js";
+import * as React from "react";
+//#region src/chrome/app-shell.d.ts
+interface AppShellRootProps extends React.ComponentPropsWithoutRef<"div"> {
+  /** Whether the mobile navigation drawer is open, when controlled. Pass with `onNavOpenChange`. */
+  navOpen?: boolean;
+  /** Initial open state of the mobile navigation drawer when uncontrolled. Defaults to `false`. */
+  defaultNavOpen?: boolean;
+  /** Called with the next open state whenever the drawer is opened or dismissed. */
+  onNavOpenChange?: (open: boolean) => void;
+}
+type AppShellBodyProps = React.ComponentPropsWithoutRef<"div">;
+interface AppShellSidebarProps extends SidebarRootProps {
+  /** The drawer's heading, and its accessible name. Defaults to `"Navigation"`. */
+  drawerTitle?: React.ReactNode;
+  /** Accessible name for the drawer's close affordance. Defaults to `"Close navigation"`. */
+  closeLabel?: string;
+  /** Extra classes for the drawer's popup surface. */
+  drawerClassName?: string;
+  /**
+   * Draw the column's collapse rail. Defaults to `true`.
+   *
+   * The shell renders the `Sidebar.Rail` itself rather than taking one in
+   * `children`, because collapsing is a property of the *column* and the same
+   * children are also the drawer's: a rail passed as a child would be laid out
+   * inside the overlay, where there is nothing to collapse.
+   */
+  collapsible?: boolean;
+  /**
+   * Which landmark **both** shapes announce as. Defaults to `"navigation"`.
+   *
+   * One prop rather than two, because the column and the drawer are one
+   * navigation wearing two shapes: the answer cannot differ by viewport.
+   */
+  landmark?: SidebarLandmark;
+}
+interface AppShellNavTriggerProps extends Omit<React.ComponentPropsWithoutRef<"button">, "children"> {
+  /** Accessible name for the control. Defaults to `"Open navigation"`. */
+  label?: string;
+  /** The icon it draws. Defaults to the shell's own three-stroke glyph. */
+  icon?: React.ElementType;
+  /**
+   * Which rung of the control ladder the button takes. Defaults to `"md"`.
+   *
+   * The rest of the window furniture in this library is built at `"sm"`, and
+   * that is right for a mouse — but this control renders *only* below the `md`
+   * breakpoint, which is to say only on a touch screen, where `sm` (20px at
+   * normal density) is under the 24×24 CSS-pixel floor WCAG 2.2 SC 2.5.8 sets.
+   * `"md"` is 24px at normal and large, and the token layer's
+   * `@media (pointer: coarse)` rule lifts ultra-compact to the same 24px, so
+   * the default clears the floor at every density a finger can reach it at.
+   */
+  size?: "sm" | "md" | "lg";
+}
+interface AppShellContentProps extends React.ComponentPropsWithoutRef<"main"> {
+  /**
+   * Render the `<main>` landmark. Defaults to `true`.
+   *
+   * Set it `false` when the shell is embedded in a document that already has a
+   * `<main>` — a specimen, a screenshot, a shell shown inside a device frame on
+   * a page of prose. A document may have only one, and a nested one is a defect
+   * rather than a nicety.
+   */
+  main?: boolean;
+}
+interface AppShellScrollerProps extends React.ComponentPropsWithoutRef<"div"> {
+  /** Draw the standard work-area gutters. Defaults to `true`. */
+  padded?: boolean;
+}
+interface AppShellAsideProps extends React.ComponentPropsWithoutRef<"aside"> {
+  /** Width of the column. Any CSS length. Defaults to `"18rem"`. */
+  width?: string;
+}
+/**
+ * The console frame: title bar, navigation, work area, status bar — one
+ * viewport tall, with exactly one thing scrolling.
+ *
+ * Every console screen in this system is the same five parts in the same
+ * arrangement, and the value here is not the parts (they already exist as
+ * `TitleBar`, `Sidebar`, `Toolbar` and `StatusBar`) but the arithmetic between
+ * them: `h-dvh` on the frame rather than `min-h-dvh`, an unbroken `min-h-0`
+ * chain from the frame down to the scroller, `min-w-0` on the content column,
+ * and a scroller that is not the document. Get one of those wrong and the
+ * status bar leaves the screen or the navigation column gets shoved off the
+ * side; the shell exists so no page has to get them right again.
+ *
+ * The bars are ordinary children — `TitleBar` and `StatusBar` are already
+ * `shrink-0` and need no wrapper — so a shell reads as the page's outline.
+ *
+ * This is also the only component in the library with a viewport breakpoint:
+ * below `md` the navigation column becomes a drawer and a trigger appears in
+ * the bar. See {@link AppShellSidebar} for the ruling.
+ *
+ * @example
+ * <AppShell.Root>
+ *   <TitleBar center="main-stage.cue" actions={<Chip tone="ok">live</Chip>}>
+ *     <AppShell.NavTrigger />
+ *     <Eyebrow>CUE++</Eyebrow>
+ *   </TitleBar>
+ *   <AppShell.Body>
+ *     <AppShell.Sidebar aria-label="Console" drawerTitle="Console">
+ *       <Sidebar.Section label="Show">
+ *         <Sidebar.Item icon={List} active>Cues</Sidebar.Item>
+ *       </Sidebar.Section>
+ *     </AppShell.Sidebar>
+ *     <AppShell.Content>
+ *       <Toolbar.Root aria-label="Playback"><Toolbar.Button icon={Play}>Go</Toolbar.Button></Toolbar.Root>
+ *       <AppShell.Scroller><Panel>…</Panel></AppShell.Scroller>
+ *     </AppShell.Content>
+ *     <AppShell.Aside aria-label="Inspector">…</AppShell.Aside>
+ *   </AppShell.Body>
+ *   <StatusBar><StatusBar.Item tone="ok">Art-Net</StatusBar.Item></StatusBar>
+ * </AppShell.Root>
+ */
+declare const AppShell: {
+  Root: React.ForwardRefExoticComponent<AppShellRootProps & React.RefAttributes<HTMLDivElement>>;
+  Body: React.ForwardRefExoticComponent<Omit<React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref"> & React.RefAttributes<HTMLDivElement>>;
+  Sidebar: React.ForwardRefExoticComponent<AppShellSidebarProps & React.RefAttributes<HTMLElement>>;
+  NavTrigger: React.ForwardRefExoticComponent<AppShellNavTriggerProps & React.RefAttributes<HTMLButtonElement>>;
+  Content: React.ForwardRefExoticComponent<AppShellContentProps & React.RefAttributes<HTMLElement>>;
+  Scroller: React.ForwardRefExoticComponent<AppShellScrollerProps & React.RefAttributes<HTMLDivElement>>;
+  Aside: React.ForwardRefExoticComponent<AppShellAsideProps & React.RefAttributes<HTMLElement>>;
+};
+//#endregion
+export { AppShell, AppShellAsideProps, AppShellBodyProps, AppShellContentProps, AppShellNavTriggerProps, AppShellRootProps, AppShellScrollerProps, AppShellSidebarProps };