@50arms/ui 0.0.0-stage → 35.2.0

package/dist/theme.css

@@ -0,0 +1,360 @@
+/* @50arms/ui — the Tailwind-build side of this package.
+ *
+ * GENERATED by scripts/postbuild-css.mjs from the @theme blocks in
+ * src/styles/. Do not edit; edit the source stylesheets.
+ *
+ * Import it alongside the compiled stylesheet, after Tailwind:
+ *
+ *   @import "tailwindcss";
+ *   @import "@50arms/ui/theme.css";    <- @source + the @theme blocks
+ *   @import "@50arms/ui/styles.css";   <- tokens, base, component CSS
+ *   @import "@50arms/ui/fonts.css";
+ *
+ * IT CARRIES TWO THINGS, and both are load-bearing.
+ *
+ * 1. `@source` — YOUR Tailwind build generates this library's utilities.
+ *
+ *    The package ships NO generated utilities (`flex`, `grid-cols-1`,
+ *    `md:grid-cols-2`). It used to, and they collided: a compiled stylesheet
+ *    emits into `@layer utilities`, which is the same layer name YOUR Tailwind
+ *    uses, at equal specificity, and the library is imported last — so the
+ *    library won every tie. Measured in a browser at 1440px:
+ *    `grid grid-cols-1 xl:grid-cols-[1.6fr_1fr]` rendered ONE track, because
+ *    the library's `.grid-cols-1` sat 449 rules AFTER the app's `xl:` rule.
+ *
+ *    Pointing your compiler at the shipped code instead means there is one
+ *    Tailwind build, one `@layer utilities`, and Tailwind's own variant
+ *    ordering — under which `xl:` beats `md:` because breakpoints are sorted,
+ *    not because of which file was imported last.
+ *
+ *    THIS REQUIRES TAILWIND 4 IN THE CONSUMING BUILD. Without it you get
+ *    tokens, base and component CSS and no utilities at all — components
+ *    render unstyled, loudly, on the first screen.
+ *
+ * 2. The @theme blocks — YOUR utilities learn this library's token names.
+ *
+ *    A consuming build has never seen our `@theme`, so `bg-surface` written in
+ *    your own JSX would compile to nothing, silently. These blocks are lifted
+ *    verbatim out of the source stylesheets at build time rather than
+ *    hand-maintained, because a second copy drifts and drift here is invisible.
+ */
+
+/* Relative to THIS file, per Tailwind's @source resolution. Points at the
+   shipped modules (every .js file under dist/) — exactly the code you are importing, so the utilities your
+   build generates are exactly the ones the components ask for. */
+@source "./**/*.js";
+
+/* from src/styles/authored.css */
+@theme inline {
+  /* --- Surfaces + structure --- */
+  --color-canvas: var(--canvas);
+  --color-canvas-subtle: var(--canvas-subtle);
+  --color-surface: var(--surface);
+  --color-surface-sunken: var(--surface-sunken);
+  --color-surface-raised: var(--surface-raised);
+  --color-surface-overlay: var(--surface-overlay);
+  --color-surface-inset: var(--surface-inset);
+  --color-surface-hover: var(--surface-hover);
+  --color-surface-active: var(--surface-active);
+  --color-surface-selected: var(--surface-selected);
+
+  --color-border-subtle: var(--border-subtle);
+  --color-border: var(--border);
+  --color-border-strong: var(--border-strong);
+  --color-border-interactive: var(--border-interactive);
+
+  /* --- Content --- */
+  --color-primary: var(--text-primary);
+  --color-secondary: var(--text-secondary);
+  --color-tertiary: var(--text-tertiary);
+  --color-disabled: var(--text-disabled);
+  --color-inverse: var(--text-inverse);
+
+  /* --- Accent (celadon) --- */
+  --color-accent: var(--accent);
+  --color-accent-hover: var(--accent-hover);
+  --color-accent-active: var(--accent-active);
+  --color-accent-subtle: var(--accent-subtle);
+  --color-accent-subtle-hover: var(--accent-subtle-hover);
+  --color-accent-border: var(--accent-border);
+  --color-accent-text: var(--accent-text);
+  --color-accent-contrast: var(--accent-contrast);
+
+  /* --- Control (DX-5080: input on/selected/focus, success green) --- */
+  --color-control: var(--control);
+  --color-control-hover: var(--control-hover);
+  --color-control-subtle: var(--control-subtle);
+  --color-control-subtle-hover: var(--control-subtle-hover);
+  --color-control-border: var(--control-border);
+  --color-control-text: var(--control-text);
+  --color-control-contrast: var(--control-contrast);
+
+  /* --- Brand (ember) --- */
+  --color-brand: var(--brand);
+  --color-brand-hover: var(--brand-hover);
+  --color-brand-subtle: var(--brand-subtle);
+  --color-brand-text: var(--brand-text);
+  --color-brand-contrast: var(--brand-contrast);
+
+  /* --- Status --- */
+  --color-success: var(--success);
+  --color-success-subtle: var(--success-subtle);
+  --color-success-text: var(--success-text);
+  --color-success-border: var(--success-border);
+
+  --color-warning: var(--warning);
+  --color-warning-subtle: var(--warning-subtle);
+  --color-warning-subtle-hover: var(--warning-subtle-hover);
+  --color-warning-text: var(--warning-text);
+  --color-warning-border: var(--warning-border);
+
+  /* DX-4657 - the orange tone: the step between `warning` (amber) and `danger` (red). */
+  --color-orange: var(--orange);
+  --color-orange-subtle: var(--orange-subtle);
+  --color-orange-text: var(--orange-text);
+  --color-orange-border: var(--orange-border);
+
+  --color-danger: var(--danger);
+  --color-danger-hover: var(--danger-hover);
+  --color-danger-subtle: var(--danger-subtle);
+  --color-danger-text: var(--danger-text);
+  --color-danger-border: var(--danger-border);
+  --color-danger-contrast: var(--danger-contrast);
+
+  /* --- Chart palette (DX-3963): eight ordered categorical hues + one sequential --- */
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+  --color-chart-6: var(--chart-6);
+  --color-chart-7: var(--chart-7);
+  --color-chart-8: var(--chart-8);
+  --color-chart-seq: var(--chart-seq);
+
+  /* --- Confidence (a 1-5 self-rating, one colour per level) --- */
+  --color-confidence-1: var(--confidence-1);
+  --color-confidence-2: var(--confidence-2);
+  --color-confidence-3: var(--confidence-3);
+  --color-confidence-4: var(--confidence-4);
+  --color-confidence-5: var(--confidence-5);
+  --color-confidence-none: var(--confidence-none);
+
+  --color-info: var(--info);
+  --color-info-subtle: var(--info-subtle);
+  --color-info-text: var(--info-text);
+  --color-info-border: var(--info-border);
+
+  /* DX-3662 — the 8th tone: a quieter grey for a CLOSED/inert fact (a
+     terminated card, a retired record) — distinct from `--neutral`
+     (`text-tertiary`/`bg-tertiary`, the "not yet decided" grey every OTHER
+     pending/undetermined state already draws from). Both are on the same
+     near-zero-chroma axis on purpose (an inert fact and an undecided one are
+     both "no signal", just at different points in a lifecycle) but pinned to
+     different `L`s so they stay tellable apart side by side — see
+     `muted-quieter-than-neutral.test.ts` for the measured contrast-ranking
+     floor this promises (DX-3696 — the file this comment used to cite,
+     `token-distance.test.ts`, does not exist in this repo). */
+  --color-muted: var(--muted);
+  --color-muted-subtle: var(--muted-subtle);
+  --color-muted-text: var(--muted-text);
+  --color-muted-border: var(--muted-border);
+
+  /* --- Fields --- */
+  --color-field: var(--field-bg);
+  --color-field-hover: var(--field-bg-hover);
+  --color-field-border: var(--field-border);
+  --color-field-border-hover: var(--field-border-hover);
+  --color-field-placeholder: var(--field-placeholder);
+
+  --color-scrim: var(--scrim);
+  --color-veil: var(--veil);
+  --color-focus-halo: var(--focus-halo);
+  --color-control-focus-halo: var(--control-focus-halo);
+  --color-control-knob: var(--control-knob);
+  --color-control-knob-on: var(--control-knob-on);
+  --color-switch-track-off: var(--switch-track-off);
+  --color-meter-track: var(--meter-track);
+  --color-focus-ring: var(--focus-ring);
+
+  /* --- Type --- */
+  --font-display: var(--font-display);
+  --font-sans: var(--font-sans);
+  --font-mono: var(--font-mono);
+
+  --text-2xs: var(--text-2xs);
+  --text-xs: var(--text-xs);
+  --text-sm: var(--text-sm);
+  --text-base: var(--text-base);
+  --text-md: var(--text-md);
+  --text-lg: var(--text-lg);
+  --text-xl: var(--text-xl);
+  --text-2xl: var(--text-2xl);
+  --text-3xl: var(--text-3xl);
+  --text-4xl: var(--text-4xl);
+  --text-5xl: var(--text-5xl);
+
+  /* Remap Tailwind's weight utilities onto the non-integer ramp, so
+     `font-medium` / `font-bold` pick up 510 / 680 rather than 500 / 700. */
+  --font-weight-normal: var(--weight-normal);
+  --font-weight-medium: var(--weight-medium);
+  --font-weight-semibold: var(--weight-semibold);
+  --font-weight-bold: var(--weight-bold);
+
+  --leading-tight: var(--leading-tight);
+  --leading-snug: var(--leading-snug);
+  --leading-normal: var(--leading-normal);
+  --leading-relaxed: var(--leading-relaxed);
+
+  --tracking-tighter: var(--tracking-tighter);
+  --tracking-tight: var(--tracking-tight);
+  --tracking-normal: var(--tracking-normal);
+  --tracking-wide: var(--tracking-wide);
+  --tracking-widest: var(--tracking-widest);
+
+  /* --- Shape --- */
+  --radius-xs: var(--radius-xs);
+  --radius-sm: var(--radius-sm);
+  --radius-md: var(--radius-md);
+  --radius-lg: var(--radius-lg);
+  --radius-xl: var(--radius-xl);
+  --radius-2xl: var(--radius-2xl);
+  --radius-3xl: var(--radius-3xl);
+
+  /* --- Control heights, exposed as sizing utilities (h-control-md etc.) --- */
+  /* Tailwind's spacing BASE, retargeted through the size multiplier.
+     This one line is what makes every `p-4`, `gap-3`, `size-5` in every
+     component respond to the size control — without it the utilities keep
+     Tailwind's fixed 0.25rem and only the hand-written control heights move,
+     which is why the first version of the control read as "changes padding
+     slightly" and nothing else. */
+  --spacing: calc(0.25rem * var(--ui-scale));
+
+  --spacing-control-2xs: var(--control-2xs);
+  --spacing-control-xs: var(--control-xs);
+  --spacing-control-sm: var(--control-sm);
+  --spacing-control-md: var(--control-md);
+  --spacing-control-lg: var(--control-lg);
+  --spacing-control-xl: var(--control-xl);
+
+  /* --- Elevation --- */
+  --shadow-xs: var(--shadow-xs);
+  --shadow-sm: var(--shadow-sm);
+  --shadow-knob: var(--shadow-knob);
+  --shadow-md: var(--shadow-md);
+  --shadow-lg: var(--shadow-lg);
+  --shadow-xl: var(--shadow-xl);
+  --shadow-tooltip: var(--shadow-tooltip);
+  --shadow-glow-accent: var(--shadow-glow-accent);
+
+  /* --- Motion ---
+     The curves, durations and `animate-*` utilities are owned by motion.css,
+     which declares them directly in Tailwind's own namespaces. All that is
+     left here is retargeting the framework's bare `transition` default off
+     its Material-1-era `cubic-bezier(0.4, 0, 0.2, 1)` @ 150ms.              */
+  --default-transition-duration: var(--dur-base);
+  --default-transition-timing-function: var(--ease-standard);
+}
+
+/* from src/styles/tokens.css */
+@theme inline {
+  --color-surface-selected-hover: var(--surface-selected-hover);
+  --color-danger-subtle-hover: var(--danger-subtle-hover);
+}
+
+/* from src/styles/motion.css */
+@theme static {
+  --ease-standard: cubic-bezier(0.2, 0, 0, 1);   /* on-screen to on-screen  */
+  --ease-entrance: cubic-bezier(0, 0, 0.2, 1);   /* decelerate IN           */
+  --ease-exit: cubic-bezier(0.4, 0, 1, 1);       /* accelerate OUT          */
+  --ease-emphasis: cubic-bezier(0.05, 0.7, 0.1, 1);
+  /* y1 = 1: hits full speed instantly, then decelerates. This is why hover
+     feedback with it reads as instantaneous. */
+  --ease-hover: cubic-bezier(0.4, 1, 0.6, 1);
+  --ease-out-strong: cubic-bezier(0.23, 1, 0.32, 1);
+  --ease-in-strong: cubic-bezier(0.32, 0, 0.67, 0);
+
+  /* --- Springs, baked as linear() ---------------------------------------
+     Generated by integrating the damped-spring ODE and sampling 50 points.
+     Fewer than ~25 points reads robotic; 50 is indistinguishable from a real
+     spring.
+
+     KEY PROPERTY: a linear() curve encodes SHAPE ONLY — it is a function of
+     the damping ratio alone. Replaying it over any duration yields a real,
+     physically-valid spring. So there is one curve per damping ratio, and
+     duration stays a free parameter chosen from the bands below.
+
+     Zero JS. A JS spring runtime costs 35-40 KB to do what these do free. */
+
+  /* zeta 0.751 — 2.8% overshoot. The UI default. */
+  --ease-snappy: linear(0, 0.0118, 0.0436, 0.0903, 0.1478, 0.2123, 0.281,
+    0.3513, 0.4214, 0.4896, 0.5549, 0.6164, 0.6734, 0.7257, 0.773, 0.8154,
+    0.853, 0.8858, 0.9143, 0.9386, 0.9591, 0.9762, 0.9901, 1.0013, 1.0101,
+    1.0168, 1.0216, 1.025, 1.027, 1.028, 1.0282, 1.0276, 1.0266, 1.0252,
+    1.0235, 1.0216, 1.0197, 1.0177, 1.0157, 1.0138, 1.012, 1.0103, 1.0087,
+    1.0073, 1.006, 1.0049, 1.0038, 1.003, 1.0022, 1.0015, 1);
+
+  /* zeta 1.000 — critically damped, ZERO overshoot. Use where overshoot would
+     lie: progress, numeric values, destructive confirmations. */
+  --ease-smooth: linear(0, 0.0151, 0.0535, 0.107, 0.1694, 0.2361, 0.304,
+    0.3707, 0.4346, 0.4949, 0.551, 0.6025, 0.6494, 0.6918, 0.7299, 0.7638,
+    0.7941, 0.8208, 0.8444, 0.8651, 0.8832, 0.8991, 0.913, 0.925, 0.9354,
+    0.9445, 0.9524, 0.9591, 0.965, 0.97, 0.9743, 0.9781, 0.9813, 0.984,
+    0.9864, 0.9884, 0.9901, 0.9916, 0.9928, 0.9939, 0.9948, 0.9956, 0.9963,
+    0.9968, 0.9973, 0.9977, 0.9981, 0.9984, 0.9986, 0.9988, 1);
+
+  /* zeta 0.400 — 25.3% overshoot. Rare, deliberate delight only. */
+  --ease-bouncy: linear(0, 0.0552, 0.1966, 0.3883, 0.5977, 0.7985, 0.9716,
+    1.1054, 1.1955, 1.243, 1.2533, 1.2343, 1.1953, 1.1451, 1.0919, 1.042,
+    0.9998, 0.968, 0.9472, 0.9371, 0.9361, 0.9421, 0.9527, 0.9658, 0.9792,
+    0.9916, 1.0018, 1.0094, 1.0141, 1.0162, 1.016, 1.0142, 1.0114, 1.008,
+    1.0046, 1.0016, 0.9991, 0.9973, 0.9963, 0.9959, 0.996, 0.9965, 0.9973,
+    0.9981, 0.999, 0.9997, 1.0003, 1.0007, 1.001, 1.0011, 1);
+
+  /* zeta 0.899 — 0.2% overshoot. A kiss of spring, for large surfaces. */
+  --ease-gentle: linear(0, 0.0128, 0.0462, 0.0941, 0.1516, 0.2146, 0.2804,
+    0.3465, 0.4112, 0.4734, 0.5321, 0.5869, 0.6375, 0.6837, 0.7255, 0.7631,
+    0.7966, 0.8264, 0.8526, 0.8756, 0.8955, 0.9129, 0.9278, 0.9406, 0.9515,
+    0.9607, 0.9685, 0.975, 0.9804, 0.9849, 0.9886, 0.9916, 0.994, 0.996,
+    0.9975, 0.9987, 0.9996, 1.0003, 1.0008, 1.0011, 1.0014, 1.0015, 1.0016,
+    1.0016, 1.0015, 1.0015, 1.0014, 1.0013, 1.0012, 1.0011, 1);
+
+  /* Pen curve for the checkbox tick: slows at the stroke's corner (29.5% of
+     duration, dipping to 52% speed) and decelerates into the tip. Tuned to
+     the specific path `M5 12.5 L10 17.5 L19 7`, whose corner sits at 33.83%
+     of arc length — regenerate for a different path. */
+  --ease-pen: linear(0, 0.0426, 0.085, 0.1271, 0.1683, 0.2077, 0.2443, 0.2766,
+    0.3043, 0.3282, 0.3507, 0.3743, 0.4012, 0.4319, 0.4657, 0.5012, 0.5374,
+    0.5735, 0.609, 0.6438, 0.6776, 0.7106, 0.7427, 0.7737, 0.8037, 0.8325,
+    0.8602, 0.8868, 0.9121, 0.9361, 0.9588, 0.9801, 1);
+}
+
+/* from src/styles/motion.css */
+@theme static {
+  --animate-fade-in: dx-fade-in var(--dur-base) var(--ease-entrance) both;
+  --animate-rise-in: dx-rise-in var(--dur-base) var(--ease-entrance) both;
+  --animate-scale-in: dx-scale-in var(--dur-fast) var(--ease-snappy) both;
+  --animate-fade-out: dx-fade-in var(--dur-exit) var(--ease-exit) reverse both;
+
+  /* The 500ms delay is deliberate — a skeleton sits still before it starts
+     breathing, which reads as composed rather than instantly agitated. */
+  --animate-pulse: dx-pulse 1.8s var(--ease-standard) 0.5s infinite;
+  --animate-sweep: dx-sweep 1.6s var(--ease-standard) infinite;
+  /* A spinner is the one animation someone WATCHES rather than glances at, and
+     a fast one reads as frantic — it makes a two-second wait feel like the app
+     is struggling. Slow enough to look composed, fast enough to look alive.
+
+     The two rates are deliberately not multiples of each other: 1.4s against
+     2.2s means the arc's growth lands in a different place on every rotation,
+     so the motion never settles into a pattern the eye can predict and start
+     ignoring. */
+  --animate-spin: dx-spin 1.4s linear infinite;
+  --animate-spinner-dash: dx-spinner-dash 2.2s var(--ease-standard) infinite;
+
+  /* Live TEXT — "Thinking…", "Ran 3 commands". Distinct from the skeleton
+     sweep above, which stands in for content that has not arrived; this one
+     marks content that IS here and still changing. Slow, because it sits
+     beside prose someone is reading and a fast highlight travelling through a
+     sentence makes it harder to read, not more obviously alive. */
+  --animate-shimmer: dx-shimmer 2.4s var(--ease-standard) infinite;
+}

package/dist/types/components/Accordion.d.ts

@@ -0,0 +1,15 @@
+import type { ReactNode, Ref } from "react";
+import { Accordion as BaseAccordion } from "@base-ui/react/accordion";
+export interface AccordionProps extends Omit<BaseAccordion.Root.Props, "className"> {
+    className?: string;
+    ref?: Ref<HTMLDivElement>;
+}
+export declare function Accordion({ className, children, ref, ...props }: AccordionProps): import("react").JSX.Element;
+export interface AccordionItemProps extends Omit<BaseAccordion.Item.Props, "className" | "title"> {
+    title: ReactNode;
+    /** Sits at the trailing edge of the header, before the chevron. */
+    meta?: ReactNode;
+    className?: string;
+    ref?: Ref<HTMLDivElement>;
+}
+export declare function AccordionItem({ title, meta, className, children, ref, ...props }: AccordionItemProps): import("react").JSX.Element;

package/dist/types/components/AgentWorkingSpinner.d.ts

@@ -0,0 +1,23 @@
+import type { Ref, SVGProps } from "react";
+import type { IconSize } from "./Icon";
+export interface AgentWorkingSpinnerProps extends Omit<SVGProps<SVGSVGElement>, "ref"> {
+    size?: IconSize;
+    /**
+     * An accessible name ("Agent working"). Given: `role="status"` + `aria-label`.
+     * Omitted: `aria-hidden`, for the usual case of sitting inside something that
+     * already announces its own busy state.
+     */
+    label?: string;
+    ref?: Ref<SVGSVGElement>;
+}
+/**
+ * "An AI agent is working on this." A four-point sparkle that gently pulses,
+ * with two small dots orbiting it at different rates (so the motion never
+ * settles into a predictable loop). Deliberately NOT an arc: the generic
+ * `Spinner` means "waiting"; this means "something is thinking and acting".
+ *
+ * Pure SVG + CSS keyframes (`dx-agent-*` in motion.css); colour is
+ * `currentColor`. Under reduced motion it renders as a static sparkle with the
+ * dots parked at rest.
+ */
+export declare function AgentWorkingSpinner({ size, label, className, style, ref, ...props }: AgentWorkingSpinnerProps): import("react").JSX.Element;

package/dist/types/components/AppShell.d.ts

@@ -0,0 +1,164 @@
+import type { MouseEvent, ReactNode } from "react";
+import { type IconName } from "./Icon";
+export type NavItem = {
+    id: string;
+    label: string;
+    icon: IconName;
+    /** A count or status shown at the trailing edge. */
+    badge?: ReactNode;
+    href?: string;
+    /**
+     * Receives the click event, which a client-side router NEEDS in order to
+     * suppress the browser's own navigation.
+     *
+     * IT USED TO RECEIVE NOTHING, and that made this component quietly
+     * unusable with a history router. The anchor only calls `preventDefault()`
+     * when `href` is absent, so an item with BOTH `href` and `onClick` did the
+     * client-side navigation AND a full page load — tearing down the app tree
+     * and every live connection it held, on every nav click. The design system's
+     * own demo could not surface it: a hash router's `href="#/x"` never reloads
+     * either way. It showed up the moment a real consumer wired history routing.
+     *
+     * Dropping `href` to force the `preventDefault` branch works and costs too
+     * much — a nav item without an `href` is not a link, so it loses the hover
+     * URL, ctrl/cmd-click-to-new-tab and copy-link-address. Keep the `href`,
+     * take the event:
+     *
+     * ```tsx
+     * onClick: (e) => {
+     *   // Let the browser have the clicks that mean "not here" — a modified
+     *   // click or a middle click is an explicit request for a new tab, and
+     *   // swallowing it is the most-reported bug in hand-rolled SPA links.
+     *   if (e.defaultPrevented || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey) return;
+     *   e.preventDefault();
+     *   navigate(item.href);
+     * }
+     * ```
+     *
+     * Still router-agnostic: the shell hands over the event and decides nothing.
+     */
+    onClick?: (event: MouseEvent<HTMLAnchorElement>) => void;
+};
+export type NavSection = {
+    label?: string;
+    items: NavItem[];
+};
+export interface AppShellProps {
+    /** Brand mark, top of the sidebar. */
+    brand?: ReactNode;
+    /**
+     * DX-3412 — an alternate, narrower brand mark shown in place of `brand`
+     * when the sidebar is COLLAPSED (`data-collapsed`) — a logo-only mark that
+     * fits the 56px collapsed rail (`w-14`), where the full `brand` (typically
+     * a logo + team name) would overflow. Omit to render nothing in the
+     * collapsed rail's brand row, the pre-DX-3412 behavior.
+     */
+    brandCollapsed?: ReactNode;
+    sections: NavSection[];
+    activeId?: string;
+    /** Pinned to the bottom of the sidebar — account, version, help. */
+    sidebarFooter?: ReactNode;
+    /** The top bar's content: search, actions, avatar. */
+    header?: ReactNode;
+    /**
+     * The landmark the content region is exposed as. `"main"` is right for the
+     * shell that IS the page.
+     *
+     * Set `"none"` when this shell is EMBEDDED in a page that already has a
+     * `<main>` — a preview of the shell inside documentation, or a sub-shell
+     * within a settings area. A document may only have one main landmark, and a
+     * second one is not a cosmetic problem: assistive technology offers "skip to
+     * main content" as a single destination, so two of them makes that command
+     * ambiguous and the shortcut stops being reliable.
+     *
+     * @default "main"
+     */
+    contentLandmark?: "main" | "none";
+    /**
+     * The accessible name of the sidebar's navigation landmark.
+     *
+     * A `<nav>` is a landmark, and assistive technology lists landmarks as
+     * navigation destinations. An UNNAMED one is announced as just "navigation",
+     * so two of them on a page — a shell previewed inside a page that is itself a
+     * shell, a sub-shell in a settings area — produce two identical entries and
+     * the list stops being useful. Same failure `contentLandmark` exists for,
+     * one landmark over.
+     *
+     * The default names it rather than leaving it bare; give an EMBEDDED shell a
+     * distinct one.
+     *
+     * @default the provider's `appShell.mainNavigation`
+     */
+    navLabel?: string;
+    /**
+     * Which box scrolls when the content is taller than the screen.
+     *
+     * `"content"` — the default, and what an application shell IS. The shell is
+     * exactly the viewport, the header and sidebar are fixed by structure, and
+     * the content column scrolls itself. A screen that wants to fill the height
+     * it has been given writes `flex-1 min-h-0` and never names a viewport unit
+     * or one of this library's tokens.
+     *
+     * `"document"` — the shell grows with its content and the PAGE scrolls, with
+     * the header and sidebar stuck to the top. For a shell embedded in a longer
+     * document, or a page whose content genuinely wants the browser's own
+     * scrollbar. It is the opt-out rather than the default, deliberately: the
+     * bounded arrangement is the one nobody has to compute anything for, and a
+     * default that made consumers subtract a header height from `100dvh` is what
+     * this prop exists to have stopped.
+     *
+     * @default "content"
+     */
+    scroll?: "content" | "document";
+    /**
+     * Change this to send the content back to the top — a route path, a record
+     * id, whatever identifies "a different screen is showing now".
+     *
+     * IT EXISTS BECAUSE BOUNDING THE SHELL MOVED THE SCROLLER. Every routed
+     * application resets the scroll on navigation, and while the DOCUMENT was
+     * the scroller they all wrote `window.scrollTo({ top: 0 })`. That line is
+     * inert here: the window no longer scrolls, so a route change would leave
+     * the new screen opened halfway down with nothing to indicate why.
+     *
+     * The alternative was to hand out a ref and let each consumer scroll it,
+     * which is the same work in every application plus a piece of this
+     * component's internals in all of them. The scroller stays private; the
+     * element also carries `data-app-shell-content` for the rarer jobs — scroll
+     * restoration on a back navigation, an intersection observer — that need the
+     * box itself.
+     */
+    scrollResetKey?: string | number;
+    /**
+     * Remembers whether the sidebar is collapsed, under `danxbot-<persistId>`.
+     * `false` stops it being remembered at all.
+     *
+     * COLLAPSING IS THE ONE GESTURE ON THIS SHELL THAT ONLY MAKES SENSE KEPT.
+     * Its entire purpose is to give the content the sidebar's width back, and it
+     * was plain `useState` — so every refresh handed the width straight back to
+     * the navigation. Somebody who wants a narrow sidebar wants it on every load;
+     * re-collapsing it on each one is the app forgetting a decision that was
+     * never provisional.
+     *
+     * NOTE THE DIFFERENCE FROM `PanelGroup`'s `persistId`, which is undefined by
+     * default and persists nothing until a caller names it. That is right there
+     * and wrong here: a page can hold any number of panel groups, so none of them
+     * can claim a default key without colliding with the next one, whereas an
+     * application has exactly ONE shell and can safely name itself. Two shells on
+     * one origin — a shell previewed inside a shell — give the inner one its own
+     * id, which is what the test for that case pins.
+     *
+     * It is the ONLY thing this component stores, and it is the only KIND of
+     * thing it should: a per-viewer arrangement that can come back empty with no
+     * consequence. Every read and write goes through `lib/persist`, which
+     * swallows the throw `localStorage` raises in a private window or wherever
+     * storage is blocked by policy — the read happens in a `useState`
+     * initializer, where an unhandled throw unmounts the whole tree. A blocked
+     * browser gets an expanded sidebar and a working app, never a blank page.
+     *
+     * @default "app-shell-sidebar"
+     */
+    persistId?: string | false;
+    children: ReactNode;
+    className?: string;
+}
+export declare function AppShell({ brand, brandCollapsed, sections, activeId, sidebarFooter, header, contentLandmark, navLabel, scroll, scrollResetKey, persistId, children, className, }: AppShellProps): import("react").JSX.Element;

package/dist/types/components/Attention.d.ts

@@ -0,0 +1,87 @@
+import type { HTMLAttributes, ReactNode, Ref } from "react";
+import { type AttentionEffect, type AttentionEffects, type AttentionIntensity, type AttentionSpeed, type ValidAttentionEffects } from "../lib/attention";
+export type { AttentionEffect, AttentionEffects, AttentionIntensity, AttentionSpeed };
+export type AttentionShape = "circle" | "pill" | "rounded" | "square" | "inherit";
+export type AttentionTone = "accent" | "brand" | "info" | "success" | "warning" | "danger" | "neutral";
+export interface AttentionProps<E extends AttentionEffects = AttentionEffects> extends Omit<HTMLAttributes<HTMLElement>, "children"> {
+    /** What to draw the eye to. Rendered untouched; its box is the box the effect hugs. */
+    children: ReactNode;
+    /**
+     * The shape of the control AND of its effect (DX-4504): `circle` (a circular
+     * icon button), `pill`, `rounded` (the library's large radius) or `square`
+     * re-cut the wrapped control's own corners (its border-radius, with an
+     * `!important` that beats a `rounded-md` utility), so there is never a square
+     * button inside a circular effect. Only the corners change: the box, hit area
+     * and layout stay the control's own. `circle` is 50%, so it is a circle on a
+     * square control and an ellipse on any other: use `pill` there. `inherit`
+     * leaves the control alone and MEASURES its own border-radius for the effect.
+     *
+     * @default "inherit"
+     */
+    shape?: AttentionShape;
+    /**
+     * `ripple` slow click-ripple circles: each grows from the centre and fades to nothing as it reaches its radius, staggered so one is always growing, each to a different radius.
+     * `pulse` a tinted shape behind the child breathing in scale and opacity.
+     * `glow` a soft halo that breathes.
+     * `ring` a bright arc travelling round the border.
+     * `beacon` one radar ping every `interval`.
+     * `shimmer` a glint sweeping across the child every `interval`.
+     * `bounce` / `wiggle` a nudge of the child itself every `interval`.
+     *
+     * Or a list to combine them (DX-4504), e.g. `["wiggle", "shimmer"]`: each draws its own layer, stacked in one
+     * fixed order (glow, pulse, ripple, beacon, ring behind the control; shimmer over it) whatever order they are
+     * listed in, each at its own speed. `bounce` and `wiggle` both move the control itself, so they cannot be
+     * combined with each other: a literal list naming both is a type error, and at runtime neither is drawn and a
+     * console error names the conflict.
+     *
+     * @default "ripple"
+     */
+    effect?: E & ValidAttentionEffects<E>;
+    /** Highlight the whole background behind the child. This is the static tint, and it stays under reduced motion. @default false */
+    fill?: boolean;
+    /**
+     * Clip the `ripple` circles to the control's shape, like a click ripple
+     * (`true`), or let them grow out past its edge (`false`). Only `ripple` has
+     * circles to clip; every other effect ignores it.
+     *
+     * The circles paint BEHIND the control's content, so a contained ripple
+     * shows on a transparent control (a ghost or outline button, a card with no
+     * background) and is hidden by a solid background. On a solid control use
+     * `contain={false}`: the circles then grow out past its edge, where they show.
+     *
+     * @default true
+     */
+    contain?: boolean;
+    /** The colour, as one of the library's semantic tones. @default "accent" */
+    tone?: AttentionTone;
+    /**
+     * `slow`, `normal` or `fast`, or a number of milliseconds for one cycle of
+     * the effect. For the periodic effects (`beacon`, `shimmer`, `bounce`,
+     * `wiggle`) the cycle is the gap between two bursts, and `interval` wins over
+     * a numeric `speed`.
+     *
+     * @default "normal"
+     */
+    speed?: AttentionSpeed;
+    /** How strong: the opacity of the waves and tint, and how far a wave reaches. @default "medium" */
+    intensity?: AttentionIntensity;
+    /** How many waves `ripple` keeps in flight, 1 to 5 (anything else is clamped). Ignored by every other effect. @default 3 */
+    rings?: number;
+    /**
+     * Draw the effect. Switching it off fades the effect out and removes the
+     * layers; switching it back on fades it in.
+     *
+     * @default true
+     */
+    active?: boolean;
+    /**
+     * Milliseconds between two bursts of a periodic effect (`beacon`, `shimmer`,
+     * `bounce`, `wiggle`). Ignored, with a development warning, by the continuous
+     * effects, which have no rest to size.
+     */
+    interval?: number;
+    /** Render a block `div` (for a card or a row) instead of an inline `span` hugging an inline control. A layout choice made once: changing it swaps the element, which re-mounts the child. @default false */
+    block?: boolean;
+    ref?: Ref<HTMLElement>;
+}
+export declare function Attention<const E extends AttentionEffects = "ripple">({ children, shape, effect, fill, contain, tone, speed, intensity, rings, active, interval, block, className, style, ref, ...props }: AttentionProps<E>): import("react").JSX.Element;