@12-apps/ui 6.1.0 → 6.3.0

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@12-apps/ui",
-  "version": "6.1.0",
+  "version": "6.3.0",
   "license": "MIT",
-  "packageManager": "pnpm@9.0.0",
+  "packageManager": "pnpm@10.34.5",
   "type": "module",
   "engines": {
     "node": ">=18.0.0",
@@ -532,6 +532,18 @@
     "./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"
+    },
+    "./copy": {
+      "types": "./dist/types/copy.d.ts",
+      "default": "./dist/copy.js"
+    },
+    "./pt-BR": {
+      "types": "./dist/types/pt-BR.d.ts",
+      "default": "./dist/pt-BR.js"
     }
   },
   "typesVersions": {

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';

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,111 @@
+'use client';
+
+import type { ConfirmActionCopy } from "../../../copy";
+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;
+  /** The dialog's own words. REQUIRED — this package ships no default copy. */
+  copy: ConfirmActionCopy;
+  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,
+  copy,
+}: 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}
+        copy={copy}
+        title={title}
+        entityName={entityName}
+        description={description}
+        confirmText={confirmText}
+        dataTestId={dataTestId}
+      />
+    ),
+  };
+}