@charcuterie/ui 2.9.0 → 2.10.0

package/README.md

@@ -38,6 +38,15 @@ The router is **injected** rather than depended on — `RouterLinkProvider` at t
 with `@charcuterie/ui/react-router` as an optional subpath adapter and a plain `<a>` when
 nothing is provided. Recipe: **Guides/Routing** in Storybook.
 
+**The unified app shell adds four**: `Shell`, `Header`, `Rail`, `Main` — the fleet's largest
+single duplication, where ten of twelve UI repos hand-roll the page chrome and three of them
+have a file named `AppShell.tsx` (two of those headers are a *byte-identical* class string,
+arrived at independently). One `contentWidth` on `Shell` feeds both the header row and the
+content column, `isSticky` writes `position` and `z-index` together, and a `Rail` collapses
+by restyling rather than by rendering itself twice.
+[Decision](../../docs/decisions/2026-08-10-the-app-shell-is-shell-header-rail-main.md);
+`Shell`'s docs page carries three copy-wholesale templates.
+
 ## Install and wire
 
 ```ts

package/dist/Header/Header.d.ts

@@ -0,0 +1,52 @@
+import { type ComponentPropsWithRef, type ReactNode } from "react";
+import { type ContentWidth } from "../Shell/contentWidth.ts";
+export type HeaderProps = ComponentPropsWithRef<"header"> & {
+    actions?: ReactNode;
+    contentWidth?: ContentWidth;
+    heading?: string;
+    headingLevel?: 1 | 2;
+    isSticky?: boolean;
+};
+/**
+ * The page header — the `<header>` landmark, the app's name, and
+ * the controls that belong to the frame rather than to the page.
+ *
+ * **`isSticky` defaults to true, and it sets `position` as well as
+ * `z-index`.** That pairing is the whole point. mux-magic's
+ * `PageHeader` is documented as a sticky header and sets only
+ * `z-index` (`PageHeader.tsx:173`) — it is a flex-column shell that
+ * scrolls away like any other block, and the z-index it carries
+ * has nothing to stack against. The bug is invisible: the CSS is
+ * valid, the intent is stated in a comment, and nobody scrolls a
+ * component in a review. Here the two cannot come apart, because
+ * one boolean writes both.
+ *
+ * The z-index is `--layer-sticky` from the token scale, never a
+ * hand-picked number. The fleet's headers currently sit at `z-40`
+ * (mail-sifter, points-market), `z-50` (rip-deck), `z-10`
+ * (spoolbuddy) and `z-[100]` (mux-magic), with no ordering
+ * guarantee between a header and anything else — which is exactly
+ * what the scale exists to settle: `sticky` (100) is below
+ * `dropdown` (200), `modal` (400) and `toast` (500), so a menu
+ * opened *from* the header paints over it.
+ *
+ * ## The width comes from `Shell`
+ *
+ * The `<header>` itself is full-bleed — the border and the
+ * translucent fill run edge to edge — and only its **inner row** is
+ * capped, which is what makes a constrained header look right on an
+ * ultrawide. That cap is `Shell`'s `contentWidth`, not a second
+ * opinion: see `shellContext.ts` for the shipped app whose header
+ * and `<main>` disagree by 80rem.
+ *
+ * ## No invented colours
+ *
+ * `bg-surface-raised/85` + `backdrop-blur-md` + `border-border-subtle`.
+ * The fleet's copy of this line is `bg-surface-base/90`, which puts
+ * the header at the *same* colour as the page behind it and leans
+ * entirely on the blur to separate them — so it vanishes against a
+ * page that is not scrolled. `raised` means *more separated from
+ * base*, which is the role this element actually wants.
+ */
+export declare const Header: ({ actions, children, className, contentWidth, heading, headingLevel, isSticky, ...headerProps }: HeaderProps) => ReactNode;
+//# sourceMappingURL=Header.d.ts.map

package/dist/Header/Header.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Header.d.ts","sourceRoot":"","sources":["../../src/Header/Header.tsx"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,SAAS,EAEf,MAAM,OAAO,CAAA;AAEd,OAAO,EACL,KAAK,YAAY,EAGlB,MAAM,0BAA0B,CAAA;AAIjC,MAAM,MAAM,WAAW,GACrB,qBAAqB,CAAC,QAAQ,CAAC,GAAG;IAChC,OAAO,CAAC,EAAE,SAAS,CAAA;IACnB,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,CAAA;IACpB,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,eAAO,MAAM,MAAM,GAAI,iGASpB,WAAW,KAAG,SA4ChB,CAAA"}

package/dist/Header/Header.js

@@ -0,0 +1,55 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useContext, } from "react";
+import { DEFAULT_CONTENT_WIDTH, toMaxInlineSize, } from "../Shell/contentWidth.js";
+import { ShellContext } from "../Shell/shellContext.js";
+import { toClassName } from "../toClassName.js";
+/**
+ * The page header — the `<header>` landmark, the app's name, and
+ * the controls that belong to the frame rather than to the page.
+ *
+ * **`isSticky` defaults to true, and it sets `position` as well as
+ * `z-index`.** That pairing is the whole point. mux-magic's
+ * `PageHeader` is documented as a sticky header and sets only
+ * `z-index` (`PageHeader.tsx:173`) — it is a flex-column shell that
+ * scrolls away like any other block, and the z-index it carries
+ * has nothing to stack against. The bug is invisible: the CSS is
+ * valid, the intent is stated in a comment, and nobody scrolls a
+ * component in a review. Here the two cannot come apart, because
+ * one boolean writes both.
+ *
+ * The z-index is `--layer-sticky` from the token scale, never a
+ * hand-picked number. The fleet's headers currently sit at `z-40`
+ * (mail-sifter, points-market), `z-50` (rip-deck), `z-10`
+ * (spoolbuddy) and `z-[100]` (mux-magic), with no ordering
+ * guarantee between a header and anything else — which is exactly
+ * what the scale exists to settle: `sticky` (100) is below
+ * `dropdown` (200), `modal` (400) and `toast` (500), so a menu
+ * opened *from* the header paints over it.
+ *
+ * ## The width comes from `Shell`
+ *
+ * The `<header>` itself is full-bleed — the border and the
+ * translucent fill run edge to edge — and only its **inner row** is
+ * capped, which is what makes a constrained header look right on an
+ * ultrawide. That cap is `Shell`'s `contentWidth`, not a second
+ * opinion: see `shellContext.ts` for the shipped app whose header
+ * and `<main>` disagree by 80rem.
+ *
+ * ## No invented colours
+ *
+ * `bg-surface-raised/85` + `backdrop-blur-md` + `border-border-subtle`.
+ * The fleet's copy of this line is `bg-surface-base/90`, which puts
+ * the header at the *same* colour as the page behind it and leans
+ * entirely on the blur to separate them — so it vanishes against a
+ * page that is not scrolled. `raised` means *more separated from
+ * base*, which is the role this element actually wants.
+ */
+export const Header = ({ actions, children, className, contentWidth, heading, headingLevel = 1, isSticky = true, ...headerProps }) => {
+    const shell = useContext(ShellContext);
+    const Heading = `h${headingLevel}`;
+    const maxInlineSize = toMaxInlineSize(contentWidth ??
+        shell?.contentWidth ??
+        DEFAULT_CONTENT_WIDTH);
+    return (_jsx("header", { ...headerProps, className: toClassName("col-span-full row-start-1 border-border-subtle border-b bg-surface-raised/85 backdrop-blur-md", isSticky && "sticky top-0 z-[var(--layer-sticky)]", className), children: _jsxs("div", { className: "mx-auto flex w-full min-w-0 flex-wrap items-center gap-3 px-4 py-3 sm:px-6", style: { maxInlineSize }, children: [heading ? (_jsx(Heading, { className: "min-w-0 truncate font-semibold text-lg leading-tight", children: heading })) : null, children ? (_jsx("div", { className: "flex min-w-0 flex-1 items-center gap-2", children: children })) : null, actions ? (_jsx("div", { className: "ms-auto flex shrink-0 items-center gap-2", children: actions })) : null] }) }));
+};
+//# sourceMappingURL=Header.js.map

package/dist/Header/Header.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Header.js","sourceRoot":"","sources":["../../src/Header/Header.tsx"],"names":[],"mappings":";AAAA,OAAO,EAGL,UAAU,GACX,MAAM,OAAO,CAAA;AAEd,OAAO,EAEL,qBAAqB,EACrB,eAAe,GAChB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAW/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,MAAM,CAAC,MAAM,MAAM,GAAG,CAAC,EACrB,OAAO,EACP,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,OAAO,EACP,YAAY,GAAG,CAAC,EAChB,QAAQ,GAAG,IAAI,EACf,GAAG,WAAW,EACF,EAAa,EAAE;IAC3B,MAAM,KAAK,GAAG,UAAU,CAAC,YAAY,CAAC,CAAA;IAEtC,MAAM,OAAO,GAAG,IAAI,YAAY,EAAW,CAAA;IAE3C,MAAM,aAAa,GAAG,eAAe,CACnC,YAAY;QACV,KAAK,EAAE,YAAY;QACnB,qBAAqB,CACxB,CAAA;IAED,OAAO,CACL,oBACM,WAAW,EACf,SAAS,EAAE,WAAW,CACpB,+FAA+F,EAC/F,QAAQ,IAAI,sCAAsC,EAClD,SAAS,CACV,YAED,eACE,SAAS,EAAC,4EAA4E,EACtF,KAAK,EAAE,EAAE,aAAa,EAAE,aAEvB,OAAO,CAAC,CAAC,CAAC,CACT,KAAC,OAAO,IAAC,SAAS,EAAC,sDAAsD,YACtE,OAAO,GACA,CACX,CAAC,CAAC,CAAC,IAAI,EAEP,QAAQ,CAAC,CAAC,CAAC,CACV,cAAK,SAAS,EAAC,wCAAwC,YACpD,QAAQ,GACL,CACP,CAAC,CAAC,CAAC,IAAI,EAEP,OAAO,CAAC,CAAC,CAAC,CACT,cAAK,SAAS,EAAC,0CAA0C,YACtD,OAAO,GACJ,CACP,CAAC,CAAC,CAAC,IAAI,IACJ,GACC,CACV,CAAA;AACH,CAAC,CAAA"}

package/dist/Main/Main.d.ts

@@ -0,0 +1,113 @@
+import { type ComponentPropsWithRef, type ReactNode } from "react";
+import { type ContentWidth } from "../Shell/contentWidth.ts";
+export type MainProps = ComponentPropsWithRef<"main"> & {
+    contentWidth?: ContentWidth;
+};
+/**
+ * The `<main>` landmark and the content column.
+ *
+ * ## The width is the whole component
+ *
+ * The owner's complaint, verbatim:
+ *
+ * > "All these apps seem to be really narrow with a very large
+ * > max-width. By that I mean 1 column, but waaaaaaay too wide. In
+ * > almost all cases, what I really want is something like Rip-Deck
+ * > where the app has a narrower main column but the wrapping grids
+ * > are all full-width in most of these apps only when you have too
+ * > many items."
+ *
+ * That is two requirements, and they pull opposite ways: a
+ * **narrow** column by default, which **widens** when the content
+ * is a grid with enough items to justify it. A fixed `max-w-7xl`
+ * answers neither — it is too wide for the one-column case, which
+ * is the complaint, and it is a hard ceiling on the many-items
+ * case.
+ *
+ * So the cap is a *value*, not a constant, and it arrives from
+ * three places in priority order: this component's own
+ * `contentWidth`, then `Shell`'s (the usual answer, so the header
+ * matches), then `screen.lg`.
+ *
+ * ### How it composes with the adaptive-columns hook
+ *
+ * rip-deck's `useLayoutColumns` — being lifted into this library
+ * separately — decides a column count from the viewport and folds
+ * it into a page cap with `contentMaxWidthRem(columns)`: 1 column →
+ * 56rem, 2 → 72rem, 3 → 106rem. It returns a **number of rem**, and
+ * `ContentWidth` accepts `` `${number}rem` `` for exactly this:
+ *
+ * ```tsx
+ * const { columns } = useLayoutColumns({ cardCount: bays.length })
+ *
+ * <Shell contentWidth={`${contentMaxWidthRem(columns)}rem`}>
+ *   <Header heading="Rip Deck" />
+ *   <Main>
+ *     <BayGrid columns={columns} />
+ *   </Main>
+ * </Shell>
+ * ```
+ *
+ * The seam is deliberately one prop and no hook import: this
+ * package must not depend on a layout hook to lay out a page, and
+ * the hook must not know that a `Shell` exists. Putting the value
+ * on `Shell` rather than on `Main` is what keeps the header's cap
+ * in step with the column's as the count changes.
+ *
+ * ## `@container`, and what `contain: inline-size` costs
+ *
+ * The content column establishes a container query, so an app's
+ * grids inside it respond to **the column's** width rather than
+ * the window's — a poster grid beside an open rail and the same
+ * grid full-bleed are the pair a media query cannot tell apart,
+ * and getting it wrong at intermediate widths is what the fleet's
+ * grids do today.
+ *
+ * `container-type: inline-size` implies `contain: layout style
+ * inline-size`, and both halves have consequences worth stating:
+ *
+ *  - **The element may not be sized by its own contents.** Here
+ *    that is free and in fact wanted: the column has a definite
+ *    inline size from its parent — itself a grid item with
+ *    `minmax(0, 1fr)` — so wide content can no longer widen it,
+ *    which is half of why the page does not scroll sideways.
+ *  - **`contain: layout` makes it a containing block for
+ *    `position: fixed` descendants.** An app rendering a fixed
+ *    element *inside* `Main` gets it positioned against the
+ *    column, not the viewport. Every overlay in this library
+ *    portals to `document.body` and is therefore unaffected
+ *    ([decision](../../../../docs/decisions/2026-08-03-overlays-portal-to-the-body-not-the-top-layer.md));
+ *    an app's own fixed chrome belongs in `Shell`, beside `Main`
+ *    rather than in it.
+ *
+ * ## Two more things it does, both one line
+ *
+ * `tabIndex={-1}` so `Shell`'s skip link moves **focus** and not
+ * merely the reading cursor — without it, Safari and Firefox scroll
+ * to `<main>` and leave the next Tab back in the header.
+ *
+ * `wrap-anywhere` so an unbroken string — a filesystem path, a
+ * hash, a URL — wraps instead of widening the page.
+ *
+ * **`anywhere`, not `break-word`, and the difference is the whole
+ * point.** Both break a long word onto the next line, so they look
+ * identical in a screenshot. Only `anywhere` also shrinks the
+ * element's **min-content size** — which is what a flex or grid
+ * item's automatic minimum resolves against, and therefore what
+ * decides whether the string can push its own column wider. With
+ * `break-word` the ink wraps while the intrinsic contribution
+ * stays the full length of the token, so the layout above it can
+ * still be forced open. This is the second of the two overflow
+ * sources found in plex-channels, and the nastier one: it produces
+ * **no overflowing element box at all**, so every
+ * `getBoundingClientRect()` in a test reads clean while the page
+ * scrolls sideways.
+ *
+ * It is the cheap half of the horizontal-scroll fix; the other
+ * halves are `minmax(0, 1fr)` and `overflow-x: clip` in `Shell`. A
+ * `<table>` is the one thing none of them can save: tables do not
+ * wrap, so a wide one goes in an `overflow-x-auto` wrapper, which
+ * `Main.mdx` shows.
+ */
+export declare const Main: ({ children, className, contentWidth, id, ...mainProps }: MainProps) => ReactNode;
+//# sourceMappingURL=Main.d.ts.map

package/dist/Main/Main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Main.d.ts","sourceRoot":"","sources":["../../src/Main/Main.tsx"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,SAAS,EAEf,MAAM,OAAO,CAAA;AAEd,OAAO,EACL,KAAK,YAAY,EAGlB,MAAM,0BAA0B,CAAA;AAIjC,MAAM,MAAM,SAAS,GAAG,qBAAqB,CAAC,MAAM,CAAC,GAAG;IACtD,YAAY,CAAC,EAAE,YAAY,CAAA;CAC5B,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyGG;AACH,eAAO,MAAM,IAAI,GAAI,yDAMlB,SAAS,KAAG,SA0Cd,CAAA"}

package/dist/Main/Main.js

@@ -0,0 +1,123 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useUniqueId } from "@charcuterie/logic";
+import { useContext, } from "react";
+import { DEFAULT_CONTENT_WIDTH, toMaxInlineSize, } from "../Shell/contentWidth.js";
+import { ShellContext } from "../Shell/shellContext.js";
+import { toClassName } from "../toClassName.js";
+/**
+ * The `<main>` landmark and the content column.
+ *
+ * ## The width is the whole component
+ *
+ * The owner's complaint, verbatim:
+ *
+ * > "All these apps seem to be really narrow with a very large
+ * > max-width. By that I mean 1 column, but waaaaaaay too wide. In
+ * > almost all cases, what I really want is something like Rip-Deck
+ * > where the app has a narrower main column but the wrapping grids
+ * > are all full-width in most of these apps only when you have too
+ * > many items."
+ *
+ * That is two requirements, and they pull opposite ways: a
+ * **narrow** column by default, which **widens** when the content
+ * is a grid with enough items to justify it. A fixed `max-w-7xl`
+ * answers neither — it is too wide for the one-column case, which
+ * is the complaint, and it is a hard ceiling on the many-items
+ * case.
+ *
+ * So the cap is a *value*, not a constant, and it arrives from
+ * three places in priority order: this component's own
+ * `contentWidth`, then `Shell`'s (the usual answer, so the header
+ * matches), then `screen.lg`.
+ *
+ * ### How it composes with the adaptive-columns hook
+ *
+ * rip-deck's `useLayoutColumns` — being lifted into this library
+ * separately — decides a column count from the viewport and folds
+ * it into a page cap with `contentMaxWidthRem(columns)`: 1 column →
+ * 56rem, 2 → 72rem, 3 → 106rem. It returns a **number of rem**, and
+ * `ContentWidth` accepts `` `${number}rem` `` for exactly this:
+ *
+ * ```tsx
+ * const { columns } = useLayoutColumns({ cardCount: bays.length })
+ *
+ * <Shell contentWidth={`${contentMaxWidthRem(columns)}rem`}>
+ *   <Header heading="Rip Deck" />
+ *   <Main>
+ *     <BayGrid columns={columns} />
+ *   </Main>
+ * </Shell>
+ * ```
+ *
+ * The seam is deliberately one prop and no hook import: this
+ * package must not depend on a layout hook to lay out a page, and
+ * the hook must not know that a `Shell` exists. Putting the value
+ * on `Shell` rather than on `Main` is what keeps the header's cap
+ * in step with the column's as the count changes.
+ *
+ * ## `@container`, and what `contain: inline-size` costs
+ *
+ * The content column establishes a container query, so an app's
+ * grids inside it respond to **the column's** width rather than
+ * the window's — a poster grid beside an open rail and the same
+ * grid full-bleed are the pair a media query cannot tell apart,
+ * and getting it wrong at intermediate widths is what the fleet's
+ * grids do today.
+ *
+ * `container-type: inline-size` implies `contain: layout style
+ * inline-size`, and both halves have consequences worth stating:
+ *
+ *  - **The element may not be sized by its own contents.** Here
+ *    that is free and in fact wanted: the column has a definite
+ *    inline size from its parent — itself a grid item with
+ *    `minmax(0, 1fr)` — so wide content can no longer widen it,
+ *    which is half of why the page does not scroll sideways.
+ *  - **`contain: layout` makes it a containing block for
+ *    `position: fixed` descendants.** An app rendering a fixed
+ *    element *inside* `Main` gets it positioned against the
+ *    column, not the viewport. Every overlay in this library
+ *    portals to `document.body` and is therefore unaffected
+ *    ([decision](../../../../docs/decisions/2026-08-03-overlays-portal-to-the-body-not-the-top-layer.md));
+ *    an app's own fixed chrome belongs in `Shell`, beside `Main`
+ *    rather than in it.
+ *
+ * ## Two more things it does, both one line
+ *
+ * `tabIndex={-1}` so `Shell`'s skip link moves **focus** and not
+ * merely the reading cursor — without it, Safari and Firefox scroll
+ * to `<main>` and leave the next Tab back in the header.
+ *
+ * `wrap-anywhere` so an unbroken string — a filesystem path, a
+ * hash, a URL — wraps instead of widening the page.
+ *
+ * **`anywhere`, not `break-word`, and the difference is the whole
+ * point.** Both break a long word onto the next line, so they look
+ * identical in a screenshot. Only `anywhere` also shrinks the
+ * element's **min-content size** — which is what a flex or grid
+ * item's automatic minimum resolves against, and therefore what
+ * decides whether the string can push its own column wider. With
+ * `break-word` the ink wraps while the intrinsic contribution
+ * stays the full length of the token, so the layout above it can
+ * still be forced open. This is the second of the two overflow
+ * sources found in plex-channels, and the nastier one: it produces
+ * **no overflowing element box at all**, so every
+ * `getBoundingClientRect()` in a test reads clean while the page
+ * scrolls sideways.
+ *
+ * It is the cheap half of the horizontal-scroll fix; the other
+ * halves are `minmax(0, 1fr)` and `overflow-x: clip` in `Shell`. A
+ * `<table>` is the one thing none of them can save: tables do not
+ * wrap, so a wide one goes in an `overflow-x-auto` wrapper, which
+ * `Main.mdx` shows.
+ */
+export const Main = ({ children, className, contentWidth, id, ...mainProps }) => {
+    const shell = useContext(ShellContext);
+    // Always called, never conditionally: a `Main` outside a `Shell`
+    // still needs an id an app can point its own skip link at.
+    const fallbackId = useUniqueId();
+    const maxInlineSize = toMaxInlineSize(contentWidth ??
+        shell?.contentWidth ??
+        DEFAULT_CONTENT_WIDTH);
+    return (_jsx("main", { ...mainProps, className: toClassName("col-start-1 row-start-3 min-w-0 md:col-start-2 md:row-start-2", className), id: id ?? shell?.mainId ?? fallbackId, tabIndex: -1, children: _jsx("div", { className: "@container mx-auto flex w-full min-w-0 flex-col gap-6 wrap-anywhere px-4 py-6 sm:px-6", style: { maxInlineSize }, children: children }) }));
+};
+//# sourceMappingURL=Main.js.map

package/dist/Main/Main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Main.js","sourceRoot":"","sources":["../../src/Main/Main.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAA;AAChD,OAAO,EAGL,UAAU,GACX,MAAM,OAAO,CAAA;AAEd,OAAO,EAEL,qBAAqB,EACrB,eAAe,GAChB,MAAM,0BAA0B,CAAA;AACjC,OAAO,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAA;AACvD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAM/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAyGG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,EACnB,QAAQ,EACR,SAAS,EACT,YAAY,EACZ,EAAE,EACF,GAAG,SAAS,EACF,EAAa,EAAE;IACzB,MAAM,KAAK,GAAG,UAAU,CAAC,YAAY,CAAC,CAAA;IAEtC,iEAAiE;IACjE,2DAA2D;IAC3D,MAAM,UAAU,GAAG,WAAW,EAAE,CAAA;IAEhC,MAAM,aAAa,GAAG,eAAe,CACnC,YAAY;QACV,KAAK,EAAE,YAAY;QACnB,qBAAqB,CACxB,CAAA;IAED,OAAO,CACL,kBACM,SAAS,EACb,SAAS,EAAE,WAAW,CACpB,+DAA+D,EAC/D,SAAS,CACV,EACD,EAAE,EAAE,EAAE,IAAI,KAAK,EAAE,MAAM,IAAI,UAAU,EACrC,QAAQ,EAAE,CAAC,CAAC,YAaZ,cACE,SAAS,EAAC,uFAAuF,EACjG,KAAK,EAAE,EAAE,aAAa,EAAE,YAEvB,QAAQ,GACL,GACD,CACR,CAAA;AACH,CAAC,CAAA"}

package/dist/Rail/Rail.d.ts

@@ -0,0 +1,61 @@
+import type { ComponentPropsWithRef, ReactNode } from "react";
+export type RailLandmark = "complementary" | "navigation";
+export type RailSide = "end" | "start";
+export type RailProps = ComponentPropsWithRef<"aside"> & {
+    label: string;
+    landmark?: RailLandmark;
+    side?: RailSide;
+};
+/**
+ * A side rail — the nav column, the filter panel, the drive list.
+ *
+ * `side` places it, `landmark` decides what it *is*, and `label`
+ * is required for a reason: two unnamed rails in one page are two
+ * landmarks of the same type with no way to tell them apart, which
+ * is axe's `landmark-unique` and, more to the point, is a screen
+ * reader announcing "complementary" twice. It is also what makes
+ * the rail scopeable — `getByRole("navigation", { name: "Sections" })`
+ * disambiguates a "Settings" link that also exists in the header.
+ *
+ * ## It collapses without duplicating itself
+ *
+ * Below `md` the shell is one column and the rail becomes a
+ * horizontally-scrolling strip above (`side="start"`) or below
+ * (`side="end"`) the content. Above it, the rail is a fixed-width
+ * column in the grid.
+ *
+ * **The same element, restyled — not a second copy.** The fleet's
+ * habit is to render the whole thing twice behind `hidden` and
+ * `lg:hidden`: mux-magic's `PageHeader` does it across two ~55-line
+ * blocks and mail-sifter's `TriageQueue` does it again. The cost is
+ * not bytes, it is that every control exists **twice in the DOM at
+ * every viewport** — so tests must be defensively scoped, an agent
+ * driving the page finds two of each button and cannot tell which
+ * is the visible one, and the two copies drift.
+ *
+ * A media query gets the whole job done here because only the
+ * rail's *position* changes, never its contents. plex-channels'
+ * `App.tsx` shows the pattern for when that is not true — a
+ * `useMediaQuery` over `matchMedia` through `useSyncExternalStore`,
+ * mounting exactly one instance and relocating it — and it is
+ * strictly more machinery for the same guarantee, so it is not what
+ * this component uses.
+ *
+ * The `md` breakpoint is 48rem, which is `screen.md`: Tailwind v4's
+ * default `--breakpoint-*` scale and this repo's `screen.*` scale
+ * carry the same five values, so `md:` and the token agree by
+ * construction rather than by coincidence maintained by hand.
+ *
+ * ## The narrow strip scrolls itself
+ *
+ * `overflow-x-auto` on the rail is what keeps a twelve-item nav
+ * from widening the *page* at 390px: the overflow is contained in
+ * an element that scrolls, which is the sanctioned answer for
+ * content that genuinely cannot wrap. `min-w-0` is on it for the
+ * same reason `Shell`'s middle track is `minmax(0, 1fr)` — a flex
+ * or grid child's automatic minimum is its content, and one long
+ * unbroken string otherwise pushes the whole layout out of the
+ * viewport.
+ */
+export declare const Rail: ({ children, className, label, landmark, side, ...railProps }: RailProps) => ReactNode;
+//# sourceMappingURL=Rail.d.ts.map

package/dist/Rail/Rail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Rail.d.ts","sourceRoot":"","sources":["../../src/Rail/Rail.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,qBAAqB,EACrB,SAAS,EACV,MAAM,OAAO,CAAA;AAId,MAAM,MAAM,YAAY,GAAG,eAAe,GAAG,YAAY,CAAA;AAEzD,MAAM,MAAM,QAAQ,GAAG,KAAK,GAAG,OAAO,CAAA;AAEtC,MAAM,MAAM,SAAS,GAAG,qBAAqB,CAAC,OAAO,CAAC,GAAG;IACvD,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,YAAY,CAAA;IACvB,IAAI,CAAC,EAAE,QAAQ,CAAA;CAChB,CAAA;AAUD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,eAAO,MAAM,IAAI,GAAI,8DAOlB,SAAS,KAAG,SAkBd,CAAA"}

package/dist/Rail/Rail.js

@@ -0,0 +1,64 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { toClassName } from "../toClassName.js";
+const LANDMARK_ELEMENT = {
+    complementary: "aside",
+    navigation: "nav",
+};
+/**
+ * A side rail — the nav column, the filter panel, the drive list.
+ *
+ * `side` places it, `landmark` decides what it *is*, and `label`
+ * is required for a reason: two unnamed rails in one page are two
+ * landmarks of the same type with no way to tell them apart, which
+ * is axe's `landmark-unique` and, more to the point, is a screen
+ * reader announcing "complementary" twice. It is also what makes
+ * the rail scopeable — `getByRole("navigation", { name: "Sections" })`
+ * disambiguates a "Settings" link that also exists in the header.
+ *
+ * ## It collapses without duplicating itself
+ *
+ * Below `md` the shell is one column and the rail becomes a
+ * horizontally-scrolling strip above (`side="start"`) or below
+ * (`side="end"`) the content. Above it, the rail is a fixed-width
+ * column in the grid.
+ *
+ * **The same element, restyled — not a second copy.** The fleet's
+ * habit is to render the whole thing twice behind `hidden` and
+ * `lg:hidden`: mux-magic's `PageHeader` does it across two ~55-line
+ * blocks and mail-sifter's `TriageQueue` does it again. The cost is
+ * not bytes, it is that every control exists **twice in the DOM at
+ * every viewport** — so tests must be defensively scoped, an agent
+ * driving the page finds two of each button and cannot tell which
+ * is the visible one, and the two copies drift.
+ *
+ * A media query gets the whole job done here because only the
+ * rail's *position* changes, never its contents. plex-channels'
+ * `App.tsx` shows the pattern for when that is not true — a
+ * `useMediaQuery` over `matchMedia` through `useSyncExternalStore`,
+ * mounting exactly one instance and relocating it — and it is
+ * strictly more machinery for the same guarantee, so it is not what
+ * this component uses.
+ *
+ * The `md` breakpoint is 48rem, which is `screen.md`: Tailwind v4's
+ * default `--breakpoint-*` scale and this repo's `screen.*` scale
+ * carry the same five values, so `md:` and the token agree by
+ * construction rather than by coincidence maintained by hand.
+ *
+ * ## The narrow strip scrolls itself
+ *
+ * `overflow-x-auto` on the rail is what keeps a twelve-item nav
+ * from widening the *page* at 390px: the overflow is contained in
+ * an element that scrolls, which is the sanctioned answer for
+ * content that genuinely cannot wrap. `min-w-0` is on it for the
+ * same reason `Shell`'s middle track is `minmax(0, 1fr)` — a flex
+ * or grid child's automatic minimum is its content, and one long
+ * unbroken string otherwise pushes the whole layout out of the
+ * viewport.
+ */
+export const Rail = ({ children, className, label, landmark = "complementary", side = "start", ...railProps }) => {
+    const Element = LANDMARK_ELEMENT[landmark];
+    return (_jsx(Element, { ...railProps, "aria-label": label, className: toClassName("flex min-w-0 gap-2 overflow-x-auto border-border-subtle p-4 md:row-start-2 md:w-64 md:flex-col md:overflow-x-visible", side === "start"
+            ? "row-start-2 border-b md:col-start-1 md:border-b-0 md:border-e"
+            : "row-start-4 border-t md:col-start-3 md:border-t-0 md:border-s", className), children: children }));
+};
+//# sourceMappingURL=Rail.js.map

package/dist/Rail/Rail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Rail.js","sourceRoot":"","sources":["../../src/Rail/Rail.tsx"],"names":[],"mappings":";AAKA,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA;AAY/C,MAAM,gBAAgB,GAGlB;IACF,aAAa,EAAE,OAAO;IACtB,UAAU,EAAE,KAAK;CAClB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG,CAAC,EACnB,QAAQ,EACR,SAAS,EACT,KAAK,EACL,QAAQ,GAAG,eAAe,EAC1B,IAAI,GAAG,OAAO,EACd,GAAG,SAAS,EACF,EAAa,EAAE;IACzB,MAAM,OAAO,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAA;IAE1C,OAAO,CACL,KAAC,OAAO,OACF,SAAS,gBACD,KAAK,EACjB,SAAS,EAAE,WAAW,CACpB,sHAAsH,EACtH,IAAI,KAAK,OAAO;YACd,CAAC,CAAC,+DAA+D;YACjE,CAAC,CAAC,+DAA+D,EACnE,SAAS,CACV,YAEA,QAAQ,GACD,CACX,CAAA;AACH,CAAC,CAAA"}

package/dist/Shell/Shell.d.ts

@@ -0,0 +1,112 @@
+import { type ComponentPropsWithRef, type ReactNode } from "react";
+import { type ContentWidth } from "./contentWidth.ts";
+export type ShellProps = ComponentPropsWithRef<"div"> & {
+    contentWidth?: ContentWidth;
+    skipLinkLabel?: string;
+};
+/**
+ * The page frame: one `Header`, up to two `Rail`s, one `Main`.
+ *
+ * **The largest duplicated surface in the fleet.** Ten of twelve UI
+ * repos hand-roll this, and three of them have a file literally
+ * called `AppShell.tsx` — mail-sifter's and points-market's headers
+ * are a **byte-identical** string
+ * (`sticky top-0 z-40 border-b border-border-subtle bg-surface-base/90 backdrop-blur-md`),
+ * arrived at independently, and board-games' is the same structure
+ * with `sticky` dropped. The remaining seven spell it as
+ * `PageChrome`, `Header`, `DashboardHeader`, `Layout` (twice),
+ * `TitleBar`, and inline in `App.tsx`.
+ *
+ * Three things fall out of owning it once, and each is a bug
+ * somewhere in that list today:
+ *
+ *  - **A skip link.** All ten are missing one. A keyboard user
+ *    tabs through the whole header on every page.
+ *  - **One width, not two.** `Header` and `Main` read the same
+ *    `contentWidth` through context — see `shellContext.ts` for
+ *    the app where they disagree.
+ *  - **Sticky that is actually sticky.** mux-magic's `PageHeader`
+ *    is *described* as sticky and sets only `z-index`; it never
+ *    sets `position: sticky`, so the z-index does nothing and the
+ *    header scrolls away. `Header`'s `isSticky` sets both or
+ *    neither.
+ *
+ * ## The layout is one grid, and the rails do not duplicate
+ *
+ * Three columns at `md` and up — `auto minmax(0, 1fr) auto`, so an
+ * absent rail is a **zero-width track** rather than a conditional
+ * subtree — collapsing to a single column below it, where the
+ * children simply stack in DOM order. The same `Rail` element is
+ * in the document at every width; nothing is rendered twice behind
+ * `hidden`/`lg:hidden`.
+ *
+ * That matters beyond tidiness. mux-magic's `PageHeader` renders
+ * its entire control set twice (lines 290–345 and 356–410) and
+ * mail-sifter's `TriageQueue` does the same, so every action
+ * exists twice in the DOM at every viewport: tests have to be
+ * defensively scoped with `within(toolbar)`, and any agent driving
+ * the page sees phantom controls it cannot click.
+ *
+ * `minmax(0, 1fr)` on the middle track is the horizontal-scroll
+ * fix, not a formality. A grid track's automatic minimum is
+ * `min-content`, so **one long unbroken string in `Main` widens
+ * the whole page** — which is the bug plex-channels' narrow view
+ * has today. rip-deck's `BayGrid` documents the same fix from the
+ * other end.
+ *
+ * There is no `gap`: an empty `auto` track is 0 wide, but a `gap`
+ * beside it is not, so a shell with no rails would carry two
+ * mystery gutters. `Rail` and `Main` bring their own padding.
+ *
+ * ## `overflow-x: clip` — the structural guarantee
+ *
+ * `minmax(0, 1fr)` fixes the tracks and `Main`'s `wrap-anywhere`
+ * fixes the text, but neither reaches the shape that actually
+ * broke plex-channels: **a closed panel parked at
+ * `transform: translateX(110%)`**. A transform does not take a box
+ * out of the document's scrollable overflow region — and neither
+ * does `visibility: hidden` — so an off-screen drawer that looks
+ * absent still makes the page scroll to it. It is a favourite
+ * fleet pattern and no amount of `min-width: 0` touches it.
+ *
+ * `clip`, not `hidden`, and the two are not interchangeable here:
+ * `overflow: hidden` creates a **scroll container**, which would
+ * become the sticky containing block for `Header` and freeze it in
+ * place. `overflow-x: clip` creates no scrollport, so `Header`
+ * keeps sticking to the viewport, and `overflow-y` stays `visible`
+ * — a pair that is legal for `clip` and illegal for `hidden`,
+ * which would compute the other axis to `auto`.
+ *
+ * The trade is deliberate: content wider than the frame is
+ * **clipped rather than reachable by scrolling sideways**, which is
+ * exactly the outcome asked for. Content that genuinely needs to
+ * be wider owns a scroll container of its own — the pattern
+ * `Main.mdx` documents for tables.
+ *
+ * ### `relative` is what makes the clip reach anything
+ *
+ * `overflow-x: clip` only clips descendants whose **containing
+ * block chain passes through the clipping element**. An absolutely
+ * positioned element with no positioned ancestor resolves against
+ * the *initial* containing block instead, so it sails straight
+ * past every `overflow` in the tree and lands its overflow on
+ * `documentElement` — where `document.body.scrollWidth` still
+ * reads clean and only `document.documentElement.scrollWidth`
+ * shows it.
+ *
+ * That is not hypothetical: it is measured. Before this
+ * `relative`, the parked-drawer fixture reported `shellScroll:
+ * 390`, `bodyScroll: 390` and `docScroll: 742` at a 390px
+ * viewport — the shell dutifully clipping a box it had no
+ * authority over.
+ *
+ * The obvious candidate to own it, `Main`'s content column, does
+ * **not**: `container-type: inline-size` computes `contain` to
+ * `none` in Chromium and establishes no containing block for
+ * absolute positioning, which is measured too — the drawer's
+ * `offsetParent` was `BODY`. So `Shell` takes the job, which is
+ * also the honest place for it: the frame is what an app's parked
+ * chrome is parked against.
+ */
+export declare const Shell: ({ children, className, contentWidth, skipLinkLabel, ...divProps }: ShellProps) => ReactNode;
+//# sourceMappingURL=Shell.d.ts.map

package/dist/Shell/Shell.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Shell.d.ts","sourceRoot":"","sources":["../../src/Shell/Shell.tsx"],"names":[],"mappings":"AACA,OAAO,EACL,KAAK,qBAAqB,EAC1B,KAAK,SAAS,EAEf,MAAM,OAAO,CAAA;AAGd,OAAO,EACL,KAAK,YAAY,EAElB,MAAM,mBAAmB,CAAA;AAG1B,MAAM,MAAM,UAAU,GAAG,qBAAqB,CAAC,KAAK,CAAC,GAAG;IACtD,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B,aAAa,CAAC,EAAE,MAAM,CAAA;CACvB,CAAA;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuGG;AACH,eAAO,MAAM,KAAK,GAAI,mEAMnB,UAAU,KAAG,SAwCf,CAAA"}