@12-apps/ui 1.7.0 → 1.8.0

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

@@ -0,0 +1,352 @@
+"use client";
+
+import { useTheme } from "@mui/material/styles";
+import { type ReactNode } from "react";
+
+import { Checkbox } from "../../form/Checkbox";
+import { Card } from "../../layout/Card";
+import type { DescriptionItemProps } from "../DescriptionItem";
+import { Box } from "../../../mui/Box";
+
+import {
+  cardSurfaceStyles,
+  isActionable,
+  isSelectable,
+  slotTestIds,
+  type CardSurfaceProps,
+} from "./card-surface";
+import { DragHandle, useDragItem } from "./data-views-drag";
+import { DENSITY_ROW_PADDING, type DataViewsDensity } from "./data-views-layout-context";
+import { RAIL_COUNT, useListRails } from "./list-card-rails";
+import {
+  ListCardCaption,
+  ListCardMeta,
+  ListCardTail,
+  META_BREAK,
+  STACK_BREAK,
+} from "./base-list-card-slots";
+
+/**
+ * THE "LISTA" LAYOUT'S CARD — {@link BaseCard}'s horizontal sibling.
+ *
+ * `ListBody` always described the shape it wanted ("a marker, a title, a
+ * subtitle and a value on the right") and never provided it, so every host
+ * hand-rolled a `<Box>` flex row: a tint for selection with no checkbox, fixed
+ * `minWidth` columns that ignored density and never collapsed, no hover, no
+ * focus ring, and a `borderBottom` fighting the gap between rows.
+ *
+ * THE LIST OWNS THE COLUMNS. Inside a {@link ListCardGroup} this card is
+ * `grid-template-columns: subgrid` across the group's rails, so the value sits
+ * on its own edge and cannot be shunted about by the width of the status chip
+ * beside it. Standalone it falls back to the same template on its own. See
+ * `list-card-rails`.
+ *
+ * IT ANSWERS ITS OWN WIDTH, not the viewport — a container query, because the
+ * same row renders full-bleed on a phone, in a 300px board column, and beside a
+ * filter panel that opens and closes. Below `STACK_BREAK` it leaves the shared
+ * rails entirely and goes two-line, which is the standard mobile transaction
+ * row and beats truncating everything: title + value, then subtitle + status.
+ */
+
+export interface BaseListCardProps extends CardSurfaceProps {
+  /** A marker: avatar, thumbnail or status glyph. Earn the pixels — a generic
+   *  icon repeated down fifty rows is noise. */
+  leading?: ReactNode;
+  /** First-class title. Rendered as the link when `href` is set. */
+  title?: ReactNode;
+  /** Secondary line under the title. */
+  subtitle?: ReactNode;
+  /**
+   * Middle columns as labelled pairs — {@link DescriptionItem}s, not free-form
+   * nodes, so a screen reader reads "Data, 05/08/2026" rather than four
+   * unrelated strings. Stacked (label above value) by default.
+   *
+   * The FIRST rung of the collapse ladder: the only slot whose absence does not
+   * stop the row being identified or acted on.
+   */
+  meta?: DescriptionItemProps[];
+  /** Escape hatch for a middle section these pairs cannot express. */
+  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
+   * buttons are not the resting state of the page.
+   */
+  actions?: ReactNode;
+  /** Always show the inline actions, rather than on hover/focus. */
+  actionsAlwaysVisible?: boolean;
+  /** The 3-dots overflow menu, pinned to the end. Also opens on right-click. */
+  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. */
+  children?: ReactNode;
+  /** 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. */
+  density?: DataViewsDensity;
+  /** Fine-grained size multiplier on top of `density`. */
+  scale?: number;
+  /** Flush style: a bottom rule instead of an outline. Row-only. */
+  divider?: boolean;
+  /** This row's id for drag purposes. Inert outside a `DragContainerProvider`. */
+  dragId?: string | number;
+}
+
+/** The rails, for a card with no group above it. */
+const STANDALONE_RAILS =
+  "auto auto auto minmax(0, 1fr) auto max-content max-content auto";
+
+/**
+ * Whether a click was really a click, or the tail of a text selection.
+ *
+ * Without this, selecting an order id to copy it navigates away instead — the
+ * single most annoying thing a clickable row does.
+ */
+function isTextSelection(): boolean {
+  return (globalThis.getSelection?.()?.toString().length ?? 0) > 0;
+}
+
+/** 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();
+  };
+}
+
+/** The grip. Its gutter is reserved whether or not anything drags. */
+function DragSlot({
+  drag,
+  testId,
+}: {
+  drag: ReturnType<typeof useDragItem>;
+  testId?: string;
+}): React.JSX.Element {
+  if (!drag.draggable) return <Box data-slot="drag" />;
+  return (
+    <Box data-slot="drag" sx={{ position: "relative", zIndex: 1 }}>
+      <DragHandle
+        handleProps={drag.handleProps}
+        gated={drag.handleProps !== undefined}
+        testId={testId}
+      />
+    </Box>
+  );
+}
+
+/** The select checkbox. Its gutter is reserved whether or not it is here. */
+function SelectSlot({
+  selectable,
+  selected,
+  onToggleSelect,
+  testId,
+}: {
+  selectable: boolean;
+  selected: boolean;
+  onToggleSelect?: (event?: React.MouseEvent) => void;
+  testId?: string;
+}): React.JSX.Element {
+  if (!selectable) return <Box data-slot="select" />;
+  return (
+    // z-index 1: above the stretched link, or the anchor swallows the click.
+    <Box data-slot="select" sx={{ position: "relative", zIndex: 1 }}>
+      <Checkbox
+        checked={selected}
+        onChange={() => onToggleSelect?.()}
+        onClick={(event) => {
+          event.stopPropagation();
+          onToggleSelect?.(event);
+        }}
+        size="small"
+        data-testid={testId}
+        aria-label="Selecionar"
+      />
+    </Box>
+  );
+}
+
+/** Geometry: the rails, the density padding, the two-line collapse. */
+function rowSx(opts: {
+  inGroup: boolean;
+  pad: number;
+  padY: number;
+  divider: boolean;
+  interactive: boolean;
+  draggable: boolean;
+}): Record<string, unknown> {
+  const { inGroup, pad, padY, divider, interactive, draggable } = opts;
+  return {
+    position: "relative",
+    display: "grid",
+    // 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: STANDALONE_RAILS }),
+    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: 3,
+    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" }
+      : {}),
+  };
+}
+
+/**
+ * A selectable full-width row: a marker, a title over a subtitle, labelled
+ * middle columns, a value, a status, actions and a menu.
+ *
+ * A SHELL, like {@link BaseCard}. Domain rows live in the app and compose it.
+ */
+/**
+ * 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(props.draggable === false || !actionable ? undefined : props.dragId),
+    pad: 1.5 * scale,
+    padY: DENSITY_ROW_PADDING[group?.density ?? props.density ?? "cozy"] * scale,
+    // 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?.()),
+  };
+}
+
+export function BaseListCard(props: BaseListCardProps): React.JSX.Element {
+  const { selected = false, divider = false, href, onClick } = props;
+  const { group, actionable, scale, theme, selectable, slot, drag, pad, padY, acts } =
+    useRowShell(props);
+
+  return (
+    <Card
+      variant="outlined"
+      borderRadius="lg"
+      className={props.className}
+      dataTestId={props.testId}
+      aria-label={props["aria-label"]}
+      aria-disabled={actionable ? undefined : true}
+      onContextMenu={props.onContextMenu}
+      {...(acts ? actionProps(onClick) : {})}
+      {...drag.itemProps}
+      // A PLAIN OBJECT: `Card` merges by spreading, so a function sx vanishes.
+      sx={{
+        ...cardSurfaceStyles({ ...props, selectable, shape: "row", state: drag.dragging ? "disabled" : props.state }, theme),
+        ...rowSx({
+          inGroup: group !== null,
+          pad,
+          padY,
+          divider,
+          interactive: acts || href != null,
+          draggable: drag.draggable && drag.handleProps === undefined,
+        }),
+      }}
+    >
+      <DragSlot drag={drag} testId={slot("drag")} />
+      <SelectSlot
+        selectable={selectable}
+        selected={selected}
+        onToggleSelect={props.onToggleSelect}
+        testId={slot("checkbox")}
+      />
+      <Box data-slot="leading" sx={{ display: "flex", alignItems: "center" }}>
+        {props.leading}
+      </Box>
+      <ListCardCaption
+        title={props.title}
+        subtitle={props.subtitle}
+        href={href}
+        target={props.target}
+        scale={scale}
+        testId={slot("title")}
+      />
+      <ListCardMeta meta={props.meta} metaSlot={props.metaSlot} />
+      <ListCardTail
+        value={props.value}
+        status={props.status}
+        actions={actionable ? props.actions : undefined}
+        actionsAlwaysVisible={props.actionsAlwaysVisible}
+        menu={props.menu}
+        scale={scale}
+        testId={slot}
+      />
+      {props.children != null && (
+        <Box sx={{ gridColumn: "1 / -1", mt: pad * 0.5, minWidth: 0 }}>{props.children}</Box>
+      )}
+    </Card>
+  );
+}
+
+export { META_BREAK, STACK_BREAK };

package/src/components/data-display/DataViews/card-surface.ts

@@ -0,0 +1,297 @@
+import { alpha, keyframes, type CSSObject, type Theme } from "@mui/material";
+
+import { fadeInScaleAnimation } from "../Badge/Badge.animations";
+
+/**
+ * A plain style object, not MUI's `SxProps`.
+ *
+ * `SxProps` is a union including arrays and functions, so a value typed as one
+ * cannot be spread — and these fragments exist precisely to be merged. Note also
+ * that `Card` merges by SPREADING (`sx={{ ...defaults, ...sx }}`), so handing it
+ * a function yields nothing at all: resolve the theme with `useTheme` first.
+ */
+type CardSx = CSSObject | Record<string, unknown>;
+
+/** The ring, as scale + opacity so it never leaves the compositor. */
+const pulseRing = keyframes`
+  0% { transform: scale(1); opacity: 0.9; }
+  70% { transform: scale(1.04); opacity: 0; }
+  100% { transform: scale(1.04); opacity: 0; }
+`;
+
+/**
+ * THE CONTRACT BOTH CARDS IMPLEMENT.
+ *
+ * `BaseCard` (a tile) and `BaseListCard` (a row) are one object seen from two
+ * angles, so the surface — variant, colour, selectability, draggability,
+ * emphasis and state — is declared once and spread into both.
+ */
+
+/**
+ * How much chrome the surface claims. Button's vocabulary, spelled Button's
+ * way: a card and a button are both surfaces the operator presses, and having
+ * one say `outline` while the other says `outlined` taxes everyone who writes
+ * both. Chip's `filled | outlined` was the wrong model — a chip is a token in a
+ * sentence and has only those two things to say.
+ */
+export type CardSurfaceVariant = "outline" | "ghost" | "text" | "glass";
+
+/** The theme colour a card's selection and emphasis are drawn in. */
+export type CardSurfaceColor =
+  | "primary"
+  | "secondary"
+  | "success"
+  | "warning"
+  | "error"
+  | "info";
+
+/**
+ * Why this card is asking to be noticed.
+ *
+ * ONE union, not six booleans. `glow`/`pulse`/`animate`/`bounce`/`shimmer`
+ * combined into 32 states of which about three meant anything —
+ * `pulse + shimmer + bounce` is not a thing anyone wants, and every one of
+ * those combinations was a state somebody could reach by accident.
+ */
+export type CardEmphasis =
+  /** Nothing. The overwhelming default. */
+  | "none"
+  /** Look here now: an accent bar, and a ring that beats six times and settles. */
+  | "attention"
+  /** This just arrived: an accent bar and one fade-in. */
+  | "new";
+
+/** A row and a tile carry emphasis differently — see `emphasisSx`. */
+type CardShape = "row" | "tile";
+
+/**
+ * What this record IS, as opposed to how it looks.
+ *
+ * `dimmed` only greyed pixels, which left a cancelled row's buttons live and
+ * clickable. This carries the meaning, so the card can also stop offering
+ * actions on something that cannot be acted on.
+ */
+export type CardState = "default" | "cancelled" | "disabled";
+
+export interface CardSurfaceProps {
+  /** How much chrome the surface claims. Defaults to `outline`. */
+  variant?: CardSurfaceVariant;
+  /** Theme colour for selection and emphasis. Defaults to `primary`. */
+  color?: CardSurfaceColor;
+  /**
+   * Can this card be selected — and does it show it?
+   *
+   * The capability, separate from the handler. `selectable` gets the checkbox
+   * AND the selected treatment; `selectable={false}` has neither, however
+   * `selected` is set, so a stale flag arriving with the data cannot make a
+   * read-only row render as picked. Defaults to whether `onToggleSelect` exists.
+   */
+  selectable?: boolean;
+  /** Whether this card is currently in the selection. */
+  selected?: boolean;
+  /**
+   * Opt OUT of dragging even inside a drag container.
+   *
+   * Draggability is the container's decision (see `data-views-drag`); this is
+   * the card's veto — a pinned row, a summary line, a record that may not move.
+   */
+  draggable?: boolean;
+  /**
+   * Where this card leads.
+   *
+   * PREFER THIS TO `onClick`. A clickable `<div>` cannot be cmd-clicked,
+   * middle-clicked or "copy link address"'d, and wrapping interactive children
+   * in a click handler is the a11y violation it looks like. With `href` the
+   * title is a real `<a>` stretched over the card by a pseudo-element: one
+   * whole-row target, correct tab order, every browser affordance intact, and
+   * the buttons inside stay ordinary buttons.
+   */
+  href?: string;
+  /** Anchor target, when `href` is set. */
+  target?: string;
+  /** Card click, for a card that does not navigate. See `href` first. */
+  onClick?: () => void;
+  /** What this record is. `cancelled`/`disabled` also suppress the actions. */
+  state?: CardState;
+  /** Why this card is asking to be noticed. Defaults to `none`. */
+  emphasis?: CardEmphasis;
+  className?: string;
+  /**
+   * One id; the parts derive from it (`${testId}-checkbox`, `-drag`, `-menu`,
+   * `-value`). A prop per slot would have been `checkboxTestId`,
+   * `menuTestId`, `valueTestId`… one for every part anybody ever tested.
+   */
+  testId?: string;
+  "aria-label"?: string;
+}
+
+/** Every slot's test id, derived from the card's one. */
+export function slotTestIds(testId: string | undefined): (slot: string) => string | undefined {
+  return (slot) => (testId ? `${testId}-${slot}` : undefined);
+}
+
+/** Is this card selectable? Explicit wins; otherwise a handler implies it. */
+export function isSelectable(
+  props: Pick<CardSurfaceProps, "selectable"> & { onToggleSelect?: () => void },
+): boolean {
+  return props.selectable ?? props.onToggleSelect != null;
+}
+
+/** Can this record be acted on at all? */
+export function isActionable(state: CardState | undefined): boolean {
+  return state !== "disabled" && state !== "cancelled";
+}
+
+/**
+ * Variant styling. Everything but `outline` drops the border.
+ *
+ * `ghost` keeps a faint SURFACE where `text` has none — without that the two
+ * were pixel-identical at rest and the union carried a distinction it did not
+ * draw. Ghost is "a surface, quietly"; text is "no surface at all", which is
+ * what a host wants when it is drawing the container itself.
+ */
+function variantSx(variant: CardSurfaceVariant): CardSx {
+  if (variant === "ghost") {
+    return {
+      border: 0,
+      backgroundColor: "action.hover",
+      "&:hover": { backgroundColor: "action.selected" },
+    };
+  }
+  if (variant === "text") {
+    return { border: 0, backgroundColor: "transparent", boxShadow: "none" };
+  }
+  if (variant === "glass") {
+    return {
+      backgroundColor: "rgba(255,255,255,0.55)",
+      backdropFilter: "blur(8px)",
+      borderColor: "rgba(255,255,255,0.35)",
+    };
+  }
+  return {};
+}
+
+/**
+ * MOTION IS OPT-IN, ALWAYS.
+ *
+ * Everything animated here is wrapped in this. Fifty rows breathing in unison
+ * is a vestibular trigger, and honouring the OS setting is not a polish item —
+ * it is the difference between a list somebody can look at and one they cannot.
+ */
+const MOTION_OK = "@media (prefers-reduced-motion: no-preference)";
+
+/**
+ * THE ROW'S ATTENTION SIGNAL IS A BAR, NOT A HALO.
+ *
+ * A glow is a weak signal in a list: full-width rows stacked tight means the
+ * halo bleeds 15px into the neighbours above and below and reads as a rendering
+ * artifact, and stacked with a `selected` ring and the browser's focus ring it
+ * becomes three concentric halos on one row. Five rows needing attention at
+ * once turns the page into a smear.
+ *
+ * A 3px accent on the leading edge is stronger, costs no motion at all, works
+ * under reduced-motion, cannot bleed into a neighbour, and stacks cleanly
+ * however many rows raise their hand. It is where operational tables land.
+ */
+function accentBar(main: string): CardSx {
+  return {
+    "&::before": {
+      content: '""',
+      position: "absolute",
+      insetInlineStart: 0,
+      insetBlock: 0,
+      width: 3,
+      borderStartStartRadius: "inherit",
+      borderEndStartRadius: "inherit",
+      backgroundColor: main,
+      pointerEvents: "none",
+    },
+  };
+}
+
+/**
+ * The tile's halo. Button's glow, kept for `BaseCard` — a grid of tiles has gaps
+ * around each card, so the spread has somewhere to go that a row does not.
+ */
+function glowSx(main: string): CardSx {
+  return {
+    boxShadow: `0 0 20px 5px ${alpha(main, 0.6)}, 0 0 40px 10px ${alpha(main, 0.3)}`,
+    filter: "brightness(1.05)",
+  };
+}
+
+/**
+ * A breath that STOPS.
+ *
+ * Six iterations, not `infinite`. A restaurant admin has this open for a whole
+ * shift, and something pulsing in the periphery forever is fatigue rather than
+ * urgency — worse, once two or three rows are doing it the signal means
+ * nothing. It settles, and the accent bar carries the state from then on.
+ *
+ * Animating `transform`/`opacity` on a pseudo-element, never `box-shadow`: a
+ * box-shadow keyframe repaints every frame, and fifty of them drop frames on
+ * exactly the tablet a restaurant floor uses. This one is compositor-only.
+ */
+function pulseSx(main: string): CardSx {
+  return {
+    [MOTION_OK]: {
+      "&::after": {
+        content: '""',
+        position: "absolute",
+        inset: 0,
+        borderRadius: "inherit",
+        border: `2px solid ${main}`,
+        animation: `${pulseRing} 1.6s ease-out 6`,
+        pointerEvents: "none",
+      },
+    },
+  };
+}
+
+/** The emphasis treatments, in the terms the shape can actually carry. */
+function emphasisSx(emphasis: CardEmphasis, main: string, shape: CardShape): CardSx {
+  if (emphasis === "attention") {
+    // The bar on both; the halo only where there is room for it to spread.
+    return {
+      ...accentBar(main),
+      ...(shape === "tile" ? glowSx(main) : {}),
+      ...pulseSx(main),
+    };
+  }
+  if (emphasis === "new") {
+    return {
+      ...accentBar(main),
+      [MOTION_OK]: { animation: `${fadeInScaleAnimation} 240ms ease-out` },
+    };
+  }
+  return {};
+}
+
+/**
+ * The shared half of a card's styling. Each component adds its own geometry —
+ * a tile's aspect ratio, a row's rails.
+ */
+export function cardSurfaceStyles(
+  props: CardSurfaceProps & { selectable: boolean; shape: CardShape },
+  theme: Theme,
+): CardSx {
+  const { variant = "outline", color = "primary", selected = false, selectable } = props;
+  const { state = "default", emphasis = "none" } = props;
+  const main = theme.palette[color].main;
+  // Selection styling is gated on the CAPABILITY: a card that cannot be
+  // selected must not render as selected because a stale flag came with its data.
+  const showSelected = selectable && selected;
+  return {
+    transition: "border-color 120ms, box-shadow 120ms, background-color 120ms",
+    opacity: state === "default" ? 1 : 0.6,
+    ...variantSx(variant),
+    ...(showSelected
+      ? {
+          borderColor: `${color}.main`,
+          boxShadow: `inset 0 0 0 1px ${main}`,
+          backgroundColor: "action.selected",
+        }
+      : {}),
+    ...emphasisSx(emphasis, main, props.shape),
+  };
+}