@multiplatform.one/table 6.7.0 → 7.0.0

package/src/components/SimpleTable/index.tsx

@@ -3,19 +3,22 @@
  *
  * Renders data as a table using Layer 1 Table primitives with a thin
  * data-mapping loop. Supports column alignment, intent props on rows
- * via `_intent` property in data objects, and responsive card layout
- * on mobile via `useMedia`.
+ * via `_intent` property in data objects, responsive card layout
+ * on mobile via `useMedia`, and optional row press (LC-49 / LC-50 / LC-71).
  *
- * No filtering, sorting, pagination, or state management -- just render data.
+ * No filtering, sorting, pagination, or table state — just render data.
  */
 
 import { EmptyState } from "@multiplatform.one/components";
-import { useResolvedKnobs } from "@multiplatform.one/theme";
+import { ensureFocusVisibleRing, hairline, useResolvedKnobs } from "@multiplatform.one/theme";
+import { useCallback, useState, type ReactNode } from "react";
 import { useTranslation } from "react-i18next";
-import type { ViewProps } from "tamagui";
-import { Text, View, useMedia } from "tamagui";
+import type { FontSizeTokens, ViewProps } from "tamagui";
+import { Text, View, isWeb, useMedia } from "tamagui";
 import { Table } from "@multiplatform.one/table-primitives";
 import type { DataTableLayout } from "../../types";
+import { isInteractiveInnerTarget } from "../../utils/rowPress";
+import { withInterp } from "../../utils/withInterp";
 
 // ===========================================================================
 // Types
@@ -30,6 +33,8 @@ export interface SimpleTableColumn {
   header: string;
   /** Text alignment for the column */
   align?: "left" | "center" | "right";
+  /** Optional cell renderer. Strings/numbers still pick up table type + align. */
+  cell?: (value: unknown, row: Record<string, any>, rowIndex: number) => ReactNode;
 }
 
 export interface SimpleTableProps extends ViewProps {
@@ -44,6 +49,20 @@ export interface SimpleTableProps extends ViewProps {
   layout?: DataTableLayout;
   /** Accessible label for the table */
   "aria-label"?: string;
+  /** Visible caption (also the accessible name; wins over `aria-label`). */
+  caption?: string;
+  /**
+   * Row activation: click/tap anywhere on the row, and Enter/Space while
+   * focused. One roving tab stop (LC-49). Keyboard-origin focus paints one
+   * inset ring on the row (LC-71); selected/`_intent` is fill, never a ring.
+   */
+  onRowPress?: (row: Record<string, any>, rowIndex: number) => void;
+  /** Accessible name for a pressable row. Falls back to the first cell. */
+  rowLabel?: (row: Record<string, any>) => string;
+  /** Stable row identity. Defaults to the row index. */
+  getRowId?: (row: Record<string, any>, rowIndex: number) => string;
+  /** Disable row press (rows stay visible; activation is inert). */
+  disabled?: boolean;
 }
 
 // ===========================================================================
@@ -61,6 +80,206 @@ function alignToFlex(align?: "left" | "center" | "right"): "flex-start" | "cente
   }
 }
 
+function cellLocationFor(index: number, count: number): "first" | "middle" | "last" {
+  if (index === 0) return "first";
+  if (index === count - 1) return "last";
+  return "middle";
+}
+
+function rowLocationFor(index: number, count: number): "first" | "middle" | "last" {
+  if (index === 0) return "first";
+  if (index === count - 1) return "last";
+  return "middle";
+}
+
+function resolveRowId(
+  row: Record<string, any>,
+  index: number,
+  getRowId?: (row: Record<string, any>, rowIndex: number) => string,
+): string {
+  return getRowId?.(row, index) ?? String(index);
+}
+
+type KnobBody = {
+  fontFamily: string;
+  fontWeight: string;
+  color?: string;
+};
+
+function AlignedCellText({
+  children,
+  align,
+  body,
+  sizeToken,
+  emphasized,
+  muted,
+}: {
+  children: string | number;
+  align?: "left" | "center" | "right";
+  body: KnobBody;
+  sizeToken: string;
+  emphasized?: boolean;
+  muted?: boolean;
+}) {
+  return (
+    <Text
+      {...body}
+      fontSize={sizeToken as FontSizeTokens}
+      color={muted ? "$color11" : "$color12"}
+      fontWeight={emphasized ? "600" : body.fontWeight}
+      display="block"
+      width="100%"
+      textAlign={align ?? "left"}
+      numberOfLines={1}
+      ellipsizeMode="tail"
+      {...(isWeb ? { title: String(children) } : {})}
+      {...(align === "right" ? ({ fontVariant: ["tabular-nums"] } as any) : {})}
+    >
+      {children}
+    </Text>
+  );
+}
+
+function renderCellContent(
+  col: SimpleTableColumn,
+  row: Record<string, any>,
+  rowIndex: number,
+  colIndex: number,
+  body: KnobBody,
+  sizeToken: string,
+): ReactNode {
+  const raw = row[col.accessorKey];
+  const rendered = col.cell ? col.cell(raw, row, rowIndex) : raw;
+  if (rendered == null || typeof rendered === "string" || typeof rendered === "number") {
+    return (
+      <AlignedCellText
+        align={col.align}
+        body={body}
+        sizeToken={sizeToken}
+        emphasized={colIndex === 0}
+      >
+        {rendered ?? ""}
+      </AlignedCellText>
+    );
+  }
+  return rendered;
+}
+
+// ===========================================================================
+// Row press (LC-49 / LC-50 / LC-71)
+// ===========================================================================
+
+function useSimpleTableRowPress({
+  data,
+  columns,
+  onRowPress,
+  rowLabel,
+  disabled,
+}: {
+  data: Array<Record<string, any>>;
+  columns: SimpleTableColumn[];
+  onRowPress?: (row: Record<string, any>, rowIndex: number) => void;
+  rowLabel?: (row: Record<string, any>) => string;
+  disabled?: boolean;
+}) {
+  const { t } = useTranslation();
+  const isSSR = typeof window === "undefined";
+  const rowPressActive = Boolean(onRowPress) && !disabled;
+  const [rowPressAnchor, setRowPressAnchor] = useState(0);
+  const effectiveRowPressAnchor = Math.min(rowPressAnchor, Math.max(data.length - 1, 0));
+
+  const deriveRowLabel = useCallback(
+    (row: Record<string, any>, rowIndex: number): string => {
+      const fromAccessor = rowLabel?.(row);
+      if (fromAccessor) return fromAccessor;
+      const first = columns[0] ? row[columns[0].accessorKey] : undefined;
+      if ((typeof first === "string" && first.length > 0) || typeof first === "number") {
+        return String(first);
+      }
+      return withInterp(t("Row {{row}}", { row: rowIndex + 1 }), { row: rowIndex + 1 });
+    },
+    [rowLabel, columns, t],
+  );
+
+  const getRowPressProps = useCallback(
+    (row: Record<string, any>, rowIndex: number, variant: "row" | "card" = "row") => {
+      if (!rowPressActive) return {};
+      const handlePress = (event: any) => {
+        if (event?.defaultPrevented) return;
+        const targetEl = event?.target ?? event?.nativeEvent?.target;
+        if (isWeb && typeof Element !== "undefined" && targetEl instanceof Element) {
+          const boundary = targetEl.closest('[data-row-press="true"]');
+          if (isInteractiveInnerTarget(targetEl, boundary)) return;
+        }
+        onRowPress?.(row, rowIndex);
+      };
+      return {
+        "aria-label": deriveRowLabel(row, rowIndex),
+        onPress: handlePress,
+        cursor: "pointer" as const,
+        pressStyle: { backgroundColor: "$backgroundPress" },
+        ...(variant === "card" ? { role: "button" as const } : {}),
+        ...(isWeb && !isSSR
+          ? {
+              tabIndex: rowIndex === effectiveRowPressAnchor ? 0 : -1,
+              // LC-71: inset ring on the row (table/card clip severs an outer
+              // ring). focusVisibleStyle = keyboard-origin only — mouse click
+              // paints fill/press, never a ring. Selected/`_intent` is fill.
+              focusVisibleStyle: ensureFocusVisibleRing({ outlineOffset: -2 }),
+              "data-row-press": "true",
+              onFocus: (e: any) => {
+                if (e.target === e.currentTarget) setRowPressAnchor(rowIndex);
+              },
+              onBlur: (e: any) => {
+                const next = e.relatedTarget;
+                if (!(next instanceof Element) || !next.closest('[data-row-press="true"]')) {
+                  setRowPressAnchor(0);
+                }
+              },
+              onKeyDown: (e: any) => {
+                if (e.defaultPrevented) return;
+                if (e.target !== e.currentTarget) return;
+                const key = e.key;
+                if (key === "Enter" || key === " " || key === "Spacebar") {
+                  e.preventDefault();
+                  e.stopPropagation();
+                  if (e.repeat) return;
+                  onRowPress?.(row, rowIndex);
+                  return;
+                }
+                if (key === "ArrowDown" || key === "ArrowUp" || key === "Home" || key === "End") {
+                  e.preventDefault();
+                  e.stopPropagation();
+                  const rowEl = e.currentTarget as HTMLElement;
+                  const scope =
+                    rowEl.closest('[data-row-press-scope="true"]') ?? rowEl.ownerDocument;
+                  const pressRows = Array.from(
+                    scope.querySelectorAll('[data-row-press="true"]'),
+                  ) as HTMLElement[];
+                  const currentIdx = pressRows.indexOf(rowEl);
+                  if (currentIdx < 0) return;
+                  const nextIdx =
+                    key === "Home"
+                      ? 0
+                      : key === "End"
+                        ? pressRows.length - 1
+                        : Math.min(
+                            Math.max(currentIdx + (key === "ArrowDown" ? 1 : -1), 0),
+                            pressRows.length - 1,
+                          );
+                  pressRows[nextIdx]?.focus();
+                }
+              },
+            }
+          : {}),
+      };
+    },
+    [rowPressActive, deriveRowLabel, onRowPress, effectiveRowPressAnchor, isSSR],
+  );
+
+  return { rowPressActive, getRowPressProps };
+}
+
 // ===========================================================================
 // Mobile Card Layout
 // ===========================================================================
@@ -68,52 +287,138 @@ function alignToFlex(align?: "left" | "center" | "right"): "flex-start" | "cente
 interface SimpleTableMobileCardsProps {
   data: Array<Record<string, any>>;
   columns: SimpleTableColumn[];
+  caption?: string;
+  onRowPress?: (row: Record<string, any>, rowIndex: number) => void;
+  rowLabel?: (row: Record<string, any>) => string;
+  getRowId?: (row: Record<string, any>, rowIndex: number) => string;
+  disabled?: boolean;
 }
 
-function SimpleTableMobileCards({ data, columns }: SimpleTableMobileCardsProps) {
+function SimpleTableMobileCards({
+  data,
+  columns,
+  caption,
+  onRowPress,
+  rowLabel,
+  getRowId,
+  disabled,
+}: SimpleTableMobileCardsProps) {
   const { t } = useTranslation();
+  const { knobProps } = useResolvedKnobs({ component: "SimpleTable" });
+  const { rowPressActive, getRowPressProps } = useSimpleTableRowPress({
+    data,
+    columns,
+    onRowPress,
+    rowLabel,
+    disabled,
+  });
+  const tableZebraOn = knobProps.tableZebra === "on";
+  const [titleCol, ...detailCols] = columns;
+
   if (data.length === 0) {
     return (
-      <EmptyState
-        compact
-        backgroundColor="$color1"
-        borderRadius="$4"
-        aria-live="polite"
-        title={t("No data available")}
-      />
+      <View flexDirection="column" {...knobProps.gap}>
+        {caption ? (
+          <Text {...knobProps.label} color="$color11">
+            {caption}
+          </Text>
+        ) : null}
+        <EmptyState compact aria-live="polite" title={t("No data available")} />
+      </View>
     );
   }
 
   return (
-    <View flexDirection="column" gap="$2">
+    <View
+      flexDirection="column"
+      {...knobProps.gap}
+      {...(rowPressActive ? ({ "data-row-press-scope": "true" } as any) : {})}
+    >
+      {caption ? (
+        <Text {...knobProps.label} color="$color11">
+          {caption}
+        </Text>
+      ) : null}
       {data.map((row, rowIndex) => {
         const intent = row._intent as IntentName | undefined;
+        const titleValue = titleCol ? row[titleCol.accessorKey] : undefined;
+        const titleRendered = titleCol?.cell
+          ? titleCol.cell(titleValue, row, rowIndex)
+          : titleValue;
 
         return (
           <View
-            key={rowIndex}
-            backgroundColor="$color1"
-            borderRadius="$4"
-            borderWidth={1}
-            borderColor="$color6"
-            padding="$3"
-            {...(intent ? { theme: intent } : {})}
+            key={resolveRowId(row, rowIndex, getRowId)}
+            testID="simple-table-card"
+            {...knobProps.surface}
+            {...knobProps.cardSurface}
+            elevation={knobProps.elevation}
+            {...(tableZebraOn && rowIndex % 2 === 1 ? { backgroundColor: "$color2" } : {})}
+            {...(intent ? { theme: intent, backgroundColor: "$color3" as const } : {})}
+            hoverStyle={{ backgroundColor: "$backgroundHover" }}
+            {...({ animation: "quick" } as any)}
+            {...({
+              "data-table-zebra": tableZebraOn ? (rowIndex % 2 === 0 ? "even" : "odd") : "off",
+            } as any)}
+            {...(getRowPressProps(row, rowIndex, "card") as any)}
           >
-            {columns.map((col) => (
+            {titleCol ? (
+              <View
+                {...(detailCols.length > 0
+                  ? {
+                      paddingBottom: "$2",
+                      marginBottom: "$2",
+                      ...hairline.bottom,
+                      borderBottomColor: "$color6",
+                    }
+                  : {})}
+              >
+                {typeof titleRendered === "string" ||
+                typeof titleRendered === "number" ||
+                titleRendered == null ? (
+                  <AlignedCellText
+                    align={titleCol.align}
+                    body={knobProps.body}
+                    sizeToken={knobProps.sizeToken}
+                    emphasized
+                  >
+                    {titleRendered ?? ""}
+                  </AlignedCellText>
+                ) : (
+                  titleRendered
+                )}
+              </View>
+            ) : null}
+            {detailCols.map((col, detailIndex) => (
               <View
                 key={col.accessorKey}
                 flexDirection="row"
                 alignItems="center"
                 paddingVertical="$1.5"
                 gap="$2"
+                {...(detailIndex < detailCols.length - 1
+                  ? { ...hairline.bottom, borderBottomColor: "$color6" }
+                  : {})}
               >
-                <Text fontSize="$3" color="$color10" fontWeight="500" width="40%" flexShrink={0}>
+                <Text
+                  {...knobProps.label}
+                  color="$color10"
+                  width="40%"
+                  flexShrink={0}
+                  numberOfLines={1}
+                  ellipsizeMode="tail"
+                >
                   {col.header}
                 </Text>
-                <View flex={1}>
-                  <Text fontSize="$3" color="$color12" textAlign={col.align ?? "left"}>
-                    {String(row[col.accessorKey] ?? "")}
-                  </Text>
+                <View flex={1} minWidth={0}>
+                  {renderCellContent(
+                    col,
+                    row,
+                    rowIndex,
+                    detailIndex + 1,
+                    knobProps.body,
+                    knobProps.sizeToken,
+                  )}
                 </View>
               </View>
             ))}
@@ -135,36 +440,75 @@ export interface SimpleTableDesktopProps extends ViewProps {
   columns: SimpleTableColumn[];
   /** Accessible label for the table */
   "aria-label"?: string;
+  caption?: string;
+  onRowPress?: (row: Record<string, any>, rowIndex: number) => void;
+  rowLabel?: (row: Record<string, any>) => string;
+  getRowId?: (row: Record<string, any>, rowIndex: number) => string;
+  disabled?: boolean;
 }
 
 /** Desktop table layout using Layer 1 Table primitives. Exported for testing. */
-export function SimpleTableDesktop({ data, columns, ...props }: SimpleTableDesktopProps) {
+export function SimpleTableDesktop({
+  data,
+  columns,
+  caption,
+  onRowPress,
+  rowLabel,
+  getRowId,
+  disabled,
+  ...props
+}: SimpleTableDesktopProps) {
   const { knobProps } = useResolvedKnobs({ component: "SimpleTable" });
   const { t } = useTranslation();
+  const { rowPressActive, getRowPressProps } = useSimpleTableRowPress({
+    data,
+    columns,
+    onRowPress,
+    rowLabel,
+    disabled,
+  });
+  const tableZebraOn = knobProps.tableZebra === "on";
+  const ariaLabel = caption ? undefined : props["aria-label"];
 
   return (
-    <View {...props}>
-      <Table aria-label={props["aria-label"]} {...knobProps.borderRadius}>
+    <View
+      {...props}
+      minWidth={0}
+      // overflow="auto" (scrollbar only when content overflows) is web-only —
+      // outside RN's "scroll" | "hidden" | "visible" union (house Record cast).
+      {...({ overflow: "auto" } as Record<string, unknown>)}
+    >
+      <Table aria-label={ariaLabel} {...({ "aria-rowcount": data.length + 1 } as any)}>
+        {caption ? (
+          <Table.Caption>
+            <Text {...knobProps.label} color="$color11">
+              {caption}
+            </Text>
+          </Table.Caption>
+        ) : null}
         <Table.Head>
           <Table.Row>
             {columns.map((col, colIndex) => (
               <Table.HeaderCell
                 key={col.accessorKey}
                 justifyContent={alignToFlex(col.align)}
-                cellLocation={
-                  colIndex === 0 ? "first" : colIndex === columns.length - 1 ? "last" : "middle"
-                }
+                cellLocation={cellLocationFor(colIndex, columns.length)}
                 data-align={col.align ?? "left"}
               >
                 {/* Block text filling the cell + textAlign: alignment that
                     works in the real <th> (display:table-cell — flex props
                     are inert there) and in the flex displayMode alike. */}
                 <Text
+                  {...knobProps.body}
+                  {...knobProps.label}
+                  color="$color11"
                   fontWeight="600"
-                  fontSize="$3"
                   display="block"
                   width="100%"
                   textAlign={col.align ?? "left"}
+                  numberOfLines={1}
+                  ellipsizeMode="tail"
+                  {...(col.align === "right" ? ({ fontVariant: ["tabular-nums"] } as any) : {})}
                 >
                   {col.header}
                 </Text>
@@ -172,48 +516,56 @@ export function SimpleTableDesktop({ data, columns, ...props }: SimpleTableDeskt
             ))}
           </Table.Row>
         </Table.Head>
-        <Table.Body>
+        <Table.Body {...(rowPressActive ? ({ "data-row-press-scope": "true" } as any) : {})}>
           {data.length === 0 ? (
             <Table.Row>
-              <Table.Cell>
-                <EmptyState compact title={t("No data available")} />
+              <Table.Cell cellWidth="auto" {...({ colSpan: Math.max(columns.length, 1) } as any)}>
+                <EmptyState compact aria-live="polite" title={t("No data available")} />
               </Table.Cell>
             </Table.Row>
           ) : (
             data.map((row, rowIndex) => {
               const intent = row._intent as IntentName | undefined;
               const intentProps = intent ? { [intent]: true } : {};
+              const isLast = rowIndex === data.length - 1;
+              const zebraFill =
+                !intent && tableZebraOn && rowIndex % 2 === 1
+                  ? { backgroundColor: "$color2" as const }
+                  : {};
 
               return (
                 <Table.Row
-                  key={rowIndex}
-                  rowLocation={
-                    rowIndex === 0 ? "first" : rowIndex === data.length - 1 ? "last" : "middle"
-                  }
+                  key={resolveRowId(row, rowIndex, getRowId)}
+                  rowLocation={rowLocationFor(rowIndex, data.length)}
+                  hoverStyle={{ backgroundColor: "$backgroundHover" }}
+                  {...({ animation: "quick" } as any)}
+                  {...zebraFill}
                   {...intentProps}
+                  {...({
+                    "data-table-zebra": tableZebraOn
+                      ? rowIndex % 2 === 0
+                        ? "even"
+                        : "odd"
+                      : "off",
+                  } as any)}
+                  {...(getRowPressProps(row, rowIndex) as any)}
                 >
                   {columns.map((col, colIndex) => (
                     <Table.Cell
                       key={col.accessorKey}
                       justifyContent={alignToFlex(col.align)}
-                      cellLocation={
-                        colIndex === 0
-                          ? "first"
-                          : colIndex === columns.length - 1
-                            ? "last"
-                            : "middle"
-                      }
+                      cellLocation={cellLocationFor(colIndex, columns.length)}
                       data-align={col.align ?? "left"}
+                      {...(!isLast ? { ...hairline.bottom, borderBottomColor: "$color6" } : {})}
                     >
-                      <Text
-                        fontSize="$3"
-                        color="$color12"
-                        display="block"
-                        width="100%"
-                        textAlign={col.align ?? "left"}
-                      >
-                        {String(row[col.accessorKey] ?? "")}
-                      </Text>
+                      {renderCellContent(
+                        col,
+                        row,
+                        rowIndex,
+                        colIndex,
+                        knobProps.body,
+                        knobProps.sizeToken,
+                      )}
                     </Table.Cell>
                   ))}
                 </Table.Row>
@@ -230,7 +582,17 @@ export function SimpleTableDesktop({ data, columns, ...props }: SimpleTableDeskt
 // Main Component
 // ===========================================================================
 
-export function SimpleTable({ data, columns, layout = "auto", ...props }: SimpleTableProps) {
+export function SimpleTable({
+  data,
+  columns,
+  layout = "auto",
+  caption,
+  onRowPress,
+  rowLabel,
+  getRowId,
+  disabled,
+  ...props
+}: SimpleTableProps) {
   const { knobProps } = useResolvedKnobs({ component: "SimpleTable" });
   const { sm } = useMedia();
 
@@ -238,11 +600,30 @@ export function SimpleTable({ data, columns, layout = "auto", ...props }: Simple
   if (layout === "cards" || (layout === "auto" && sm === false)) {
     return (
       <View {...knobProps.containerRadius} {...props} testID="simple-table-cards">
-        <SimpleTableMobileCards data={data} columns={columns} />
+        <SimpleTableMobileCards
+          data={data}
+          columns={columns}
+          caption={caption}
+          onRowPress={onRowPress}
+          rowLabel={rowLabel}
+          getRowId={getRowId}
+          disabled={disabled}
+        />
       </View>
     );
   }
 
   // Desktop/tablet: standard table layout using Layer 1 primitives
-  return <SimpleTableDesktop data={data} columns={columns} {...props} />;
+  return (
+    <SimpleTableDesktop
+      data={data}
+      columns={columns}
+      caption={caption}
+      onRowPress={onRowPress}
+      rowLabel={rowLabel}
+      getRowId={getRowId}
+      disabled={disabled}
+      {...props}
+    />
+  );
 }