@12-apps/ui 1.18.0 → 1.20.0

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

@@ -0,0 +1,160 @@
+"use client";
+
+import { createContext, useContext, type ReactNode } from "react";
+
+import { Box } from "../../../mui/Box";
+
+/**
+ * THE CELL CONFIG — the list declares its columns once, every row obeys them.
+ *
+ * The row used to name its middle slots: a title, a subtitle beneath it, then
+ * labelled `meta` pairs, then a value, then a status. That vocabulary was the
+ * mistake twice over. It reads as a description of every list, and no list is
+ * quite that shape — so a consumer wanting a date over a time, or an order
+ * number over the client who placed it, had to pick whichever named slot was
+ * least wrong and take its styling with it. And because each row decided its own
+ * content, alignment across a list was a convention the rows could break.
+ *
+ * So cells are CONFIGURED, the way a data grid's columns are: the list declares
+ * them once, and every card renders the same columns in the same tracks from its
+ * own row. Two cards cannot disagree about the shape of the list, because
+ * neither of them is deciding it.
+ *
+ * THE SECOND LINE IS AN OPTION, NOT A SUBTITLE. `secondary` is not "the small
+ * grey text under the title" — it is the cell's second line, for whatever pairs
+ * naturally in this list: date over time, name over e-mail, pedido over cliente.
+ * It carries no meaning the config did not put there, and a cell that wants one
+ * line simply omits it.
+ */
+export interface ListCardCellConfig<T extends Record<string, unknown> = Record<string, unknown>> {
+  /** Stable key. Also the cell's `data-slot`, so a test can find it by name. */
+  id: string;
+  /** The cell's first line, from the row. */
+  primary: (row: T) => ReactNode;
+  /** An optional second line beneath it. Anything that pairs with the first. */
+  secondary?: (row: T) => ReactNode;
+  /**
+   * Which edge the lines sit on. `end` is what a column of numbers wants, so its
+   * digits line up with the values above and below it — and it switches the cell
+   * to tabular figures, since nothing else ever asks for that alignment.
+   */
+  align?: "start" | "center" | "end";
+  /**
+   * This cell's track, as a `grid-template-columns` entry. Defaults to an even
+   * share of the spare width.
+   *
+   * A cell holding a number usually wants `max-content`: the rail is then as
+   * wide as the widest amount in the list and no wider, and its right edge does
+   * not move when a longer row arrives.
+   */
+  width?: string;
+  /** Emphasise the first line — for the one figure the row is really about. */
+  strong?: boolean;
+}
+
+const ALIGN_ITEMS = { start: "flex-start", center: "center", end: "flex-end" } as const;
+const TEXT_ALIGN = { start: "left", center: "center", end: "right" } as const;
+
+/** The default track: an even share of whatever width the row has spare. */
+export const DEFAULT_CELL_WIDTH = "minmax(0, 1fr)";
+
+/** The tracks a cell config asks for, in order. */
+export function cellTracks(cells: readonly ListCardCellConfig<never>[] | undefined): string[] {
+  return (cells ?? []).map((cell) => cell.width ?? DEFAULT_CELL_WIDTH);
+}
+
+/**
+ * The config handed down by the list.
+ *
+ * A card inside a group takes its columns from here rather than from props, so
+ * there is exactly one declaration of the list's shape and no way for a row to
+ * hold a different one.
+ */
+const CellConfigContext = createContext<readonly ListCardCellConfig<never>[] | null>(null);
+
+export function CellConfigProvider({
+  cells,
+  children,
+}: {
+  cells: readonly ListCardCellConfig<never>[] | undefined;
+  children: ReactNode;
+}): React.JSX.Element {
+  return <CellConfigContext.Provider value={cells ?? null}>{children}</CellConfigContext.Provider>;
+}
+
+/** The list's cell config, if it declared one. */
+export function useCellConfig(): readonly ListCardCellConfig<never>[] | null {
+  return useContext(CellConfigContext);
+}
+
+/**
+ * One cell rendered from its config.
+ *
+ * Both lines truncate rather than wrap: a row is a fixed-height scanning unit,
+ * and a cell that grows to two lines because one name was long drags every rail
+ * on that row down with it. Whatever does not fit belongs in the expandable
+ * body, which is the entire reason the body exists.
+ */
+function Cell<T extends Record<string, unknown>>({
+  config,
+  row,
+}: {
+  config: ListCardCellConfig<T>;
+  row: T;
+}): React.JSX.Element {
+  const align = config.align ?? "start";
+  const numeric = align === "end" ? { fontVariantNumeric: "tabular-nums" } : {};
+  const clamp = {
+    minWidth: 0,
+    maxWidth: "100%",
+    overflow: "hidden",
+    textOverflow: "ellipsis",
+    whiteSpace: "nowrap",
+  } as const;
+  const secondary = config.secondary?.(row);
+  return (
+    <Box
+      data-slot={`cell-${config.id}`}
+      sx={{
+        minWidth: 0,
+        display: "flex",
+        flexDirection: "column",
+        alignItems: ALIGN_ITEMS[align],
+        justifyContent: "center",
+        textAlign: TEXT_ALIGN[align],
+      }}
+    >
+      <Box
+        component="span"
+        sx={{ ...clamp, fontSize: 14, fontWeight: config.strong ? 700 : 600, lineHeight: 1.25, ...numeric }}
+      >
+        {config.primary(row)}
+      </Box>
+      {secondary != null && (
+        <Box
+          component="span"
+          sx={{ ...clamp, fontSize: 12.5, lineHeight: 1.3, color: "text.secondary", ...numeric }}
+        >
+          {secondary}
+        </Box>
+      )}
+    </Box>
+  );
+}
+
+/** Every configured cell of a row, in the list's declared order. */
+export function ListCardCells<T extends Record<string, unknown>>({
+  cells,
+  row,
+}: {
+  cells: readonly ListCardCellConfig<T>[];
+  row: T;
+}): React.JSX.Element {
+  return (
+    <>
+      {cells.map((config) => (
+        <Cell key={config.id} config={config} row={row} />
+      ))}
+    </>
+  );
+}

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

@@ -4,6 +4,7 @@ import { createContext, useContext, type ReactNode } from "react";
 
 import { Box } from "../../../mui/Box";
 import { DENSITY_ROW_PADDING, type DataViewsDensity } from "./data-views-layout-context";
+import { CellConfigProvider, cellTracks, type ListCardCellConfig } from "./list-card-cells";
 
 /**
  * THE LIST OWNS THE COLUMNS, NOT THE ROW.
@@ -27,6 +28,15 @@ import { DENSITY_ROW_PADDING, type DataViewsDensity } from "./data-views-layout-
 
 /** One rail. Fixed where alignment matters, flexible where it does not. */
 export interface ListRails {
+  /**
+   * The disclosure chevron, ahead of everything.
+   *
+   * Reserved on the same terms as the gutters behind it: a list where only SOME
+   * rows carry an expandable body would otherwise indent those rows and no
+   * others, and a column of captions that starts at two different offsets reads
+   * as a rendering fault rather than as a row you can open.
+   */
+  disclose: string;
   /** Reserved even when nothing drags: toggling drag mode must not shift the list. */
   drag: string;
   /** Reserved even when nothing is selectable, for the same reason. */
@@ -38,8 +48,6 @@ export interface ListRails {
   meta: string;
   /** The value's own rail, with a fixed right edge. */
   value: string;
-  /** Wide enough for the longest status this list holds. */
-  status: string;
   actions: string;
 }
 
@@ -83,6 +91,7 @@ export function contentRails(metaColumns: number): Pick<ListRails, "caption" | "
 }
 
 export const DEFAULT_RAILS: ListRails = {
+  disclose: "auto",
   drag: "auto",
   select: "auto",
   leading: "auto",
@@ -94,14 +103,21 @@ export const DEFAULT_RAILS: ListRails = {
   // NOT an `fr`: the value's whole promise is a fixed right edge, and a rail
   // that grows with the spare width moves that edge on every list.
   value: "max-content",
-  status: "max-content",
   actions: "auto",
 };
 
-interface ListRailsValue {
+export interface ListRailsValue {
   density: DataViewsDensity;
   /** Whether the gutters are held open even when empty. */
   reserveGutters: boolean;
+  /**
+   * How many tracks a row spans.
+   *
+   * Fixed at {@link RAIL_COUNT} for the named-slot layout, but a cell-configured
+   * list has as many tracks as the config declares, and every row must span the
+   * same number or subgrid tears.
+   */
+  railCount: number;
 }
 
 const ListRailsContext = createContext<ListRailsValue | null>(null);
@@ -122,13 +138,13 @@ export function useListRails(): ListRailsValue | null {
  */
 export function railsTemplate(rails: RailOverrides): string {
   return [
+    rails.disclose,
     rails.drag,
     rails.select,
     rails.leading,
     rails.caption,
     rails.meta,
     rails.value,
-    rails.status,
     rails.actions,
   ]
     .filter((rail): rail is string => rail != null)
@@ -163,7 +179,7 @@ export const RAIL_GAP_PX = RAIL_GAP * 8;
  * mode on does not shift every row sideways.
  */
 export function railsTemplateFor(
-  gutters: { drag: boolean; select: boolean },
+  gutters: { disclose: boolean; drag: boolean; select: boolean },
   metaColumns: number,
 ): string {
   return railsTemplate({
@@ -171,14 +187,42 @@ export function railsTemplateFor(
     // Standalone, the card can simply COUNT its pairs — no `metaColumns` to be
     // told, and no guess.
     ...contentRails(metaColumns),
+    ...(gutters.disclose ? {} : { disclose: null }),
     ...(gutters.drag ? {} : { drag: null }),
     ...(gutters.select ? {} : { select: null }),
   });
 }
 
-/** How many rails there are — the span a card claims. */
+/** How many rails the named-slot layout has — the span such a card claims. */
 export const RAIL_COUNT = 8;
 
+/**
+ * The gutters and the trailing menu that bracket a CONFIGURED row.
+ *
+ * A cell-configured list still has a head and a tail the config does not
+ * describe: the disclosure chevron, the drag grip and the checkbox in front, and
+ * the overflow menu behind. The menu is not optional — it is where a row's
+ * actions live, and a list that hid it would have nowhere to put them.
+ */
+const CELL_FIXED_RAILS = 4;
+
+/** Tracks for a cell-configured row: gutters, leading, the cells, then the menu. */
+export function cellRailsTemplate(cells: readonly string[]): string {
+  return [
+    DEFAULT_RAILS.disclose,
+    DEFAULT_RAILS.drag,
+    DEFAULT_RAILS.select,
+    DEFAULT_RAILS.leading,
+    ...cells,
+    DEFAULT_RAILS.actions,
+  ].join(" ");
+}
+
+/** How many tracks such a row spans — the fixed head/tail plus one per cell. */
+export function cellRailCount(cells: number): number {
+  return CELL_FIXED_RAILS + cells + 1;
+}
+
 /**
  * A list of {@link BaseListCard}s that share one set of columns.
  *
@@ -191,6 +235,7 @@ export const RAIL_COUNT = 8;
 export function ListCardGroup({
   children,
   density = "cozy",
+  cells,
   metaColumns,
   rails,
   reserveGutters = true,
@@ -199,6 +244,20 @@ export function ListCardGroup({
 }: {
   children: ReactNode;
   density?: DataViewsDensity;
+  /**
+   * The list's CELL CONFIG — declared once here, obeyed by every row.
+   *
+   * This is what makes the columns line up by construction rather than by
+   * convention: the group resolves the tracks and hands the same config to every
+   * card, so two rows cannot disagree about the shape of the list because
+   * neither of them decides it.
+   *
+   * Supplying this replaces the named-slot layout (title/subtitle/meta/value/
+   * status) for the rows inside — they render `row` through these cells instead.
+   * The gutters and the overflow menu are unaffected; they bracket the cells and
+   * are not the config's to describe.
+   */
+  cells?: readonly ListCardCellConfig<never>[];
   /**
    * How many labelled pairs the rows in this list carry.
    *
@@ -226,8 +285,12 @@ export function ListCardGroup({
     ...(metaColumns == null ? {} : contentRails(metaColumns)),
     ...rails,
   };
+  const configured = cells != null && cells.length > 0;
+  const template = configured ? cellRailsTemplate(cellTracks(cells)) : railsTemplate(resolved);
+  const railCount = configured ? cellRailCount(cells.length) : RAIL_COUNT;
   return (
-    <ListRailsContext.Provider value={{ density, reserveGutters }}>
+    <ListRailsContext.Provider value={{ density, reserveGutters, railCount }}>
+     <CellConfigProvider cells={cells}>
       <Box
         data-testid={dataTestId}
         sx={{
@@ -237,13 +300,14 @@ export function ListCardGroup({
           // honest place to ask the question.
           containerType: "inline-size",
           display: "grid",
-          gridTemplateColumns: railsTemplate(resolved),
+          gridTemplateColumns: template,
           alignItems: "center",
           rowGap: gap ?? DENSITY_ROW_PADDING[density],
         }}
       >
         {children}
       </Box>
+     </CellConfigProvider>
     </ListRailsContext.Provider>
   );
 }