@mohasinac/appkit 4.62.1 → 4.63.0

package/dist/ui/components/Button.d.ts

@@ -76,6 +76,15 @@ export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElemen
      * Children and aria-label props override the action defaults when explicitly provided.
      */
     action?: ActionDef;
+    /**
+     * Replace the confirmation dialog's BODY for this one render.
+     *
+     * Does not create a dialog: ignored unless `action.confirmation` exists, so
+     * the registry still decides whether an action is confirmed at all. This
+     * only substitutes the sentence, for the case where the consequence is data
+     * the registry should not hold a copy of. See the note at `confirmBody`.
+     */
+    confirmationBody?: React.ReactNode;
 }
-export declare function Button({ variant, size, className, isLoading, disabled, children, gap, textSize, paddingX, paddingY, weight, textColor, border, rounded, shadow, justify, asChild, action, ...props }: ButtonProps): React.JSX.Element;
+export declare function Button({ variant, size, className, isLoading, disabled, children, gap, textSize, paddingX, paddingY, weight, textColor, border, rounded, shadow, justify, asChild, action, confirmationBody, ...props }: ButtonProps): React.JSX.Element;
 export {};

package/dist/ui/components/Button.js

@@ -143,7 +143,7 @@ const ACTION_ICON_SIZE = {
     md: "md",
     lg: "lg",
 };
-function ActionIcon({ action, size, }) {
+function ActionIcon({ action, confirmationBody, size, }) {
     const Glyph = resolveIcon(action?.iconKey);
     if (!Glyph)
         return null;
@@ -158,7 +158,7 @@ const ACTION_KIND_VARIANT = {
     link: "ghost",
     chip: "outline",
 };
-export function Button({ variant, size = "md", className = "", isLoading = false, disabled, children, gap, textSize, paddingX, paddingY, weight, textColor, border, rounded, shadow, justify, asChild = false, action, ...props }) {
+export function Button({ variant, size = "md", className = "", isLoading = false, disabled, children, gap, textSize, paddingX, paddingY, weight, textColor, border, rounded, shadow, justify, asChild = false, action, confirmationBody, ...props }) {
     const [confirmOpen, setConfirmOpen] = useState(false);
     // React 17+ no longer pools SyntheticEvents, so it's safe to hold onto the
     // original triggering event across the confirmation dialog's async gap and
@@ -242,6 +242,28 @@ export function Button({ variant, size = "md", className = "", isLoading = false
     const confirmVariant = confirmDef?.confirmKind
         ? (ACTION_KIND_VARIANT[confirmDef.confirmKind] ?? "primary")
         : "primary";
+    /*
+     * The body a caller supplied, when the consequence is DATA rather than copy.
+     *
+     * 🛑 It cannot CREATE a dialog — `confirmPortal` still gates on
+     * `action.confirmation` existing. So the registry keeps every decision that
+     * matters: whether this action is confirmed at all, its title, its confirm
+     * label, and its destructive kind. Only the sentence in the middle can be
+     * substituted, and only when the ActionDef has already declared that there
+     * IS one.
+     *
+     * Why the seam is needed: `/admin/integrations` renders one row per
+     * integration, and "what switching this off does" genuinely differs per row
+     * — payments abandons in-flight payments, support hides a contact route,
+     * shipping selects a working manual path and stops nothing. That text already
+     * lives on `INTEGRATIONS[id].offConsequence`, which is also what the row
+     * itself renders. The alternatives were worse in both directions: four
+     * near-duplicate ActionDefs with the consequence copied into the registry (a
+     * second place for one sentence to drift from — Root Cause #42), or a generic
+     * "are you sure?" that flattens exactly the distinction the model exists to
+     * preserve.
+     */
+    const confirmBody = confirmationBody ?? confirmDef?.body;
     // Built once and rendered alongside EITHER the asChild clone or the plain
     // <button> below — this must never live inside an early return for only
     // one of those two branches, or the other branch can never open a
@@ -258,7 +280,7 @@ export function Button({ variant, size = "md", className = "", isLoading = false
                 padding: "1.5rem",
                 maxWidth: "380px", width: "calc(100% - 2rem)",
                 boxShadow: "var(--appkit-shadow-lg, 0 20px 60px rgba(0,0,0,0.2))",
-            }, children: [_jsx("p", { id: "appkit-action-confirm-title", style: { fontWeight: 600, marginBottom: "0.5rem", fontSize: "1rem" }, children: confirmDef.title }), _jsx("p", { style: { fontSize: "0.875rem", color: "var(--appkit-color-text-muted)", marginBottom: "1.25rem" }, children: confirmDef.body }), _jsxs("div", { style: { display: "flex", gap: "0.5rem", justifyContent: "flex-end" }, children: [_jsx(Button, { variant: "ghost", size: "sm", onClick: () => setConfirmOpen(false), children: confirmDef.cancelLabel ?? "Cancel" }), _jsx(Button, { variant: confirmVariant, size: "sm", onClick: handleConfirm, children: confirmDef.confirmLabel })] })] }) }), document.body);
+            }, children: [_jsx("p", { id: "appkit-action-confirm-title", style: { fontWeight: 600, marginBottom: "0.5rem", fontSize: "1rem" }, children: confirmDef.title }), _jsx("p", { style: { fontSize: "0.875rem", color: "var(--appkit-color-text-muted)", marginBottom: "1.25rem" }, children: confirmBody }), _jsxs("div", { style: { display: "flex", gap: "0.5rem", justifyContent: "flex-end" }, children: [_jsx(Button, { variant: "ghost", size: "sm", onClick: () => setConfirmOpen(false), children: confirmDef.cancelLabel ?? "Cancel" }), _jsx(Button, { variant: confirmVariant, size: "sm", onClick: handleConfirm, children: confirmDef.confirmLabel })] })] }) }), document.body);
     if (asChild && React.isValidElement(resolvedChildren)) {
         const child = resolvedChildren;
         // Never spread the caller's raw onClick here — it must go through

package/dist/ui/components/Chart.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The one chart primitive — C-chart.
+ *
+ * ## Why this exists
+ *
+ * Three features had already hand-rolled the same thing:
+ * `AdminAnalyticsCharts`, `SellerRevenueChart` and `TesterFeedbackChart` each
+ * re-declare the same eight `dynamic(() => import("recharts"))` wrappers with
+ * the same `as React.ComponentType<any>` cast and their own hardcoded fills.
+ * Three copies is the Duplication Framework's Rule-of-Three trigger, so this is
+ * consolidation of something that exists, not speculative infrastructure.
+ *
+ * It is also what lets a chart live in CMS content: `ChartSpec` is a plain
+ * JSON-serialisable object, so a rich-text author can embed one as
+ * `<figure data-chart='{...}'>` and the renderer hydrates it here.
+ *
+ * The data contract and its validator live in `./chart-spec`, which is pure —
+ * see that file's header for why the split matters.
+ *
+ * ## 🛑 recharts is client-only, and that is not incidental
+ *
+ * Every recharts component is behind `dynamic(..., { ssr: false })`, so this
+ * module renders its chrome on the server and the plot only in the browser.
+ * `RichTextRenderer` is a Server Component; it can mount this because this is a
+ * client component, but nothing here may be called during SSR.
+ *
+ * ## 🛑 The palette lives in CSS and NOWHERE ELSE
+ *
+ * There is deliberately no colour literal in this file. An earlier draft kept a
+ * `FALLBACK_SERIES_COLORS` array of eight hexes beside the identical eight in
+ * `Chart.style.css` — which is a denormalised mirror of exactly the kind Root
+ * Cause #42 is about: the day someone re-steps a hue for contrast, they fix one
+ * copy, and the chart renders one colour in CSS and a different one in JS with
+ * nothing reporting the disagreement.
+ *
+ * So the colours are read from the cascade at runtime, and if the stylesheet is
+ * absent the chart renders with recharts' own defaults plus a one-time console
+ * warning naming the likely cause. A wrong-but-plausible colour is worse than
+ * an obviously unstyled one.
+ *
+ * Colour is read off THIS element rather than from `useTheme()`, which throws
+ * without a `<ThemeProvider>` — a chart has to survive a preview iframe, an
+ * email preview or a test harness, the same reason `useCanSeePrices` uses
+ * `useOptionalSession` (Root Cause #20).
+ */
+import React from "react";
+import { type ChartSpec } from "./chart-spec";
+export interface ChartProps {
+    spec: ChartSpec;
+    /** Plot height in px. Default 300. */
+    height?: number;
+    className?: string;
+    /** Hide the table-view toggle. The legend is never optional for ≥2 series. */
+    hideTableToggle?: boolean;
+}
+export declare function Chart({ spec, height, className, hideTableToggle, }: ChartProps): React.JSX.Element;
+/**
+ * Render a `ChartSpec` from untrusted JSON, showing the validation reason when
+ * it does not parse — never rendering nothing.
+ */
+export declare function ChartFromJson({ json, ...rest }: {
+    json: string;
+} & Omit<ChartProps, "spec">): React.JSX.Element;

package/dist/ui/components/Chart.js

@@ -0,0 +1,169 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+/**
+ * The one chart primitive — C-chart.
+ *
+ * ## Why this exists
+ *
+ * Three features had already hand-rolled the same thing:
+ * `AdminAnalyticsCharts`, `SellerRevenueChart` and `TesterFeedbackChart` each
+ * re-declare the same eight `dynamic(() => import("recharts"))` wrappers with
+ * the same `as React.ComponentType<any>` cast and their own hardcoded fills.
+ * Three copies is the Duplication Framework's Rule-of-Three trigger, so this is
+ * consolidation of something that exists, not speculative infrastructure.
+ *
+ * It is also what lets a chart live in CMS content: `ChartSpec` is a plain
+ * JSON-serialisable object, so a rich-text author can embed one as
+ * `<figure data-chart='{...}'>` and the renderer hydrates it here.
+ *
+ * The data contract and its validator live in `./chart-spec`, which is pure —
+ * see that file's header for why the split matters.
+ *
+ * ## 🛑 recharts is client-only, and that is not incidental
+ *
+ * Every recharts component is behind `dynamic(..., { ssr: false })`, so this
+ * module renders its chrome on the server and the plot only in the browser.
+ * `RichTextRenderer` is a Server Component; it can mount this because this is a
+ * client component, but nothing here may be called during SSR.
+ *
+ * ## 🛑 The palette lives in CSS and NOWHERE ELSE
+ *
+ * There is deliberately no colour literal in this file. An earlier draft kept a
+ * `FALLBACK_SERIES_COLORS` array of eight hexes beside the identical eight in
+ * `Chart.style.css` — which is a denormalised mirror of exactly the kind Root
+ * Cause #42 is about: the day someone re-steps a hue for contrast, they fix one
+ * copy, and the chart renders one colour in CSS and a different one in JS with
+ * nothing reporting the disagreement.
+ *
+ * So the colours are read from the cascade at runtime, and if the stylesheet is
+ * absent the chart renders with recharts' own defaults plus a one-time console
+ * warning naming the likely cause. A wrong-but-plausible colour is worse than
+ * an obviously unstyled one.
+ *
+ * Colour is read off THIS element rather than from `useTheme()`, which throws
+ * without a `<ThemeProvider>` — a chart has to survive a preview iframe, an
+ * email preview or a test harness, the same reason `useCanSeePrices` uses
+ * `useOptionalSession` (Root Cause #20).
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import dynamic from "next/dynamic.js";
+import { CHART_MAX_SERIES, parseChartAttr, } from "./chart-spec.js";
+/*
+ * recharts exports generic components (<DataPointType>) whose inferred props do
+ * not satisfy `dynamic()`'s ComponentType constraint, so each needs a cast.
+ * This is the SINGLE copy of that cast in the codebase — the three feature
+ * charts above should migrate onto this module rather than repeating it.
+ */
+const ResponsiveContainer = dynamic(() => import("recharts").then((m) => m.ResponsiveContainer), { ssr: false });
+const BarChart = dynamic(() => import("recharts").then((m) => m.BarChart), { ssr: false });
+const LineChart = dynamic(() => import("recharts").then((m) => m.LineChart), { ssr: false });
+const AreaChart = dynamic(() => import("recharts").then((m) => m.AreaChart), { ssr: false });
+const Bar = dynamic(() => import("recharts").then((m) => m.Bar), { ssr: false });
+const Line = dynamic(() => import("recharts").then((m) => m.Line), { ssr: false });
+const Area = dynamic(() => import("recharts").then((m) => m.Area), { ssr: false });
+const XAxis = dynamic(() => import("recharts").then((m) => m.XAxis), { ssr: false });
+const YAxis = dynamic(() => import("recharts").then((m) => m.YAxis), { ssr: false });
+const CartesianGrid = dynamic(() => import("recharts").then((m) => m.CartesianGrid), { ssr: false });
+const Tooltip = dynamic(() => import("recharts").then((m) => m.Tooltip), { ssr: false });
+/** `""` → `undefined`, so recharts falls back to its own default. */
+const orUndef = (s) => (s.length > 0 ? s : undefined);
+let warnedMissingStylesheet = false;
+/**
+ * Resolve the palette from the element's own computed style, and re-resolve
+ * whenever the active theme changes.
+ *
+ * Two triggers, because there are two ways the theme can move: the viewer's
+ * toggle (which stamps `data-theme` on `<html>`) and the OS preference (which
+ * only the media query sees). Watching one and not the other leaves a chart
+ * stranded in the previous palette.
+ *
+ * Returns `null` until the first read completes — one frame after mount, which
+ * is invisible given the plot itself is behind `ssr: false` anyway.
+ */
+function useChartPalette(ref) {
+    const [palette, setPalette] = useState(null);
+    const read = useCallback(() => {
+        const el = ref.current;
+        if (!el || typeof window === "undefined")
+            return;
+        const cs = window.getComputedStyle(el);
+        const v = (name) => cs.getPropertyValue(name).trim();
+        const series = Array.from({ length: CHART_MAX_SERIES }, (_, i) => v(`--chart-${i + 1}`));
+        if (!series[0] && !warnedMissingStylesheet) {
+            warnedMissingStylesheet = true;
+            // eslint-disable-next-line no-console
+            console.warn("[appkit] <Chart> found no --chart-* custom properties. " +
+                'Import the stylesheet once at your app root: import "@mohasinac/appkit/styles". ' +
+                "Rendering with recharts' default colours until then.");
+        }
+        setPalette({
+            series,
+            grid: v("--chart-grid"),
+            axis: v("--chart-axis"),
+            inkMuted: v("--chart-ink-muted"),
+        });
+    }, [ref]);
+    useEffect(() => {
+        read();
+        if (typeof window === "undefined")
+            return;
+        const observer = new MutationObserver(read);
+        observer.observe(document.documentElement, {
+            attributes: true,
+            attributeFilter: ["data-theme", "style", "class"],
+        });
+        const mq = window.matchMedia("(prefers-color-scheme: dark)");
+        mq.addEventListener("change", read);
+        return () => {
+            observer.disconnect();
+            mq.removeEventListener("change", read);
+        };
+    }, [read]);
+    return palette;
+}
+const fmt = (n, unit) => `${Number.isInteger(n) ? n : n.toFixed(2)}${unit ? ` ${unit}` : ""}`;
+export function Chart({ spec, height = 300, className = "", hideTableToggle = false, }) {
+    const rootRef = useRef(null);
+    const palette = useChartPalette(rootRef);
+    const [showTable, setShowTable] = useState(false);
+    /** recharts wants row-per-category; the spec is column-per-series. */
+    const rows = useMemo(() => spec.categories.map((cat, i) => {
+        const row = { category: cat };
+        for (const s of spec.series)
+            row[s.label] = s.values[i] ?? 0;
+        return row;
+    }), [spec]);
+    const multi = spec.series.length >= 2;
+    const accessibleName = spec.title ?? spec.caption ?? "Chart";
+    const colorAt = (i) => orUndef(palette?.series[i % CHART_MAX_SERIES] ?? "");
+    const renderTable = () => (_jsx("div", { className: "appkit-chart__scroll", children: _jsxs("table", { className: "appkit-chart__table", children: [_jsx("caption", { className: "appkit-chart__caption", children: accessibleName }), _jsx("thead", { children: _jsxs("tr", { children: [_jsx("th", { scope: "col", children: "Category" }), spec.series.map((s) => (_jsxs("th", { scope: "col", children: [s.label, spec.unit ? ` (${spec.unit})` : ""] }, s.label)))] }) }), _jsx("tbody", { children: spec.categories.map((cat, i) => (_jsxs("tr", { children: [_jsx("th", { scope: "row", children: cat }), spec.series.map((s) => (_jsx("td", { children: fmt(s.values[i] ?? 0, spec.unit) }, s.label)))] }, cat))) })] }) }));
+    const tooltip = (_jsx(Tooltip, { content: (props) => {
+            if (!props?.active || !Array.isArray(props.payload) || !props.payload.length) {
+                return null;
+            }
+            return (_jsxs("div", { className: "appkit-chart__tooltip", children: [_jsx("div", { className: "appkit-chart__tooltip-label", children: props.label }), props.payload.map((p) => (_jsxs("div", { className: "appkit-chart__tooltip-row", children: [_jsx("span", { style: { color: p.color }, children: String(p.dataKey) }), _jsx("span", { children: fmt(Number(p.value), spec.unit) })] }, String(p.dataKey))))] }));
+        } }));
+    const axes = (_jsxs(_Fragment, { children: [_jsx(CartesianGrid, { stroke: orUndef(palette?.grid ?? ""), vertical: false }), _jsx(XAxis, { dataKey: "category", stroke: orUndef(palette?.axis ?? ""), tick: { fill: orUndef(palette?.inkMuted ?? ""), fontSize: 12 }, tickLine: false }), _jsx(YAxis, { stroke: orUndef(palette?.axis ?? ""), tick: { fill: orUndef(palette?.inkMuted ?? ""), fontSize: 12 }, tickLine: false, width: 48 }), tooltip] }));
+    let plot;
+    if (spec.kind === "bar" || spec.kind === "groupedBar") {
+        plot = (_jsxs(BarChart, { data: rows, barGap: 2, barCategoryGap: "20%", children: [axes, spec.series.map((s, i) => (_jsx(Bar, { dataKey: s.label, fill: colorAt(i), radius: [4, 4, 0, 0] }, s.label)))] }));
+    }
+    else if (spec.kind === "line") {
+        plot = (_jsxs(LineChart, { data: rows, children: [axes, spec.series.map((s, i) => (_jsx(Line, { type: "monotone", dataKey: s.label, stroke: colorAt(i), strokeWidth: 2, dot: { r: 3 }, activeDot: { r: 5 } }, s.label)))] }));
+    }
+    else {
+        plot = (_jsxs(AreaChart, { data: rows, children: [axes, spec.series.map((s, i) => (_jsx(Area, { type: "monotone", dataKey: s.label, stroke: colorAt(i), strokeWidth: 2, fill: colorAt(i), fillOpacity: 0.18 }, s.label)))] }));
+    }
+    return (_jsxs("div", { ref: rootRef, className: `appkit-chart ${className}`.trim(), role: "group", "aria-label": accessibleName, children: [multi && palette ? (_jsx("div", { className: "appkit-chart__legend", children: spec.series.map((s, i) => (_jsxs("span", { children: [_jsx("span", { className: "appkit-chart__legend-swatch", style: { background: colorAt(i) }, "aria-hidden": "true" }), s.label] }, s.label))) })) : null, showTable ? (renderTable()) : (_jsx("div", { className: "appkit-chart__plot", style: { height }, children: palette ? (_jsx(ResponsiveContainer, { width: "100%", height: "100%", children: plot })) : null })), spec.caption ? _jsx("p", { className: "appkit-chart__caption", children: spec.caption }) : null, hideTableToggle ? null : (_jsx("div", { className: "appkit-chart__toolbar", children: _jsx("button", { type: "button", className: "appkit-chart__toggle", onClick: () => setShowTable((v) => !v), "aria-pressed": showTable, children: showTable ? "Show chart" : "Show as table" }) }))] }));
+}
+/**
+ * Render a `ChartSpec` from untrusted JSON, showing the validation reason when
+ * it does not parse — never rendering nothing.
+ */
+export function ChartFromJson({ json, ...rest }) {
+    const result = useMemo(() => parseChartAttr(json), [json]);
+    if (!result.ok) {
+        return (_jsx("div", { className: "appkit-chart", children: _jsxs("p", { className: "appkit-chart__error", children: ["Chart could not be rendered: ", result.reason] }) }));
+    }
+    return _jsx(Chart, { spec: result.spec, ...rest });
+}

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

@@ -0,0 +1,214 @@
+/*
+ * Chart palette + chrome.
+ *
+ * ── 🛑 The custom properties are scoped to `.appkit-chart`, NOT `:root` ────
+ *
+ * Two reasons, and the second is the load-bearing one:
+ *
+ *  1. A chart palette is not a theme token. Nothing outside a chart should be
+ *     able to consume `--chart-3`, and putting it on `:root` invites exactly
+ *     that.
+ *  2. `audit-theme-drift` matches `:root { ... }` blocks in the token layer
+ *     against the TypeScript theme presets, so a NEW `:root` custom property
+ *     declared here is a drift finding waiting to happen. Scoping to the
+ *     component sidesteps the question entirely.
+ *
+ * Reading them off the chart's OWN element (rather than `documentElement`) is
+ * also what makes the cascade do the work: a `[data-theme]` override below
+ * resolves correctly with no JS mode detection.
+ *
+ * ── 🛑 The dark steps are SELECTED, not flipped ───────────────────────────
+ *
+ * Both palettes were run through the dataviz validator against the real app
+ * surfaces (#ffffff and #0f172a). The light set is the reference order. The
+ * dark set keeps that hue ORDER — because the order is what the adjacent-pair
+ * CVD check passes on — and re-steps only the four hues that fell outside the
+ * dark lightness band (L 0.48–0.67).
+ *
+ * Re-ordering instead was tried and was much worse: moving pink next to green
+ * produced an adjacent deuteranopia ΔE of 1.7, i.e. two series a red-green
+ * colourblind reader cannot tell apart at all.
+ *
+ * Light set carries a sub-3:1 contrast WARN on --chart-3/4/5. That is not
+ * dismissable: the component always renders a legend for ≥2 series and offers
+ * a table view, which is the required relief.
+ *
+ * If you change ANY value here, re-run:
+ *   node scripts/validate_palette.js "<the 8 hexes>" --mode light --surface "#ffffff"
+ *   node scripts/validate_palette.js "<the 8 hexes>" --mode dark  --surface "#0f172a"
+ */
+
+.appkit-chart {
+  --chart-1: #2a78d6;
+  --chart-2: #eb6834;
+  --chart-3: #1baf7a;
+  --chart-4: #eda100;
+  --chart-5: #e87ba4;
+  --chart-6: #008300;
+  --chart-7: #4a3aa7;
+  --chart-8: #e34948;
+
+  --chart-grid: rgba(113, 113, 122, 0.22);
+  --chart-axis: rgba(113, 113, 122, 0.55);
+  --chart-ink: var(--appkit-color-text, #18181b);
+  --chart-ink-muted: var(--appkit-color-text-muted, #52525b);
+  --chart-tooltip-bg: var(--appkit-color-surface-elevated, #ffffff);
+  --chart-tooltip-border: var(--appkit-color-border, rgba(113, 113, 122, 0.3));
+
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+  margin: 1.5rem 0;
+}
+
+@media (prefers-color-scheme: dark) {
+  .appkit-chart {
+    --chart-2: #E36430;
+    --chart-4: #C38600;
+    --chart-5: #D76691;
+    --chart-7: #6655CE;
+    --chart-grid: rgba(161, 161, 170, 0.2);
+    --chart-axis: rgba(161, 161, 170, 0.5);
+  }
+}
+
+/*
+ * The viewer's explicit toggle must win over the media query in BOTH
+ * directions — `applyTheme` stamps `data-theme="<theme id>"` on <html>, and a
+ * light theme chosen on a dark-OS machine has to restore the light steps.
+ * `:root[data-theme]` is deliberately broad here: the attribute carries a theme
+ * ID (e.g. "default-light"), not the literal mode, so the mode-specific
+ * selectors below key off the id prefix the built-in themes use.
+ */
+:root[data-theme*="dark"] .appkit-chart {
+  --chart-2: #E36430;
+  --chart-4: #C38600;
+  --chart-5: #D76691;
+  --chart-7: #6655CE;
+  --chart-grid: rgba(161, 161, 170, 0.2);
+  --chart-axis: rgba(161, 161, 170, 0.5);
+}
+
+:root[data-theme*="light"] .appkit-chart {
+  --chart-2: #eb6834;
+  --chart-4: #eda100;
+  --chart-5: #e87ba4;
+  --chart-7: #4a3aa7;
+  --chart-grid: rgba(113, 113, 122, 0.22);
+  --chart-axis: rgba(113, 113, 122, 0.55);
+}
+
+.appkit-chart__caption {
+  font-size: 0.8125rem;
+  line-height: 1.5;
+  color: var(--chart-ink-muted);
+  margin: 0;
+}
+
+.appkit-chart__legend {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 0.5rem 1.25rem;
+  align-items: center;
+  font-size: 0.75rem;
+  color: var(--chart-ink-muted);
+}
+
+.appkit-chart__legend-swatch {
+  display: inline-block;
+  width: 11px;
+  height: 11px;
+  border-radius: 2px;
+  margin-right: 0.4rem;
+  vertical-align: -1px;
+  flex: 0 0 auto;
+}
+
+.appkit-chart__plot {
+  width: 100%;
+}
+
+/* Wide charts scroll in their own container so the page body never does. */
+.appkit-chart__scroll {
+  overflow-x: auto;
+  width: 100%;
+}
+
+.appkit-chart__toolbar {
+  display: flex;
+  justify-content: flex-end;
+}
+
+.appkit-chart__toggle {
+  font: inherit;
+  font-size: 0.6875rem;
+  letter-spacing: 0.04em;
+  text-transform: uppercase;
+  color: var(--chart-ink-muted);
+  background: none;
+  border: 1px solid var(--chart-tooltip-border);
+  border-radius: 3px;
+  padding: 0.2rem 0.5rem;
+  cursor: pointer;
+}
+
+.appkit-chart__toggle:hover {
+  color: var(--chart-ink);
+}
+
+.appkit-chart__toggle:focus-visible {
+  outline: 2px solid var(--appkit-color-focus-ring, #2a78d6);
+  outline-offset: 2px;
+}
+
+.appkit-chart__table {
+  border-collapse: collapse;
+  width: 100%;
+  font-size: 0.8125rem;
+  font-variant-numeric: tabular-nums;
+  color: var(--chart-ink);
+}
+
+.appkit-chart__table th,
+.appkit-chart__table td {
+  border-bottom: 1px solid var(--chart-grid);
+  padding: 0.4rem 0.6rem;
+  text-align: left;
+}
+
+.appkit-chart__table td + td,
+.appkit-chart__table th + th {
+  text-align: right;
+  white-space: nowrap;
+}
+
+.appkit-chart__tooltip {
+  background: var(--chart-tooltip-bg);
+  border: 1px solid var(--chart-tooltip-border);
+  border-radius: 4px;
+  padding: 0.5rem 0.65rem;
+  font-size: 0.75rem;
+  color: var(--chart-ink);
+  font-variant-numeric: tabular-nums;
+  box-shadow: 0 2px 8px rgba(0, 0, 0, 0.12);
+}
+
+.appkit-chart__tooltip-label {
+  font-weight: 600;
+  margin-bottom: 0.25rem;
+  color: var(--chart-ink);
+}
+
+.appkit-chart__tooltip-row {
+  display: flex;
+  gap: 0.75rem;
+  justify-content: space-between;
+}
+
+.appkit-chart__error {
+  font-size: 0.8125rem;
+  color: var(--appkit-color-error, #e34948);
+  border: 1px solid var(--appkit-color-error, #e34948);
+  border-radius: 4px;
+  padding: 0.6rem 0.75rem;
+}

package/dist/ui/components/Disclaimer.js

@@ -1,6 +1,15 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React from "react";
-import { Div, Stack, Text } from "../index.js";
+/*
+ * 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";
 /**

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) => {