@12-apps/ui 6.1.0 → 6.2.0

package/src/components/data-display/CardKit/list-card-parts.tsx

@@ -0,0 +1,163 @@
+'use client';
+
+import type { JSX, ReactNode } from 'react';
+
+import { Box } from '../../../mui/Box';
+
+import type { CardFactProps, CardLedgerLine } from './CardKit.types';
+
+/**
+ * THE SHARED FURNITURE OF AN EXPANDED LIST-CARD BODY.
+ *
+ * `BaseListCard` says nothing about what goes inside a row's expanded area — it
+ * spans the rails and stops, because the design belongs to the consumer. Right
+ * for the card; wrong as the place where every entity in an admin app invents
+ * its own two-column layout, its own label/value pair and its own ledger.
+ *
+ * So the four shapes that actually repeat live here, once. Nothing here knows a
+ * domain: they take `ReactNode` and lay it out.
+ */
+
+/** The expanded body's two-column split: detail on the left, a ledger right. */
+export function DetailColumns({ left, right }: { left: ReactNode; right: ReactNode }): JSX.Element {
+  return (
+    <Box sx={{ display: 'grid', gridTemplateColumns: { xs: '1fr', md: '1fr 1fr' }, gap: 3 }}>
+      <Box sx={{ minWidth: 0 }}>{left}</Box>
+      <Box sx={{ minWidth: 0 }}>{right}</Box>
+    </Box>
+  );
+}
+
+/**
+ * One labelled fact inside an expanded body.
+ *
+ * Horizontal, not stacked: the body is already a wide area with room for a
+ * label beside its value, and stacking them there would ape the summary rails
+ * above without their alignment.
+ */
+export function Fact({ label, value }: CardFactProps): JSX.Element {
+  return (
+    <Box sx={{ display: 'flex', justifyContent: 'space-between', gap: 2, fontSize: 13, py: 0.25 }}>
+      <Box component="span" sx={{ color: 'text.secondary', flexShrink: 0 }}>
+        {label}
+      </Box>
+      <Box component="span" sx={{ minWidth: 0, textAlign: 'right', overflowWrap: 'anywhere' }}>
+        {value}
+      </Box>
+    </Box>
+  );
+}
+
+/**
+ * A money ledger: rows of label/amount, then a ruled total.
+ *
+ * The total is separated by a RULE rather than by weight alone, because a
+ * subtotal and a total in one column with only bold between them is the classic
+ * misread — the eye lands on whichever number is larger.
+ *
+ * The figures arrive pre-formatted. This is a layout, and a component that
+ * formatted money would be choosing a locale on the consumer's behalf.
+ */
+export function Ledger({
+  lines,
+  total,
+}: {
+  lines: CardLedgerLine[];
+  total: { label: string; value: ReactNode };
+}): JSX.Element {
+  return (
+    <Box sx={{ display: 'flex', flexDirection: 'column', gap: 0.25 }}>
+      {lines.map((line) => (
+        <Box
+          key={line.label}
+          sx={{
+            display: 'flex',
+            justifyContent: 'space-between',
+            fontSize: 13,
+            color: line.tone === 'info' ? 'info.main' : 'text.secondary',
+          }}
+        >
+          <Box component="span">{line.label}</Box>
+          <Box component="span" sx={{ fontVariantNumeric: 'tabular-nums' }}>
+            {line.value}
+          </Box>
+        </Box>
+      ))}
+      <Box
+        sx={{
+          display: 'flex',
+          justifyContent: 'space-between',
+          fontWeight: 700,
+          borderTop: 1,
+          borderColor: 'divider',
+          pt: 0.5,
+          mt: 0.5,
+        }}
+      >
+        <Box component="span">{total.label}</Box>
+        <Box component="span" sx={{ fontVariantNumeric: 'tabular-nums' }}>
+          {total.value}
+        </Box>
+      </Box>
+    </Box>
+  );
+}
+
+/** A heading inside the expanded body, for a section that needs naming. */
+export function BodyHeading({ children }: { children: ReactNode }): JSX.Element {
+  return (
+    <Box
+      sx={{
+        fontSize: 11,
+        fontWeight: 700,
+        letterSpacing: 0.4,
+        textTransform: 'uppercase',
+        color: 'text.disabled',
+        mb: 0.5,
+      }}
+    >
+      {children}
+    </Box>
+  );
+}
+
+/**
+ * A wrapping run of small items — permission names, role names, target ids.
+ *
+ * The whole reason several entities earn a list card at all: a `string[]` has no
+ * honest table cell. Truncated to "3 items" it says nothing; printed in full it
+ * destroys the column. Here it simply wraps.
+ */
+export function TagList({
+  items,
+  empty,
+}: {
+  items: readonly string[];
+  /** What to show for an empty run — the consumer's sentence, no default. */
+  empty: string;
+}): JSX.Element {
+  if (items.length === 0) {
+    return <Box sx={{ fontSize: 13, color: 'text.disabled' }}>{empty}</Box>;
+  }
+  return (
+    <Box sx={{ display: 'flex', flexWrap: 'wrap', gap: 0.5 }}>
+      {items.map((item) => (
+        <Box
+          key={item}
+          component="span"
+          sx={{
+            fontSize: 12,
+            px: 0.75,
+            py: 0.25,
+            borderRadius: 1,
+            bgcolor: 'action.hover',
+            color: 'text.secondary',
+            fontFamily: 'monospace',
+          }}
+        >
+          {item}
+        </Box>
+      ))}
+    </Box>
+  );
+}

package/src/components/data-display/CardKit/row-actions-to-menu.ts

@@ -0,0 +1,29 @@
+import type { DropdownMenuItem } from '../../navigation/DropdownMenu';
+import type { RowAction } from '../DataViews';
+
+/**
+ * Adapt a list of {@link RowAction}s into single-row kebab items.
+ *
+ * Applies each action's `isVisible` guard, resolves its per-row `rowLabel`
+ * override, carries its colour, and fires `onSelect([row])` on click.
+ *
+ * The point is that ONE definition drives both surfaces. An entity that already
+ * declares its per-row actions as `RowAction[]` — because the table's multi-
+ * select menu needs them — gets the card's kebab from the same array through
+ * `renderRowMenu` / `renderCard`, with no second list to keep in step. Two
+ * lists is how a "Duplicar" that appears in the table and not on the card
+ * happens, and nothing reports it.
+ */
+export function rowActionsToMenuItems<T extends Record<string, unknown>>(
+  actions: RowAction<T>[],
+  row: T,
+): DropdownMenuItem[] {
+  return actions
+    .filter((action) => action.isVisible?.(row) ?? true)
+    .map((action) => ({
+      id: action.id,
+      label: action.rowLabel?.(row) ?? action.label,
+      color: action.color,
+      onClick: () => void action.onSelect([row]),
+    }));
+}

package/src/components/data-display/CardKit/use-remove-confirm.tsx

@@ -0,0 +1,106 @@
+'use client';
+
+import type { JSX } from 'react';
+
+import { ConfirmActionDialog, useConfirmAction } from '../../feedback/ConfirmAction';
+
+import { useCardActions } from './card-actions-context';
+
+/** The `{ ok, error }` envelope a write action answers with. */
+export interface CardWriteResult {
+  ok: boolean;
+  error?: string;
+}
+
+interface RemoveConfirmOptions {
+  /** The destructive write. Called ONLY after the operator confirms. */
+  write: () => Promise<CardWriteResult>;
+  /** The popup's question. */
+  title: string;
+  /** The row being removed, echoed into the popup so it names a thing. */
+  entityName: string;
+  /**
+   * What happens, and whether it can be walked back. Say which — the difference
+   * between a soft delete a recycle bin recovers and one nothing recovers is
+   * the whole content of the decision being asked for.
+   */
+  description: string;
+  /** The confirm button's VERB. Required, never defaulted. */
+  confirmText: string;
+  /** Used when the write fails without a message of its own. */
+  fallbackError: string;
+  dataTestId: string;
+}
+
+interface RemoveConfirm {
+  /** Hand this to the menu item's `onClick`: it opens the popup, nothing more. */
+  request: () => void;
+  /** Render alongside the trigger. */
+  dialog: JSX.Element;
+}
+
+/**
+ * The confirm-before-removing wiring every card/row menu repeats, in one place.
+ *
+ * It closes the three gaps a hand-rolled version keeps re-opening: the write
+ * leaves ONLY on confirm; a refusal is surfaced twice — inside the popup, where
+ * the operator is still deciding, and in the shared snackbar behind it — and a
+ * failed attempt leaves the popup OPEN to be retried instead of vanishing over
+ * a delete that never happened.
+ *
+ * The difference from {@link useRowConfirm} is which surface it serves: this one
+ * is for a SELF-CONTAINED menu that already sits inside a
+ * `CardActionsProvider`, so it reads the refresh and the error channel from
+ * context and answers the `{ ok, error }` envelope those actions use.
+ * `useRowConfirm` is for a grid whose actions are declared as `RowAction[]` and
+ * act on a selection.
+ *
+ * ```tsx
+ * const remove = useRemoveConfirm({
+ *   write: () => deleteCategory({ tenantSlug, id: row.id }),
+ *   title: copy.deleteTitle,
+ *   entityName: row.name,
+ *   description: copy.deleteDescription,
+ *   confirmText: copy.delete,
+ *   fallbackError: copy.deleteFailed,
+ *   dataTestId: 'category-delete-confirm',
+ * });
+ * ```
+ */
+export function useRemoveConfirm({
+  write,
+  title,
+  entityName,
+  description,
+  confirmText,
+  fallbackError,
+  dataTestId,
+}: RemoveConfirmOptions): RemoveConfirm {
+  const { onRefresh, notifyError } = useCardActions();
+
+  const state = useConfirmAction(async () => {
+    const result = await write();
+    if (!result.ok) {
+      const message = result.error ?? fallbackError;
+      notifyError(message);
+      // Rejecting is what keeps the popup open carrying `message`; the snackbar
+      // above is what remains once the operator dismisses it.
+      throw new Error(message);
+    }
+    onRefresh();
+  }, fallbackError);
+
+  return {
+    request: state.request,
+    dialog: (
+      <ConfirmActionDialog
+        state={state}
+        title={title}
+        entityName={entityName}
+        description={description}
+        confirmText={confirmText}
+        dataTestId={dataTestId}
+      />
+    ),
+  };
+}

package/src/components/data-display/CardKit/use-row-confirm.tsx

@@ -0,0 +1,91 @@
+'use client';
+
+import { useState, type JSX } from 'react';
+
+import { ConfirmActionDialog, useConfirmAction } from '../../feedback/ConfirmAction';
+
+/**
+ * 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 function useRowConfirm<T>({
+  write,
+  describe,
+  dataTestId,
+  errorText,
+}: RowConfirmOptions<T>): RowConfirm<T> {
+  const [target, setTarget] = useState<T[] | null>(null);
+
+  const state = useConfirmAction(async () => {
+    if (!target) return;
+    await write(target);
+    setTarget(null);
+  }, errorText);
+
+  const request = (rows: T[]): void => {
+    // An empty selection has nothing to confirm — asking would be a popup about
+    // nothing, and confirming it would write nothing.
+    if (rows.length === 0) return;
+    setTarget(rows);
+    state.request();
+  };
+
+  return {
+    request,
+    dialog: target ? (
+      <ConfirmActionDialog state={state} {...describe(target)} dataTestId={dataTestId} />
+    ) : null,
+  };
+}

package/src/utils/export-rows.ts

@@ -0,0 +1,95 @@
+/**
+ * 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;
+}
+
+function escapeCsvCell(value: string): string {
+  // Quote when the cell contains a comma, a quote or a newline; double any
+  // embedded quote. Without this a name with a comma silently shifts every
+  // column after it by one, which reads as corrupt data rather than as a bug.
+  if (/[",\n\r]/.test(value)) {
+    return `"${value.replace(/"/g, '""')}"`;
+  }
+  return value;
+}
+
+function toCsv<T>(rows: readonly T[], columns: readonly ExportColumn<T>[]): string {
+  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}\n${body}`;
+}
+
+function toJson<T>(rows: readonly T[], columns: readonly ExportColumn<T>[]): string {
+  const records = rows.map((row) => {
+    const record: Record<string, string | number | boolean | null> = {};
+    for (const column of columns) {
+      const cell = column.value(row);
+      record[column.header] = cell == null ? null : (cell as string | number | boolean);
+    }
+    return record;
+  });
+  return JSON.stringify(records, null, 2);
+}
+
+function triggerDownload(content: string, filename: string, mimeType: string): void {
+  // A no-op without a document, so a module that imports this can still be
+  // loaded by a test runner or a server render without guarding the import.
+  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);
+}
+
+/**
+ * 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 function exportRows<T>(
+  format: ExportFormat,
+  rows: readonly T[],
+  columns: readonly ExportColumn<T>[],
+  baseName: string,
+): void {
+  if (format === 'json') {
+    triggerDownload(toJson(rows, columns), `${baseName}.json`, 'application/json');
+    return;
+  }
+  triggerDownload(toCsv(rows, columns), `${baseName}.csv`, 'text/csv;charset=utf-8');
+}

package/src/utils/index.ts

@@ -1,3 +1,4 @@
 export * from './cn';
+export * from './export-rows';
 export * from './viewport';
 export * from './withDefaults';