@mohasinac/appkit 4.62.1 → 4.63.1

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: "",

package/dist/ui/components/toolbar-collapse.d.ts

@@ -1,3 +1,16 @@
+/** Below this the toolbar defaults to collapsed. Matches the `lg` boundary
+ *  that both toolbars already use to switch between their mobile and desktop
+ *  rows, so the default flips at the same width the layout does. */
+/**
+ * Below `lg` — the complement of `DESKTOP_QUERY` in `features/layout`.
+ *
+ * Exported so `OverflowRow` can dock its collapsed control into the bottom bar
+ * at exactly the width the tab bar exists at. It is NOT imported from
+ * `features/layout`: this is `ui/`, and a `ui → features` edge inverts the
+ * layering and is how `audit-import-cycles` regressions start. One literal in
+ * the lower layer, shared, beats two that can drift apart.
+ */
+export declare const MOBILE_QUERY = "(max-width: 1023px)";
 /**
  * Tri-state on purpose: `null` means "the user has never chosen", which is
  * what lets the viewport supply the default. A plain boolean cannot express

package/dist/ui/components/toolbar-collapse.js

@@ -19,7 +19,16 @@ const STORAGE_PREFIX = "appkit:sticky-toolbar-collapsed:";
 /** Below this the toolbar defaults to collapsed. Matches the `lg` boundary
  *  that both toolbars already use to switch between their mobile and desktop
  *  rows, so the default flips at the same width the layout does. */
-const MOBILE_QUERY = "(max-width: 1023px)";
+/**
+ * Below `lg` — the complement of `DESKTOP_QUERY` in `features/layout`.
+ *
+ * Exported so `OverflowRow` can dock its collapsed control into the bottom bar
+ * at exactly the width the tab bar exists at. It is NOT imported from
+ * `features/layout`: this is `ui/`, and a `ui → features` edge inverts the
+ * layering and is how `audit-import-cycles` regressions start. One literal in
+ * the lower layer, shared, beats two that can drift apart.
+ */
+export const MOBILE_QUERY = "(max-width: 1023px)";
 /**
  * Tri-state on purpose: `null` means "the user has never chosen", which is
  * what lets the viewport supply the default. A plain boolean cannot express

package/dist/ui/index.d.ts

@@ -95,6 +95,10 @@ export type { SliderProps } from "./components/Slider";
 export { Slider } from "./components/Slider";
 export type { CheckboxProps } from "./components/Checkbox";
 export { Checkbox } from "./components/Checkbox";
+export type { ChartProps } from "./components/Chart";
+export { Chart, ChartFromJson } from "./components/Chart";
+export type { ChartKind, ChartSeries, ChartSpec, ChartSpecResult, } from "./components/chart-spec";
+export { CHART_KINDS, CHART_MAX_SERIES, exceedsSeriesLimit, parseChartAttr, parseChartSpec, } from "./components/chart-spec";
 export type { RadioGroupProps, RadioOption, RadioItemProps } from "./components/Radio";
 export { RadioGroup, RadioItem } from "./components/Radio";
 export type { ToggleProps } from "./components/Toggle";
@@ -211,6 +215,8 @@ export type { RichTextProps } from "./rich-text/RichText";
 export { RichText } from "./rich-text/RichText";
 export type { RichTextRendererProps } from "./rich-text/RichTextRenderer";
 export { RichTextRenderer } from "./rich-text/RichTextRenderer";
+export type { RichTextSegment } from "./rich-text/chart-blocks";
+export { chartFigureHtml, hasChartBlock, splitChartBlocks, } from "./rich-text/chart-blocks";
 export type { RichTextEditorProps } from "./components/RichTextEditor";
 export { RichTextEditor } from "./components/RichTextEditor";
 export type { ListingLayoutProps, ListingLayoutLabels, } from "./components/ListingLayout";

package/dist/ui/index.js

@@ -82,6 +82,8 @@ export { DateInput, DateRangeInput } from "./components/DateInput.js";
 export { Textarea } from "./components/Textarea.js";
 export { Slider } from "./components/Slider.js";
 export { Checkbox } from "./components/Checkbox.js";
+export { Chart, ChartFromJson } from "./components/Chart.js";
+export { CHART_KINDS, CHART_MAX_SERIES, exceedsSeriesLimit, parseChartAttr, parseChartSpec, } from "./components/chart-spec.js";
 export { RadioGroup, RadioItem } from "./components/Radio.js";
 export { Toggle } from "./components/Toggle.js";
 export { QuantityStepper } from "./components/QuantityStepper.js";
@@ -148,6 +150,7 @@ export { classNames, mergeTailwindClasses } from "./style.helper.js";
 export { SideModal } from "./components/SideModal.js";
 export { RichText } from "./rich-text/RichText.js";
 export { RichTextRenderer } from "./rich-text/RichTextRenderer.js";
+export { chartFigureHtml, hasChartBlock, splitChartBlocks, } from "./rich-text/chart-blocks.js";
 export { RichTextEditor } from "./components/RichTextEditor.js";
 export { ListingLayout } from "./components/ListingLayout.js";
 export { SlottedListingView } from "./components/SlottedListingView.js";

package/dist/ui/rich-text/RichText.d.ts

@@ -29,6 +29,15 @@ export interface RichTextProps {
    * ```
      */
     highlightCode?: (code: string, lang: string) => string;
+    /**
+     * Render `<figure data-chart>` placeholders as live charts. Default true.
+     *
+     * Set `false` for untrusted user-generated content where an author should not
+     * be able to mount a component at all — the placeholder then renders as the
+     * empty `<figure>` it is. The JSON is still validated either way; this is
+     * about whether a chart is an affordance on that surface.
+     */
+    charts?: boolean;
 }
 /**
  * RichText renders sanitised HTML from a CMS / ProseMirror output.
@@ -42,4 +51,4 @@ export interface RichTextProps {
  * <RichText html={desc} copyableCode />
  * ```
  */
-export declare function RichText({ html, className, proseClass, copyableCode, highlightCode, }: RichTextProps): import("react").JSX.Element;
+export declare function RichText({ html, className, proseClass, copyableCode, highlightCode, charts, }: RichTextProps): import("react").JSX.Element;

package/dist/ui/rich-text/RichText.js

@@ -3,6 +3,8 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { useMemo } from "react";
 import { Div } from "../components/Div.js";
 import { normalizeRichTextHtml } from "../../utils/string.formatter.js";
+import { splitChartBlocks } from "./chart-blocks.js";
+import { ChartFromJson } from "../components/Chart.js";
 // --- Allowed HTML tags (safe subset — no script/object; iframe allowed for YouTube only) -------
 const ALLOWED_TAGS = new Set([
     "p",
@@ -52,6 +54,19 @@ const ALLOWED_ATTRS = {
     "*": ["class", "id", "lang", "dir", "aria-label", "role", "tabindex"],
     a: ["href", "title", "target", "rel"],
     img: ["src", "alt", "width", "height", "loading", "data-align"],
+    /*
+     * `data-chart` carries a JSON ChartSpec that the renderer hydrates into
+     * <Chart>. Safe to allow because it is DATA, never markup: it is read with
+     * `getAttribute`, run through `JSON.parse`, and then validated field-by-field
+     * by `parseChartSpec`, which accepts only a fixed `kind` enum, string labels
+     * and finite numbers. Nothing in it reaches `innerHTML`, so a script payload
+     * smuggled into the string fails validation and renders as an error message.
+     *
+     * 🛑 It must stay on `figure` only. Allowing it via "*" would let it ride on
+     * an <a> or <iframe>, where the surrounding element's own attack surface is
+     * the problem rather than the attribute.
+     */
+    figure: ["data-chart"],
     td: ["colspan", "rowspan"],
     th: ["colspan", "rowspan", "scope"],
     ol: ["type", "start"],
@@ -167,7 +182,7 @@ function attachCopyButtons(container) {
  * <RichText html={desc} copyableCode />
  * ```
  */
-export function RichText({ html, className = "", proseClass = "prose max-w-none dark:prose-invert", copyableCode = false, highlightCode, }) {
+export function RichText({ html, className = "", proseClass = "prose max-w-none dark:prose-invert", copyableCode = false, highlightCode, charts = true, }) {
     const safe = useMemo(() => {
         const sanitized = sanitiseHtml(normalizeRichTextHtml(html));
         if (!highlightCode || typeof document === "undefined")
@@ -186,5 +201,21 @@ export function RichText({ html, className = "", proseClass = "prose max-w-none
             attachCopyButtons(el);
         }
     };
-    return (_jsx(Div, { ref: ref, className: `appkit-rich-text ${proseClass} ${className}`, dangerouslySetInnerHTML: { __html: safe } }));
+    /*
+     * Split AFTER sanitising, never before.
+     *
+     * The sanitiser round-trips through `DOMParser` and re-serialises, which
+     * rewrites the single-quoted `data-chart='{"k":1}'` we emit into
+     * double-quoted `data-chart="{&quot;k&quot;:1}"`. `splitChartBlocks` handles
+     * both spellings precisely because of this step — splitting first would
+     * leave chart segments that the sanitiser never got to inspect.
+     */
+    const segments = useMemo(() => (charts ? splitChartBlocks(safe) : [{ type: "html", html: safe }]), [safe, charts]);
+    // Fast path: no charts. Byte-identical to the pre-chart render.
+    if (segments.length === 1 && segments[0].type === "html") {
+        return (_jsx(Div, { ref: ref, className: `appkit-rich-text ${proseClass} ${className}`, dangerouslySetInnerHTML: { __html: segments[0].html } }));
+    }
+    return (_jsx(Div, { ref: ref, className: `appkit-rich-text ${proseClass} ${className}`, children: segments.map((seg, i) => seg.type === "html" ? (_jsx("div", { className: "appkit-rich-text__seg", dangerouslySetInnerHTML: { __html: seg.html } }, `h${i}`)) : (
+        // eslint-disable-next-line react/no-array-index-key
+        _jsx(ChartFromJson, { json: seg.json }, `c${i}`))) }));
 }

package/dist/ui/rich-text/RichText.style.css

@@ -25,6 +25,24 @@
   border-bottom-color: var(--appkit-color-border);
 }
 
+/*
+ * The chart-draft panel the toolbar's "Chart" button opens.
+ *
+ * It sits between the toolbar and the editable area, so it needs the same
+ * recessive surface the toolbar has — without it the panel reads as part of the
+ * document being edited rather than as editor chrome, which is misleading when
+ * the thing inside it is a block of JSON.
+ */
+.appkit-rich-text-editor__chart {
+  background-color: var(--appkit-color-surface-raised);
+  border-bottom: 1px solid var(--appkit-color-border);
+}
+
+.dark .appkit-rich-text-editor__chart {
+  background-color: var(--appkit-color-slate-900);
+  border-bottom-color: var(--appkit-color-border);
+}
+
 .appkit-rich-text-editor__btn {
   border: 1px solid var(--appkit-color-border);
   color: var(--appkit-color-zinc-700);
@@ -331,3 +349,20 @@
 .dark .appkit-rich-text del {
   color: var(--appkit-color-zinc-400);
 }
+
+/*
+ * Chart-block segment wrapper.
+ *
+ * `RichTextRenderer` has to split the HTML around `<figure data-chart>` and
+ * each resulting run needs an element to carry `dangerouslySetInnerHTML` —
+ * there is no way to inject HTML without one. `display: contents` removes that
+ * element from the box tree so the runs lay out exactly as they did when they
+ * were one `innerHTML` dump.
+ *
+ * 🛑 Without this, `prose`'s adjacency and first/last-child margin rules
+ * restart at every chart, so paragraphs either side of a chart space
+ * differently from paragraphs anywhere else on the page.
+ */
+.appkit-rich-text__seg {
+  display: contents;
+}