@12-apps/ui 1.5.2 → 1.6.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/ui",
-  "version": "1.5.2",
+  "version": "1.6.1",
   "license": "MIT",
   "packageManager": "pnpm@9.0.0",
   "type": "module",
@@ -194,7 +194,7 @@
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@12-apps/forms-core": "^1.4.3",
+    "@12-apps/forms-core": "^1.5.1",
     "@emotion/react": "^11.14.0",
     "@emotion/styled": "^11.14.0",
     "@monaco-editor/react": "^4.7.0",
@@ -209,8 +209,8 @@
     "recharts": "^3.5.1"
   },
   "devDependencies": {
-    "@12-apps/eslint-config": "^1.5.3",
-    "@12-apps/typescript-config": "^1.5.3",
+    "@12-apps/eslint-config": "^1.6.1",
+    "@12-apps/typescript-config": "^1.6.1",
     "@playwright/test": "^1.55.0",
     "@storybook/addon-docs": "^9.1.10",
     "@storybook/addon-links": "^9.1.10",

package/src/components/data-display/DataViews/DataViewsBoard.tsx

@@ -0,0 +1,327 @@
+"use client";
+
+import { Box } from "../../../mui/Box";
+import { Text } from "../../typography/Text";
+
+import type { DataViewCardSelection } from "./data-views-types";
+
+/**
+ * One column of the board — a single value of the grouping field, with the label
+ * to print above it.
+ *
+ * `tone` is an opaque palette hint (e.g. `"success"`, `"error"`) the host picks
+ * from its own state machine; the board only uses it to colour the column's
+ * header accent, so an unknown tone degrades to the default rather than throwing.
+ */
+export interface BoardGroup {
+  value: string;
+  label: string;
+  tone?: string;
+}
+
+/**
+ * The BOARD layout's configuration: the same page the table rendered, laid out
+ * as columns of the entity's own card.
+ *
+ * The board earns its place when a page's buckets are STATES IN A STATE MACHINE
+ * rather than arbitrary groupings — payments are exactly that shape. Derive
+ * `groups` and the table's `scopes` from ONE state-machine definition: two
+ * hand-maintained lists of the same states will drift, and the drift shows up as
+ * a column the tabs do not have.
+ */
+export interface BoardConfig<T extends Record<string, unknown>> {
+  /** The row field whose value places a card in a column. */
+  groupBy: keyof T & string;
+  /** The columns, in DELIBERATE reading order — the board renders this order. */
+  groups: BoardGroup[];
+  /** Optional numeric row field summed per column (e.g. the amount in cents). */
+  sumBy?: keyof T & string;
+  /**
+   * Formats a column's total. The PAGE's own formatter, so the board prints
+   * money in the store's currency instead of inventing a second convention.
+   * Omitted ⇒ the raw sum.
+   */
+  formatSum?: (total: number) => string;
+  /** Header for the column collecting rows in states the front end does not declare. */
+  extraLabel?: string;
+}
+
+/** The default header for the catch-all column (see {@link groupRows}). */
+const DEFAULT_EXTRA_LABEL = "Sem etapa";
+
+/** One resolved column: a declared group (or the catch-all) plus its loaded rows. */
+interface ResolvedColumn<T> {
+  key: string;
+  label: string;
+  tone?: string;
+  rows: T[];
+}
+
+/** Read the grouping value off a row as a string (`null`/`undefined` ⇒ ""). */
+function groupValueOf<T extends Record<string, unknown>>(row: T, groupBy: string): string {
+  const value = row[groupBy];
+  return value === null || value === undefined ? "" : String(value);
+}
+
+/**
+ * Place every loaded row into a column, in the DECLARED order, and collect the
+ * leftovers into one extra column at the end.
+ *
+ * Nothing is ever dropped, and that is the point: a state added to the back end
+ * before the front end knows about it must not make rows disappear. On a
+ * payments board, a silently dropped row is money nobody can see. The extra
+ * column only exists when something landed in it — once every row is placed it
+ * is gone, so the common case shows exactly the declared columns.
+ *
+ * A declared group with no rows KEEPS its position: the order is a reading
+ * order chosen by the host, not a ranking derived from the data.
+ */
+export function groupRows<T extends Record<string, unknown>>(
+  rows: T[],
+  board: BoardConfig<T>,
+): ResolvedColumn<T>[] {
+  const declared = new Map<string, T[]>(board.groups.map((group) => [group.value, []]));
+  const extra: T[] = [];
+  for (const row of rows) {
+    const bucket = declared.get(groupValueOf(row, board.groupBy));
+    if (bucket) bucket.push(row);
+    else extra.push(row);
+  }
+  const columns: ResolvedColumn<T>[] = board.groups.map((group) => ({
+    key: group.value,
+    label: group.label,
+    tone: group.tone,
+    rows: declared.get(group.value) ?? [],
+  }));
+  if (extra.length > 0) {
+    columns.push({ key: "__extra__", label: board.extraLabel ?? DEFAULT_EXTRA_LABEL, rows: extra });
+  }
+  return columns;
+}
+
+/** A column's total over the rows ON THIS PAGE, or null when nothing is summed. */
+function sumOf<T extends Record<string, unknown>>(rows: T[], sumBy: string | undefined): number | null {
+  if (!sumBy) return null;
+  return rows.reduce((total, row) => {
+    const value = row[sumBy];
+    return typeof value === "number" && Number.isFinite(value) ? total + value : total;
+  }, 0);
+}
+
+/** Map a `tone` hint onto a theme colour, defaulting for anything unrecognised. */
+function toneColor(tone: string | undefined): string {
+  const known = ["primary", "secondary", "success", "warning", "error", "info"];
+  return tone && known.includes(tone) ? `${tone}.main` : "divider";
+}
+
+/**
+ * A column's heading: the label, the page count and the optional sum.
+ *
+ * The count is labelled "nesta página" EVERYWHERE it appears, including in its
+ * accessible name. The scope tabs above the board show whole-query totals from
+ * the server; an unlabelled column count would contradict them the moment there
+ * is a second page, and the reader has no way to tell which number to believe.
+ */
+function BoardColumnHeader({
+  label,
+  count,
+  sum,
+  testId,
+}: {
+  label: string;
+  count: number;
+  /** The formatted total, or null when the board sums nothing. */
+  sum: string | null;
+  testId: string;
+}): React.JSX.Element {
+  return (
+    <Box sx={{ display: "flex", flexDirection: "column", gap: 0.25 }}>
+      <Box sx={{ display: "flex", alignItems: "baseline", justifyContent: "space-between", gap: 1 }}>
+        <Text variant="caption" as="span">
+          <Box component="span" sx={{ fontWeight: 600 }}>
+            {label}
+          </Box>
+        </Text>
+        <Text variant="caption" as="span">
+          <Box
+            component="span"
+            data-testid={`${testId}-count`}
+            aria-label={`${label}: ${count} nesta página`}
+            sx={{ color: "text.secondary", whiteSpace: "nowrap" }}
+          >
+            {count} nesta página
+          </Box>
+        </Text>
+      </Box>
+      {sum !== null && (
+        <Text variant="caption" as="span">
+          <Box
+            component="span"
+            data-testid={`${testId}-sum`}
+            aria-label={`Soma desta página: ${sum}`}
+            sx={{ color: "text.secondary" }}
+          >
+            {sum}
+          </Box>
+        </Text>
+      )}
+    </Box>
+  );
+}
+
+interface BoardColumnProps<T extends Record<string, unknown>> {
+  column: ResolvedColumn<T>;
+  board: BoardConfig<T>;
+  getRowId: (row: T) => string | number;
+  renderCard: (row: T, selection: DataViewCardSelection) => React.ReactNode;
+  selectedIds: Set<string | number>;
+  onToggleId: (id: string | number) => void;
+  cardScale: number;
+  width: number;
+  testId: string;
+}
+
+/** One column: its header over a vertical stack of the entity's own cards. */
+function BoardColumn<T extends Record<string, unknown>>({
+  column,
+  board,
+  getRowId,
+  renderCard,
+  selectedIds,
+  onToggleId,
+  cardScale,
+  width,
+  testId,
+}: BoardColumnProps<T>): React.JSX.Element {
+  const total = sumOf(column.rows, board.sumBy);
+  return (
+    <Box
+      data-testid={testId}
+      sx={{
+        flex: `0 0 ${width}px`,
+        minWidth: width,
+        display: "flex",
+        flexDirection: "column",
+        gap: 1,
+        borderTop: 3,
+        borderStyle: "solid",
+        borderColor: toneColor(column.tone),
+        borderRadius: 1,
+        bgcolor: "action.hover",
+        p: 1,
+      }}
+    >
+      <BoardColumnHeader
+        label={column.label}
+        count={column.rows.length}
+        sum={total === null ? null : String(board.formatSum ? board.formatSum(total) : total)}
+        testId={testId}
+      />
+      {column.rows.length === 0 ? (
+        <Text variant="caption" as="p">
+          <Box component="span" data-testid={`${testId}-empty`} sx={{ color: "text.disabled" }}>
+            Nada nesta etapa
+          </Box>
+        </Text>
+      ) : (
+        column.rows.map((row) => {
+          const id = getRowId(row);
+          return (
+            <Box key={id}>
+              {renderCard(row, {
+                selected: selectedIds.has(id),
+                onToggleSelect: () => onToggleId(id),
+                scale: cardScale,
+              })}
+            </Box>
+          );
+        })
+      )}
+    </Box>
+  );
+}
+
+interface DataViewsBoardProps<T extends Record<string, unknown>> {
+  /** The LOADED page, verbatim. The board never filters, sorts or paginates. */
+  rows: T[];
+  board: BoardConfig<T>;
+  getRowId: (row: T) => string | number;
+  renderCard: (row: T, selection: DataViewCardSelection) => React.ReactNode;
+  selectedIds: Set<string | number>;
+  onToggleId: (id: string | number) => void;
+  /** Card size multiplier from the toolbar zoom slider — the same knob as cards. */
+  cardScale: number;
+  dataTestId?: string;
+}
+
+/** The board's column width at scale 1; the zoom slider multiplies it. */
+const BASE_COLUMN_WIDTH = 240;
+/** Never narrower than this, however far the zoom is wound down (touch targets). */
+const MIN_COLUMN_WIDTH = 220;
+
+/**
+ * The BOARD layout: the loaded page distributed into columns of the entity's own
+ * card. A rendering, not a second source of truth — switching to it emits no
+ * query, and it shows exactly the rows the table showed.
+ *
+ * The board scrolls HORIZONTALLY inside its own box rather than letting the page
+ * scroll sideways, and its columns keep a usable width at every zoom, so a phone
+ * gets a real board instead of six unreadable slivers.
+ *
+ * Cards are not draggable between columns. Dragging a payment from Recusado to
+ * Pago is a domain transition with side effects, not a re-render: it needs the
+ * allowed-transition set from the state machine plus a confirmation, and
+ * `RowAction.isVisible` is the existing per-row guard to reuse when that lands.
+ */
+export function DataViewsBoard<T extends Record<string, unknown>>({
+  rows,
+  board,
+  getRowId,
+  renderCard,
+  selectedIds,
+  onToggleId,
+  cardScale,
+  dataTestId,
+}: DataViewsBoardProps<T>): React.JSX.Element {
+  const columns = groupRows(rows, board);
+  const width = Math.max(MIN_COLUMN_WIDTH, Math.round(BASE_COLUMN_WIDTH * cardScale));
+  const testId = dataTestId ? `${dataTestId}-board` : "data-views-board";
+  return (
+    <Box sx={{ mt: 1.5 }}>
+      <Text variant="caption" as="p">
+        <Box component="span" data-testid={`${testId}-scale-note`} sx={{ color: "text.secondary" }}>
+          As contagens e somas abaixo referem-se apenas aos itens desta página.
+        </Box>
+      </Text>
+      <Box
+        data-testid={testId}
+        sx={{
+          mt: 1,
+          display: "flex",
+          alignItems: "flex-start",
+          gap: 1.5,
+          // The BOARD scrolls, not the page: without `maxWidth` the flex row
+          // widens its parent and the whole document scrolls sideways.
+          maxWidth: "100%",
+          overflowX: "auto",
+          pb: 1,
+        }}
+      >
+        {columns.map((column) => (
+          <BoardColumn
+            key={column.key}
+            column={column}
+            board={board}
+            getRowId={getRowId}
+            renderCard={renderCard}
+            selectedIds={selectedIds}
+            onToggleId={onToggleId}
+            cardScale={cardScale}
+            width={width}
+            testId={`${testId}-column-${column.key}`}
+          />
+        ))}
+      </Box>
+    </Box>
+  );
+}

package/src/components/data-display/DataViews/DataViewsGrid.tsx

@@ -5,9 +5,14 @@ import { useEffect, useRef } from "react";
 import { type SortFieldDefinition } from "../../layout/ContentToolbar";
 
 import { GridShell } from "./data-views-grid-parts";
+import type { DisplayPanelView } from "./data-views-display-panel";
+import type { BoardConfig } from "./DataViewsBoard";
+import type { DataViewExport } from "./data-views-export";
+import type { ScopeConfig } from "./data-views-scopes";
 import type { DataViewCardSelection } from "./data-views-types";
 import {
   type DataViewColumn,
+  type DataViewsLayout,
   type DataViewServer,
   type DataViewState,
   type DataViewSyncState,
@@ -47,6 +52,12 @@ interface DataViewsGridProps<T extends Record<string, unknown>> {
   onVisibleRowsChange?: (rows: T[]) => void;
   /** Saved-views UI injected into the toolbar (FUT-89). */
   toolbarRightSlot?: React.ReactNode;
+  /**
+   * The saved-view chrome for the Exibir panel: its VISÃO header (with the
+   * views dropdown) and its Redefinir / Salvar visão footer. Supplied by
+   * `DataViewsTableBase`; without it the panel is tabs only.
+   */
+  displayView?: DisplayPanelView;
   /** Big page title in the header row (next to the funnel + gear). */
   title?: string;
   /** Primary page actions rendered at the header's right. */
@@ -56,6 +67,18 @@ interface DataViewsGridProps<T extends Record<string, unknown>> {
    * columns (asc/desc each) when omitted.
    */
   sortFields?: SortFieldDefinition[];
+  /**
+   * Per-sort-field VALUE KIND (`"currency" | "number" | "date" | "text"`), so the
+   * Exibir panel phrases the direction in that column's own terms. "Crescente"
+   * on a currency column is a puzzle; "Menor → maior" is not. Defaults to text.
+   */
+  sortKinds?: Record<string, string>;
+  /**
+   * Opt-in "Exportar" control. The grid hands the host the current query,
+   * UNPAGINATED, and the host re-queries — the grid never fetches, and an
+   * export therefore follows the filters rather than the loaded page.
+   */
+  exportConfig?: DataViewExport;
   /**
    * A single, reusable list of row actions that drives BOTH the per-row "⋮"
    * kebab AND the bulk-actions menu (tabwoah model). When provided, the grid
@@ -86,8 +109,36 @@ interface DataViewsGridProps<T extends Record<string, unknown>> {
    * (reusing the same search/filter/sort). Omit ⇒ table only (unchanged).
    */
   renderCard?: (row: T, selection: DataViewCardSelection) => React.ReactNode;
-  /** Which layout to show first when cards are available (default "table"). */
-  defaultLayout?: "cards" | "table";
+  /**
+   * Opt-in "Quadro" (board) layout: the loaded page laid out as columns of one
+   * grouping field. Reuses `renderCard`, so supplying a board WITHOUT one simply
+   * offers no board. Best when the groups are states in a state machine — derive
+   * these groups and `scopes` from ONE definition so the two cannot drift.
+   */
+  board?: BoardConfig<T>;
+  /**
+   * Opt-in "Lista" layout (FUT-733): one FULL-WIDTH row per record, rendered by
+   * the entity — a marker, a title, a subtitle and a value on the right. Sits
+   * between the table (compare columns) and the cards (browse); omit ⇒ not
+   * offered, exactly as `renderCard` gates the cards.
+   */
+  renderListRow?: (row: T, selection: DataViewCardSelection) => React.ReactNode;
+  /**
+   * The page-level partition rendered as an exclusive tab strip above the
+   * toolbar, with server-supplied counts. Requires `server`: a scope is applied
+   * at the backend, never in the browser.
+   */
+  scopes?: ScopeConfig[];
+  /** The row field the scopes partition by — used only to reject a pill over the same field. */
+  scopeFieldId?: string;
+  /** Which layout to show first when the user has expressed no preference (default "table"). */
+  defaultLayout?: DataViewsLayout;
+  /**
+   * Ignore the remembered cross-screen layout preference and pin to
+   * `defaultLayout`. For tables that exist to SHOW a layout — stories, docs,
+   * screenshots — not for real screens.
+   */
+  ignoreStoredLayout?: boolean;
   /**
    * Opt into the responsive inline filter UX (collapsible filter row on wide
    * screens, modal on narrow). Default `false` keeps the classic slide-in panel.
@@ -100,63 +151,17 @@ interface DataViewsGridProps<T extends Record<string, unknown>> {
 }
 
 /**
- * The reusable admin DataViews table (FUT-88): the shared ContentToolbar +
- * TableFilter panel over `@12-apps/ui` DataGrid. State + derived data live in
- * {@link useDataViewsState}; the render lives in `GridShell`. This component just
- * connects the two. Reused across every admin list page.
+ * Surface the visible (filtered) rows so a page-level Export matches the view.
+ *
+ * Pages pass inline column/field arrays, so `matched` is a fresh reference on
+ * every render even when its contents are unchanged. The guard is a signature
+ * over the rows' *contents* (not just their ids), so the callback — and the
+ * parent `useState` it usually drives — fires only when the visible data
+ * actually changes. Ids alone are not enough: a server refresh can change a
+ * visible row's values while keeping its id, and the export must reflect them.
+ * Content-equal renders keep the same signature, so this never loops.
  */
-export function DataViewsGrid<T extends Record<string, unknown>>({
-  rows,
-  columns,
-  fields,
-  rangeFields = [],
-  getRowId,
-  onRowClick,
-  emptyState,
-  dataTestId,
-  testIdPrefix = "table",
-  appliedState,
-  syncState,
-  onStateChange,
-  onVisibleRowsChange,
-  toolbarRightSlot,
-  sortFields,
-  rowActions,
-  rowActionsLeading,
-  bulkActions,
-  renderRowMenu,
-  renderCard,
-  defaultLayout,
-  inlineFilters,
-  alwaysShowSearch,
-  server,
-}: DataViewsGridProps<T>): React.JSX.Element {
-  const controller = useDataViewsState({
-    rows,
-    columns,
-    fields,
-    rangeFields,
-    getRowId,
-    onRowClick,
-    appliedState,
-    syncState,
-    onStateChange,
-    testIdPrefix,
-    sortFields,
-    rowActions,
-    rowActionsLeading,
-    renderRowMenu,
-    server,
-  });
-
-  // Surface the visible (filtered) rows so a page-level Export matches the view. Pages pass
-  // inline column/field arrays, so `matched` is a fresh reference on every render even when
-  // its contents are unchanged. Guard on a signature over the rows' *contents* (not just ids)
-  // so we only notify — and trigger the parent's setState — when the visible data actually
-  // changes. Ids alone are not enough: a server refresh can change a visible row's values
-  // while keeping its id, and the export must reflect those new values. Content-equal renders
-  // keep the same signature, so the effect + a parent `useState` never loop.
-  const { matched } = controller;
+function useVisibleRowsNotifier<T>(matched: T[], onVisibleRowsChange?: (rows: T[]) => void): void {
   const visibleSignature = JSON.stringify(matched);
   const lastSignature = useRef<string | null>(null);
   useEffect(() => {
@@ -164,24 +169,22 @@ export function DataViewsGrid<T extends Record<string, unknown>>({
     lastSignature.current = visibleSignature;
     onVisibleRowsChange?.(matched);
   }, [visibleSignature, matched, onVisibleRowsChange]);
+}
 
-  return (
-    <GridShell
-      c={controller}
-      rows={rows}
-      fields={fields}
-      rangeFields={rangeFields}
-      getRowId={getRowId}
-      testIdPrefix={testIdPrefix}
-      dataTestId={dataTestId}
-      emptyState={emptyState}
-      toolbarRightSlot={toolbarRightSlot}
-      rowActions={rowActions}
-      bulkActions={bulkActions}
-      renderCard={renderCard}
-      defaultLayout={defaultLayout}
-      inlineFilters={inlineFilters}
-      alwaysShowSearch={alwaysShowSearch}
-    />
-  );
+/**
+ * The reusable admin DataViews table (FUT-88): the shared ContentToolbar +
+ * TableFilter panel over `@12-apps/ui` DataGrid. State + derived data live in
+ * {@link useDataViewsState}; the render lives in `GridShell`. This component just
+ * connects the two. Reused across every admin list page.
+ */
+export function DataViewsGrid<T extends Record<string, unknown>>(
+  props: DataViewsGridProps<T>,
+): React.JSX.Element {
+  // Forwarded as a whole rather than restated name-by-name twice: this component
+  // only ADDS the controller, and a 25-name destructure repeated in the JSX is
+  // where a newly added prop silently stops being passed on.
+  const { rangeFields = [], testIdPrefix = "table" } = props;
+  const controller = useDataViewsState({ ...props, rangeFields, testIdPrefix });
+  useVisibleRowsNotifier(controller.matched, props.onVisibleRowsChange);
+  return <GridShell {...props} c={controller} rangeFields={rangeFields} testIdPrefix={testIdPrefix} />;
 }