@12-apps/ui 1.18.0 → 1.20.0

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

@@ -1,30 +1,25 @@
 "use client";
 
-import { useTheme } from "@mui/material/styles";
+import { Collapse } from "@mui/material";
 import { type ReactNode } from "react";
 
 import { Card } from "../../layout/Card";
 import type { DescriptionItemProps } from "../DescriptionItem";
 import { Box } from "../../../mui/Box";
 
+import { type CardSurfaceProps } from "./card-surface";
+import { DropIndicator } from "./data-views-drag";
+import { useDisclosure } from "./base-list-card-disclosure";
+import { actionProps, metaShape, rowStyles, useRowShell } from "./base-list-card-geometry";
+import { DiscloseSlot, DragSlot, SelectSlot } from "./base-list-card-gutters";
+import { type DataViewsDensity } from "./data-views-layout-context";
+import { cellRailsTemplate } from "./list-card-rails";
+import { ListCardCells, cellTracks, useCellConfig, type ListCardCellConfig } from "./list-card-cells";
 import {
-  CARD_RADIUS,
-  cardSurfaceStyles,
-  isActionable,
-  isSelectable,
-  slotTestIds,
-  type CardSurfaceProps,
-} from "./card-surface";
-import { useDragItem } from "./data-views-drag";
-import { DragSlot, SelectSlot } from "./base-list-card-gutters";
-import { DENSITY_ROW_PADDING, type DataViewsDensity } from "./data-views-layout-context";
-import { RAIL_COUNT, RAIL_GAP, railsTemplateFor, useListRails } from "./list-card-rails";
-import {
+  ListCardActions,
   ListCardCaption,
   ListCardMeta,
   ListCardTail,
-  META_BREAK,
-  STACK_BREAK,
 } from "./base-list-card-slots";
 
 /**
@@ -70,8 +65,6 @@ export interface BaseListCardProps extends CardSurfaceProps {
   metaSlot?: ReactNode;
   /** The number this row is about. Its own rail, tabular figures, never truncated. */
   value?: ReactNode;
-  /** A status chip or badge. Its own fixed slot, so it cannot move the value. */
-  status?: ReactNode;
   /**
    * Inline actions — the one or two things done often enough to deserve a
    * button. Revealed on hover and `:focus-within` by default, so fifty rows of
@@ -84,8 +77,39 @@ export interface BaseListCardProps extends CardSurfaceProps {
   menu?: ReactNode;
   /** What opens the overflow menu on right-click / long-press. */
   onContextMenu?: (event: React.MouseEvent) => void;
-  /** Extra content below the main row; spans every rail. */
+  /**
+   * THE EXPANDABLE BODY — and the whole reason this is a card and not a table
+   * row.
+   *
+   * A summary row of labelled columns is a table row with a border round it: it
+   * restates what the table already says and gives nobody a reason to switch to
+   * it. What a card can do that a table cell cannot is OPEN — carry the record's
+   * own detail underneath its summary, in whatever shape that record wants.
+   *
+   * So this container makes no claim about what goes in here. It spans every
+   * rail and imposes nothing: an order puts its line items and a totals ledger
+   * here, a cart adds its recovery actions, a role lists its permissions. The
+   * design of that area belongs entirely to the consumer, and none of it is the
+   * envelope's business.
+   *
+   * ABSENT ⇒ NO CHEVRON. A row given nothing to reveal renders no disclosure
+   * control at all, rather than one that opens onto an empty box, so a column of
+   * chevrons is a truthful index of which rows have more behind them.
+   */
   children?: ReactNode;
+  /** Open on first render, for an uncontrolled card. Ignored when `expanded` is set. */
+  defaultExpanded?: boolean;
+  /**
+   * Open state, when the LIST wants to own it.
+   *
+   * Left unset the card keeps its own, and rows open independently — several at
+   * once, which is what comparing two records requires. Pass this (with
+   * `onExpandedChange`) to impose something else, an accordion being the usual
+   * reason.
+   */
+  expanded?: boolean;
+  /** Fired with the state the card is asking to move to. */
+  onExpandedChange?: (expanded: boolean) => void;
   /** Toggle this row's selection. Receives the raw event so a list can range-select. */
   onToggleSelect?: (event?: React.MouseEvent) => void;
   /** How much air the row gets. Vertical only — a full-width row cannot narrow. */
@@ -102,237 +126,175 @@ export interface BaseListCardProps extends CardSurfaceProps {
   divider?: boolean;
   /** This row's id for drag purposes. Inert outside a `DragContainerProvider`. */
   dragId?: string | number;
+  /**
+   * The record this row is about, read by the list's cell config.
+   *
+   * Required only when cells are configured — the config's `primary`/`secondary`
+   * are functions of the row, so without one there is nothing to render them
+   * from and the card falls back to its named slots.
+   */
+  row?: Record<string, unknown>;
+  /**
+   * A cell config for a STANDALONE card.
+   *
+   * Inside a `ListCardGroup` the list's config wins and this is ignored: one
+   * declaration of the list's shape is the whole point, and a row permitted to
+   * override it could put its columns somewhere no other row has them.
+   */
+  cells?: readonly ListCardCellConfig<never>[];
 }
 
 
 
+
 /**
- * Whether a click was really a click, or the tail of a text selection.
+ * Which cell config applies, and whether this row resolves its own tracks.
  *
- * Without this, selecting an order id to copy it navigates away instead — the
- * single most annoying thing a clickable row does.
+ * The list's config wins over the card's: one declaration of the list's shape is
+ * the point, so a row inside a group cannot introduce a column of its own. And
+ * the template is standalone-only — inside a group the GROUP owns it and the row
+ * is subgrid over it, because a row resolving its own tracks is exactly what
+ * stops a list from lining up.
  */
-function isTextSelection(): boolean {
-  return (globalThis.getSelection?.()?.toString().length ?? 0) > 0;
+function useResolvedCells(
+  props: BaseListCardProps,
+  inGroup: boolean,
+): {
+  cells: readonly ListCardCellConfig<never>[] | null;
+  configured: boolean;
+  cellTemplate: string | null;
+} {
+  const groupCells = useCellConfig();
+  const cells = groupCells ?? props.cells ?? null;
+  const configured = cells != null && cells.length > 0 && props.row != null;
+  const cellTemplate = configured && !inGroup ? cellRailsTemplate(cellTracks(cells)) : null;
+  return { cells, configured, cellTemplate };
 }
 
-/** Keyboard equivalence for a card that acts but does not navigate. */
-function clickKeys(onClick: () => void) {
-  return (event: React.KeyboardEvent): void => {
-    if (event.key !== "Enter" && event.key !== " ") return;
-    event.preventDefault();
-    onClick();
-  };
-}
 
 /**
- * Geometry: the rails, the density padding, the two-line collapse.
- *
- * SCALE IS `zoom`, NOT A SET OF MULTIPLIED FONT SIZES.
- *
- * It used to be the latter, on exactly three values — title, value, row padding
- * — so the slider left the subtitle, the meta labels, the rules, the checkbox,
- * the grip, the chip and the menu at their fixed sizes, and the row came apart
- * as you dragged it. Multiplying the rest is not a fix: the checkbox and the
- * chip are MUI internals sized in their own px, and no prop we pass reaches
- * them.
+ * The row's middle: either the list's configured cells, or the named slots.
  *
- * `zoom` scales the used value of every length in the subtree — ours and theirs
- * — and unlike `transform: scale` it REFLOWS, so the row still occupies the
- * space it draws and the rails still resolve. Verified against the group: at
- * 1.4 all four rows keep identical rail edges, because subgrid tracks and the
- * zoom that reads them are the same for every row.
+ * Split out because the branch is the only conditional shape the card has, and
+ * inlined it pushed `BaseListCard` past both the line and the complexity gate.
  */
-function rowSx(opts: {
-  inGroup: boolean;
-  gutters: { drag: boolean; select: boolean };
-  metaColumns: number;
-  pad: number;
-  padY: number;
-  scale: number;
-  divider: boolean;
-  interactive: boolean;
-  draggable: boolean;
-}): Record<string, unknown> {
-  const { inGroup, gutters, metaColumns, pad, padY, scale, divider, interactive, draggable } = opts;
-  return {
-    position: "relative",
-    borderRadius: CARD_RADIUS,
-    display: "grid",
-    zoom: scale,
-    // SUBGRID AND `container-type` CANNOT COEXIST on one element: containment
-    // makes the box size independently of its parent, so the browser drops the
-    // subgrid and every slot stacks into one column. (Observed exactly that —
-    // computed `grid-template-columns: 1222px` on a card asking for subgrid.)
-    //
-    // So inside a group the GROUP is the query container and the row is the
-    // subgrid; standalone, the row is both the container and its own grid.
-    ...(inGroup
-      ? { gridColumn: `span ${RAIL_COUNT}`, gridTemplateColumns: "subgrid" }
-      : {
-          containerType: "inline-size",
-          gridTemplateColumns: railsTemplateFor(gutters, metaColumns),
-        }),
-    alignItems: "center",
-    // Wide enough that the meta cluster, the value and the status read as three
-    // columns rather than one run of text — the complaint that started all this
-    // was `MÉTODO PIX R$ 13,90` scanning as a single phrase.
-    columnGap: RAIL_GAP,
-    width: "100%",
-    px: pad,
-    py: padY,
-    cursor: draggable ? "grab" : interactive ? "pointer" : undefined,
-    ...(draggable ? { touchAction: "none", "&:active": { cursor: "grabbing" } } : {}),
-    ...(interactive ? { "&:hover": { backgroundColor: "action.hover" } } : {}),
-    // A real focus ring, which a clickable <div> never had.
-    "&:focus-visible": { outline: 2, outlineStyle: "solid", outlineColor: "primary.main", outlineOffset: 2 },
-    // TWO-LINE, below the point where the shared rails stop helping.
-    //
-    // The standard mobile transaction row: what the record IS and what it COST
-    // on the first line, the supporting detail on the second. Better than
-    // truncating four columns into ellipses, and the reason each slot carries a
-    // `data-slot` — the placement is explicit rather than whatever order the
-    // children happen to be in.
-    //
-    //   [ select ][ leading ][ title …………… ][   menu ]
-    //                        [ status …………… ][  value ]
-    //
-    // The MENU stays in the top-right corner at every width. It is the row's
-    // one fixed landmark — an overflow that moves to the second line on a phone
-    // is an overflow nobody finds twice.
-    [`@container (max-width: ${STACK_BREAK}px)`]: {
-      gridTemplateColumns: "auto auto minmax(0, 1fr) max-content",
-      ...(inGroup ? { gridColumn: `span ${RAIL_COUNT}` } : {}),
-      rowGap: 0.75,
-      columnGap: 1,
-      '& > [data-slot="drag"]': { display: "none" },
-      '& > [data-slot="select"]': { gridArea: "1 / 1" },
-      '& > [data-slot="leading"]': { gridArea: "1 / 2" },
-      '& > [data-slot="caption"]': { gridArea: "1 / 3" },
-      '& > [data-slot="actions"]': { gridArea: "1 / 4", justifyContent: "flex-end" },
-      '& > [data-slot="meta"]': { display: "none" },
-      // Second line, starting under the title rather than under the checkbox.
-      '& > [data-slot="status"]': { gridArea: "2 / 3", justifyContent: "flex-start" },
-      '& > [data-slot="value"]': { gridArea: "2 / 4", textAlign: "right" },
-    },
-    ...(divider
-      ? { border: 0, borderRadius: 0, borderBottom: 1, borderBottomStyle: "solid", borderBottomColor: "divider" }
-      : {}),
-  };
+function RowContent({
+  card,
+  cells,
+  configured,
+  slot,
+  actionable,
+  meta,
+}: {
+  card: BaseListCardProps;
+  cells: readonly ListCardCellConfig<never>[] | null;
+  configured: boolean;
+  slot: (name: string) => string | undefined;
+  actionable: boolean;
+  meta: { columns: number; present: boolean };
+}): React.JSX.Element {
+  if (configured && cells != null) {
+    return (
+      <>
+        {/* The list's columns, rendered from this row. */}
+        <ListCardCells cells={cells} row={card.row as never} />
+        {/* THE MENU IS NOT PART OF THE CONFIG and never optional: it is where a
+          * row's actions live, and a list that folded it into a cell would have
+          * nowhere left to put them. So it brackets the cells on its own rail,
+          * exactly as the gutters do at the other end. */}
+        <ListCardActions
+          actions={actionable ? card.actions : undefined}
+          alwaysVisible={card.actionsAlwaysVisible}
+          menu={card.menu}
+          testId={slot}
+        />
+      </>
+    );
+  }
+  return (
+    <>
+      <ListCardCaption
+        title={card.title}
+        subtitle={card.subtitle}
+        href={card.href}
+        target={card.target}
+        testId={slot("title")}
+      />
+      <ListCardMeta meta={card.meta} metaSlot={card.metaSlot} trailingRule={card.value != null} />
+      <ListCardTail
+        value={card.value}
+        separated={meta.present}
+        actions={actionable ? card.actions : undefined}
+        actionsAlwaysVisible={card.actionsAlwaysVisible}
+        menu={card.menu}
+        testId={slot}
+      />
+    </>
+  );
 }
 
 /**
- * A selectable full-width row: a marker, a title over a subtitle, labelled
- * middle columns, a value, a status, actions and a menu.
+ * The revealed body, and the rule that separates it from the summary.
  *
- * A SHELL, like {@link BaseCard}. Domain rows live in the app and compose it.
- */
-/**
- * The id this row drags under, or nothing.
+ * `gridColumn: 1 / -1` so it spans every rail: the summary's columns are the
+ * LIST's, and nothing about them should constrain a detail area whose design
+ * belongs to the consumer.
  *
- * `undefined` is the inert answer: `useDragItem` treats a missing id as "no
- * drag", which is how the card's own veto (`draggable={false}`) and an
- * unactionable record both switch dragging off without the card knowing
- * anything about the container above it.
- */
-function dragIdFor(
-  props: BaseListCardProps,
-  actionable: boolean,
-): string | number | undefined {
-  return props.draggable === false || !actionable ? undefined : props.dragId;
-}
-
-/**
- * What the meta cluster amounts to — asked once, used three times: to size the
- * rail, to close the cluster with a rule, and to decide whether the value has
- * anything to be divided FROM.
+ * Collapse rather than an unmount, so the body animates open and keeps its own
+ * state between peeks — a consumer putting a form or a scrolled table in here
+ * would otherwise have it reset on every toggle. `unmountOnExit` is deliberately
+ * NOT set: fifty closed rows pay for fifty hidden subtrees, which is the trade
+ * taken because the alternative re-runs every consumer's effects per toggle.
  */
-function metaShape(props: BaseListCardProps): { columns: number; present: boolean } {
-  const columns = props.meta?.length ?? 0;
-  return { columns, present: columns > 0 || props.metaSlot != null };
-}
-
-/**
- * Everything the row derives before it can render — extracted so the component
- * stays inside the size budget.
- */
-function useRowShell(props: BaseListCardProps) {
-  const actionable = isActionable(props.state);
-  const group = useListRails();
-  const scale = props.scale ?? 1;
-  return {
-    group,
-    actionable,
-    scale,
-    theme: useTheme(),
-    selectable: isSelectable(props),
-    slot: slotTestIds(props.testId),
-    drag: useDragItem(dragIdFor(props, actionable)),
-    // Standalone holds no gutter open: there is no list beside it to line up
-    // with, so a reserved-but-empty rail is pure inset.
-    reserve: group?.reserveGutters ?? false,
-    // 1, not 1.5. The row's contents still have to line up with the toolbar
-    // above them, but 12px of card padding stacked on the checkbox's own 9px
-    // and an empty drag gutter's 24px read as a row indented for no reason.
-    //
-    // Not multiplied by `scale` — the row's `zoom` already scales it, and doing
-    // both would square the factor on padding alone.
-    pad: 1,
-    padY: DENSITY_ROW_PADDING[group?.density ?? props.density ?? "cozy"],
-    // A card that navigates does so with a real anchor, so it takes no click
-    // handler of its own — the stretched link IS the target.
-    acts: props.onClick != null && props.href == null && actionable,
-  };
-}
-
-/** The click/keyboard props a row that acts (but does not navigate) needs. */
-function actionProps(onClick: (() => void) | undefined) {
-  return {
-    role: "button",
-    tabIndex: 0,
-    onClick: () => {
-      if (isTextSelection()) return;
-      onClick?.();
-    },
-    onKeyDown: clickKeys(() => onClick?.()),
-  };
-}
-
-/** The surface and the geometry, merged — the row's whole `sx` in one place. */
-function rowStyles(
-  props: BaseListCardProps,
-  shell: ReturnType<typeof useRowShell>,
-): Record<string, unknown> {
-  const { group, theme, selectable, drag, reserve, pad, padY, scale, acts } = shell;
-  return {
-    ...cardSurfaceStyles(
-      {
-        ...props,
-        selectable,
-        shape: "row",
-        state: drag.dragging ? "disabled" : props.state,
-      },
-      theme,
-    ),
-    ...rowSx({
-      inGroup: group !== null,
-      gutters: { drag: reserve || drag.draggable, select: reserve || selectable },
-      metaColumns: metaShape(props).columns,
-      pad,
-      padY,
-      scale,
-      divider: props.divider ?? false,
-      interactive: acts || props.href != null,
-      draggable: drag.draggable && drag.handleProps === undefined,
-    }),
-  };
+function ExpandableBody({
+  disclosure,
+  padY,
+  pad,
+  children,
+}: {
+  disclosure: { expandable: boolean; expanded: boolean; regionId: string };
+  padY: number;
+  pad: number;
+  children: ReactNode;
+}): React.JSX.Element {
+  if (!disclosure.expandable) return <></>;
+  return (
+    <Box sx={{ gridColumn: "1 / -1", minWidth: 0 }}>
+      <Collapse in={disclosure.expanded} timeout={150}>
+        <Box
+          id={disclosure.regionId}
+          role="region"
+          sx={{
+            minWidth: 0,
+            // `padY`, not a fraction of the horizontal padding. The card's own
+            // `py` wraps the summary AND the body, so once the body is in flow
+            // the summary has no bottom padding of its own — at `comfortable`
+            // the row visibly lost the height it had while closed.
+            mt: padY,
+            pt: padY,
+            // A RULE BETWEEN SUMMARY AND BODY, bled through the row's horizontal
+            // padding so it spans the card edge to edge. Inset, it reads as a
+            // border around the content rather than a division of the card.
+            borderTop: 1,
+            borderColor: "divider",
+            mx: -pad,
+            px: pad,
+          }}
+        >
+          {children}
+        </Box>
+      </Collapse>
+    </Box>
+  );
 }
 
 export function BaseListCard(props: BaseListCardProps): React.JSX.Element {
-  const { selected = false, href, onClick } = props;
+  const { selected = false, onClick } = props;
   const shell = useRowShell(props);
-  const { actionable, selectable, slot, drag, reserve, pad, acts } = shell;
+  const { actionable, selectable, slot, drag, reserve, pad, padY, acts } = shell;
   const meta = metaShape(props);
+  const disclosure = useDisclosure(props);
+  const { cells, configured, cellTemplate } = useResolvedCells(props, shell.group != null);
 
   return (
     <Card
@@ -345,8 +307,17 @@ export function BaseListCard(props: BaseListCardProps): React.JSX.Element {
       {...(acts ? actionProps(onClick) : {})}
       {...drag.itemProps}
       // A PLAIN OBJECT: `Card` merges by spreading, so a function sx vanishes.
-      sx={rowStyles(props, shell)}
+      sx={rowStyles(props, shell, cellTemplate)}
     >
+      {drag.dropEdge != null && <DropIndicator edge={drag.dropEdge} />}
+      <DiscloseSlot
+        expandable={disclosure.expandable}
+        expanded={disclosure.expanded}
+        reserve={reserve}
+        onToggle={disclosure.toggle}
+        controls={disclosure.regionId}
+        testId={slot("disclose")}
+      />
       <DragSlot drag={drag} reserve={reserve} testId={slot("drag")} />
       <SelectSlot
         selectable={selectable}
@@ -358,32 +329,12 @@ export function BaseListCard(props: BaseListCardProps): React.JSX.Element {
       <Box data-slot="leading" sx={{ display: "flex", alignItems: "center" }}>
         {props.leading}
       </Box>
-      <ListCardCaption
-        title={props.title}
-        subtitle={props.subtitle}
-        href={href}
-        target={props.target}
-        testId={slot("title")}
-      />
-      <ListCardMeta
-        meta={props.meta}
-        metaSlot={props.metaSlot}
-        trailingRule={props.value != null}
-      />
-      <ListCardTail
-        value={props.value}
-        separated={meta.present}
-        status={props.status}
-        actions={actionable ? props.actions : undefined}
-        actionsAlwaysVisible={props.actionsAlwaysVisible}
-        menu={props.menu}
-        testId={slot}
-      />
-      {props.children != null && (
-        <Box sx={{ gridColumn: "1 / -1", mt: pad * 0.5, minWidth: 0 }}>{props.children}</Box>
-      )}
+      <RowContent card={props} cells={cells} configured={configured} slot={slot} actionable={actionable} meta={meta} />
+      <ExpandableBody disclosure={disclosure} padY={padY} pad={pad}>
+        {props.children}
+      </ExpandableBody>
     </Card>
   );
 }
 
-export { META_BREAK, STACK_BREAK };
+export { META_BREAK, STACK_BREAK } from "./base-list-card-slots";

package/src/components/data-display/DataViews/data-views-drag.tsx

@@ -44,6 +44,23 @@ export interface DragContainerValue {
   handleProps?: (id: string | number) => DragItemProps;
   /** The id currently being dragged, so its card can dim itself. */
   activeId?: string | number | null;
+  /**
+   * WHERE THE DRAGGED ITEM WOULD LAND — the one thing a drag cannot be honest
+   * without.
+   *
+   * A list that dims the row you picked up and shows nothing else asks you to
+   * guess the outcome and find out by dropping. The marker turns that into a
+   * statement: THIS gap is where it goes.
+   *
+   * Published by the container, not computed by the card, for the same reason
+   * everything else here is: only the thing holding the items knows the
+   * geometry — which one you are over, which edge of it, and whether that
+   * position is legal. A card knows none of that about its neighbours.
+   *
+   * `null` while nothing is being dragged, or while the pointer is over no
+   * valid target.
+   */
+  dropIndicator?: { id: string | number; edge: "before" | "after" } | null;
 }
 
 const DragContainerContext = createContext<DragContainerValue | null>(null);
@@ -73,19 +90,65 @@ export function useDragItem(dragId: string | number | undefined): {
   itemProps: DragItemProps;
   handleProps: DragItemProps | undefined;
   dragging: boolean;
+  /** Which of this card's edges the marker sits on, or null for neither. */
+  dropEdge: "before" | "after" | null;
 } {
   const container = useContext(DragContainerContext);
   if (!container || dragId === undefined) {
-    return { draggable: false, itemProps: {}, handleProps: undefined, dragging: false };
+    return { draggable: false, itemProps: {}, handleProps: undefined, dragging: false, dropEdge: null };
   }
+  const indicator = container.dropIndicator;
   return {
     draggable: true,
     itemProps: container.itemProps(dragId),
     handleProps: container.handleProps?.(dragId),
     dragging: container.activeId === dragId,
+    dropEdge: indicator != null && indicator.id === dragId ? indicator.edge : null,
   };
 }
 
+/**
+ * THE DROP MARKER — one rule across the card's edge, drawn where the item lands.
+ *
+ * Shared by every draggable surface rather than reimplemented per card, so a
+ * reorderable list, a board column and a grid of tiles all say the same thing
+ * the same way. A consumer wiring its own DnD gets this for free by publishing
+ * `dropIndicator`; it never draws the marker itself.
+ *
+ * ABSOLUTE, AND OUTSIDE THE FLOW ON PURPOSE. A marker that took layout space
+ * would push every row below it down by its own height the moment it appeared —
+ * the list would twitch as you dragged across it, and the gap you were aiming
+ * at would move out from under the pointer. Drawn over the gap instead, nothing
+ * reflows.
+ *
+ * `pointerEvents: none` so it cannot swallow the dragover events that placed it,
+ * and `aria-hidden` because the position it reports belongs in a live region the
+ * LIST owns — fifty rows each announcing a marker is a screen-reader nightmare.
+ */
+export function DropIndicator({ edge }: { edge: "before" | "after" }): React.JSX.Element {
+  return (
+    <Box
+      aria-hidden
+      data-slot="drop-indicator"
+      data-drop-edge={edge}
+      sx={{
+        position: "absolute",
+        left: 0,
+        right: 0,
+        // Centred ON the gap rather than inside the card: the item lands
+        // BETWEEN two rows, and a rule sitting within one of them reads as
+        // "into this row" instead.
+        ...(edge === "before" ? { top: -2 } : { bottom: -2 }),
+        height: 3,
+        borderRadius: 2,
+        bgcolor: "primary.main",
+        pointerEvents: "none",
+        zIndex: 2,
+      }}
+    />
+  );
+}
+
 /**
  * The grip. Six dots, the convention everywhere, drawn rather than imported so
  * this costs no icon dependency.

package/src/components/data-display/DataViews/data-views-types.ts

@@ -63,7 +63,7 @@ export interface DataViewCardSelection {
  * ratio and grows in BOTH width and height as the zoom slider widens its grid
  * track, so a grid of cards stays visually uniform.
  */
-export type CardAspectRatio = "1:1" | "4:3" | "16:9" | "9:16" | "3:4";
+export type CardAspectRatio = "1:1" | "4:3" | "16:9" | "9:16" | "3:4" | "3:1";
 
 /** Numeric width/height factor for each {@link CardAspectRatio} (CSS `aspect-ratio`). */
 export const CARD_ASPECT_RATIOS: Record<CardAspectRatio, number> = {
@@ -72,6 +72,15 @@ export const CARD_ASPECT_RATIOS: Record<CardAspectRatio, number> = {
   "16:9": 16 / 9,
   "9:16": 9 / 16,
   "3:4": 3 / 4,
+  /**
+   * The BANNER tile: too short for media, sized for two lines of text.
+   *
+   * Every other ratio here is picture-shaped, because they were added for cards
+   * built around a thumbnail. A card whose subject is a NAME and a NUMBER — a
+   * cart, an order, anything triaged rather than browsed — spends most of a 4:3
+   * tile on an icon that repeats down the whole grid and says nothing.
+   */
+  "3:1": 3,
 };
 
 /** One selectable value inside a filter pill. */