@cueplusplus/ui 0.13.0

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,243 @@
+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;
+  /**
+   * Whether the navigation column is collapsed to an icon rail, when
+   * controlled. Pass with `onRailChange`. Defaults to expanded.
+   *
+   * It is the column's own collapse, owned one level up. Collapsing is a
+   * property of the column, but the header cell over it is a child of the bar
+   * — a different branch of the tree — and a length only one of them knows is
+   * a length they will eventually disagree about. So the frame holds the
+   * state, stamps `data-rail` on itself for anything that has to answer to it,
+   * and hands it down to `Sidebar.Root` as its controlled `collapsed`.
+   *
+   * **Persistence is the caller's.** A rail is set once and expected to be
+   * remembered, and where it is remembered — `localStorage`, a cookie the
+   * server can read before first paint, a user record — is a decision about
+   * hydration and privacy that a layout component has no business making.
+   */
+  rail?: boolean;
+  /** Initial rail state when uncontrolled. Defaults to `false`. */
+  defaultRail?: boolean;
+  /** Called with the next rail state whenever the column is collapsed or expanded. */
+  onRailChange?: (rail: boolean) => void;
+  /** Width of the navigation column while expanded. Any CSS length. Defaults to `"14rem"`. */
+  navWidth?: string;
+  /**
+   * Width of the navigation column while railed. Any CSS length. Defaults to
+   * `"3.5rem"` — a `--cue-icon-md` glyph centred in a `--cue-control-md` row,
+   * with a gutter either side that still reads as a column rather than a strip.
+   */
+  railWidth?: string;
+}
+interface AppShellBarProps extends React.ComponentPropsWithoutRef<"div"> {
+  /**
+   * The header cell over the navigation column: the app mark, and whatever
+   * control rails it.
+   *
+   * Omit it and the bar is one undivided strip — no empty bordered cell, which
+   * is worse than no cell.
+   */
+  brand?: React.ReactNode;
+  /**
+   * Extra classes for the header cell — the bordered box that spans the
+   * navigation column, not the row of brand content inside it. Anything about
+   * the cell's width, rim or gutter belongs here; anything about how the mark
+   * and its controls sit belongs on the nodes passed as `brand`.
+   */
+  brandClassName?: string;
+  /**
+   * Make the bar's dead space a window drag handle. Defaults to `false`.
+   *
+   * This is the same contract {@link TitleBar} has always offered, on the bar
+   * a console with a navigation column actually uses — a desktop app should
+   * not need a `TitleBar` *and* an `AppShell.Bar` stacked on top of each other
+   * to get one draggable row, which is two chrome rungs of a small window
+   * spent on furniture.
+   *
+   * Every structural surface is attributed and every interactive cluster is
+   * carved back out, because the two shells this ships into fail in opposite
+   * directions. Tauri matches the *exact* element under the cursor, so the
+   * brand cell and the rest cell carry the attribute themselves — a click on
+   * the cell's own dead space targets the cell, never the root beneath it, and
+   * a bar that only attributed its root would be draggable nowhere. Electron
+   * builds a geometric mask from painted boxes instead and excludes nothing on
+   * its own, so the brand content, the leading children and `actions` each sit
+   * in a cluster marked `app-region: no-drag` — without it a button that merely
+   * overlaps the bar stops receiving clicks at all. See `./_drag.ts`.
+   *
+   * **It changes how the clusters are sized, and that is a trade.** Off, each
+   * cluster grows into its cell, so a caller's own `ms-auto` reaches the cell's
+   * trailing rim. On, the clusters take their content's width and `actions` is
+   * pushed over with `ms-auto` instead, because a cluster that fills its cell
+   * is a `no-drag` rectangle painted over every dead pixel the cell just
+   * attributed — the bar would be draggable nowhere but its paddings and its
+   * one gap. The dead area belongs to the window in drag mode, and a caller who
+   * needs content to reach the rim there should say so on a box of their own
+   * inside the cluster.
+   *
+   * `select-none` comes with it: dragging a window and selecting the text you
+   * started the drag on are the same gesture, and the shell wins.
+   *
+   * Not wired here: double-click-to-maximise. Tauri's injected script already
+   * does it for any drag region, macOS's cancel-by-dragging-away included.
+   * Electron does not, and an Electron app has to listen for `dblclick` and
+   * toggle the window itself. Which of those an app is, is not something a
+   * layout component can know.
+   */
+  platformDrag?: boolean;
+  /**
+   * A title centred on the **bar**, not between the cells beside it.
+   *
+   * Absolutely positioned against the bar's own box, so it stays put when a
+   * button appears in `actions` or the column rails — the whole reason a
+   * document name in desktop chrome is not just another flex child.
+   * `pointer-events-none` so the dead space around a short title still drags,
+   * which is also what makes it click through to the drag surface underneath
+   * in Tauri, whose hit-testing is the browser's own.
+   *
+   * Inert by construction. Anything the reader has to click belongs in
+   * `actions` or in `children`, where it can be carved out of the drag region.
+   */
+  center?: React.ReactNode;
+  /**
+   * The trailing cluster: connection state, a run indicator, an overflow menu.
+   *
+   * Pinned to the bar's trailing edge and never squeezed, so it reads as window
+   * furniture rather than the end of a sentence. `children` keeps flowing into
+   * the same cell ahead of it, which is what lets an existing web-shell caller
+   * pass free-form content and gain a cluster without rearranging anything.
+   */
+  actions?: React.ReactNode;
+}
+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. The
+ * one bar the shell does own is {@link AppShellBar}, and it owns it for one
+ * reason: it is divided by the navigation column, which means it has to be
+ * measured from the same length the column is.
+ *
+ * That length is `--cue-nav-width`, written on the frame. `rail` rewrites it,
+ * `data-rail` announces it, and the column and the header cell over it move
+ * together because neither holds a width of its own. Persistence and the
+ * toggle are the caller's — see {@link AppShellRootProps.rail}.
+ *
+ * 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>>;
+  Bar: React.ForwardRefExoticComponent<AppShellBarProps & 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, AppShellBarProps, AppShellBodyProps, AppShellContentProps, AppShellNavTriggerProps, AppShellRootProps, AppShellScrollerProps, AppShellSidebarProps };