@mohasinac/appkit 4.62.0 → 4.63.0

package/dist/ui/components/Disclaimer.js

@@ -0,0 +1,83 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import React from "react";
+/*
+ * Defining modules, not `../index` — Root Cause #18.
+ *
+ * The barrel re-exports THIS component, so importing three primitives back
+ * through it closed a two-module cycle (`audit-import-cycles` component 1).
+ * The deep paths below have one direction only.
+ */
+import { Div } from "./Div.js";
+import { Stack } from "./Layout.js";
+import { Text } from "./Typography.js";
+import { DISCLAIMERS, } from "../../_internal/shared/content/disclaimers.js";
+import { resolvePublishedCopy, resolvePublishedValues, } from "../../_internal/shared/content/published-values.js";
+/**
+ * The one way to render a disclaimer (Phase 12).
+ *
+ * ## 🛑 `id` only — there is no `text` prop, deliberately
+ *
+ * A `text` escape hatch would make this a styled box, and then the legally
+ * material disclaimers would be written at their call sites again, drift, and
+ * end up weakest exactly where they matter most. That is the failure this
+ * registry exists to close. If a surface needs a disclaimer that does not
+ * exist, the fix is a new registry entry — which is also what gets it
+ * reviewed.
+ *
+ * ## Tokens resolve here
+ *
+ * The protection entry quotes `{{saleProtectionMaxValue}}` and the claim
+ * windows, so the published limits come from the constants that ENFORCE them
+ * (Phase 9's mechanism). A change to `SALE_PROTECTION_MAX_VALUE` updates the
+ * terms rather than contradicting them.
+ *
+ * Code-derived values are the default; a caller with settings in hand passes
+ * better ones for the money figures.
+ *
+ * ## Safe in a Server Component
+ *
+ * No hooks, no state, and the registry is a plain object — so this renders on
+ * either side of the boundary. Do not add state here without checking every
+ * RSC call site (Root Cause #76).
+ */
+const CODE_DERIVED_VALUES = resolvePublishedValues();
+/**
+ * Renders `**bold**` and nothing else.
+ *
+ * 🛑 A deliberately tiny subset, not a markdown renderer. The emphasis is
+ * load-bearing in exactly the places it is used — "**not insurance**" in the
+ * protection entry, "**under review**" versus "**verified**" in the scam
+ * registry — and those are the phrases a reader skims past without it.
+ *
+ * 🛑 And it returns ELEMENTS, never HTML. The bodies are our own constants so
+ * injection is not the risk; the risk is that a `dangerouslySetInnerHTML`
+ * here would invite someone to pass admin-editable text through it later,
+ * which is how a disclaimer box becomes a stored-XSS surface.
+ */
+function renderEmphasis(text) {
+    return text.split(/(\*\*[^*]+\*\*)/g).map((part, i) => part.startsWith("**") && part.endsWith("**") && part.length > 4 ? (_jsx(Text, { as: "span", weight: "semibold", children: part.slice(2, -2) }, i)) : (_jsx(React.Fragment, { children: part }, i)));
+}
+export function Disclaimer({ id, publishedValues = CODE_DERIVED_VALUES, inline = false, className = "", }) {
+    const entry = DISCLAIMERS[id];
+    /*
+     * A `Record<DisclaimerId, …>` means this cannot happen through the type, but
+     * an `as DisclaimerId` cast at a call site could — and rendering nothing is
+     * the wrong failure here. A missing disclaimer is invisible, which is the
+     * whole problem; so it renders nothing only when the registry genuinely has
+     * no entry, and the audit is what catches that case before it ships.
+     */
+    if (!entry)
+        return null;
+    const body = resolvePublishedCopy(entry.body, publishedValues);
+    const content = (_jsxs(Stack, { gap: "xs", children: [entry.heading && (_jsx(Text, { size: "xs", weight: "semibold", transform: "uppercase", color: "muted", children: entry.heading })), _jsx(Text, { size: "xs", color: "muted", className: "leading-relaxed", children: renderEmphasis(body) })] }));
+    if (inline)
+        return _jsx(Div, { className: className, children: content });
+    /*
+     * 🛑 `surface` + the matching ink, never a status background with literal
+     * white text. `-surface` is a near-white tint in light themes and a dark
+     * tint in dark ones, so a fixed `text-white` is invisible in exactly one
+     * theme — Root Cause #67, which shipped 26 invisible surfaces that way.
+     * `Text color="muted"` above pairs correctly with both.
+     */
+    return (_jsx(Div, { surface: entry.tone === "warning" ? "warning-surface" : "muted", rounded: "lg", padding: "sm", className: className, children: content }));
+}

package/dist/ui/components/OverflowRow.js

@@ -26,14 +26,22 @@ import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-run
  * @tag sideEffects:dom-measurement
  */
 import { useCallback, useEffect, useId, useMemo, useRef, useState } from "react";
+import { createPortal } from "react-dom";
 import NextLink from "next/link.js";
 import { Check, ChevronDown, Search } from "lucide-react";
 import { Avatar } from "./Avatar.js";
 import { Icon } from "./Icon.js";
 import { Input } from "./Input.js";
 import { useRowCollapse } from "./row-collapse.js";
+import { MOBILE_QUERY } from "./toolbar-collapse.js";
+import { useBottomChromeSlot } from "./bottom-chrome-slot.js";
+import { useMediaQuery } from "../../react/hooks/useMediaQuery.js";
 const UI_OVERFLOW_ROW = {
     shell: "appkit-overflow-row",
+    /** The in-flow measuring box, once the control itself has been portalled away. */
+    shellDocked: "appkit-overflow-row--docked",
+    /** The portalled control, as its own row inside `BottomChrome`. */
+    dock: "appkit-overflow-row__dock",
     row: "appkit-overflow-row__row",
     pill: "appkit-overflow-row__pill",
     pillActive: "appkit-overflow-row__pill--active",
@@ -77,11 +85,22 @@ export function OverflowRow({ items, ariaLabel, activeId, variant = "tabs", plac
     const shellRef = useRef(null);
     const rowRef = useRef(null);
     const triggerRef = useRef(null);
+    /*
+     * The portalled control, when docked into the bottom bar. Needed only by the
+     * outside-click handler: a portal moves the node out of `shellRef`'s subtree
+     * in the DOM, so `shell.contains(target)` is FALSE for a click on the
+     * trigger itself — the dropdown would close on the very click that opened
+     * it, which reads as the control being dead.
+     */
+    const dockRef = useRef(null);
     const searchRef = useRef(null);
     const listboxId = useId();
     const [open, setOpen] = useState(false);
     const [query, setQuery] = useState("");
     const [activeIndex, setActiveIndex] = useState(0);
+    // Both before any conditional return — the collapsed branch is one.
+    const bottomChromeSlot = useBottomChromeSlot();
+    const isMobile = useMediaQuery(MOBILE_QUERY);
     const signature = useMemo(() => signatureOf(items), [items]);
     const collapsed = useRowCollapse(shellRef, rowRef, signature, {
         disabled: alwaysCollapsed,
@@ -92,7 +111,11 @@ export function OverflowRow({ items, ariaLabel, activeId, variant = "tabs", plac
         if (!open)
             return;
         const onDown = (event) => {
-            if (!shellRef.current?.contains(event.target))
+            const target = event.target;
+            const inShell = shellRef.current?.contains(target) ?? false;
+            // See `dockRef` — when docked, the control lives outside the shell.
+            const inDock = dockRef.current?.contains(target) ?? false;
+            if (!inShell && !inDock)
                 setOpen(false);
         };
         document.addEventListener("mousedown", onDown);
@@ -166,7 +189,7 @@ export function OverflowRow({ items, ariaLabel, activeId, variant = "tabs", plac
     const hasAnyVisual = items.some((item) => item.imageUrl || item.iconName || item.emoji || item.dotTone);
     // ── Collapsed: one searchable dropdown ──────────────────────────────────
     if (collapsed) {
-        return (_jsxs("div", { ref: shellRef, className: [UI_OVERFLOW_ROW.shell, className].filter(Boolean).join(" "), "data-collapsed": "true", children: [_jsxs("button", { ref: triggerRef, type: "button", className: UI_OVERFLOW_ROW.trigger, "aria-haspopup": "listbox", "aria-expanded": open, "aria-controls": open ? listboxId : undefined, "aria-label": ariaLabel, onClick: () => setOpen((prev) => !prev), onKeyDown: (event) => {
+        const dropdown = (_jsxs(_Fragment, { children: [_jsxs("button", { ref: triggerRef, type: "button", className: UI_OVERFLOW_ROW.trigger, "aria-haspopup": "listbox", "aria-expanded": open, "aria-controls": open ? listboxId : undefined, "aria-label": ariaLabel, onClick: () => setOpen((prev) => !prev), onKeyDown: (event) => {
                         if (!open && (event.key === "ArrowDown" || event.key === "Enter")) {
                             event.preventDefault();
                             setOpen(true);
@@ -186,6 +209,35 @@ export function OverflowRow({ items, ariaLabel, activeId, variant = "tabs", plac
                                     const body = (_jsxs(_Fragment, { children: [hasAnyVisual ? visualOf(item, "option") : null, _jsx("span", { className: UI_OVERFLOW_ROW.optionLabel, children: item.label }), typeof item.count === "number" && (_jsx("span", { className: UI_OVERFLOW_ROW.optionCount, children: item.count > 99 ? "99+" : item.count })), isSelected && (_jsx(Check, { className: `w-4 h-4 ${UI_OVERFLOW_ROW.check}`, "aria-hidden": "true" }))] }));
                                     return item.href ? (_jsx(Link, { ...linkProps, id: `${listboxId}-${item.id}`, role: "option", "aria-selected": isSelected, href: item.href, className: classes, onMouseEnter: () => setActiveIndex(index), children: body }, item.id)) : (_jsx("button", { id: `${listboxId}-${item.id}`, role: "option", type: "button", "aria-selected": isSelected, disabled: item.disabled, className: classes, onClick: () => commit(item), onMouseEnter: () => setActiveIndex(index), children: body }, item.id));
                                 })] })] }))] }));
+        /*
+         * ── Mobile: the collapsed row docks into the bottom bar ────────────────
+         *
+         * A row that has collapsed to a dropdown is no longer a row — it is one
+         * control, and on a phone the place for one control is the thumb zone,
+         * not a band competing with the page heading. It joins `BottomChrome` as
+         * its OWN row, so it stacks above a CTA bar instead of overlapping it,
+         * and the tier's single `ResizeObserver` adds its height to
+         * `--bottom-chrome-height` — which is what keeps page content from being
+         * hidden behind it on scroll, with no consumer doing anything.
+         *
+         * 🛑 `shellRef` STAYS IN PLACE, always. It is what `useRowCollapse`
+         * measures the available width against; portal it into the bottom bar and
+         * it would measure the VIEWPORT instead, read as "there is room now",
+         * expand, return to the narrow container, collapse, and oscillate forever.
+         * So the shell remains an empty in-flow box at the original position and
+         * only the CONTROL is portalled. The expanded branch below is unchanged
+         * and still renders the real row there.
+         */
+        const docked = isMobile && !!bottomChromeSlot;
+        return (_jsx("div", { ref: shellRef, className: [
+                UI_OVERFLOW_ROW.shell,
+                docked ? UI_OVERFLOW_ROW.shellDocked : "",
+                className,
+            ]
+                .filter(Boolean)
+                .join(" "), "data-collapsed": "true", "data-docked": docked ? "true" : "false", children: docked
+                ? createPortal(_jsx("div", { ref: dockRef, className: UI_OVERFLOW_ROW.dock, children: dropdown }), bottomChromeSlot)
+                : dropdown }));
     }
     // ── Expanded: the pill row ──────────────────────────────────────────────
     return (_jsx("div", { ref: shellRef, className: [UI_OVERFLOW_ROW.shell, className].filter(Boolean).join(" "), "data-collapsed": "false", children: _jsx("div", { ref: rowRef, className: UI_OVERFLOW_ROW.row, role: variant === "tabs" ? "tablist" : undefined, "aria-label": ariaLabel, children: items.map((item) => {

package/dist/ui/components/OverflowRow.style.css

@@ -233,3 +233,41 @@
   font-size: var(--appkit-text-sm);
   color: var(--appkit-color-text-muted);
 }
+
+/* ── Docked: the collapsed control lives in the bottom bar on mobile ────────
+ *
+ * The shell stays in flow as a zero-height measuring box — `useRowCollapse`
+ * compares the row's cached natural width against THIS element, so it must
+ * keep the original container's width. Portalling it instead would make it
+ * measure the viewport, read as "there is room", expand, and oscillate.
+ */
+.appkit-overflow-row--docked {
+  height: 0;
+  /* Not `display:none`: a hidden box has no width, and width is the entire
+     input to the collapse decision. */
+  overflow: hidden;
+}
+
+.appkit-overflow-row__dock {
+  position: relative;
+  display: flex;
+  width: 100%;
+  pointer-events: auto;
+  padding: var(--appkit-space-2) var(--appkit-space-4);
+  background: var(--appkit-color-surface-elevated);
+  border-top: 1px solid var(--appkit-color-border);
+}
+
+.appkit-overflow-row__dock > .appkit-overflow-row__trigger {
+  width: 100%;
+}
+
+/* 🛑 Opens UPWARD when docked. The default popover is `top: 100%`, which from
+   a bar at the bottom edge renders off-screen — the control would look dead.
+   `BottomChrome` deliberately sets no `overflow`, so the panel may escape the
+   tier; that is the documented contract its own header relies on. */
+.appkit-overflow-row__dock .appkit-overflow-row__popover {
+  top: auto;
+  bottom: calc(100% + var(--appkit-space-1));
+  width: 100%;
+}

package/dist/ui/components/RichTextEditor.js

@@ -1,6 +1,44 @@
 "use client";
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useMemo, useRef } from "react";
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useId, useMemo, useRef, useState } from "react";
+import { parseChartAttr, CHART_KINDS } from "./chart-spec.js";
+import { chartFigureHtml } from "../rich-text/chart-blocks.js";
+/**
+ * What the Chart button drops into the editor to be edited.
+ *
+ * A filled, working example rather than an empty skeleton: an author editing
+ * real numbers into a chart that already renders can see what each field does,
+ * where one facing `{"kind":"","categories":[],"series":[]}` has to guess the
+ * shape before anything appears at all.
+ */
+const STARTER_CHART = JSON.stringify({
+    kind: "groupedBar",
+    title: "Untitled chart",
+    categories: ["First", "Second", "Third"],
+    series: [
+        { label: "Series A", values: [3, 5, 4] },
+        { label: "Series B", values: [4, 2, 6] },
+    ],
+    unit: "",
+    caption: "",
+}, null, 2);
+/** The chart JSON editor shown under the toolbar, with live validation. */
+function ChartDraftPanel({ draft, onDraftChange, onInsert, onCancel, }) {
+    const result = useMemo(() => parseChartAttr(draft), [draft]);
+    /*
+     * 🛑 Generated, not a literal. Two RichTextEditors on one page — a category
+     * form with a description and an SEO blurb, say — would otherwise emit the
+     * SAME hardcoded id twice, so the second panel's `htmlFor` and
+     * `aria-describedby` resolve to the FIRST one's textarea and error. A screen
+     * reader then reads the wrong field's error and clicking the label focuses
+     * the wrong box, which is exactly the class of bug the `ariaLabelledBy` note
+     * at the top of this file exists about.
+     */
+    const panelId = useId();
+    const fieldId = `${panelId}-draft`;
+    const errorId = `${panelId}-error`;
+    return (_jsxs("div", { className: "appkit-rich-text-editor__chart border-b p-2 border-[var(--appkit-color-border)]", children: [_jsxs("label", { className: "mb-1 block text-xs font-medium text-[var(--appkit-color-text-muted)]", htmlFor: fieldId, children: ["Chart data \u2014 kinds: ", CHART_KINDS.join(", "), ". Each series needs one value per category."] }), _jsx("textarea", { id: fieldId, value: draft, onChange: (e) => onDraftChange(e.target.value), rows: 12, spellCheck: false, "aria-invalid": !result.ok, "aria-describedby": result.ok ? undefined : errorId, className: "w-full rounded border p-2 font-mono text-xs border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface-input)] text-[var(--appkit-color-text)]" }), result.ok ? null : (_jsx("p", { id: errorId, role: "alert", className: "mt-1 text-xs text-[var(--appkit-color-error)]", children: result.reason })), _jsxs("div", { className: "mt-2 flex gap-2", children: [_jsx("button", { type: "button", onClick: onInsert, disabled: !result.ok, className: "rounded px-2 py-1 text-xs font-medium transition disabled:cursor-not-allowed disabled:opacity-50 bg-[var(--appkit-color-primary)] text-[var(--appkit-color-text-on-primary)]", children: "Insert chart" }), _jsx("button", { type: "button", onClick: onCancel, className: "rounded px-2 py-1 text-xs font-medium transition hover:bg-surface-hover text-[var(--appkit-color-text-muted)]", children: "Cancel" })] })] }));
+}
 // Matches exactly what this editor's own toolbar (bold/italic/underline/
 // lists/link/clear-formatting) and typing can legitimately produce.
 // Anything else — <script>, <img onerror=...>, <iframe>, <svg>, <style>,
@@ -10,6 +48,9 @@ import { useEffect, useMemo, useRef } from "react";
 const ALLOWED_TAGS = new Set([
     "B", "STRONG", "I", "EM", "U", "S", "STRIKE",
     "UL", "OL", "LI", "A", "BR", "DIV", "SPAN", "P",
+    // FIGURE is here only because the toolbar's "Chart" button produces it.
+    // It carries no text content — see sanitizeAttribute for the data-chart rule.
+    "FIGURE",
 ]);
 function isSafeHref(href) {
     const trimmed = href.trim();
@@ -18,14 +59,33 @@ function isSafeHref(href) {
     // relative), or "#" — reject everything else including javascript:.
     return /^(https?:\/\/|mailto:|\/(?!\/)|#)/i.test(trimmed);
 }
+/**
+ * 🛑 This is the SAVE-time sanitiser, and it is a different, stricter one from
+ * `RichText.tsx`'s render-time `sanitiseHtml`. Both had to learn about
+ * `data-chart` — teaching only the renderer, as a first pass here did, means a
+ * chart inserted in the editor is silently deleted the moment it is saved,
+ * with the toolbar button appearing to work perfectly.
+ *
+ * The rule is stricter than the renderer's on purpose: the value is not merely
+ * allowed through, it must PARSE as a valid ChartSpec. Invalid JSON or a spec
+ * that fails validation loses the attribute, and the empty `<figure>` that
+ * remains is then dropped by `sanitizeElement`. So malformed chart data cannot
+ * be persisted at all, which is the right place to stop it — once stored, it
+ * is every future reader's problem.
+ */
 function sanitizeAttribute(el, attr) {
-    const isSafeAnchorHref = el.tagName === "A" && attr.name.toLowerCase() === "href";
-    if (!isSafeAnchorHref) {
-        el.removeAttribute(attr.name);
+    const name = attr.name.toLowerCase();
+    if (el.tagName === "A" && name === "href") {
+        if (!isSafeHref(attr.value))
+            el.setAttribute("href", "#");
+        return;
+    }
+    if (el.tagName === "FIGURE" && name === "data-chart") {
+        if (!parseChartAttr(attr.value).ok)
+            el.removeAttribute(attr.name);
         return;
     }
-    if (!isSafeHref(attr.value))
-        el.setAttribute("href", "#");
+    el.removeAttribute(attr.name);
 }
 function sanitizeElement(root, el) {
     if (!ALLOWED_TAGS.has(el.tagName)) {
@@ -33,6 +93,14 @@ function sanitizeElement(root, el) {
         return;
     }
     Array.from(el.attributes).forEach((attr) => sanitizeAttribute(el, attr));
+    // A <figure> is only legal here as a chart carrier. If the attribute did not
+    // survive validation above, what is left is an empty element with no text and
+    // no meaning — drop it rather than persist a blank block the author cannot
+    // see, select, or delete.
+    if (el.tagName === "FIGURE" && !el.hasAttribute("data-chart")) {
+        root.removeChild(el);
+        return;
+    }
     sanitizeChildren(el);
 }
 function sanitizeChildren(root) {
@@ -55,6 +123,7 @@ function sanitizeRichTextHtml(html) {
 }
 export function RichTextEditor({ value, onChange, disabled = false, className = "", minHeightClassName = "min-h-[180px]", placeholder = "Write formatted content...", ariaLabelledBy, ariaLabel, }) {
     const editorRef = useRef(null);
+    const [chartDraft, setChartDraft] = useState(null);
     const emitChange = () => {
         if (!editorRef.current)
             return;
@@ -102,12 +171,34 @@ export function RichTextEditor({ value, onChange, disabled = false, className =
                 exec("createLink", href);
             },
         },
+        {
+            label: "Chart",
+            title: "Insert chart",
+            run: () => setChartDraft(STARTER_CHART),
+        },
         {
             label: "Clear",
             title: "Clear formatting",
             run: () => exec("removeFormat"),
         },
     ], []);
+    /*
+     * `insertHTML` rather than building a node and splicing it in: the editor is
+     * a contenteditable and execCommand is already how every other toolbar action
+     * writes, so this keeps the caret and the undo stack behaving the same way.
+     * The inserted markup then goes straight through `emitChange` →
+     * `sanitizeRichTextHtml`, so the chart is validated on the way out exactly as
+     * a pasted one would be — the button gets no privileged path.
+     */
+    const insertChart = () => {
+        if (chartDraft === null)
+            return;
+        const parsed = parseChartAttr(chartDraft);
+        if (!parsed.ok)
+            return;
+        exec("insertHTML", chartFigureHtml(parsed.spec));
+        setChartDraft(null);
+    };
     useEffect(() => {
         const editor = editorRef.current;
         if (!editor)
@@ -120,7 +211,7 @@ export function RichTextEditor({ value, onChange, disabled = false, className =
             editor.innerHTML = safeValue;
         }
     }, [value]);
-    return (_jsxs("div", { className: `appkit-rich-text-editor rounded-lg border border-zinc-200 bg-[var(--appkit-color-surface)] border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] ${className}`, "data-section": "richtexteditor-div-582", children: [_jsx("div", { className: "appkit-rich-text-editor__toolbar flex flex-wrap gap-1 border-b p-2 border-[var(--appkit-color-border)]", "data-section": "richtexteditor-div-583", children: toolbarActions.map((action) => (_jsx("button", { type: "button", title: action.title, onClick: action.run, disabled: disabled, className: "appkit-rich-text-editor__btn rounded px-2 py-1 text-xs font-medium transition hover:bg-surface-hover disabled:cursor-not-allowed disabled:opacity-50 text-[var(--appkit-color-text-muted)]", children: action.label }, action.title))) }), _jsx("div", { ref: editorRef, 
+    return (_jsxs("div", { className: `appkit-rich-text-editor rounded-lg border border-zinc-200 bg-[var(--appkit-color-surface)] border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] ${className}`, "data-section": "richtexteditor-div-582", children: [_jsx("div", { className: "appkit-rich-text-editor__toolbar flex flex-wrap gap-1 border-b p-2 border-[var(--appkit-color-border)]", "data-section": "richtexteditor-div-583", children: toolbarActions.map((action) => (_jsx("button", { type: "button", title: action.title, onClick: action.run, disabled: disabled, className: "appkit-rich-text-editor__btn rounded px-2 py-1 text-xs font-medium transition hover:bg-surface-hover disabled:cursor-not-allowed disabled:opacity-50 text-[var(--appkit-color-text-muted)]", children: action.label }, action.title))) }), chartDraft !== null ? (_jsx(ChartDraftPanel, { draft: chartDraft, onDraftChange: setChartDraft, onInsert: insertChart, onCancel: () => setChartDraft(null) })) : null, _jsx("div", { ref: editorRef, 
                 /*
                  * 🛑 `role` and `aria-label` USED TO BE DECLARED HERE TOO, hardcoded
                  * to "Rich text editor" — and when the labelling props were added

package/dist/ui/components/chart-spec.d.ts

@@ -0,0 +1,68 @@
+export declare const CHART_KINDS: readonly ["bar", "groupedBar", "line", "area"];
+export type ChartKind = (typeof CHART_KINDS)[number];
+/**
+ * 🛑 Eight, and a ninth is never a generated hue.
+ *
+ * The categorical palette is a fixed, validated ORDER of eight steps, checked
+ * for colourblind separation between adjacent pairs. A 9th colour generated at
+ * runtime cannot be validated, so a 9-series chart is REFUSED and the author is
+ * told to fold the tail into "Other" or split into small multiples.
+ */
+export declare const CHART_MAX_SERIES = 8;
+export interface ChartSeries {
+    label: string;
+    values: number[];
+}
+export interface ChartSpec {
+    kind: ChartKind;
+    /** X-axis categories. `series[].values` must be exactly this long. */
+    categories: string[];
+    series: ChartSeries[];
+    /** Appended to every value in tooltips and the table view. */
+    unit?: string;
+    /** Rendered under the plot. */
+    caption?: string;
+    /** Accessible name. Falls back to the caption. */
+    title?: string;
+}
+export type ChartSpecResult = {
+    ok: true;
+    spec: ChartSpec;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Validate an untrusted object into a `ChartSpec`.
+ *
+ * 🛑 Returns a REASON rather than throwing or silently returning null. This
+ * parses author-supplied JSON out of a `data-chart` attribute, and an author
+ * who mistyped needs to be told which rule they broke — a chart that quietly
+ * renders nothing is the failure mode this codebase keeps paying for.
+ *
+ * 🛑 There is deliberately no second y-axis in the shape. A dual-axis chart
+ * invites comparing two incommensurable scales on one plot; two measures mean
+ * two charts, small multiples, or indexing to a common base.
+ */
+export declare function parseChartSpec(input: unknown): ChartSpecResult;
+/**
+ * Parse the JSON string carried by a `data-chart` attribute.
+ *
+ * 🛑 The normalised error is deliberately NOT surfaced to the caller. The
+ * thrown value is a `SyntaxError` from `JSON.parse` carrying nothing an author
+ * can act on beyond "it is not JSON" — which the returned reason already says,
+ * in their language, at the place they will read it. Returning the engine's
+ * message instead is how server text reaches a user (Root Cause #86). Malformed
+ * authored content is an expected input here, not an incident to report.
+ *
+ * `normalizeError` is still called, because that is what `audit-catch-normalize`
+ * actually accepts: its header also lists "return immediately" as sufficient,
+ * but the implementation only tests for `normalizeError(var)` or `throw var`
+ * (audit-catch-normalize.mjs:210-213), so a bare early return is reported.
+ */
+export declare function parseChartAttr(json: string): ChartSpecResult;
+/**
+ * How many series the palette can colour. Exposed so a caller can decide to
+ * fold a tail into "Other" BEFORE validation rejects the whole chart.
+ */
+export declare function exceedsSeriesLimit(count: number): boolean;

package/dist/ui/components/chart-spec.js

@@ -0,0 +1,140 @@
+/**
+ * The chart DATA contract — pure, and deliberately separate from `<Chart>`.
+ *
+ * ## 🛑 Why this is not in Chart.tsx
+ *
+ * `Chart.tsx` is `"use client"` and statically reaches recharts. Anything that
+ * imports it inherits both. But the validator needs to be callable from places
+ * that are neither:
+ *
+ *   - `chart-blocks.ts`, which must stay SSR-safe because `RichTextRenderer`
+ *     is a Server Component;
+ *   - a route handler or a seed script validating authored content before it
+ *     is stored, where pulling in recharts would be absurd.
+ *
+ * Keeping the types and the parser here means a server-side caller gets the
+ * contract without the renderer — the same split as Root Cause #24's lesson
+ * about a file that mixed Node-only crypto with client-safe display helpers.
+ *
+ * No React, no DOM, no recharts.
+ */
+import { normalizeError } from "../../errors/normalize.js";
+export const CHART_KINDS = ["bar", "groupedBar", "line", "area"];
+/**
+ * 🛑 Eight, and a ninth is never a generated hue.
+ *
+ * The categorical palette is a fixed, validated ORDER of eight steps, checked
+ * for colourblind separation between adjacent pairs. A 9th colour generated at
+ * runtime cannot be validated, so a 9-series chart is REFUSED and the author is
+ * told to fold the tail into "Other" or split into small multiples.
+ */
+export const CHART_MAX_SERIES = 8;
+/**
+ * Validate an untrusted object into a `ChartSpec`.
+ *
+ * 🛑 Returns a REASON rather than throwing or silently returning null. This
+ * parses author-supplied JSON out of a `data-chart` attribute, and an author
+ * who mistyped needs to be told which rule they broke — a chart that quietly
+ * renders nothing is the failure mode this codebase keeps paying for.
+ *
+ * 🛑 There is deliberately no second y-axis in the shape. A dual-axis chart
+ * invites comparing two incommensurable scales on one plot; two measures mean
+ * two charts, small multiples, or indexing to a common base.
+ */
+export function parseChartSpec(input) {
+    if (typeof input !== "object" || input === null) {
+        return { ok: false, reason: "Chart data must be an object." };
+    }
+    const o = input;
+    const kind = o.kind;
+    if (typeof kind !== "string" || !CHART_KINDS.includes(kind)) {
+        return {
+            ok: false,
+            reason: `Chart "kind" must be one of ${CHART_KINDS.join(", ")}.`,
+        };
+    }
+    if (!Array.isArray(o.categories) ||
+        o.categories.length === 0 ||
+        !o.categories.every((c) => typeof c === "string" && c.length > 0)) {
+        return { ok: false, reason: 'Chart "categories" must be a non-empty array of labels.' };
+    }
+    const categories = o.categories;
+    if (!Array.isArray(o.series) || o.series.length === 0) {
+        return { ok: false, reason: 'Chart "series" must be a non-empty array.' };
+    }
+    if (o.series.length > CHART_MAX_SERIES) {
+        return {
+            ok: false,
+            reason: `A chart carries at most ${CHART_MAX_SERIES} series (got ${o.series.length}). ` +
+                `Fold the smallest into an "Other" series, or split into separate charts — ` +
+                `a 9th colour cannot be checked for colourblind separation.`,
+        };
+    }
+    const series = [];
+    for (const [i, raw] of o.series.entries()) {
+        if (typeof raw !== "object" || raw === null) {
+            return { ok: false, reason: `Series ${i + 1} must be an object.` };
+        }
+        const s = raw;
+        if (typeof s.label !== "string" || s.label.length === 0) {
+            return { ok: false, reason: `Series ${i + 1} needs a non-empty "label".` };
+        }
+        if (!Array.isArray(s.values) ||
+            !s.values.every((v) => typeof v === "number" && Number.isFinite(v))) {
+            return {
+                ok: false,
+                reason: `Series "${s.label}" — "values" must be an array of finite numbers.`,
+            };
+        }
+        if (s.values.length !== categories.length) {
+            return {
+                ok: false,
+                reason: `Series "${s.label}" has ${s.values.length} values but there are ` +
+                    `${categories.length} categories. They must match one-to-one.`,
+            };
+        }
+        series.push({ label: s.label, values: s.values });
+    }
+    return {
+        ok: true,
+        spec: {
+            kind: kind,
+            categories,
+            series,
+            ...(typeof o.unit === "string" ? { unit: o.unit } : {}),
+            ...(typeof o.caption === "string" ? { caption: o.caption } : {}),
+            ...(typeof o.title === "string" ? { title: o.title } : {}),
+        },
+    };
+}
+/**
+ * Parse the JSON string carried by a `data-chart` attribute.
+ *
+ * 🛑 The normalised error is deliberately NOT surfaced to the caller. The
+ * thrown value is a `SyntaxError` from `JSON.parse` carrying nothing an author
+ * can act on beyond "it is not JSON" — which the returned reason already says,
+ * in their language, at the place they will read it. Returning the engine's
+ * message instead is how server text reaches a user (Root Cause #86). Malformed
+ * authored content is an expected input here, not an incident to report.
+ *
+ * `normalizeError` is still called, because that is what `audit-catch-normalize`
+ * actually accepts: its header also lists "return immediately" as sufficient,
+ * but the implementation only tests for `normalizeError(var)` or `throw var`
+ * (audit-catch-normalize.mjs:210-213), so a bare early return is reported.
+ */
+export function parseChartAttr(json) {
+    try {
+        return parseChartSpec(JSON.parse(json));
+    }
+    catch (err) {
+        void normalizeError(err);
+        return { ok: false, reason: "Chart data is not valid JSON." };
+    }
+}
+/**
+ * How many series the palette can colour. Exposed so a caller can decide to
+ * fold a tail into "Other" BEFORE validation rejects the whole chart.
+ */
+export function exceedsSeriesLimit(count) {
+    return count > CHART_MAX_SERIES;
+}

package/dist/ui/components/index.style.css

@@ -51,6 +51,7 @@
 @import "./Toggle.style.css";
 @import "./QuantityStepper.style.css";
 @import "./Checkbox.style.css";
+@import "./Chart.style.css";
 @import "./EmptyState.style.css";
 @import "./SkipToMain.style.css";
 @import "./Toast.style.css";

package/dist/ui/components/surface-tokens.d.ts

@@ -226,7 +226,7 @@ export declare const PADDING_PRESETS: {
     readonly "content-banner": "py-[var(--appkit-space-10)] md:py-[var(--appkit-space-12)] lg:py-[var(--appkit-space-16)]";
 };
 export type PaddingPresetKey = PaddingKey;
-export type XPaddingKey = "none" | "x-xs" | "x-sm" | "x-md" | "x-5" | "x-lg" | "x-xl" | "x-sm-md" | "x-sm-lg-md" | "x-md-lg" | "x-md-xl" | "x-md-2xl" | "x-page" | "l-xl";
+export type XPaddingKey = "none" | "x-xs" | "x-sm" | "x-md" | "x-5" | "x-lg" | "x-xl" | "x-sm-md" | "x-sm-lg-md" | "x-md-lg" | "x-md-xl" | "x-md-2xl" | "x-page" | "l-md" | "l-xl";
 type YPaddingKey = "none" | "y-2xs" | "y-2xs-tall" | "y-xs" | "y-xs-tall" | "y-sm" | "y-sm-tall" | "y-md" | "y-md-lg" | "y-lg" | "y-xl" | "y-2xl" | "y-3xl" | "y-4xl" | "y-5xl" | "y-6xl" | "y-2-5xl" | "t-2xs" | "b-2xs" | "t-xs" | "b-xs" | "t-sm" | "b-sm" | "t-md" | "b-md" | "b-md-lg" | "b-lg" | "t-md-b-lg";
 export declare const X_ONLY_MAP: Record<XPaddingKey, string>;
 export type OverflowKey = "auto" | "hidden" | "scroll" | "visible" | "x-auto" | "x-hidden" | "y-auto" | "y-hidden";

package/dist/ui/components/surface-tokens.js

@@ -232,6 +232,15 @@ export const X_ONLY_MAP = {
     // selection-checkbox gutter).
     /** Asymmetric: `pl-8` — reserves a left gutter (e.g. for an overlaid selection checkbox). */
     "l-xl": "pl-[var(--appkit-space-8)]",
+    /**
+     * Asymmetric: `pl-4` — indents a nested block under its own heading.
+     *
+     * The grouped order-item rows (admin and seller) are the motivating pair:
+     * a group header followed by its member lines, where the indent is the only
+     * thing expressing the nesting. `x-md` would pad the right edge too, which
+     * is not what an indent means.
+     */
+    "l-md": "pl-[var(--appkit-space-4)]",
 };
 const Y_ONLY_MAP = {
     none: "",