@godxjp/ui 20.0.0 → 20.2.0

package/README.md

@@ -133,8 +133,15 @@ One token `--phi-unit` drives page/section/card spacing; micro control gaps use
 
 ```bash
 pnpm preview          # preview app → http://localhost:6008 (fixed port, kills stale)
+pnpm typecheck && pnpm lint && pnpm run audit          # the cheap gates — run these freely
+pnpm vitest run src/components/<group>/__tests__ --maxWorkers=2   # ONLY what you touched
+
+# Heavy — CI's job. Run locally AT MOST ONCE, right before opening a PR, and never
+# with other agents working on the same machine: `verify` builds the library AND the
+# preview site AND runs all 506 test files. Measured with agents in parallel: 70 vitest
+# workers, load average 90, an overheating laptop.
 pnpm preview:build    # static build — also what deploys to GitHub Pages
-pnpm verify           # typecheck · lint · format · the 5 guards · test
+pnpm verify           # typecheck · lint · format · the 5 guards · FULL suite
 pnpm release --ui <patch|minor|major> --mcp <…|skip>   # publish lib + MCP in lockstep
 ```
 
@@ -174,5 +181,4 @@ This repo ships two packages — `@godxjp/ui` (this dir) and `@godxjp/ui-mcp` (`
 - [docs/COMPONENTS.md](./docs/COMPONENTS.md) · [docs/TOKENS.md](./docs/TOKENS.md) · [docs/SPACING.md](./docs/SPACING.md)
 - [docs/PROPS-VOCABULARY.md](./docs/PROPS-VOCABULARY.md) · [docs/PROPS-REGISTRY.md](./docs/PROPS-REGISTRY.md)
 - [docs/DATETIME.md](./docs/DATETIME.md) · [docs/FORMS.md](./docs/FORMS.md) · [docs/TESTING.md](./docs/TESTING.md)
-- **Architecture decisions** under `debate/*/04-Decision.md` (ADRs from the design debates)
 - MCP: **godxjp-ui-mcp** (`.mcp.json`) — live catalog for agents

package/dist/app/app-provider.js

@@ -14,7 +14,13 @@ import {
   enableLiveRelativeFormatting,
   syncDatetimeContext
 } from "../lib/datetime/index.js";
-import { DEFAULT_STORAGE_KEY, readStoredPreferences, writeStoredPreferences } from "./storage.js";
+import {
+  DEFAULT_STORAGE_KEY,
+  pickPersistedAxes,
+  readStoredPreferences,
+  resolvePersistedAxes,
+  writeStoredPreferences
+} from "./storage.js";
 import {
   applyThemeAxes,
   PREFERS_DARK_SCHEME_QUERY
@@ -105,8 +111,18 @@ function AppProvider({
     fontSize,
     scaling
   });
+  const persistKey = Array.isArray(persist) ? [...persist].sort().join(",") : String(persist);
+  const persistedAxes = React.useMemo(
+    () => resolvePersistedAxes(persist),
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [persistKey]
+  );
+  const commitPreferences = React.useCallback(() => {
+    if (persistedAxes.size === 0) return;
+    writeStoredPreferences(storageKey, pickPersistedAxes(prefsRef.current, persistedAxes));
+  }, [persistedAxes, storageKey]);
   React.useEffect(() => {
-    const stored = persist ? readStoredPreferences(storageKey) : {};
+    const stored = pickPersistedAxes(readStoredPreferences(storageKey), persistedAxes);
     const nextLocale = stored.locale ?? defaultLocale;
     const nextTimezone = stored.timezone ?? resolveDefaultTimezone(defaultTimezone, systemTimezone);
     const nextTimeFormat = resolveInitialTimeFormat(
@@ -154,7 +170,7 @@ function AppProvider({
     initialDensity,
     initialFontSize,
     initialScaling,
-    persist,
+    persistedAxes,
     storageKey,
     systemTimezone
   ]);
@@ -188,81 +204,81 @@ function AppProvider({
       prefsRef.current = { ...prefsRef.current, locale: next };
       setLocaleState(next);
       onLocaleChange?.(next);
-      if (persist) writeStoredPreferences(storageKey, prefsRef.current);
+      commitPreferences();
     },
-    [onLocaleChange, persist, storageKey]
+    [onLocaleChange, commitPreferences]
   );
   const setTimezone = React.useCallback(
     (next) => {
       prefsRef.current = { ...prefsRef.current, timezone: next };
       setTimezoneState(next);
       onTimezoneChange?.(next);
-      if (persist) writeStoredPreferences(storageKey, prefsRef.current);
+      commitPreferences();
     },
-    [onTimezoneChange, persist, storageKey]
+    [onTimezoneChange, commitPreferences]
   );
   const setTimeFormat = React.useCallback(
     (next) => {
       prefsRef.current = { ...prefsRef.current, timeFormat: next };
       setTimeFormatState(next);
       onTimeFormatChange?.(next);
-      if (persist) writeStoredPreferences(storageKey, prefsRef.current);
+      commitPreferences();
     },
-    [onTimeFormatChange, persist, storageKey]
+    [onTimeFormatChange, commitPreferences]
   );
   const setDateFormat = React.useCallback(
     (next) => {
       prefsRef.current = { ...prefsRef.current, dateFormat: next };
       setDateFormatState(next);
       onDateFormatChange?.(next);
-      if (persist) writeStoredPreferences(storageKey, prefsRef.current);
+      commitPreferences();
     },
-    [onDateFormatChange, persist, storageKey]
+    [onDateFormatChange, commitPreferences]
   );
   const setTheme = React.useCallback(
     (next) => {
       prefsRef.current = { ...prefsRef.current, theme: next };
       setThemeState(next);
       onThemeChange?.(next);
-      if (persist) writeStoredPreferences(storageKey, prefsRef.current);
+      commitPreferences();
     },
-    [onThemeChange, persist, storageKey]
+    [onThemeChange, commitPreferences]
   );
   const setBrand = React.useCallback(
     (next) => {
       prefsRef.current = { ...prefsRef.current, brand: next };
       setBrandState(next);
       onBrandChange?.(next);
-      if (persist) writeStoredPreferences(storageKey, prefsRef.current);
+      commitPreferences();
     },
-    [onBrandChange, persist, storageKey]
+    [onBrandChange, commitPreferences]
   );
   const setDensity = React.useCallback(
     (next) => {
       prefsRef.current = { ...prefsRef.current, density: next };
       setDensityState(next);
       onDensityChange?.(next);
-      if (persist) writeStoredPreferences(storageKey, prefsRef.current);
+      commitPreferences();
     },
-    [onDensityChange, persist, storageKey]
+    [onDensityChange, commitPreferences]
   );
   const setFontSize = React.useCallback(
     (next) => {
       prefsRef.current = { ...prefsRef.current, fontSize: next };
       setFontSizeState(next);
       onFontSizeChange?.(next);
-      if (persist) writeStoredPreferences(storageKey, prefsRef.current);
+      commitPreferences();
     },
-    [onFontSizeChange, persist, storageKey]
+    [onFontSizeChange, commitPreferences]
   );
   const setScaling = React.useCallback(
     (next) => {
       prefsRef.current = { ...prefsRef.current, scaling: next };
       setScalingState(next);
       onScalingChange?.(next);
-      if (persist) writeStoredPreferences(storageKey, prefsRef.current);
+      commitPreferences();
     },
-    [onScalingChange, persist, storageKey]
+    [onScalingChange, commitPreferences]
   );
   const requestHeaders = React.useMemo(
     () => buildRequestHeaders(locale, timezone, timeFormat, dateFormat),

package/dist/app/index.d.ts

@@ -12,3 +12,5 @@ export { AppProvider, useAppContext, useOptionalAppContext, useAppLocale, useApp
 export { useFormatting, useDateTime } from "./use-formatting.js";
 export { syncDatetimeContext, getDatetimeContext, formatDate, isFormatDateValue, detectFormatDateKind, formatAppDate, formatAppDateTime, formatAppTime, formatAppDateLong, formatAppRelative, formatCalendarDate, formatTimeOfDay, parseDateInput, normalizeHhmm, isValidHhmm, type FormatDateOptions, type FormatDateKind, type FormatDatetimeOptions, } from "../lib/datetime/index.js";
 export { useTranslation, usePickerLocales } from "../i18n/use-translation.js";
+export { OverlayPortalProvider } from "../lib/overlay-portal.js";
+export type { OverlayPortalProviderProps } from "../lib/overlay-portal.js";

package/dist/app/index.js

@@ -36,8 +36,10 @@ import {
   isValidHhmm
 } from "../lib/datetime/index.js";
 import { useTranslation, usePickerLocales } from "../i18n/use-translation.js";
+import { OverlayPortalProvider } from "../lib/overlay-portal.js";
 export {
   AppProvider,
+  OverlayPortalProvider,
   detectFormatDateKind,
   formatAppDate,
   formatAppDateLong,

package/dist/app/storage.d.ts

@@ -14,6 +14,23 @@ export type StoredAppPreferences = {
     /** Continuous global size multiplier; `null` defers to the density preset. */
     scaling?: number | null;
 };
+/**
+ * The axes a viewer's preferences are made of — the keys of {@link StoredAppPreferences}.
+ *
+ * They do NOT share an owner. `theme`, `density`, `fontSize`, `scaling` and `brand` are the
+ * viewer's, and belong in this browser. `locale`, `timezone`, `timeFormat` and `dateFormat` are
+ * frequently the SERVER's — resolved per request from a cookie, an account row or an Accept-Language
+ * header — and a copy in local storage then wins over the value the server just sent, because
+ * storage is read after the props. That is why `persist` takes a LIST as well as a boolean: one
+ * flag for axes with two different owners forces an all-or-nothing choice, and the consumer that
+ * hits it turns persistence off entirely and loses the viewer's theme with it.
+ */
+export declare const APP_PREFERENCE_AXES: readonly ["locale", "timezone", "timeFormat", "dateFormat", "theme", "brand", "density", "fontSize", "scaling"];
+export type AppPreferenceAxis = (typeof APP_PREFERENCE_AXES)[number];
+/** `true` → every axis, `false` → none, a list → exactly those. */
+export declare function resolvePersistedAxes(persist: boolean | readonly AppPreferenceAxis[]): ReadonlySet<AppPreferenceAxis>;
+/** The subset of `preferences` on the given axes; the rest are dropped, not set to undefined. */
+export declare function pickPersistedAxes(preferences: StoredAppPreferences, axes: ReadonlySet<AppPreferenceAxis>): StoredAppPreferences;
 export declare function readStoredPreferences(storageKey: string): StoredAppPreferences;
 export declare function writeStoredPreferences(storageKey: string, preferences: StoredAppPreferences): void;
 export { DEFAULT_STORAGE_KEY };

package/dist/app/storage.js

@@ -8,6 +8,31 @@ import {
   isAppTheme
 } from "./theme-axes.js";
 const DEFAULT_STORAGE_KEY = "godxjp.app";
+const APP_PREFERENCE_AXES = [
+  "locale",
+  "timezone",
+  "timeFormat",
+  "dateFormat",
+  "theme",
+  "brand",
+  "density",
+  "fontSize",
+  "scaling"
+];
+function resolvePersistedAxes(persist) {
+  if (persist === true) return new Set(APP_PREFERENCE_AXES);
+  if (persist === false) return /* @__PURE__ */ new Set();
+  return new Set(persist);
+}
+function pickPersistedAxes(preferences, axes) {
+  const out = {};
+  for (const axis of APP_PREFERENCE_AXES) {
+    if (axes.has(axis) && preferences[axis] !== void 0) {
+      out[axis] = preferences[axis];
+    }
+  }
+  return out;
+}
 function readStoredPreferences(storageKey) {
   if (typeof window === "undefined") return {};
   try {
@@ -37,7 +62,10 @@ function writeStoredPreferences(storageKey, preferences) {
   }
 }
 export {
+  APP_PREFERENCE_AXES,
   DEFAULT_STORAGE_KEY,
+  pickPersistedAxes,
   readStoredPreferences,
+  resolvePersistedAxes,
   writeStoredPreferences
 };

package/dist/app/theme-axes.d.ts

@@ -43,3 +43,5 @@ export declare const isAppFontSize: (v: unknown) => v is AppFontSize;
  * `data-brand` so the app's own `--primary` token applies.
  */
 export declare function applyThemeAxes(el: HTMLElement, axes: Partial<AppThemeAxes>): void;
+/** Apply an entity's action palette, including portals. Call the returned cleanup on scope exit. */
+export declare function applyPrimaryColor(root: HTMLElement, color: string, foreground?: string | null): () => void;

package/dist/app/theme-axes.js

@@ -39,12 +39,57 @@ function applyThemeAxes(el, axes) {
     else el.style.setProperty("--scaling", String(axes.scaling));
   }
 }
+function applyPrimaryColor(root, color, foreground) {
+  const parse = (value) => {
+    if (!/^#[\da-f]{6}$/i.test(value)) return null;
+    return [1, 3, 5].map((offset) => parseInt(value.slice(offset, offset + 2), 16) / 255);
+  };
+  const rgb = parse(color);
+  if (!rgb) return () => {
+  };
+  const luminance = (channels) => channels.reduce(
+    (sum, value, index) => sum + (value <= 0.04045 ? value / 12.92 : ((value + 0.055) / 1.055) ** 2.4) * [0.2126, 0.7152, 0.0722][index],
+    0
+  );
+  const text = foreground && parse(foreground) || (luminance(rgb) > 0.179 ? [0, 0, 0] : [1, 1, 1]);
+  const hsl = (channels) => {
+    const [r, g, b] = channels;
+    const max = Math.max(r, g, b), min = Math.min(r, g, b);
+    const delta = max - min, lightness = (max + min) / 2;
+    const saturation = delta === 0 ? 0 : delta / (1 - Math.abs(2 * lightness - 1));
+    const hue = delta === 0 ? 0 : 60 * (max === r ? ((g - b) / delta + 6) % 6 : max === g ? (b - r) / delta + 2 : (r - g) / delta + 4);
+    return `${hue} ${saturation * 100}% ${lightness * 100}%`;
+  };
+  const away = luminance(text) > 0.5 ? 0 : 1;
+  const shade = (amount) => hsl(rgb.map((channel) => channel * (1 - amount) + away * amount));
+  const palette = {
+    "--primary": hsl(rgb),
+    "--primary-foreground": hsl(text),
+    "--primary-hover": shade(0.12),
+    "--primary-active": shade(0.24),
+    "--primary-border": hsl(rgb),
+    "--ring": hsl(rgb)
+  };
+  const previous = Object.keys(palette).map((key) => [
+    key,
+    root.style.getPropertyValue(key),
+    root.style.getPropertyPriority(key)
+  ]);
+  for (const [key, value] of Object.entries(palette)) root.style.setProperty(key, value);
+  return () => {
+    for (const [key, value, priority] of previous) {
+      if (value) root.style.setProperty(key, value, priority);
+      else root.style.removeProperty(key);
+    }
+  };
+}
 export {
   APP_BRANDS,
   APP_DENSITIES,
   APP_FONT_SIZES,
   APP_THEMES,
   PREFERS_DARK_SCHEME_QUERY,
+  applyPrimaryColor,
   applyThemeAxes,
   isAppBrand,
   isAppDensity,

package/dist/components/charts/chart-cartesian.d.ts

@@ -11,6 +11,7 @@ type CartesianChartProps = {
     series: ChartSeriesProp[];
     categoryKey: string;
     label: React.ReactNode;
+    showCaption?: boolean;
     description?: React.ReactNode;
     size?: "xs" | "sm" | "md" | "lg";
     height?: number;
@@ -27,5 +28,5 @@ type CartesianChartProps = {
     /** bar */
     horizontal?: boolean;
 };
-export declare function CartesianChart({ kind, data, series, categoryKey, label, description, size, height, showLegend, showGrid, numberFormat, emptyMessage, className, id, curved, stacked, horizontal, }: CartesianChartProps): React.JSX.Element;
+export declare function CartesianChart({ kind, data, series, categoryKey, label, showCaption, description, size, height, showLegend, showGrid, numberFormat, emptyMessage, className, id, curved, stacked, horizontal, }: CartesianChartProps): React.JSX.Element;
 export {};

package/dist/components/charts/chart-cartesian.js

@@ -13,18 +13,22 @@ import {
   ResponsiveContainer,
   Tooltip,
   XAxis,
-  YAxis
-} from "recharts";
+  YAxis,
+  assertRechartsPeer
+} from "./recharts-peer.js";
+import { cn } from "../../lib/utils.js";
 import { EmptyState } from "../data-display/empty-state.js";
 import { useTranslation } from "../../i18n/use-translation.js";
 import { ChartFrame, chartColor, chartHeight, useChartNumberFormat } from "./chart-frame.js";
 import { buildCartesianSummary } from "./chart-summary.js";
+import { useCategoryAxisMetrics } from "./chart-category-axis.js";
 function CartesianChart({
   kind,
   data,
   series,
   categoryKey,
   label,
+  showCaption = true,
   description,
   size = "md",
   height,
@@ -38,6 +42,7 @@ function CartesianChart({
   stacked = false,
   horizontal = false
 }) {
+  assertRechartsPeer();
   const { t, locale } = useTranslation();
   const fmt = useChartNumberFormat(numberFormat);
   const list = React.useMemo(
@@ -56,6 +61,41 @@ function CartesianChart({
   const resolvedHeight = chartHeight(size, height);
   const tickFormatter = (value) => fmt.format(value);
   const curve = curved ? "monotone" : "linear";
+  const measuresCategoryAxis = kind === "bar" && horizontal;
+  const canvasRef = React.useRef(null);
+  const probeRef = React.useRef(null);
+  const categoryLabels = React.useMemo(
+    () => measuresCategoryAxis ? data.map((datum) => String(datum[categoryKey] ?? "")) : [],
+    [measuresCategoryAxis, data, categoryKey]
+  );
+  const categoryAxis = useCategoryAxisMetrics(
+    canvasRef,
+    probeRef,
+    categoryLabels,
+    measuresCategoryAxis && hasData
+  );
+  const categoryTick = (tickProps) => {
+    const full = String(tickProps.payload?.value ?? "");
+    const shown = categoryAxis.display(full);
+    return (
+      // `recharts-text` is what chart-layout.css styles the tick typography through; the rest of
+      // the class list is recharts' own (it hands `recharts-cartesian-axis-tick-value` in).
+      /* @__PURE__ */ jsxs(
+        "text",
+        {
+          className: cn("recharts-text", tickProps.className),
+          x: tickProps.x,
+          y: tickProps.y,
+          textAnchor: tickProps.textAnchor,
+          dominantBaseline: "central",
+          children: [
+            shown === full ? null : /* @__PURE__ */ jsx("title", { children: full }),
+            shown
+          ]
+        }
+      )
+    );
+  };
   const axes = (numberAxisVertical) => /* @__PURE__ */ jsxs(Fragment, { children: [
     showGrid ? /* @__PURE__ */ jsx(CartesianGrid, { strokeDasharray: "3 3", stroke: "hsl(var(--border))" }) : null,
     numberAxisVertical ? /* @__PURE__ */ jsxs(Fragment, { children: [
@@ -95,7 +135,9 @@ function CartesianChart({
           dataKey: categoryKey,
           tickLine: false,
           stroke: "hsl(var(--muted-foreground))",
-          fontSize: 12
+          fontSize: 12,
+          width: categoryAxis.width,
+          tick: categoryTick
         }
       )
     ] }),
@@ -158,6 +200,7 @@ function CartesianChart({
     ChartFrame,
     {
       label,
+      showCaption,
       description,
       summaryRows: summary.rows,
       imgSummary: summary.img,
@@ -165,6 +208,12 @@ function CartesianChart({
       height: resolvedHeight,
       className,
       id,
+      canvasRef,
+      canvasExtra: measuresCategoryAxis ? (
+        // Out-of-flow, hidden, and inside `.ui-chart` — so it inherits exactly the typography
+        // the axis ticks are painted in, including the `[lang="ja"]` face.
+        /* @__PURE__ */ jsx("span", { ref: probeRef, className: "ui-chart-axis-probe", "aria-hidden": "true" })
+      ) : null,
       children: hasData ? /* @__PURE__ */ jsx(ResponsiveContainer, { width: "100%", height: "100%", minWidth: 0, children: chart() }) : /* @__PURE__ */ jsx(EmptyState, { title: emptyMessage ?? t("chart.empty") })
     }
   );

package/dist/components/charts/chart-category-axis.d.ts

@@ -0,0 +1,55 @@
+import * as React from "react";
+/**
+ * Category-axis sizing for the HORIZONTAL bar chart (gh#409 · 1).
+ *
+ * recharts reserves a fixed 60px for the category axis whatever the ticks say, so a Japanese
+ * company name — 8–10 full-width glyphs, 100–125px — was painted OUTSIDE the chart box and the
+ * SVG clip cut it from the START, removing exactly the identifying `株式会社` prefix. Latin text
+ * degrades gracefully there; 全角 does not, and `docs/DESIGN-AUTHORITY.md` gives anything the user
+ * READS to the Japanese standard.
+ *
+ * The mechanism: measure every tick in the real rendered typography, size the axis from the
+ * WIDEST one, cap that at a token-owned fraction of the canvas so one long name can never eat
+ * the bars, and truncate anything past the cap at its END — the start, which identifies the row,
+ * always survives, and the full string stays reachable through the tick's `<title>` and the
+ * figure's screen-reader list.
+ *
+ * The two knobs are component tokens (`src/tokens/components/chart.css`). They are read back in
+ * px from real CSS properties on the probe element, because a custom property's computed value
+ * keeps whatever unit its author wrote.
+ */
+/** Axis knobs resolved from the probe's computed style. `gap` is px, `maxFraction` unitless. */
+export type CategoryAxisKnobs = {
+    /** Space between the tick text and the plot area. */
+    gap: number;
+    /** Share of the canvas the category axis may take, 0..1. */
+    maxFraction: number;
+};
+/** What the chart needs to draw the axis: its reserved width and the text of each tick. */
+export type CategoryAxisMetrics = {
+    /** `width` for recharts' `YAxis`, or `undefined` while nothing has been measured yet. */
+    width: number | undefined;
+    /** Tick text to paint — the original label, or one truncated at its END. */
+    display: (label: string) => string;
+};
+/**
+ * Axis width from the measured tick widths: the widest tick, capped, plus the gap.
+ * Pure — the browser measurement is injected, so the rule is testable without a layout engine.
+ */
+export declare function resolveCategoryAxisWidth(textWidths: readonly number[], available: number, { gap, maxFraction }: CategoryAxisKnobs): {
+    width: number;
+    textCap: number;
+};
+/**
+ * Cut `label` at its END until it fits `maxWidth`, appending an ellipsis. The first glyph is
+ * always kept: a tick that reads `…` identifies nothing, and a tick cut from the front is the
+ * bug this exists to fix.
+ */
+export declare function truncateToWidth(label: string, maxWidth: number, measure: (text: string) => number): string;
+/**
+ * Measure the category ticks in the live document and keep the axis sized to them.
+ *
+ * Re-runs when the canvas resizes and once `document.fonts` settles, because a CJK web face
+ * arriving after first paint changes every one of these widths.
+ */
+export declare function useCategoryAxisMetrics(canvasRef: React.RefObject<HTMLDivElement | null>, probeRef: React.RefObject<HTMLSpanElement | null>, labels: readonly string[], enabled: boolean): CategoryAxisMetrics;

package/dist/components/charts/chart-category-axis.js

@@ -0,0 +1,93 @@
+"use client";
+import * as React from "react";
+const ELLIPSIS = "\u2026";
+function resolveCategoryAxisWidth(textWidths, available, { gap, maxFraction }) {
+  const textCap = Math.max(0, available * maxFraction - gap);
+  const widest = textWidths.length > 0 ? Math.max(...textWidths) : 0;
+  return { width: Math.ceil(Math.min(widest, textCap) + gap), textCap };
+}
+function truncateToWidth(label, maxWidth, measure) {
+  if (measure(label) <= maxWidth) return label;
+  const glyphs = [...label];
+  for (let keep = glyphs.length - 1; keep > 1; keep -= 1) {
+    const candidate = glyphs.slice(0, keep).join("") + ELLIPSIS;
+    if (measure(candidate) <= maxWidth) return candidate;
+  }
+  return `${glyphs[0] ?? ""}${ELLIPSIS}`;
+}
+function readKnobs(probe) {
+  const style = getComputedStyle(probe);
+  const gap = Number.parseFloat(style.marginInlineEnd);
+  const maxFraction = Number.parseFloat(
+    style.getPropertyValue("--chart-category-axis-max-fraction")
+  );
+  return {
+    gap: Number.isFinite(gap) ? gap : 0,
+    maxFraction: Number.isFinite(maxFraction) ? maxFraction : 1
+  };
+}
+function sameTruncations(a, b) {
+  if (a.size !== b.size) return false;
+  for (const [key, value] of a) {
+    if (b.get(key) !== value) return false;
+  }
+  return true;
+}
+function useCategoryAxisMetrics(canvasRef, probeRef, labels, enabled) {
+  const [measured, setMeasured] = React.useState(void 0);
+  const labelsRef = React.useRef(labels);
+  labelsRef.current = labels;
+  const key = labels.join("\0");
+  React.useEffect(() => {
+    const canvas = canvasRef.current;
+    const probe = probeRef.current;
+    if (!enabled || !canvas || !probe) {
+      setMeasured(void 0);
+      return;
+    }
+    const ticks = labelsRef.current;
+    const measure = (text) => {
+      probe.textContent = text;
+      return probe.getBoundingClientRect().width;
+    };
+    const run = () => {
+      const available = canvas.clientWidth;
+      if (available <= 0) return;
+      const knobs = readKnobs(probe);
+      const widths = ticks.map(measure);
+      const { width, textCap } = resolveCategoryAxisWidth(widths, available, knobs);
+      const truncations2 = /* @__PURE__ */ new Map();
+      ticks.forEach((label, index) => {
+        if ((widths[index] ?? 0) > textCap) {
+          truncations2.set(label, truncateToWidth(label, textCap, measure));
+        }
+      });
+      probe.textContent = "";
+      setMeasured(
+        (previous) => previous && previous.width === width && sameTruncations(previous.truncations, truncations2) ? previous : { width, truncations: truncations2 }
+      );
+    };
+    run();
+    const observer = new ResizeObserver(run);
+    observer.observe(canvas);
+    let live = true;
+    void document.fonts?.ready.then(() => {
+      if (live) run();
+    });
+    return () => {
+      live = false;
+      observer.disconnect();
+    };
+  }, [canvasRef, probeRef, enabled, key]);
+  const truncations = measured?.truncations;
+  const display = React.useCallback(
+    (label) => truncations?.get(label) ?? label,
+    [truncations]
+  );
+  return { width: measured?.width, display };
+}
+export {
+  resolveCategoryAxisWidth,
+  truncateToWidth,
+  useCategoryAxisMetrics
+};

package/dist/components/charts/chart-frame.d.ts

@@ -18,6 +18,11 @@ export declare function useChartNumberFormat(options?: Intl.NumberFormatOptions)
 type ChartFrameProps = {
     /** Visible caption; also the accessible name via `aria-labelledby` → `<figcaption>`. */
     label: React.ReactNode;
+    /**
+     * Paint the caption. `false` keeps the `<figcaption>` in the DOM as `sr-only`, so
+     * `aria-labelledby` still names the figure — only the duplicate visible title goes away.
+     */
+    showCaption?: boolean;
     /** Extra context appended to the screen-reader description. */
     description?: React.ReactNode;
     /** Pre-formatted "category: value" rows for the screen-reader text alternative. */
@@ -39,11 +44,15 @@ type ChartFrameProps = {
     id?: string;
     children: React.ReactNode;
     ref?: React.Ref<HTMLElement>;
+    /** The plot box itself — charts that measure their own axis need to read its width. */
+    canvasRef?: React.Ref<HTMLDivElement>;
+    /** Rendered inside the canvas, after `children` (the axis measuring probe). */
+    canvasExtra?: React.ReactNode;
 };
 /**
  * The accessible figure wrapper. The chart body passed as `children` is wrapped
  * in a `role="img"` element with a short `aria-label`; the full data is exposed as
  * a sibling visually-hidden list referenced by the figure's `aria-describedby`.
  */
-export declare function ChartFrame({ label, description, summaryRows, imgSummary, hasData, height, size, footer, className, id, children, ref, }: ChartFrameProps): React.JSX.Element;
+export declare function ChartFrame({ label, showCaption, description, summaryRows, imgSummary, hasData, height, size, footer, className, id, children, ref, canvasRef, canvasExtra, }: ChartFrameProps): React.JSX.Element;
 export {};

package/dist/components/charts/chart-frame.js

@@ -29,6 +29,7 @@ function useChartNumberFormat(options) {
 }
 function ChartFrame({
   label,
+  showCaption = true,
   description,
   summaryRows,
   imgSummary,
@@ -39,7 +40,9 @@ function ChartFrame({
   className,
   id,
   children,
-  ref
+  ref,
+  canvasRef,
+  canvasExtra
 }) {
   const reactId = React.useId();
   const titleId = `${id ?? reactId}-title`;
@@ -55,8 +58,21 @@ function ChartFrame({
       "aria-labelledby": titleId,
       "aria-describedby": descId,
       children: [
-        /* @__PURE__ */ jsx("figcaption", { id: titleId, className: "ui-chart-title", children: label }),
-        /* @__PURE__ */ jsx("div", { className: "ui-chart-canvas", style: { height }, role: "img", "aria-label": imgSummary, children }),
+        /* @__PURE__ */ jsx("figcaption", { id: titleId, className: showCaption ? "ui-chart-title" : "sr-only", children: label }),
+        /* @__PURE__ */ jsxs(
+          "div",
+          {
+            ref: canvasRef,
+            className: "ui-chart-canvas",
+            style: { height },
+            role: "img",
+            "aria-label": imgSummary,
+            children: [
+              children,
+              canvasExtra
+            ]
+          }
+        ),
         footer ? /* @__PURE__ */ jsx("div", { className: "ui-chart-footer", children: footer }) : null,
         /* @__PURE__ */ jsxs("p", { id: descId, className: "sr-only", children: [
           description ? /* @__PURE__ */ jsxs(Fragment, { children: [

package/dist/components/charts/compact-bar-trend.d.ts

@@ -12,4 +12,4 @@ export type { CompactBarTrendProp, CompactBarTrendProp as CompactBarTrendProps,
  * localized one-line summary, and a visually-hidden per-category value list referenced through
  * `aria-describedby` (WCAG 1.1.1).
  */
-export declare function CompactBarTrend({ data, categoryKey, valueKey, label, description, size, emphasizedIndex, showCategoryLabels, numberFormat, footer, emptyMessage, className, id, ref, }: CompactBarTrendProp): React.JSX.Element;
+export declare function CompactBarTrend({ data, categoryKey, valueKey, label, showCaption, description, size, emphasizedIndex, showCategoryLabels, numberFormat, footer, emptyMessage, className, id, ref, }: CompactBarTrendProp): React.JSX.Element;