@12-apps/ui 1.6.3 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/ui",
-  "version": "1.6.3",
+  "version": "1.8.0",
   "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.5.3",
+    "@12-apps/forms-core": "^1.7.0",
     "@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.6.3",
-    "@12-apps/typescript-config": "^1.6.3",
+    "@12-apps/eslint-config": "^1.0.1",
+    "@12-apps/typescript-config": "^1.0.2",
     "@playwright/test": "^1.55.0",
     "@storybook/addon-docs": "^9.1.10",
     "@storybook/addon-links": "^9.1.10",

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

@@ -83,7 +83,7 @@ export interface DataViewsTableBaseProps<T extends Record<string, unknown>> {
   board?: BoardConfig<T>;
   /** Opt-in "Lista" layout — one full-width, entity-rendered row per record (FUT-733). */
   renderListRow?: (row: T, selection: DataViewCardSelection) => React.ReactNode;
-  /** The page-level partition rendered as tabs above the toolbar (server mode only). */
+  /** The page-level partition rendered as tabs under the toolbar (server mode only). */
   scopes?: ScopeConfig[];
   /** The row field the scopes partition by — used only to reject a pill over the same field. */
   scopeFieldId?: string;

package/src/components/data-display/DataViews/RESPONSIVE-BEHAVIOUR.md

@@ -0,0 +1,183 @@
+# The DataViews toolbar, at every width
+
+The toolbar degrades through a **measured ladder**, not breakpoints. Nothing in
+`data-views-overflow.ts` reads a media query: a `ResizeObserver` reports the
+toolbar row's width, every control is priced, and the ladder sheds one rung at a
+time until the row fits.
+
+That is deliberate and worth restating, because it is what makes this document
+approximate. Pages declare different numbers of filters with different label
+lengths, and the same page collapses at a different width in another language. A
+shared breakpoint is wrong for at least one table by construction.
+
+**So the widths below are the ones the tests pin, not thresholds in the code.**
+They are named for the device class they stand in for, and the behaviour column
+is what the six-control Pedidos table does there. A two-filter table degrades
+later; an eight-filter one degrades sooner. Both are correct.
+
+| class | width | stands for |
+| --- | --- | --- |
+| small mobile | 320 | iPhone SE, the floor we support |
+| large mobile | 430 | iPhone Pro Max |
+| tablet | 768 | iPad portrait |
+| small desktop | 1280 | laptop |
+| large desktop | 1600 | external monitor |
+
+**These are toolbar ROW widths, not viewport widths.** The `ResizeObserver`
+watches the row, and the row is narrower than the window by whatever the page
+puts around it — around 48px in the Pedidos shell. So a 430px row is roughly a
+478px phone, and the same page at a 430px *viewport* sits one rung further down
+than this table shows. The tests drive the row directly, which is the only
+number the ladder ever sees.
+
+---
+
+## The one rule that outranks the rest
+
+**The toolbar is one line and never scrolls sideways.** Not the row, not the
+filter cluster, not the "Mais" panel, not the document. At any width, with any
+combination of filters applied, with the search open or closed.
+
+Everything below exists to keep that true. When a change breaks it, the fix is
+another rung on the ladder — never a scrollbar, and never letting controls paint
+outside the toolbar.
+
+---
+
+## The ladder
+
+Cheapest loss first. Each rung is taken only if the one before it did not free
+enough room.
+
+| # | rung | flag | what goes |
+| --- | --- | --- | --- |
+| 1 | filter controls move into "Mais" | `inline` / `overflow` | one control at a time, idle ones first |
+| 2 | Exibir / Exportar drop their labels | `compactControls` | the text, and the dropdown chevron with it |
+| 3 | the search box shrinks | — | none; it is `flex: 1` and CSS does it |
+| 4 | the search collapses to a magnifier | `searchCollapsed` | the box |
+| 5 | the "N de N" counter is dropped | `counterHidden` | the count |
+| 6 | "Limpar" leaves the bar | `clearAllHidden` | the button — it survives in the panel footer |
+
+Rung order is not arbitrary. **A control leaves the bar early if it has somewhere
+else to be, and late if it does not.** "Limpar" goes before the magnifier because
+the "Mais" panel footer still carries "Limpar todos os filtros"; the magnifier
+and "Mais" go last because nothing else on screen can stand in for them.
+
+The counter goes before the search because it is the only thing left that
+*reports* rather than *does* — an operator can act without knowing the total,
+but not without a way to search.
+
+---
+
+## Behaviour by class
+
+Read this as "what the Pedidos table does", not "what the code hard-codes".
+
+### Filters
+
+| | small mobile | large mobile | tablet | small desktop | large desktop |
+| --- | --- | --- | --- | --- | --- |
+| controls on the bar | 0 | 0 | 0 | 1–2 | 3+ |
+| "Mais" present | yes | yes | yes | yes | only if something overflowed |
+
+**An applied filter is ranked first, not exempt.** Applied controls take the
+visible slots ahead of idle ones and go into "Mais" like anything else when even
+those run out. The earlier rule exempted them outright, and on a phone four
+applied pills then claimed more width than the row had: the bar painted past its
+own edge and the pills were reachable only by scrolling it sideways.
+
+Hiding one is safe *because the badge says so* — see below. A control scrolled
+off-screen carries no signal at all, which is the failure the exemption was
+written to prevent and did not.
+
+### The "Mais" badge
+
+| state | badge shows | tone |
+| --- | --- | --- |
+| overflowed fields, none applied | count of hidden **fields** | neutral |
+| any overflowed field applied | count of **applied** ones | filled, primary |
+
+A neutral "3" would make *three filters you have not used* and *three filters
+narrowing this list* look identical. On a phone, where every filter is in there,
+that badge is the only thing on screen saying the list is filtered at all.
+
+### Search
+
+| | small mobile | large mobile | tablet | small desktop | large desktop |
+| --- | --- | --- | --- | --- | --- |
+| resting state | magnifier | magnifier | box | box | box |
+| on expanding the magnifier | **takes over** the cluster | shares the row | — | — | — |
+
+The share/takeover boundary sits inside the "large mobile" band and moves with
+the table: it is a comparison against what the box would actually be left with,
+so a page with four short filter labels shares where Pedidos, with six longer
+ones, takes over. Measured on the real Pedidos screen, takeover begins at a
+500px viewport and sharing resumes at 600px.
+
+Two distinct behaviours, and conflating them was a bug:
+
+- **Shrink** (`fill`) — an expanded box drops its usual 200px floor and takes
+  whatever the cluster has. That floor is right for a box that lives on the row
+  permanently; it is wrong for one expanded into a cluster the ladder sized for
+  an icon, where insisting on it made the row scroll (154px of overhang at
+  320px, 84px at 390px, 42px at 500px).
+- **Takeover** (`searchTakeover`) — the filters stand down and the box owns the
+  cluster, with a ✕ to leave. Only where shrinking has run out of road and what
+  is left would be too narrow to read back. On a large phone there is room to
+  share, and evicting the filters there cost the operator their filters for
+  nothing.
+
+### The right-hand controls
+
+| | small mobile | large mobile | tablet | small desktop | large desktop |
+| --- | --- | --- | --- | --- | --- |
+| Exibir / Exportar | icon | icon | label | label | label |
+| dropdown chevron | no | no | yes | yes | yes |
+| "N de N" counter | hidden | hidden | shown | shown | shown |
+
+A tablet keeps the labels, which is worth stating because it is easy to assume
+otherwise. With every filter already behind "Mais" the row has room to spare
+there, and rung 2 is taken only when the search would otherwise fall below its
+floor. The ladder spends the width it has rather than degrading on a schedule —
+that is the whole point of measuring.
+
+The chevron goes with the label. A bare icon already reads as a button, and the
+~24px each buys is the difference between a row that fits and one that scrolls.
+It is dropped from Exibir, Exportar **and** "Mais" together — one chevron left
+among three identical buttons reads as a defect.
+
+### Clear all
+
+| | small mobile | large mobile | tablet | small desktop | large desktop |
+| --- | --- | --- | --- | --- | --- |
+| on the bar | no | no | icon | icon | icon + "Limpar" |
+| in the panel footer | yes | yes | yes | yes | yes |
+
+Present only while something is applied — a dead button is worse than none — and
+last in the cluster, because it is destructive and must never appear where a
+filter control was a moment ago.
+
+It is styled flat: no border, no fill, muted until hovered. Every other control
+on the row is an outlined pill because it *opens* something; this one is an
+escape hatch, and giving it the same weight made it read as a sixth filter.
+
+### Scope tabs
+
+Below the toolbar, above the rows they narrow. Hidden entirely when the board
+layout groups by the same field the scopes partition by — a column per situação
+and a tab per situação are the same partition offered twice, and picking one tab
+leaves the board with a single populated column, which reads as data loss.
+
+---
+
+## Where this is tested
+
+`__tests__/data-views-responsive.test.tsx` drives a fake `ResizeObserver` at each
+of the five widths and asserts the tables above. It is the executable copy of
+this document; if the two disagree, the test is right and this needs updating.
+
+Two things it cannot check, because jsdom has no layout engine: actual pixel
+overflow, and how anything looks. Those are verified in a real browser against
+the running Storybook, at 1600 / 1280 / 1024 / 900 / 768 / 600 / 500 / 430 / 390
+/ 360 / 320, measured on the toolbar row, the filter cluster's own scroll box,
+and the document.

package/src/components/data-display/DataViews/base-card.tsx

@@ -2,16 +2,27 @@
 
 import { type ReactNode } from "react";
 
-import type { SxProps, Theme } from "@mui/material/styles";
+import { useTheme, type CSSObject } from "@mui/material/styles";
+
+/** See the note on `CardSx` in `card-surface` — these fragments get merged. */
+type CardSx = CSSObject | Record<string, unknown>;
 
 import { Checkbox } from "../../form/Checkbox";
 import { Card } from "../../layout/Card";
 import { Box } from "../../../mui/Box";
 import { Text } from "../../typography/Text";
 
+import { DragHandle, useDragItem } from "./data-views-drag";
+import {
+  cardSurfaceStyles,
+  isActionable,
+  isSelectable,
+  slotTestIds,
+  type CardSurfaceProps,
+} from "./card-surface";
 import { CARD_ASPECT_RATIOS, type CardAspectRatio } from "./data-views-types";
 
-interface BaseCardProps {
+export interface BaseCardProps extends CardSurfaceProps {
   /** Extra body content below the caption (chips, meta). Optional. */
   children?: ReactNode;
   /** Tile proportion. Defaults to "4:3". */
@@ -33,15 +44,17 @@ interface BaseCardProps {
   subtitle?: ReactNode;
   /** The 3-dots menu (or any action node) pinned to the top-right corner. */
   menu?: ReactNode;
-  /** Whether this card is in the grid's selection. */
-  selected?: boolean;
   /** Toggle this card's selection. Omit to hide the checkbox (non-selectable). */
   onToggleSelect?: () => void;
-  /** Card click (e.g. open/edit). The checkbox/menu stop propagation. */
-  onClick?: () => void;
-  /** Visually de-emphasise (e.g. a disabled/hidden entity). */
-  dimmed?: boolean;
-  dataTestId?: string;
+  /**
+   * This card's id for drag purposes.
+   *
+   * Draggable ONLY inside a {@link DragContainerProvider} — see
+   * `data-views-drag`. On the board that is how a card moves between columns;
+   * in a grade it is how the operator reorders. Outside a container this is
+   * inert and no grip appears.
+   */
+  dragId?: string | number;
   checkboxTestId?: string;
 }
 
@@ -50,10 +63,9 @@ function cardSx(opts: {
   aspectRatio: CardAspectRatio;
   pad: number;
   interactive: boolean;
-  dimmed: boolean;
-  selected: boolean;
-}): SxProps<Theme> {
-  const { aspectRatio, pad, interactive, dimmed, selected } = opts;
+  draggable: boolean;
+}): CardSx {
+  const { aspectRatio, pad, interactive, draggable } = opts;
   return {
     position: "relative",
     aspectRatio: String(CARD_ASPECT_RATIOS[aspectRatio]),
@@ -61,12 +73,8 @@ function cardSx(opts: {
     flexDirection: "column",
     overflow: "hidden",
     p: pad,
-    transition: "border-color 120ms, box-shadow 120ms, background-color 120ms",
-    cursor: interactive ? "pointer" : undefined,
-    opacity: dimmed ? 0.6 : 1,
-    borderColor: selected ? "primary.main" : undefined,
-    boxShadow: selected ? (theme) => `inset 0 0 0 1px ${theme.palette.primary.main}` : undefined,
-    backgroundColor: selected ? "action.selected" : undefined,
+    cursor: draggable ? "grab" : interactive ? "pointer" : undefined,
+    ...(draggable ? { touchAction: "none", "&:active": { cursor: "grabbing" } } : {}),
   };
 }
 
@@ -244,9 +252,29 @@ function CardContents({
  * per-slot helpers above; this shell just assembles them within a fixed-ratio
  * tile. Reads no context, so it renders standalone as well as inside the grid.
  */
+/**
+ * Everything the tile derives from its props before it can render — pulled out
+ * so `BaseCard` itself stays inside the complexity budget.
+ */
+function useCardShell(props: BaseCardProps) {
+  const actionable = isActionable(props.state);
+  return {
+    selectable: isSelectable(props),
+    actionable,
+    theme: useTheme(),
+    slot: slotTestIds(props.testId),
+    scale: props.scale ?? 1,
+    // The card's own veto over the container's decision — see `CardSurfaceProps`.
+    drag: useDragItem(props.draggable === false || !actionable ? undefined : props.dragId),
+  };
+}
+
 export function BaseCard(props: BaseCardProps): React.JSX.Element {
-  const { aspectRatio = "4:3", scale = 1, selected = false, dimmed = false } = props;
-  const { menu, onToggleSelect, onClick, dataTestId, checkboxTestId } = props;
+  const { aspectRatio = "4:3", selected = false } = props;
+  const { menu, onToggleSelect, onClick } = props;
+  const { selectable, actionable, theme, slot, scale, drag } = useCardShell(props);
+  const dataTestId = props.testId;
+  const checkboxTestId = slot("checkbox");
   const pad = 1.5 * scale;
 
   return (
@@ -255,11 +283,53 @@ export function BaseCard(props: BaseCardProps): React.JSX.Element {
       borderRadius="lg"
       onClick={onClick}
       dataTestId={dataTestId}
-      sx={cardSx({ aspectRatio, pad, interactive: onClick != null, dimmed, selected })}
+      className={props.className}
+      aria-label={props["aria-label"]}
+      aria-disabled={actionable ? undefined : true}
+      {...drag.itemProps}
+      // A PLAIN OBJECT, not a function. `Card` merges by spreading
+      // (`sx={{ ...defaults, ...sx }}`), and spreading a function yields
+      // nothing at all — the styles vanish silently, which is exactly how the
+      // first version of this shipped with no variants and no effects.
+      sx={{
+        // The shared half — variant, colour, selection, effects — identical to
+        // the one BaseListCard uses, so a Grade and a Lista of the same records
+        // are dressed by one set of rules.
+        ...cardSurfaceStyles(
+          {
+            ...props,
+            selectable,
+            shape: "tile",
+            // A card mid-drag is a ghost of itself; the drop target is what the
+            // eye should be on.
+            state: drag.dragging ? "disabled" : props.state,
+          },
+          theme,
+        ),
+        // …and the tile's own geometry on top.
+        ...cardSx({
+          aspectRatio,
+          pad,
+          interactive: onClick != null,
+          draggable: drag.draggable && drag.handleProps === undefined,
+        }),
+      }}
     >
+      {/* Bottom-left, opposite the menu and clear of the checkbox — a grip in
+          the same corner as a control that toggles selection means every drag
+          starts with a near-miss on it. */}
+      {drag.draggable && (
+        <Box sx={{ position: "absolute", bottom: 4, left: 4, zIndex: 2 }}>
+          <DragHandle
+            handleProps={drag.handleProps}
+            gated={drag.handleProps !== undefined}
+            testId={slot("drag")}
+          />
+        </Box>
+      )}
       <CardOverlays
         selected={selected}
-        onToggleSelect={onToggleSelect}
+        onToggleSelect={selectable ? onToggleSelect ?? (() => {}) : undefined}
         checkboxTestId={checkboxTestId}
         menu={menu}
       />

package/src/components/data-display/DataViews/base-list-card-slots.tsx

@@ -0,0 +1,256 @@
+"use client";
+
+import { type ReactNode } from "react";
+
+import { DescriptionItem, type DescriptionItemProps } from "../DescriptionItem";
+import { Box } from "../../../mui/Box";
+import { Text } from "../../typography/Text";
+
+/**
+ * WHAT SITS IN EACH RAIL.
+ *
+ * Split from `base-list-card` at the size gate: that module is the shell, the
+ * rails and the states; this is the content of each column.
+ */
+
+/** Below this the row drops its middle columns. */
+export const META_BREAK = 520;
+/** …and below this it leaves the shared rails and goes two-line. */
+export const STACK_BREAK = 360;
+
+/** Money and dates line up only if their digits are the same width. */
+const TABULAR = { fontVariantNumeric: "tabular-nums" } as const;
+
+const CLAMP = {
+  overflow: "hidden",
+  textOverflow: "ellipsis",
+  whiteSpace: "nowrap",
+} as const;
+
+/**
+ * Title over subtitle — and, when the row navigates, the anchor that covers it.
+ *
+ * The link is a real `<a>` stretched by `::after` over the whole card rather
+ * than a click handler on a `<div>`. That buys cmd-click, middle-click, "copy
+ * link address", the status bar preview and correct tab order, and it stops the
+ * buttons elsewhere in the row from being interactive elements nested inside a
+ * clickable one.
+ */
+export function ListCardCaption({
+  title,
+  subtitle,
+  href,
+  target,
+  scale,
+  testId,
+}: {
+  title?: ReactNode;
+  subtitle?: ReactNode;
+  href?: string;
+  target?: string;
+  scale: number;
+  testId?: string;
+}): React.JSX.Element {
+  return (
+    <Box data-slot="caption" sx={{ minWidth: 0 }}>
+      {title != null && (
+        <Text variant="heading" size="sm" weight="bold" as="p">
+          <Box
+            {...(href ? { component: "a", href, target } : { component: "span" })}
+            data-testid={testId}
+            sx={{
+              display: "block",
+              lineHeight: 1.2,
+              fontSize: `${0.9 * scale}rem`,
+              color: "inherit",
+              textDecoration: "none",
+              ...CLAMP,
+              ...(href
+                ? {
+                    "&::after": {
+                      content: '""',
+                      position: "absolute",
+                      inset: 0,
+                      // Under the checkbox, drag grip, actions and menu, which
+                      // all raise themselves to 1.
+                      zIndex: 0,
+                    },
+                    "&:hover": { textDecoration: "underline" },
+                  }
+                : {}),
+            }}
+          >
+            {title}
+          </Box>
+        </Text>
+      )}
+      {subtitle != null && (
+        <Text variant="caption" size="xs" color="secondary" as="p">
+          <Box component="span" sx={{ display: "block", ...CLAMP }}>
+            {subtitle}
+          </Box>
+        </Text>
+      )}
+    </Box>
+  );
+}
+
+/**
+ * The middle columns: stacked label-over-value pairs, separated by a rule.
+ *
+ * Stacked rather than side by side because `DATA 05/08/2026` inline spends the
+ * horizontal room the value rail needs, and the separator is what stops two
+ * adjacent pairs reading as one four-word phrase.
+ */
+export function ListCardMeta({
+  meta,
+  metaSlot,
+}: {
+  meta?: DescriptionItemProps[];
+  metaSlot?: ReactNode;
+}): React.JSX.Element {
+  const items = meta ?? [];
+  return (
+    <Box
+      data-slot="meta"
+      sx={{
+        display: "flex",
+        alignItems: "center",
+        gap: 2,
+        whiteSpace: "nowrap",
+        ...TABULAR,
+        // Rung 1 of the ladder.
+        [`@container (max-width: ${META_BREAK}px)`]: { display: "none" },
+      }}
+    >
+      {items.map((item, index) => (
+        <Box key={`${item.label}-${index}`} sx={{ display: "flex", alignItems: "center", gap: 2 }}>
+          {index > 0 && (
+            <Box
+              aria-hidden
+              sx={{ color: "text.disabled", opacity: 0.5, userSelect: "none", fontSize: "0.875rem" }}
+            >
+              |
+            </Box>
+          )}
+          {/* Centred: a stacked pair sitting in its own column reads as one
+              unit only when the label is over the value rather than flush left
+              of a value shorter than it — `MÉTODO` above `PIX` was visibly
+              unhinged from it. Overridable per item. */}
+          <DescriptionItem orientation="vertical" align="center" {...item} />
+        </Box>
+      ))}
+      {metaSlot}
+    </Box>
+  );
+}
+
+/** The value, on its own rail, never truncated and never shunted by the chip. */
+function ListCardValue({ value, scale }: { value: ReactNode; scale: number }): React.JSX.Element {
+  return (
+    <Text variant="body" size="sm" weight="medium" as="span">
+      <Box
+        component="span"
+        sx={{ fontSize: `${0.875 * scale}rem`, whiteSpace: "nowrap", ...TABULAR }}
+      >
+        {value}
+      </Box>
+    </Text>
+  );
+}
+
+/**
+ * The actions and the menu, at the end of the row.
+ *
+ * Actions are revealed on hover and `:focus-within` — always-visible buttons on
+ * every row of fifty is a lot of chrome for something used on one of them.
+ * `:focus-within` is what keeps them reachable by keyboard, and `visibility`
+ * rather than `display` keeps their space reserved so nothing shifts.
+ */
+function ListCardActions({
+  actions,
+  alwaysVisible,
+  menu,
+  testId,
+}: {
+  actions?: ReactNode;
+  alwaysVisible?: boolean;
+  menu?: ReactNode;
+  testId: (slot: string) => string | undefined;
+}): React.JSX.Element | null {
+  if (actions == null && menu == null) return null;
+  return (
+    // z-index 1: above the stretched link, so these stay clickable.
+    <Box
+      data-slot="actions"
+      sx={{ display: "flex", alignItems: "center", gap: 0.5, position: "relative", zIndex: 1 }}
+    >
+      {actions && (
+        <Box
+          data-testid={testId("actions")}
+          onClick={(event) => event.stopPropagation()}
+          sx={{
+            display: "flex",
+            alignItems: "center",
+            gap: 0.5,
+            ...(alwaysVisible
+              ? {}
+              : {
+                  visibility: "hidden",
+                  ".MuiPaper-root:hover &, .MuiPaper-root:focus-within &": {
+                    visibility: "visible",
+                  },
+                }),
+          }}
+        >
+          {actions}
+        </Box>
+      )}
+      {menu && (
+        <Box data-testid={testId("menu")} onClick={(event) => event.stopPropagation()}>
+          {menu}
+        </Box>
+      )}
+    </Box>
+  );
+}
+
+/** Value, status and actions — three rails, not one flex run. */
+export function ListCardTail({
+  value,
+  status,
+  actions,
+  actionsAlwaysVisible,
+  menu,
+  scale,
+  testId,
+}: {
+  value?: ReactNode;
+  status?: ReactNode;
+  actions?: ReactNode;
+  actionsAlwaysVisible?: boolean;
+  menu?: ReactNode;
+  scale: number;
+  testId: (slot: string) => string | undefined;
+}): React.JSX.Element {
+  return (
+    <>
+      <Box data-slot="value" sx={{ textAlign: "right" }} data-testid={testId("value")}>
+        {value != null && <ListCardValue value={value} scale={scale} />}
+      </Box>
+      <Box
+        data-slot="status"
+        sx={{ display: "flex", justifyContent: "flex-start" }}
+        data-testid={testId("status")}
+      >
+        {status}
+      </Box>
+      <ListCardActions
+        actions={actions}
+        alwaysVisible={actionsAlwaysVisible}
+        menu={menu}
+        testId={testId}
+      />
+    </>
+  );
+}