@12-apps/ui 6.0.2 → 6.2.0

package/dist/types/components/data-display/CardKit/use-row-confirm.d.ts

@@ -0,0 +1,57 @@
+import { type JSX } from 'react';
+/**
+ * How the popup should read for the rows about to be acted on.
+ *
+ * Built from the SELECTION rather than from a single row, because the same
+ * guard covers a bulk action: "Delete 4 categories?" and "Delete the category
+ * Drinks?" are the same question asked of a different-sized selection — and an
+ * operator who multi-selected by mistake is exactly who this popup is for.
+ */
+export interface RowConfirmCopy {
+    title: string;
+    description: string;
+    /** Echoed into the popup; omit for a multi-row selection the title covers. */
+    entityName?: string;
+    /** The VERB. Required, never defaulted — see {@link useRowConfirm}. */
+    confirmText: string;
+    /** Override where the word "cancel" would mean the ACTION itself. */
+    cancelText?: string;
+    /** Require typing this before the confirm enables — for the unrecoverable few. */
+    typeToConfirm?: string;
+}
+interface RowConfirmOptions<T> {
+    /**
+     * The destructive write, over the whole selection. Called ONLY after the
+     * operator confirms; throw (or reject) to keep the popup open carrying the
+     * message.
+     */
+    write: (rows: T[]) => Promise<unknown>;
+    /** The wording, given the selection. */
+    describe: (rows: T[]) => RowConfirmCopy;
+    dataTestId: string;
+    /** Shown when `write` fails without a message of its own. */
+    errorText?: string;
+}
+export interface RowConfirm<T> {
+    /** Hand this a grid action's `rows`: it opens the popup and writes nothing. */
+    request: (rows: T[]) => void;
+    /** Render next to the grid. */
+    dialog: JSX.Element | null;
+}
+/**
+ * Confirmation for a grid's `RowAction` — the per-row kebab entry and the
+ * multi-select actions menu both, since they run the same handler.
+ *
+ * The SELECTION is held while the popup is open, so the write sees exactly the
+ * rows the operator was looking at when they were asked. Re-reading the grid's
+ * live selection at confirm time is the bug this shape avoids: the list can
+ * refresh underneath an open dialog.
+ *
+ * `confirmText` is required and comes from `describe`, with no default. A verb
+ * defaulted in the origin's language reads as finished to the next adopter
+ * right up until an operator sees it — and `ConfirmOptions` already refuses to
+ * default one for the same reason.
+ */
+export declare function useRowConfirm<T>({ write, describe, dataTestId, errorText, }: RowConfirmOptions<T>): RowConfirm<T>;
+export {};
+//# sourceMappingURL=use-row-confirm.d.ts.map

package/dist/types/components/data-display/CardKit/use-row-confirm.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-row-confirm.d.ts","sourceRoot":"","sources":["../../../../../src/components/data-display/CardKit/use-row-confirm.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAY,KAAK,GAAG,EAAE,MAAM,OAAO,CAAC;AAI3C;;;;;;;GAOG;AACH,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,qEAAqE;IACrE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,kFAAkF;IAClF,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,UAAU,iBAAiB,CAAC,CAAC;IAC3B;;;;OAIG;IACH,KAAK,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC,wCAAwC;IACxC,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,cAAc,CAAC;IACxC,UAAU,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,+EAA+E;IAC/E,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC;IAC7B,+BAA+B;IAC/B,MAAM,EAAE,GAAG,CAAC,OAAO,GAAG,IAAI,CAAC;CAC5B;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,EAC/B,KAAK,EACL,QAAQ,EACR,UAAU,EACV,SAAS,GACV,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CAuBtC"}

package/dist/types/utils/export-rows.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Serialise rows and hand the browser a download.
+ *
+ * The companion of the grid's Export control, which emits a REQUEST and leaves
+ * the producing to the host — this is the producing half, for the common case
+ * where the host already has the rows and only needs a file out of them.
+ *
+ * Dependency-free on purpose: "Excel" is emitted as CSV, which Excel opens
+ * natively. A spreadsheet library would add ~700KB to a bundle for column
+ * widths nobody asked for, and the one thing a real `.xlsx` buys — types that
+ * survive the round trip — is not something a CSV export of an admin list is
+ * being asked for.
+ */
+type ExportFormat = 'csv' | 'json';
+/** One column of the exported file: its header, and how to read a row. */
+export interface ExportColumn<T> {
+    /** Column header, used as the CSV column and the JSON key. */
+    header: string;
+    /** Extract the cell value for a row. */
+    value: (row: T) => string | number | boolean | null | undefined;
+}
+/**
+ * Serialise `rows` using `columns` and download them as `<baseName>.<ext>`.
+ *
+ * @param format - `csv` (also what the Excel option produces) or `json`.
+ * @param baseName - File name without extension; the consumer's word for the
+ *   collection, so it is never derived from a type name here.
+ */
+export declare function exportRows<T>(format: ExportFormat, rows: readonly T[], columns: readonly ExportColumn<T>[], baseName: string): void;
+export {};
+//# sourceMappingURL=export-rows.d.ts.map

package/dist/types/utils/export-rows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"export-rows.d.ts","sourceRoot":"","sources":["../../../src/utils/export-rows.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,KAAK,YAAY,GAAG,KAAK,GAAG,MAAM,CAAC;AAEnC,0EAA0E;AAC1E,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IACf,wCAAwC;IACxC,KAAK,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC;CACjE;AAsDD;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAC1B,MAAM,EAAE,YAAY,EACpB,IAAI,EAAE,SAAS,CAAC,EAAE,EAClB,OAAO,EAAE,SAAS,YAAY,CAAC,CAAC,CAAC,EAAE,EACnC,QAAQ,EAAE,MAAM,GACf,IAAI,CAMN"}

package/dist/types/utils/index.d.ts

@@ -1,4 +1,5 @@
 export * from './cn';
+export * from './export-rows';
 export * from './viewport';
 export * from './withDefaults';
 //# sourceMappingURL=index.d.ts.map

package/dist/types/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,MAAM,CAAC;AACrB,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/index.ts"],"names":[],"mappings":"AAAA,cAAc,MAAM,CAAC;AACrB,cAAc,eAAe,CAAC;AAC9B,cAAc,YAAY,CAAC;AAC3B,cAAc,gBAAgB,CAAC"}

package/dist/utils.js

@@ -11,11 +11,61 @@ import {
   withDefaults
 } from "./chunk-Y2JYDXL7.js";
 import "./chunk-PZ5AY32C.js";
+
+// src/utils/export-rows.ts
+function escapeCsvCell(value) {
+  if (/[",\n\r]/.test(value)) {
+    return `"${value.replace(/"/g, '""')}"`;
+  }
+  return value;
+}
+function toCsv(rows, columns) {
+  const head = columns.map((column) => escapeCsvCell(column.header)).join(",");
+  const body = rows.map(
+    (row) => columns.map((column) => {
+      const cell = column.value(row);
+      return escapeCsvCell(cell == null ? "" : String(cell));
+    }).join(",")
+  ).join("\n");
+  return `${head}
+${body}`;
+}
+function toJson(rows, columns) {
+  const records = rows.map((row) => {
+    const record = {};
+    for (const column of columns) {
+      const cell = column.value(row);
+      record[column.header] = cell == null ? null : cell;
+    }
+    return record;
+  });
+  return JSON.stringify(records, null, 2);
+}
+function triggerDownload(content, filename, mimeType) {
+  if (typeof window === "undefined") return;
+  const blob = new Blob([content], { type: mimeType });
+  const url = URL.createObjectURL(blob);
+  const anchor = document.createElement("a");
+  anchor.href = url;
+  anchor.download = filename;
+  document.body.appendChild(anchor);
+  anchor.click();
+  anchor.remove();
+  URL.revokeObjectURL(url);
+}
+function exportRows(format, rows, columns, baseName) {
+  if (format === "json") {
+    triggerDownload(toJson(rows, columns), `${baseName}.json`, "application/json");
+    return;
+  }
+  triggerDownload(toCsv(rows, columns), `${baseName}.csv`, "text/csv;charset=utf-8");
+}
 export {
   DYNAMIC_VIEWPORT_HEIGHT,
   VIEWPORT_HEIGHT_FALLBACK,
   cn,
   dynamicViewportHeight,
+  exportRows,
   safeAreaBottom,
   withDefaults
 };

package/dist/utils.js.map

@@ -1 +1 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}
+{"version":3,"sources":["../src/utils/export-rows.ts"],"sourcesContent":["/**\n * Serialise rows and hand the browser a download.\n *\n * The companion of the grid's Export control, which emits a REQUEST and leaves\n * the producing to the host — this is the producing half, for the common case\n * where the host already has the rows and only needs a file out of them.\n *\n * Dependency-free on purpose: \"Excel\" is emitted as CSV, which Excel opens\n * natively. A spreadsheet library would add ~700KB to a bundle for column\n * widths nobody asked for, and the one thing a real `.xlsx` buys — types that\n * survive the round trip — is not something a CSV export of an admin list is\n * being asked for.\n */\n\ntype ExportFormat = 'csv' | 'json';\n\n/** One column of the exported file: its header, and how to read a row. */\nexport interface ExportColumn<T> {\n  /** Column header, used as the CSV column and the JSON key. */\n  header: string;\n  /** Extract the cell value for a row. */\n  value: (row: T) => string | number | boolean | null | undefined;\n}\n\nfunction escapeCsvCell(value: string): string {\n  // Quote when the cell contains a comma, a quote or a newline; double any\n  // embedded quote. Without this a name with a comma silently shifts every\n  // column after it by one, which reads as corrupt data rather than as a bug.\n  if (/[\",\\n\\r]/.test(value)) {\n    return `\"${value.replace(/\"/g, '\"\"')}\"`;\n  }\n  return value;\n}\n\nfunction toCsv<T>(rows: readonly T[], columns: readonly ExportColumn<T>[]): string {\n  const head = columns.map((column) => escapeCsvCell(column.header)).join(',');\n  const body = rows\n    .map((row) =>\n      columns\n        .map((column) => {\n          const cell = column.value(row);\n          return escapeCsvCell(cell == null ? '' : String(cell));\n        })\n        .join(','),\n    )\n    .join('\\n');\n  return `${head}\\n${body}`;\n}\n\nfunction toJson<T>(rows: readonly T[], columns: readonly ExportColumn<T>[]): string {\n  const records = rows.map((row) => {\n    const record: Record<string, string | number | boolean | null> = {};\n    for (const column of columns) {\n      const cell = column.value(row);\n      record[column.header] = cell == null ? null : (cell as string | number | boolean);\n    }\n    return record;\n  });\n  return JSON.stringify(records, null, 2);\n}\n\nfunction triggerDownload(content: string, filename: string, mimeType: string): void {\n  // A no-op without a document, so a module that imports this can still be\n  // loaded by a test runner or a server render without guarding the import.\n  if (typeof window === 'undefined') return;\n  const blob = new Blob([content], { type: mimeType });\n  const url = URL.createObjectURL(blob);\n  const anchor = document.createElement('a');\n  anchor.href = url;\n  anchor.download = filename;\n  document.body.appendChild(anchor);\n  anchor.click();\n  anchor.remove();\n  URL.revokeObjectURL(url);\n}\n\n/**\n * Serialise `rows` using `columns` and download them as `<baseName>.<ext>`.\n *\n * @param format - `csv` (also what the Excel option produces) or `json`.\n * @param baseName - File name without extension; the consumer's word for the\n *   collection, so it is never derived from a type name here.\n */\nexport function exportRows<T>(\n  format: ExportFormat,\n  rows: readonly T[],\n  columns: readonly ExportColumn<T>[],\n  baseName: string,\n): void {\n  if (format === 'json') {\n    triggerDownload(toJson(rows, columns), `${baseName}.json`, 'application/json');\n    return;\n  }\n  triggerDownload(toCsv(rows, columns), `${baseName}.csv`, 'text/csv;charset=utf-8');\n}\n"],"mappings":";;;;;;;;;;;;;;;AAwBA,SAAS,cAAc,OAAuB;AAI5C,MAAI,WAAW,KAAK,KAAK,GAAG;AAC1B,WAAO,IAAI,MAAM,QAAQ,MAAM,IAAI,CAAC;AAAA,EACtC;AACA,SAAO;AACT;AAEA,SAAS,MAAS,MAAoB,SAA6C;AACjF,QAAM,OAAO,QAAQ,IAAI,CAAC,WAAW,cAAc,OAAO,MAAM,CAAC,EAAE,KAAK,GAAG;AAC3E,QAAM,OAAO,KACV;AAAA,IAAI,CAAC,QACJ,QACG,IAAI,CAAC,WAAW;AACf,YAAM,OAAO,OAAO,MAAM,GAAG;AAC7B,aAAO,cAAc,QAAQ,OAAO,KAAK,OAAO,IAAI,CAAC;AAAA,IACvD,CAAC,EACA,KAAK,GAAG;AAAA,EACb,EACC,KAAK,IAAI;AACZ,SAAO,GAAG,IAAI;AAAA,EAAK,IAAI;AACzB;AAEA,SAAS,OAAU,MAAoB,SAA6C;AAClF,QAAM,UAAU,KAAK,IAAI,CAAC,QAAQ;AAChC,UAAM,SAA2D,CAAC;AAClE,eAAW,UAAU,SAAS;AAC5B,YAAM,OAAO,OAAO,MAAM,GAAG;AAC7B,aAAO,OAAO,MAAM,IAAI,QAAQ,OAAO,OAAQ;AAAA,IACjD;AACA,WAAO;AAAA,EACT,CAAC;AACD,SAAO,KAAK,UAAU,SAAS,MAAM,CAAC;AACxC;AAEA,SAAS,gBAAgB,SAAiB,UAAkB,UAAwB;AAGlF,MAAI,OAAO,WAAW,YAAa;AACnC,QAAM,OAAO,IAAI,KAAK,CAAC,OAAO,GAAG,EAAE,MAAM,SAAS,CAAC;AACnD,QAAM,MAAM,IAAI,gBAAgB,IAAI;AACpC,QAAM,SAAS,SAAS,cAAc,GAAG;AACzC,SAAO,OAAO;AACd,SAAO,WAAW;AAClB,WAAS,KAAK,YAAY,MAAM;AAChC,SAAO,MAAM;AACb,SAAO,OAAO;AACd,MAAI,gBAAgB,GAAG;AACzB;AASO,SAAS,WACd,QACA,MACA,SACA,UACM;AACN,MAAI,WAAW,QAAQ;AACrB,oBAAgB,OAAO,MAAM,OAAO,GAAG,GAAG,QAAQ,SAAS,kBAAkB;AAC7E;AAAA,EACF;AACA,kBAAgB,MAAM,MAAM,OAAO,GAAG,GAAG,QAAQ,QAAQ,wBAAwB;AACnF;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/ui",
-  "version": "6.0.2",
+  "version": "6.2.0",
   "license": "MIT",
   "packageManager": "pnpm@9.0.0",
   "type": "module",
@@ -532,6 +532,10 @@
     "./utility/WorkflowStep": {
       "types": "./dist/types/components/utility/WorkflowStep/index.d.ts",
       "default": "./dist/utility/WorkflowStep.js"
+    },
+    "./data-display/CardKit": {
+      "types": "./dist/types/components/data-display/CardKit/index.d.ts",
+      "default": "./dist/data-display/CardKit.js"
     }
   },
   "typesVersions": {
@@ -592,7 +596,7 @@
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@12-apps/forms-core": "^1.19.2",
+    "@12-apps/forms-core": "^1.20.0",
     "@emotion/react": "^11.14.0",
     "@emotion/styled": "^11.14.0",
     "@monaco-editor/react": "^4.7.0",
@@ -607,8 +611,8 @@
     "recharts": "^3.5.1"
   },
   "devDependencies": {
-    "@12-apps/eslint-config": "^1.21.0",
-    "@12-apps/typescript-config": "^1.20.0",
+    "@12-apps/eslint-config": "^1.21.1",
+    "@12-apps/typescript-config": "^1.20.1",
     "@playwright/test": "^1.55.0",
     "@storybook/addon-docs": "^9.1.10",
     "@storybook/addon-links": "^9.1.10",

package/src/components/data-display/CardKit/CardKebab.tsx

@@ -0,0 +1,43 @@
+'use client';
+
+import type { JSX } from 'react';
+
+import { Button } from '../../form/Button';
+import { DropdownMenu, type DropdownMenuItem } from '../../navigation/DropdownMenu';
+
+/**
+ * The "⋮" trigger every row and card menu opens from.
+ *
+ * One component rather than a `DropdownMenu` per entity, so the kebab looks and
+ * behaves identically in the card, in the list row and in the table row. The
+ * entity's menu owns its own popups; this is the trigger and the item list.
+ */
+export function CardKebab({
+  items,
+  menuLabel,
+  dataTestId,
+}: {
+  items: DropdownMenuItem[];
+  /**
+   * The trigger's accessible name — required, and with no default.
+   *
+   * It is the only text this component renders, and a screen reader announces
+   * it verbatim. A default here would be a word in the origin's language that
+   * reads as finished to the next adopter right up until somebody using a
+   * screen reader meets it.
+   */
+  menuLabel: string;
+  dataTestId?: string;
+}): JSX.Element {
+  return (
+    <DropdownMenu
+      size="sm"
+      items={items}
+      trigger={
+        <Button variant="text" size="sm" aria-label={menuLabel} dataTestId={dataTestId}>
+          ⋮
+        </Button>
+      }
+    />
+  );
+}

package/src/components/data-display/CardKit/CardKit.md

@@ -0,0 +1,87 @@
+# CardKit
+
+The furniture an admin list's cards and row menus sit in.
+
+`BaseCard` and `BaseListCard` deliberately say nothing about what goes inside
+them: the envelope is the library's and the design is the consumer's. That is
+right for a card component and exactly the wrong place for every entity in an
+admin app to invent its own kebab, its own two-column body, its own label/value
+pair and its own confirm-before-deleting. Those are not per-entity decisions —
+they are the same shape repeated — so they live here once.
+
+**The line this kit does not cross** is the entity card itself. A "product card"
+or a "discount card" knows a domain, and a domain is the consumer's.
+
+## What is in it
+
+| Export | What it is |
+|---|---|
+| `CardKebab` | The `⋮` trigger every row and card menu opens from |
+| `rowActionsToMenuItems` | One `RowAction[]` → the kebab's items, so a grid and a card cannot drift |
+| `CardActionsProvider` / `useCardActions` | The tenant, the refresh and one shared error snackbar |
+| `DetailColumns` `Fact` `Ledger` `BodyHeading` `TagList` | The expanded list-card body's repeated shapes |
+| `useRowConfirm` | Confirm a grid SELECTION before a destructive write |
+| `useRemoveConfirm` | Confirm a single row from a self-contained menu |
+| `KindCardProps` / `KindListCardProps` | The `renderCard` / `renderListRow` contracts, named |
+
+## Every sentence is yours
+
+Three props exist only because a default would have been someone else's
+language shipped as a finished-looking silence:
+
+- `CardKebab`'s **`menuLabel`** — the trigger's accessible name, announced
+  verbatim by a screen reader.
+- `CardActionsProvider`'s **`errorTitle`** — the one sentence the provider
+  renders on its own. The message beside it comes from whatever failed.
+- Both hooks' **`confirmText`** — the verb. `ConfirmOptions` already refuses to
+  default one, for the same reason: a confirm button reading "OK" tells the
+  operator nothing about what is about to happen.
+
+## Which confirm hook
+
+They differ by the surface they serve, not by what they do.
+
+**`useRowConfirm`** is for a grid whose actions are declared as `RowAction[]`
+and act on a **selection**. The popup is described from that selection, because
+the per-row kebab entry and the multi-select menu run the same handler —
+"Delete the category Drinks?" and "Delete 4 categories?" are one question asked
+of a different-sized selection, and an operator who multi-selected by mistake is
+exactly who the popup is for. The selection is held while the popup is open, so
+the write sees the rows the operator was looking at when they were asked; the
+list can refresh underneath an open dialog, and re-reading the live selection at
+confirm time is the bug this shape avoids. An empty selection opens nothing.
+
+**`useRemoveConfirm`** is for a self-contained menu already inside a
+`CardActionsProvider`. It reads the refresh and the error channel from context
+and answers the `{ ok, error }` envelope those actions use.
+
+Both close the three gaps a hand-rolled version keeps re-opening:
+
+1. the write leaves **only** on confirm;
+2. a refusal is surfaced **twice** — inside the popup, where the operator is
+   still deciding, and in the shared snackbar behind it, which is what remains
+   once they dismiss it;
+3. a failed attempt leaves the popup **open** to be retried, instead of
+   vanishing over a delete that never happened.
+
+## `useCardActions` throws outside its provider
+
+Deliberately, rather than answering a null object. A menu whose `onRefresh`
+silently did nothing would leave the operator looking at a stale row after a
+delete that worked — which reads as the delete having failed. Failing at mount
+says where the provider is missing.
+
+## The context is small on purpose
+
+It is **not** an edit-dialog host. A menu that read its dialogs from here would
+stop being portable, because the set of dialogs is per-entity. What it may read
+is three facts: the tenant it acts inside, what to do after a write lands, and
+where to put a failure.
+
+## See also
+
+- `exportRows` (`@12-apps/ui/utils`) — the producing half of the grid's Export
+  control, for the common case where the host already has the rows.
+- `useServerDataViews` (`@12-apps/app-shell/react`) — the router half of
+  `DataViewServer`. It lives there rather than here because it needs a router,
+  and a design system should not.

package/src/components/data-display/CardKit/CardKit.types.ts

@@ -0,0 +1,60 @@
+import type { ReactNode } from 'react';
+
+import type { CardAspectRatio, DataViewCardSelection } from '../DataViews';
+
+/**
+ * THE CARD KIT — what an admin list needs above `BaseCard`, and no more.
+ *
+ * `BaseCard` and `BaseListCard` deliberately say nothing about what goes inside
+ * them: the envelope is the library's and the design is the consumer's. That is
+ * the right call for a card component and exactly the wrong place for every
+ * entity in an admin app to invent its own kebab, its own two-column body, its
+ * own label/value pair and its own confirm-before-deleting. Those shapes are
+ * not per-entity decisions — they are the same shape repeated — so they live
+ * here once.
+ *
+ * The line this kit does NOT cross is the entity card itself. A "product card"
+ * or a "discount card" knows a domain, and a domain is the consumer's. What is
+ * here is the furniture such a card sits in.
+ */
+
+/**
+ * Props every KIND CARD receives — the grid's `renderCard` contract, named.
+ *
+ * `row` is `Record<string, unknown>` rather than a generic on purpose: a grid
+ * renders rows of one shape and the renderer is registered per kind, so the
+ * cast happens once inside each card rather than threading a type parameter
+ * through the grid, the layout and the selection.
+ */
+export interface KindCardProps {
+  row: Record<string, unknown>;
+  selection: DataViewCardSelection;
+  /** Force a ratio (a uniform grid); defaults to the card's own. */
+  aspectRatio?: CardAspectRatio;
+}
+
+/**
+ * Props every kind LIST card receives — the "list" layout's counterpart.
+ *
+ * The same `(row, selection)` pair `renderListRow` hands over, and nothing
+ * more. No density: a row inside a list group takes the group's, so a card
+ * accepting one could only contradict its list. No `aspectRatio`: a full-width
+ * row has no ratio to force.
+ */
+export interface KindListCardProps {
+  row: Record<string, unknown>;
+  selection: DataViewCardSelection;
+}
+
+/** One labelled fact inside an expanded body. */
+export interface CardFactProps {
+  label: string;
+  value: ReactNode;
+}
+
+/** One line of a money ledger. `info` tints a line that is not a plain cost. */
+export interface CardLedgerLine {
+  label: string;
+  value: ReactNode;
+  tone?: 'default' | 'info';
+}

package/src/components/data-display/CardKit/card-actions-context.tsx

@@ -0,0 +1,98 @@
+'use client';
+
+import { createContext, useCallback, useContext, useState, type JSX, type ReactNode } from 'react';
+
+import { Snackbar } from '@mui/material';
+
+import { Alert } from '../Alert';
+
+/**
+ * The ambient wiring a self-contained row/card menu needs, and nothing else.
+ *
+ * A menu that owns its own popups still needs three things it cannot know: the
+ * tenant it is acting inside, what to do after a write lands, and somewhere to
+ * put a failure. Passing those down through the grid, the layout and the card
+ * is four props of drilling per entity; holding them in context is one.
+ *
+ * Kept deliberately SMALL — it is not an edit-dialog host. A menu that read its
+ * dialogs from here would stop being portable, because the set of dialogs is
+ * per-entity. What it may read is the three facts below.
+ *
+ * The provider renders ONE shared error snackbar, which is the whole reason the
+ * error channel is here rather than per-menu: before it, every page carried its
+ * own error alert and every menu had to find its page's.
+ */
+interface CardActionsValue {
+  /** The tenant every action in this subtree acts inside. */
+  tenantSlug: string;
+  /** Re-read the list after a write. */
+  onRefresh: () => void;
+  /** Surface a failed action's message (the shared snackbar). */
+  notifyError: (message: string) => void;
+}
+
+const CardActionsContext = createContext<CardActionsValue | null>(null);
+
+export function CardActionsProvider({
+  tenantSlug,
+  onRefresh,
+  errorTitle,
+  autoHideMs = 6_000,
+  children,
+}: {
+  tenantSlug: string;
+  onRefresh: () => void;
+  /**
+   * The snackbar's heading — required, no default.
+   *
+   * It is the one sentence this provider renders on its own, and a default
+   * would be the origin's language shipped as a finished-looking silence. The
+   * MESSAGE beside it comes from whatever failed, which is already the host's.
+   */
+  errorTitle: string;
+  /** How long the snackbar stays up. */
+  autoHideMs?: number;
+  children: ReactNode;
+}): JSX.Element {
+  const [error, setError] = useState<string | null>(null);
+  const notifyError = useCallback((message: string) => setError(message), []);
+
+  return (
+    <CardActionsContext.Provider value={{ tenantSlug, onRefresh, notifyError }}>
+      {children}
+      <Snackbar
+        open={error !== null}
+        autoHideDuration={autoHideMs}
+        onClose={() => setError(null)}
+        anchorOrigin={{ vertical: 'bottom', horizontal: 'center' }}
+      >
+        <span>
+          <Alert
+            variant="danger"
+            title={errorTitle}
+            description={error ?? ''}
+            closable
+            onClose={() => setError(null)}
+            data-testid="card-action-error"
+          />
+        </span>
+      </Snackbar>
+    </CardActionsContext.Provider>
+  );
+}
+
+/**
+ * Read the tenant + refresh + error wiring.
+ *
+ * THROWS outside a provider rather than answering a null object, deliberately:
+ * a menu whose `onRefresh` silently did nothing would leave the operator
+ * looking at a stale row after a delete that worked, which reads as the delete
+ * having failed. Failing at mount says where the provider is missing.
+ */
+export function useCardActions(): CardActionsValue {
+  const value = useContext(CardActionsContext);
+  if (!value) {
+    throw new Error('useCardActions must be used within a CardActionsProvider');
+  }
+  return value;
+}

package/src/components/data-display/CardKit/index.ts

@@ -0,0 +1,19 @@
+/**
+ * `@12-apps/ui/data-display/CardKit` — the furniture an admin list's cards and
+ * row menus sit in.
+ *
+ * See `./CardKit.types` for where the line falls: the envelope and the repeated
+ * shapes are here; the entity card that knows a domain is the consumer's.
+ */
+export { CardKebab } from './CardKebab';
+export { CardActionsProvider, useCardActions } from './card-actions-context';
+export { rowActionsToMenuItems } from './row-actions-to-menu';
+export { BodyHeading, DetailColumns, Fact, Ledger, TagList } from './list-card-parts';
+export { useRowConfirm, type RowConfirm, type RowConfirmCopy } from './use-row-confirm';
+export { useRemoveConfirm, type CardWriteResult } from './use-remove-confirm';
+export type {
+  CardFactProps,
+  CardLedgerLine,
+  KindCardProps,
+  KindListCardProps,
+} from './CardKit.types';