@12-apps/ui 1.7.0 → 1.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/ui",
-  "version": "1.7.0",
+  "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.6.0",
+    "@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.7.0",
-    "@12-apps/typescript-config": "^1.7.0",
+    "@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/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}
+      />
+    </>
+  );
+}