@godxjp/ui 32.13.1 → 32.15.0

package/agent/patterns.json

@@ -151,7 +151,7 @@
     ]
   },
   {
-    "code": "import { Head, router } from \"@inertiajs/react\"\nimport { useMemo, useState } from \"react\"\nimport { PageContainer, Flex } from \"@godxjp/ui/layout\"\nimport { Card, CardContent, DataTable, EmptyState, Badge, type ColumnDef } from \"@godxjp/ui/data-display\"\nimport { SearchInput, Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from \"@godxjp/ui/data-entry\"\nimport { Toolbar, ToolbarGroup, Pagination } from \"@godxjp/ui/navigation\"\nimport { formatDate } from \"@godxjp/ui/datetime\"\nimport { withCrmLayout } from \"@/layouts/crm-layout\" // see \"inertia-persistent-layout\"\n\ntype Coupon = { id: string; name: string; status: string; scope: string; validFrom: string; validTo: string; usage: number }\nconst PAGE_SIZE = 10\n\nfunction Coupons({ coupons }: { coupons: Coupon[] }) {\n  const [q, setQ] = useState(\"\")\n  const [status, setStatus] = useState(\"all\")\n  const [page, setPage] = useState(1)\n\n  const filtered = useMemo(() => coupons.filter((c) => {\n    if (q && !c.name.toLowerCase().includes(q.toLowerCase())) return false\n    if (status !== \"all\" && c.status !== status) return false\n    return true\n  }), [coupons, q, status])\n  const paged = filtered.slice((page - 1) * PAGE_SIZE, page * PAGE_SIZE)\n\n  // ColumnDef = { key, header, render?, align?: \"left\"|\"center\"|\"right\", sortable?, width? }\n  const columns: ColumnDef<Coupon>[] = [\n    { key: \"name\", header: \"クーポン名\", render: (c) => <span className=\"font-medium\">{c.name}</span> },\n    { key: \"scope\", header: \"スコープ\" }, // a category is plain text; Badge is for the status column only\n    { key: \"status\", header: \"ステータス\", render: (c) => <Badge status={c.status} /> },\n    { key: \"valid\", header: \"有効期間\", render: (c) => `${formatDate(c.validFrom)} 〜 ${formatDate(c.validTo)}` },\n    { key: \"usage\", header: \"利用数\", align: \"right\", render: (c) => c.usage.toLocaleString() },\n  ]\n\n  return (\n    <>\n      <Head title=\"クーポン管理\" />\n      {/* RULE: every page wraps in PageContainer; vertical rhythm via Flex direction=\"col\"/ResponsiveGrid, never p-* or gap-* */}\n      {/* No subtitle that restates the title, no StatCard row: the total is Pagination's showTotal. */}\n      <PageContainer title=\"クーポン管理\">\n        <Flex direction=\"col\" gap=\"lg\">\n          {/* Toolbar is the filter-bar primitive (standalone, above the table surface). */}\n          <Toolbar hasActiveFilters={q !== \"\" || status !== \"all\"} onClear={() => { setQ(\"\"); setStatus(\"all\"); setPage(1) }}>\n            {/* SearchInput is value + onSearch(v) — NOT onChange */}\n            <SearchInput placeholder=\"クーポン名で検索\" value={q} onSearch={(v) => { setQ(v); setPage(1) }} />\n            <ToolbarGroup label=\"ステータス\">\n              <Select value={status} onValueChange={(v) => { setStatus(v); setPage(1) }}>\n                <SelectTrigger><SelectValue /></SelectTrigger>\n                <SelectContent>\n                  <SelectItem value=\"all\">全ステータス</SelectItem>\n                  <SelectItem value=\"公開中\">公開中</SelectItem>\n                  <SelectItem value=\"下書き\">下書き</SelectItem>\n                </SelectContent>\n              </Select>\n            </ToolbarGroup>\n          </Toolbar>\n\n          <Card>\n            <CardContent flush>\n              {filtered.length === 0\n                ? <EmptyState title=\"該当するクーポンがありません\" description=\"検索条件を変更してください。\" /> /* one sentence, no icon */\n                : <DataTable data={paged} columns={columns} getRowId={(c) => c.id} onRowClick={(c) => router.visit(`/coupons/${c.id}`)} />}\n            </CardContent>\n          </Card>\n\n          {/* Pagination ONLY for real multi-page data — hide it while empty or single-page. */}\n          {filtered.length > PAGE_SIZE && (\n            <Pagination value={page} total={filtered.length} pageSize={PAGE_SIZE} showTotal onValueChange={(p) => setPage(p)} />\n          )}\n        </Flex>\n      </PageContainer>\n    </>\n  )\n}\n\nCoupons.layout = withCrmLayout\nexport default Coupons",
+    "code": "import { Head, router } from \"@inertiajs/react\"\nimport { useMemo, useState } from \"react\"\nimport { PageContainer, Flex } from \"@godxjp/ui/layout\"\nimport { Card, CardContent, DataTable, EmptyState, Badge, type ColumnDef } from \"@godxjp/ui/data-display\"\nimport { SearchInput, Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from \"@godxjp/ui/data-entry\"\nimport { Toolbar, ToolbarGroup, Pagination } from \"@godxjp/ui/navigation\"\nimport { formatDate } from \"@godxjp/ui/datetime\"\nimport { withCrmLayout } from \"@/layouts/crm-layout\" // see \"inertia-persistent-layout\"\n\ntype Coupon = { id: string; name: string; status: string; scope: string; validFrom: string; validTo: string; usage: number }\nconst PAGE_SIZE = 10\n\nfunction Coupons({ coupons }: { coupons: Coupon[] }) {\n  const [q, setQ] = useState(\"\")\n  const [status, setStatus] = useState(\"all\")\n  const [page, setPage] = useState(1)\n\n  const filtered = useMemo(() => coupons.filter((c) => {\n    if (q && !c.name.toLowerCase().includes(q.toLowerCase())) return false\n    if (status !== \"all\" && c.status !== status) return false\n    return true\n  }), [coupons, q, status])\n  const paged = filtered.slice((page - 1) * PAGE_SIZE, page * PAGE_SIZE)\n\n  // ColumnDef = { key, header, render?, align?: \"left\"|\"center\"|\"right\", sortable?, width? }\n  const columns: ColumnDef<Coupon>[] = [\n    { key: \"name\", header: \"クーポン名\", render: (c) => <span className=\"font-medium\">{c.name}</span> },\n    { key: \"scope\", header: \"スコープ\" }, // a category is plain text; Badge is for the status column only\n    { key: \"status\", header: \"ステータス\", render: (c) => <Badge status={c.status} /> },\n    { key: \"valid\", header: \"有効期間\", render: (c) => `${formatDate(c.validFrom)} 〜 ${formatDate(c.validTo)}` },\n    { key: \"usage\", header: \"利用数\", align: \"right\", render: (c) => c.usage.toLocaleString() },\n  ]\n\n  return (\n    <>\n      <Head title=\"クーポン管理\" />\n      {/* RULE: every page wraps in PageContainer; vertical rhythm via Flex direction=\"col\"/ResponsiveGrid, never p-* or gap-* */}\n      {/* No subtitle that restates the title, no StatCard row: the total is Pagination's showTotal. */}\n      <PageContainer title=\"クーポン管理\">\n        <Flex direction=\"col\" gap=\"lg\">\n          {/* Toolbar is the filter-bar primitive (standalone, above the table surface). */}\n          <Toolbar hasActiveFilters={q !== \"\" || status !== \"all\"} onClear={() => { setQ(\"\"); setStatus(\"all\"); setPage(1) }}>\n            {/* SearchInput is value + onSearch(v) — NOT onChange */}\n            <SearchInput placeholder=\"クーポン名で検索\" value={q} onSearch={(v) => { setQ(v); setPage(1) }} />\n            {/* Status view of the SAME table = a filter: Segmented with count for 2-4 statuses, this\n                Select past 4. Never Tabs: Tabs switch panels with their own columns (gh#1324). */}\n            <ToolbarGroup label=\"ステータス\">\n              <Select value={status} onValueChange={(v) => { setStatus(v); setPage(1) }}>\n                <SelectTrigger><SelectValue /></SelectTrigger>\n                <SelectContent>\n                  <SelectItem value=\"all\">全ステータス</SelectItem>\n                  <SelectItem value=\"公開中\">公開中</SelectItem>\n                  <SelectItem value=\"下書き\">下書き</SelectItem>\n                </SelectContent>\n              </Select>\n            </ToolbarGroup>\n          </Toolbar>\n\n          <Card>\n            <CardContent flush>\n              {filtered.length === 0\n                ? <EmptyState title=\"該当するクーポンがありません\" description=\"検索条件を変更してください。\" /> /* one sentence, no icon */\n                : <DataTable data={paged} columns={columns} getRowId={(c) => c.id} onRowClick={(c) => router.visit(`/coupons/${c.id}`)} />}\n            </CardContent>\n          </Card>\n\n          {/* Pagination ONLY for real multi-page data — hide it while empty or single-page. */}\n          {filtered.length > PAGE_SIZE && (\n            <Pagination value={page} total={filtered.length} pageSize={PAGE_SIZE} showTotal onValueChange={(p) => setPage(p)} />\n          )}\n        </Flex>\n      </PageContainer>\n    </>\n  )\n}\n\nCoupons.layout = withCrmLayout\nexport default Coupons",
     "name": "inertia-list-page",
     "tagline": "Inertia + @godxjp/ui list page — PageContainer + Toolbar (above the table) + DataTable + Badge + Pagination. No KPI row, no restating subtitle.",
     "tags": [

package/agent/tokens.json

@@ -443,6 +443,36 @@
     "tier": "foundation",
     "value": "#eb6101"
   },
+  {
+    "description": "Sequential heat ramp — HeatmapChart (gh#1330). ONE hue (the --chart-1 blue, 204°) stepped by lightness alone, so the order of the steps survives every colour-vision deficiency: CVD shifts hue, and a single-hue ramp carries its meaning in luminance, which protan/deutan/tritan vision all keep. Relative luminance falls monotonically 0.805 → 0.541 → 0.330 → 0.173 → 0.064; against the light --card that is 1.21 / 1.74 / 2.72 / 4.62 / 9.03:1, each step ≥1.45:1 from the last. Step 1 is deliberately quiet (it is \"low\", not \"absent\"): an EMPTY cell is told apart by its dashed outline and its text, never by this fill. A service retunes the whole ramp here.",
+    "name": "--chart-heat-1",
+    "tier": "foundation",
+    "value": "#d6ebf8"
+  },
+  {
+    "description": "Foundation tokens: color, typography, raw spacing, ratio, radius, shadow.",
+    "name": "--chart-heat-2",
+    "tier": "foundation",
+    "value": "#94c9ec"
+  },
+  {
+    "description": "Foundation tokens: color, typography, raw spacing, ratio, radius, shadow.",
+    "name": "--chart-heat-3",
+    "tier": "foundation",
+    "value": "#4ea3dc"
+  },
+  {
+    "description": "Foundation tokens: color, typography, raw spacing, ratio, radius, shadow.",
+    "name": "--chart-heat-4",
+    "tier": "foundation",
+    "value": "#0077c7"
+  },
+  {
+    "description": "Foundation tokens: color, typography, raw spacing, ratio, radius, shadow.",
+    "name": "--chart-heat-5",
+    "tier": "foundation",
+    "value": "#004a7f"
+  },
   {
     "description": "Disabled affordance opacity — single knob (was referenced but undefined → silent failure).",
     "name": "--disabled-opacity",
@@ -1638,7 +1668,7 @@
     "value": "initial"
   },
   {
-    "description": "PageContainer `toolbar` — the fixed chrome band between the header and the (scrolling) body. ALL THREE knobs are quiet by default (rule #44): background — `transparent`, i.e. the band shows the page ground exactly as it did before the knob existed. It is bound at `:root` and NOT `initial`, unlike the divider below, because the default is a plain CSS keyword rather than another role token: there is nothing for a scoped [data-tenant]/.dark override to re-resolve, so the `initial` + call-site-fallback dance would buy nothing and only hide the default from anyone reading this file. A service that wants the band to read as its own surface — the design that asked for this knob puts a chat channel's workflow rail on the card ground — sets `--page-toolbar-background: hsl(var(--card));` ONCE in its theme. Never `className=\"bg-card\"` at the call site: that is hand-laid page chrome, it paints only under `variant=\"flush\"` gutters correctly by accident, and it cannot be re-themed per tenant. pad-block 0 — the band's ONLY breathing room, and the only one it should ever have. The band is chrome, so it sits FLUSH against the header above and the body below (src/styles/layout.css cancels the container's --page-band-gap from the band itself); there is deliberately no outside space to tune, because a ruled, painted band floating in a void divides nothing. A service that opts into the background or the divider gives the band its inset HERE (`--page-toolbar-pad-block: var(--space-2)`) instead of padding the strip at the call site. Still 0 by default: a transparent band is not a surface and has no inside to breathe, and under `fill` every pixel of it comes straight off the scroll viewport the slot exists to protect. divider — declared `initial` so the CALL SITE can fall back to --page-header-divider (`var(--page-toolbar-divider, var(--page-header-divider))`). One theme declaration therefore rules the whole page chrome consistently, and a scoped [data-tenant]/.dark override of the header divider still reaches the band — a `:root` binding would freeze it at the :root value (docs/TOKENS.md · \"Role-mirror knobs MUST be `initial`\"). Set `--page-toolbar-divider: none` to silence just this band.",
+    "description": "PageContainer `toolbar` — the fixed chrome band between the header and the (scrolling) body. ALL THREE knobs are quiet by default (rule #44): background — `transparent`, i.e. the band shows the page ground exactly as it did before the knob existed. It is bound at `:root` and NOT `initial`, unlike the divider below, because the default is a plain CSS keyword rather than another role token: there is nothing for a scoped [data-tenant]/.dark override to re-resolve, so the `initial` + call-site-fallback dance would buy nothing and only hide the default from anyone reading this file. A service that wants the band to read as its own surface — the design that asked for this knob puts a chat channel's workflow rail on the card ground — sets `--page-toolbar-background: hsl(var(--card));` ONCE in its theme. Never `className=\"bg-card\"` at the call site: that is hand-laid page chrome, it paints only under `variant=\"flush\"` gutters correctly by accident, and it cannot be re-themed per tenant. pad-block — `initial`; the call site falls back to the container's `--page-band-gap` (`var(--page-toolbar-pad-block, var(--page-band-gap))`), which is scoped on `.ui-page-container` and so cannot be bound here. The band's BOX sits FLUSH against the header above and the body below (src/styles/layout.css cancels the container's gap from the band itself — a painted, ruled band floating in a void divides nothing), and this inset gives the band's CONTENT the page's band rhythm back: a plain filter strip sits one band gap from the header and from the body, the same as any other band. At the old `0px` default a transparent strip touched both surfaces, 0px (gh#1323). A service that paints or rules the band sets a tighter inset HERE (`--page-toolbar-pad-block: var(--space-2)`) instead of padding the strip at the call site; `0px` restores the flush strip. divider — declared `initial` so the CALL SITE can fall back to --page-header-divider (`var(--page-toolbar-divider, var(--page-header-divider))`). One theme declaration therefore rules the whole page chrome consistently, and a scoped [data-tenant]/.dark override of the header divider still reaches the band — a `:root` binding would freeze it at the :root value (docs/TOKENS.md · \"Role-mirror knobs MUST be `initial`\"). Set `--page-toolbar-divider: none` to silence just this band.",
     "name": "--page-toolbar-background",
     "tier": "semantic",
     "value": "transparent"
@@ -1647,7 +1677,7 @@
     "description": "Layout primitive tokens: page, section, stack, inline.",
     "name": "--page-toolbar-pad-block",
     "tier": "semantic",
-    "value": "0px"
+    "value": "initial"
   },
   {
     "description": "Layout primitive tokens: page, section, stack, inline.",
@@ -2855,6 +2885,90 @@
     "tier": "component",
     "value": "3 3"
   },
+  {
+    "description": "Minimum cell edge per tier. `xs` is still 24px — a cell is a hover/focus target (WCAG 2.5.8).",
+    "name": "--chart-heatmap-cell-size-xs",
+    "tier": "component",
+    "value": "1.5rem"
+  },
+  {
+    "description": "Chart component tokens — the dependency-free `CompactBarTrend` primitive (`@godxjp/ui/charts`). Every piece of its geometry and every fill is a public knob so a service theme can match its own design grid WITHOUT page-local CSS or inline heights (cardinal rules #44/#45). The recharts-backed charts draw their own SVG from the foundation `--chart-1..6` palette, plus the cartesian series knobs at the bottom of this file.",
+    "name": "--chart-heatmap-cell-size-sm",
+    "tier": "component",
+    "value": "1.75rem"
+  },
+  {
+    "description": "Chart component tokens — the dependency-free `CompactBarTrend` primitive (`@godxjp/ui/charts`). Every piece of its geometry and every fill is a public knob so a service theme can match its own design grid WITHOUT page-local CSS or inline heights (cardinal rules #44/#45). The recharts-backed charts draw their own SVG from the foundation `--chart-1..6` palette, plus the cartesian series knobs at the bottom of this file.",
+    "name": "--chart-heatmap-cell-size-md",
+    "tier": "component",
+    "value": "2rem"
+  },
+  {
+    "description": "Chart component tokens — the dependency-free `CompactBarTrend` primitive (`@godxjp/ui/charts`). Every piece of its geometry and every fill is a public knob so a service theme can match its own design grid WITHOUT page-local CSS or inline heights (cardinal rules #44/#45). The recharts-backed charts draw their own SVG from the foundation `--chart-1..6` palette, plus the cartesian series knobs at the bottom of this file.",
+    "name": "--chart-heatmap-cell-size-lg",
+    "tier": "component",
+    "value": "2.5rem"
+  },
+  {
+    "description": "Active tier — chart-layout.css re-points this per `data-size`.",
+    "name": "--chart-heatmap-cell-size",
+    "tier": "component",
+    "value": "var(--chart-heatmap-cell-size-md)"
+  },
+  {
+    "description": "Surface gap between neighbouring cells (the table's border-spacing).",
+    "name": "--chart-heatmap-cell-gap",
+    "tier": "component",
+    "value": "var(--stroke-md)"
+  },
+  {
+    "description": "default = calc(var(--radius) / var(--radius-ratio) / var(--radius-ratio)), resolved at the call site",
+    "name": "--chart-heatmap-cell-radius",
+    "tier": "component",
+    "value": "initial"
+  },
+  {
+    "description": "EMPTY cell outline — the non-colour cue that tells \"no data\" from a zero (WCAG 1.4.1). Role-mirror knob, `initial` at :root; default at the call site = `var(--stroke-hairline) dashed hsl(var(--muted-foreground))`.",
+    "name": "--chart-heatmap-empty-border",
+    "tier": "component",
+    "value": "initial"
+  },
+  {
+    "description": "Top-N emphasis ring — a SHAPE cue, never colour alone. Colour is a role-mirror knob (default `hsl(var(--foreground))` at the call site); width is a plain constant.",
+    "name": "--chart-heatmap-emphasis-border",
+    "tier": "component",
+    "value": "initial"
+  },
+  {
+    "description": "Chart component tokens — the dependency-free `CompactBarTrend` primitive (`@godxjp/ui/charts`). Every piece of its geometry and every fill is a public knob so a service theme can match its own design grid WITHOUT page-local CSS or inline heights (cardinal rules #44/#45). The recharts-backed charts draw their own SVG from the foundation `--chart-1..6` palette, plus the cartesian series knobs at the bottom of this file.",
+    "name": "--chart-heatmap-emphasis-width",
+    "tier": "component",
+    "value": "var(--stroke-md)"
+  },
+  {
+    "description": "The pinned row-header column paints over cells scrolled beneath it, so it needs a ground. Role-mirror knob; default = `hsl(var(--card))` at the call site.",
+    "name": "--chart-heatmap-row-header-background",
+    "tier": "component",
+    "value": "initial"
+  },
+  {
+    "description": "Chart component tokens — the dependency-free `CompactBarTrend` primitive (`@godxjp/ui/charts`). Every piece of its geometry and every fill is a public knob so a service theme can match its own design grid WITHOUT page-local CSS or inline heights (cardinal rules #44/#45). The recharts-backed charts draw their own SVG from the foundation `--chart-1..6` palette, plus the cartesian series knobs at the bottom of this file.",
+    "name": "--chart-heatmap-tick-font-size",
+    "tier": "component",
+    "value": "var( --font-size-xs, calc(var(--font-size-base) / var(--font-size-ratio)) )"
+  },
+  {
+    "description": "Legend rhythm: the swatch edge and the gap between legend items / plot ↔ legend.",
+    "name": "--chart-heatmap-legend-swatch-size",
+    "tier": "component",
+    "value": "var(--space-3)"
+  },
+  {
+    "description": "Chart component tokens — the dependency-free `CompactBarTrend` primitive (`@godxjp/ui/charts`). Every piece of its geometry and every fill is a public knob so a service theme can match its own design grid WITHOUT page-local CSS or inline heights (cardinal rules #44/#45). The recharts-backed charts draw their own SVG from the foundation `--chart-1..6` palette, plus the cartesian series knobs at the bottom of this file.",
+    "name": "--chart-heatmap-legend-gap",
+    "tier": "component",
+    "value": "var(--space-2)"
+  },
   {
     "description": "Bubble fill. `initial` so the --muted default re-resolves at the CALL SITE under a scoped theme; a :root binding to a role var freezes at :root (docs/TOKENS.md — the :root freeze rule). Documented default = hsl(var(--muted)).",
     "name": "--chat-bubble-background",

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

@@ -3,7 +3,7 @@
  * alternative (WCAG 1.1.1). No JSX — filename pascal is intentionally NOT
  * exported, so this is not a catalog primitive.
  */
-import type { ChartDatum, ChartSeriesProp } from "../../props/components/charts.prop.js";
+import type { ChartDatum, ChartSeriesProp, HeatmapCategory, HeatmapDatum } from "../../props/components/charts.prop.js";
 type Formatter = Intl.NumberFormat;
 export type ChartSummary = {
     rows: string[];
@@ -39,4 +39,35 @@ export declare function trendRatios(data: ChartDatum[], valueKey: string): numbe
  * datum).
  */
 export declare function resolveEmphasizedIndex(index: number | undefined, length: number): number;
+/** Number of steps in the `--chart-heat-1..N` ramp. */
+export declare const HEAT_STEPS = 5;
+/** The lookup key of one heatmap cell. */
+export declare function heatmapCellKey(row: string | number, column: string | number): string;
+export type HeatmapModel = {
+    /** Finite values by cell key. A key that is absent is an EMPTY cell, never a zero. */
+    values: Map<string, number>;
+    /** Ramp step 1..HEAT_STEPS by cell key. */
+    steps: Map<string, number>;
+    /** 1-based rank of the top-N cells by cell key. */
+    ranks: Map<string, number>;
+    /** Scale domain: `min(0, smallest)` .. largest. */
+    min: number;
+    max: number;
+    /** Count of cells with a value inside the rows × columns matrix. */
+    present: number;
+    /** Count of matrix cells with no value. */
+    empty: number;
+    /** The highest cell, for the one-line summary. */
+    highest: {
+        row: HeatmapCategory;
+        column: HeatmapCategory;
+        value: number;
+    } | null;
+};
+/**
+ * Bin a heatmap's cells onto the sequential ramp. The domain starts at zero (or the smallest value,
+ * when that is negative) so the fill encodes MAGNITUDE — a heatmap of 900..1000 whose 900 painted
+ * as "empty-light" would read as a quiet hour. Cells outside `rows` × `columns` are ignored.
+ */
+export declare function buildHeatmapModel(rows: HeatmapCategory[], columns: HeatmapCategory[], data: HeatmapDatum[], topN?: number): HeatmapModel;
 export {};

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

@@ -40,11 +40,60 @@ function resolveEmphasizedIndex(index, length) {
   const resolved = index < 0 ? length + index : index;
   return resolved >= 0 && resolved < length ? resolved : -1;
 }
+const HEAT_STEPS = 5;
+function heatmapCellKey(row, column) {
+  return `${String(row)}\0${String(column)}`;
+}
+function buildHeatmapModel(rows, columns, data, topN) {
+  const rowByKey = new Map(rows.map((row) => [String(row.key), row]));
+  const columnByKey = new Map(columns.map((column) => [String(column.key), column]));
+  const values = /* @__PURE__ */ new Map();
+  const order = [];
+  for (const datum of data) {
+    const row = rowByKey.get(String(datum.row));
+    const column = columnByKey.get(String(datum.column));
+    if (!row || !column) continue;
+    if (typeof datum.value !== "number" || !Number.isFinite(datum.value)) continue;
+    const key = heatmapCellKey(row.key, column.key);
+    if (values.has(key)) continue;
+    values.set(key, datum.value);
+    order.push({ key, value: datum.value, row, column });
+  }
+  let min = 0;
+  let max = 0;
+  for (const { value } of order) {
+    if (value < min) min = value;
+    if (value > max) max = value;
+  }
+  const steps = /* @__PURE__ */ new Map();
+  for (const { key, value } of order) {
+    const ratio = max > min ? (value - min) / (max - min) : max > 0 ? 1 : 0;
+    steps.set(key, Math.min(HEAT_STEPS, Math.floor(ratio * HEAT_STEPS) + 1));
+  }
+  const ranked = [...order].sort((a, b) => b.value - a.value);
+  const ranks = /* @__PURE__ */ new Map();
+  const n = topN !== void 0 && Number.isInteger(topN) && topN > 0 ? topN : 0;
+  ranked.slice(0, n).forEach((cell, index) => ranks.set(cell.key, index + 1));
+  const top = ranked[0];
+  return {
+    values,
+    steps,
+    ranks,
+    min,
+    max,
+    present: order.length,
+    empty: rows.length * columns.length - order.length,
+    highest: top ? { row: top.row, column: top.column, value: top.value } : null
+  };
+}
 export {
+  HEAT_STEPS,
   buildCartesianSummary,
+  buildHeatmapModel,
   buildPieSummary,
   buildSeriesRows,
   buildTrendSummary,
+  heatmapCellKey,
   resolveEmphasizedIndex,
   trendRatios
 };

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

@@ -0,0 +1,19 @@
+import * as React from "react";
+import type { HeatmapChartProp } from "../../props/components/charts.prop.js";
+export type { HeatmapChartProp, HeatmapChartProp as HeatmapChartProps, HeatmapCategory, HeatmapDatum, } from "../../props/components/charts.prop.js";
+/**
+ * HeatmapChart — a **dependency-free** rows × columns matrix (weekday × hour revenue, order counts
+ * per slot). Cell fill steps through the sequential `--chart-heat-1..5` ramp.
+ *
+ * - **One structure for sight and for AT.** The matrix IS a native data table (`<th scope>` headers,
+ *   one cell per slot) with `role="grid"`, so the screen-reader text alternative is the same element
+ *   the eye reads — no second, drifting copy. Each cell carries its formatted value as text.
+ * - **Keyboard** — WAI-ARIA APG data grid: one tab stop (roving tabindex), arrows move between
+ *   cells (mirrored under RTL), Home/End go to the row's ends, Ctrl+Home/End to the first/last
+ *   cell. A focused or hovered cell shows ONE shared tooltip; Escape dismisses it.
+ * - **Never colour alone** — an empty cell is outlined (dashed) and reads "no data"; a zero is a
+ *   filled step-1 cell that reads "0"; a top-N cell wears a ring and reads "top N".
+ * - **Narrow screens** — the matrix never shrinks a cell below its `size` tier; it scrolls inside
+ *   its own box with the row header pinned, so the page never scrolls sideways.
+ */
+export declare function HeatmapChart({ rows, columns, data, label, showCaption, description, size, numberFormat, topN, showLegend, emptyMessage, className, id, ref, }: HeatmapChartProp): React.JSX.Element;

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

@@ -0,0 +1,293 @@
+"use client";
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../../lib/utils.js";
+import { EmptyState } from "../data-display/empty-state.js";
+import { Tooltip, TooltipAnchorContext, TooltipContent } from "../feedback/tooltip.js";
+import { useTranslation } from "../../i18n/use-translation.js";
+import { useChartNumberFormat } from "./chart-frame.js";
+import { HEAT_STEPS, buildHeatmapModel, heatmapCellKey } from "./chart-summary.js";
+const OPEN_DELAY = 200;
+const CLOSE_GRACE = 100;
+const RAMP = Array.from({ length: HEAT_STEPS }, (_, index) => index + 1);
+function HeatmapChart({
+  rows,
+  columns,
+  data,
+  label,
+  showCaption = true,
+  description,
+  size = "md",
+  numberFormat,
+  topN,
+  showLegend = true,
+  emptyMessage,
+  className,
+  id,
+  ref
+}) {
+  const { t } = useTranslation();
+  const fmt = useChartNumberFormat(numberFormat);
+  const countFmt = useChartNumberFormat();
+  const model = React.useMemo(
+    () => buildHeatmapModel(rows, columns, data, topN),
+    [rows, columns, data, topN]
+  );
+  const hasData = rows.length > 0 && columns.length > 0 && model.present > 0;
+  const reactId = React.useId();
+  const baseId = id ?? reactId;
+  const titleId = `${baseId}-title`;
+  const descId = `${baseId}-desc`;
+  const [active, setActive] = React.useState([0, 0]);
+  const activeRow = Math.min(active[0], Math.max(0, rows.length - 1));
+  const activeColumn = Math.min(active[1], Math.max(0, columns.length - 1));
+  const scrollRef = React.useRef(null);
+  const cellRefs = React.useRef(/* @__PURE__ */ new Map());
+  const anchorRef = React.useRef(null);
+  const timer = React.useRef(void 0);
+  const [tip, setTip] = React.useState(null);
+  React.useEffect(() => () => clearTimeout(timer.current), []);
+  const showTip = (r, c, node, delay) => {
+    clearTimeout(timer.current);
+    timer.current = setTimeout(() => {
+      anchorRef.current = node;
+      setTip([r, c]);
+    }, delay);
+  };
+  const hideTip = () => {
+    clearTimeout(timer.current);
+    timer.current = setTimeout(() => setTip(null), CLOSE_GRACE);
+  };
+  React.useEffect(() => {
+    if (!tip) return void 0;
+    const onKeyDown = (event) => {
+      if (event.key === "Escape") {
+        clearTimeout(timer.current);
+        setTip(null);
+      }
+    };
+    document.addEventListener("keydown", onKeyDown);
+    return () => document.removeEventListener("keydown", onKeyDown);
+  }, [tip]);
+  const reveal = (cell) => {
+    const scroller = scrollRef.current;
+    const header = cell.parentElement?.querySelector("th");
+    if (!scroller || !header) return;
+    const cellBox = cell.getBoundingClientRect();
+    const headerBox = header.getBoundingClientRect();
+    if (getComputedStyle(scroller).direction === "rtl") {
+      if (cellBox.right > headerBox.left) scroller.scrollLeft += cellBox.right - headerBox.left;
+    } else if (cellBox.left < headerBox.right) {
+      scroller.scrollLeft -= headerBox.right - cellBox.left;
+    }
+  };
+  const moveTo = (r, c) => {
+    const row = Math.max(0, Math.min(rows.length - 1, r));
+    const column = Math.max(0, Math.min(columns.length - 1, c));
+    setActive([row, column]);
+    const cell = cellRefs.current.get(`${row}:${column}`);
+    if (cell) {
+      cell.focus();
+      reveal(cell);
+    }
+  };
+  const onGridKeyDown = (event) => {
+    const rtl = getComputedStyle(event.currentTarget).direction === "rtl";
+    const lastRow = rows.length - 1;
+    const lastColumn = columns.length - 1;
+    const ctrl = event.ctrlKey || event.metaKey;
+    switch (event.key) {
+      case "ArrowRight":
+        moveTo(activeRow, activeColumn + (rtl ? -1 : 1));
+        break;
+      case "ArrowLeft":
+        moveTo(activeRow, activeColumn + (rtl ? 1 : -1));
+        break;
+      case "ArrowDown":
+        moveTo(activeRow + 1, activeColumn);
+        break;
+      case "ArrowUp":
+        moveTo(activeRow - 1, activeColumn);
+        break;
+      case "Home":
+        moveTo(ctrl ? 0 : activeRow, 0);
+        break;
+      case "End":
+        moveTo(ctrl ? lastRow : activeRow, lastColumn);
+        break;
+      case "Escape":
+        clearTimeout(timer.current);
+        setTip(null);
+        return;
+      default:
+        return;
+    }
+    event.preventDefault();
+  };
+  const cellText = (r, c) => {
+    const key = heatmapCellKey(rows[r].key, columns[c].key);
+    const value = model.values.get(key);
+    const rank = model.ranks.get(key);
+    return {
+      value: value === void 0 ? t("chart.heatmapNoData") : fmt.format(value),
+      top: rank === void 0 ? void 0 : t("chart.heatmapTop", { rank: countFmt.format(rank) })
+    };
+  };
+  const summary = model.highest ? `${t("chart.heatmapSummary", {
+    rows: countFmt.format(rows.length),
+    columns: countFmt.format(columns.length)
+  })} ${t("chart.heatmapHighest", {
+    value: fmt.format(model.highest.value),
+    row: model.highest.row.label,
+    column: model.highest.column.label
+  })}` : "";
+  const tipText = tip && tip[0] < rows.length && tip[1] < columns.length ? cellText(tip[0], tip[1]) : null;
+  const span = model.max - model.min;
+  const bound = (step) => model.min + span * step / HEAT_STEPS;
+  return /* @__PURE__ */ jsxs(
+    "figure",
+    {
+      ref,
+      id,
+      "data-slot": "chart",
+      "data-size": size,
+      className: cn("ui-chart ui-chart-heatmap", className),
+      "aria-labelledby": titleId,
+      "aria-describedby": descId,
+      children: [
+        /* @__PURE__ */ jsx("figcaption", { id: titleId, className: showCaption ? "ui-chart-title" : "sr-only", children: label }),
+        hasData ? /* @__PURE__ */ jsxs(Fragment, { children: [
+          /* @__PURE__ */ jsx("div", { ref: scrollRef, className: "ui-chart-heatmap-scroll", children: /* @__PURE__ */ jsxs(
+            "table",
+            {
+              role: "grid",
+              "aria-labelledby": titleId,
+              className: "ui-chart-heatmap-grid",
+              onKeyDown: onGridKeyDown,
+              children: [
+                /* @__PURE__ */ jsx("thead", { children: /* @__PURE__ */ jsxs("tr", { children: [
+                  /* @__PURE__ */ jsx("td", { className: "ui-chart-heatmap-corner" }),
+                  columns.map((column) => /* @__PURE__ */ jsx(
+                    "th",
+                    {
+                      scope: "col",
+                      className: "ui-chart-heatmap-column-header",
+                      children: column.label
+                    },
+                    String(column.key)
+                  ))
+                ] }) }),
+                /* @__PURE__ */ jsx("tbody", { children: rows.map((row, r) => /* @__PURE__ */ jsxs("tr", { children: [
+                  /* @__PURE__ */ jsx("th", { scope: "row", className: "ui-chart-heatmap-row-header", children: row.label }),
+                  columns.map((column, c) => {
+                    const key = heatmapCellKey(row.key, column.key);
+                    const empty = !model.values.has(key);
+                    const text = cellText(r, c);
+                    return /* @__PURE__ */ jsx(
+                      "td",
+                      {
+                        role: "gridcell",
+                        ref: (node) => {
+                          if (node) cellRefs.current.set(`${r}:${c}`, node);
+                          else cellRefs.current.delete(`${r}:${c}`);
+                        },
+                        tabIndex: r === activeRow && c === activeColumn ? 0 : -1,
+                        className: "ui-chart-heatmap-cell ui-focus-ring",
+                        "data-step": empty ? void 0 : model.steps.get(key),
+                        "data-empty": empty ? "" : void 0,
+                        "data-emphasized": model.ranks.has(key) ? "" : void 0,
+                        onFocus: (event) => {
+                          setActive([r, c]);
+                          showTip(r, c, event.currentTarget, 0);
+                        },
+                        onBlur: hideTip,
+                        onPointerEnter: (event) => showTip(r, c, event.currentTarget, OPEN_DELAY),
+                        onPointerLeave: hideTip,
+                        children: /* @__PURE__ */ jsx("span", { className: "sr-only", children: text.top ? `${text.value}, ${text.top}` : text.value })
+                      },
+                      String(column.key)
+                    );
+                  })
+                ] }, String(row.key))) })
+              ]
+            }
+          ) }),
+          showLegend ? /* @__PURE__ */ jsxs("div", { className: "ui-chart-heatmap-legend", children: [
+            /* @__PURE__ */ jsxs("div", { className: "ui-chart-heatmap-legend-scale", children: [
+              /* @__PURE__ */ jsx("span", { className: "ui-chart-heatmap-legend-label", "aria-hidden": "true", children: fmt.format(model.min) }),
+              /* @__PURE__ */ jsx(
+                "ul",
+                {
+                  role: "list",
+                  className: "ui-chart-heatmap-legend-ramp",
+                  "aria-label": t("chart.heatmapLegend"),
+                  children: RAMP.map((step) => /* @__PURE__ */ jsx("li", { className: "ui-chart-heatmap-legend-swatch", "data-step": step, children: /* @__PURE__ */ jsx("span", { className: "sr-only", children: fmt.formatRange(bound(step - 1), bound(step)) }) }, step))
+                }
+              ),
+              /* @__PURE__ */ jsx("span", { className: "ui-chart-heatmap-legend-label", "aria-hidden": "true", children: fmt.format(model.max) })
+            ] }),
+            model.empty > 0 ? /* @__PURE__ */ jsxs("span", { className: "ui-chart-heatmap-legend-item", children: [
+              /* @__PURE__ */ jsx(
+                "span",
+                {
+                  className: "ui-chart-heatmap-legend-swatch",
+                  "data-empty": "",
+                  "aria-hidden": "true"
+                }
+              ),
+              t("chart.heatmapNoData")
+            ] }) : null,
+            model.ranks.size > 0 ? /* @__PURE__ */ jsxs("span", { className: "ui-chart-heatmap-legend-item", children: [
+              /* @__PURE__ */ jsx(
+                "span",
+                {
+                  className: "ui-chart-heatmap-legend-swatch",
+                  "data-step": HEAT_STEPS,
+                  "data-emphasized": "",
+                  "aria-hidden": "true"
+                }
+              ),
+              t("chart.heatmapLegendTop", { count: countFmt.format(model.ranks.size) })
+            ] }) : null
+          ] }) : null
+        ] }) : /* @__PURE__ */ jsx(EmptyState, { title: emptyMessage ?? t("chart.empty") }),
+        /* @__PURE__ */ jsxs("p", { id: descId, className: "sr-only", children: [
+          description ? /* @__PURE__ */ jsxs(Fragment, { children: [
+            description,
+            " "
+          ] }) : null,
+          hasData ? summary : null
+        ] }),
+        /* @__PURE__ */ jsx(
+          Tooltip,
+          {
+            open: tip !== null,
+            onOpenChange: (next) => {
+              if (!next) setTip(null);
+            },
+            children: /* @__PURE__ */ jsx(TooltipAnchorContext.Provider, { value: anchorRef, children: tip && tipText ? /* @__PURE__ */ jsxs(
+              TooltipContent,
+              {
+                className: "ui-chart-heatmap-tooltip",
+                onPointerEnter: () => clearTimeout(timer.current),
+                onPointerLeave: hideTip,
+                children: [
+                  /* @__PURE__ */ jsx("span", { className: "ui-chart-heatmap-tooltip-title", children: t("chart.heatmapCell", {
+                    row: rows[tip[0]]?.label ?? "",
+                    column: columns[tip[1]]?.label ?? "",
+                    value: tipText.value
+                  }) }),
+                  tipText.top ? /* @__PURE__ */ jsx("span", { className: "ui-chart-heatmap-tooltip-note", children: tipText.top }) : null
+                ]
+              },
+              `${tip[0]}:${tip[1]}`
+            ) : null })
+          }
+        )
+      ]
+    }
+  );
+}
+export {
+  HeatmapChart
+};

package/dist/components/charts/index.d.ts

@@ -9,6 +9,9 @@ export type { BarChartProp, BarChartProps } from "./bar-chart.js";
  */
 export { CompactBarTrend } from "./compact-bar-trend.js";
 export type { CompactBarTrendProp, CompactBarTrendProps } from "./compact-bar-trend.js";
+/** Dependency-free rows × columns heatmap — isolated entry `@godxjp/ui/charts/heatmap-chart`. */
+export { HeatmapChart } from "./heatmap-chart.js";
+export type { HeatmapChartProp, HeatmapChartProps, HeatmapCategory, HeatmapDatum, } from "./heatmap-chart.js";
 export { AreaChart } from "./area-chart.js";
 export type { AreaChartProp, AreaChartProps } from "./area-chart.js";
 export { PieChart } from "./pie-chart.js";

package/dist/components/charts/index.js

@@ -1,6 +1,7 @@
 import { LineChart } from "./line-chart.js";
 import { BarChart } from "./bar-chart.js";
 import { CompactBarTrend } from "./compact-bar-trend.js";
+import { HeatmapChart } from "./heatmap-chart.js";
 import { AreaChart } from "./area-chart.js";
 import { PieChart } from "./pie-chart.js";
 import { CHART_COLORS } from "./chart-frame.js";
@@ -9,6 +10,7 @@ export {
   BarChart,
   CHART_COLORS,
   CompactBarTrend,
+  HeatmapChart,
   LineChart,
   PieChart
 };

package/dist/components/feedback/tooltip.d.ts

@@ -1,6 +1,15 @@
 import * as React from "react";
 type Side = "top" | "right" | "bottom" | "left";
 type Align = "start" | "center" | "end";
+/**
+ * Anchors `TooltipContent` to an element that is NOT a `TooltipTrigger` (gh#1045). `TooltipTrigger`
+ * wraps its child in RAC's `Focusable`, which stamps `tabIndex=0` on it — right for a button, wrong for a truncated `Text` inside a `treeitem`, where it
+ * would add a second tab stop. The ellipsis tooltip drives `open` itself and hands its own element
+ * here as the positioning target (RAC `Tooltip`'s `triggerRef`). HeatmapChart (gh#1330) does the
+ * same with ONE tooltip for its whole grid, anchored to the active cell. Module-internal: not in
+ * the feedback index.
+ */
+export declare const TooltipAnchorContext: React.Context<React.RefObject<Element | null> | null>;
 interface TooltipProviderProps {
     /** Delay mở dùng chung cho mọi `Tooltip` bên trong, tính bằng ms. */
     delayDuration?: number;