@multiplatform.one/table 6.1.0 → 6.3.0

package/src/components/TableInput/index.tsx

@@ -1,8 +1,37 @@
+/**
+ * TableInput — the child-table field (the forms↔table bridge).
+ *
+ * Follows the forms field contract (agent-os/standards/frontend/field-architecture.md):
+ * - Canonical change prop is `onChange(rows)` (LC-14 ONCHANGE-CANONICAL);
+ *   `onDataChange(rows)` survives as a deprecated alias that fires from the
+ *   same emit site, and `onCellChange(rowIndex, columnId, value)` is a
+ *   per-cell companion that fires before the row payload.
+ * - Three-branch render: skeleton → standalone → form-integrated `<Field>`.
+ *   The form branch resolves the form from props or `<Form>` context via
+ *   `useFormField()`, registers `useResolvedValidators(required, validators)`,
+ *   renders rows from `field.state.value`, and commits every mutation through
+ *   `field.handleChange`.
+ * - TableInput is otherwise fully controlled: standalone edits do not persist
+ *   without `onChange` (see the UncontrolledStatic story).
+ *
+ * Row identity: added rows get a collision-free generated `id`. TableInput
+ * does not maintain Frappe-style `idx` bookkeeping — order is the array
+ * order; consumers that need `idx` seed it via `defaultRow` or renumber in
+ * their own layer (frappe-ui).
+ */
+
 import { useCallback, useMemo } from "react";
-import { Field, useForm } from "@tanstack/react-form";
+import {
+  Button,
+  Field,
+  Skeleton,
+  useFormField,
+  useResolvedValidators,
+  type AnyFormApi,
+} from "@multiplatform.one/forms";
 import { flexRender, getCoreRowModel, useReactTable, type ColumnDef } from "@tanstack/react-table";
-import { Button } from "@multiplatform.one/forms";
 import { TrashIcon, PlusIcon } from "@phosphor-icons/react";
+import { useTranslation } from "react-i18next";
 import { Text, XStack, YStack } from "tamagui";
 import type {
   DataTableColumn,
@@ -12,20 +41,30 @@ import type {
 } from "../../types";
 import { Table } from "@multiplatform.one/table-primitives";
 import { DataTableCell } from "../DataTableCell";
+import { withInterp } from "../../utils/withInterp";
+import { generateRowId, isEmptyRows, SKELETON_ROW_COUNT } from "./shared";
 
 export interface TableInputProps<TData extends DataTableData = DataTableData> {
-  /** Data array for the table */
-  data: TData[];
+  /** Data array for the table (ignored in favor of form state in the form branch) */
+  data?: TData[];
   /** Column definitions with field type for cell rendering */
   columns: DataTableColumn<TData>[];
-  /** Callback when data changes */
+  /** Canonical change callback — fires with the full row array on every mutation (LC-14) */
+  onChange?: (rows: TData[]) => void;
+  /** @deprecated Alias for `onChange`; fires from the same emit site */
   onDataChange?: (data: TData[]) => void;
-  /** Callback when a specific cell changes */
+  /** Callback when a specific cell changes (fires before onChange/onDataChange) */
   onCellChange?: (rowIndex: number, columnId: string, value: unknown) => void;
   /** Form field name for TanStack Form integration */
   name?: string;
-  /** TanStack Form instance */
-  form?: ReturnType<typeof useForm>;
+  /** TanStack Form instance (resolved from `<Form>` context when omitted) */
+  form?: AnyFormApi;
+  /** Validators registered on the form field (form branch only) */
+  validators?: Record<string, unknown>;
+  /** Adds a required validator (form branch only) */
+  required?: boolean;
+  /** Renders a skeleton placeholder table instead of data */
+  skeleton?: boolean;
   /** Whether the table is read-only */
   readOnly?: boolean;
   /** Whether to show row numbers */
@@ -47,12 +86,16 @@ export interface TableInputProps<TData extends DataTableData = DataTableData> {
 }
 
 export function TableInput<TData extends DataTableData = DataTableData>({
-  data,
+  data = [],
   columns,
+  onChange,
   onDataChange,
   onCellChange,
   name,
-  form,
+  form: formProp,
+  validators,
+  required,
+  skeleton = false,
   readOnly = false,
   showRowNumbers = true,
   showAddRow = true,
@@ -60,43 +103,142 @@ export function TableInput<TData extends DataTableData = DataTableData>({
   minRows,
   maxRows,
   defaultRow,
-  emptyMessage = "No rows",
-  "aria-label": ariaLabel = "Table input",
+  emptyMessage,
+  "aria-label": ariaLabel,
 }: TableInputProps<TData>) {
+  const { t } = useTranslation();
+  const { resolvedForm } = useFormField({ form: formProp });
+  const resolvedAriaLabel = ariaLabel ?? t("Table input");
+  const resolvedValidators = useResolvedValidators(
+    required,
+    validators,
+    resolvedAriaLabel,
+    name,
+    isEmptyRows,
+  );
+
+  // Single emit site: canonical onChange plus deprecated alias (LC-14).
+  const emitChange = useCallback(
+    (next: TData[]) => {
+      onChange?.(next);
+      onDataChange?.(next);
+    },
+    [onChange, onDataChange],
+  );
+
+  const innerProps = {
+    columns,
+    onCellChange,
+    skeleton,
+    readOnly,
+    showRowNumbers,
+    showAddRow,
+    showDeleteRow,
+    minRows,
+    maxRows,
+    defaultRow,
+    emptyMessage: emptyMessage ?? t("No rows"),
+    ariaLabel: resolvedAriaLabel,
+    t,
+  };
+
+  // Generic JSX (`<TableInputInner<TData> …/>`) breaks one-dev's source
+  // annotation transform; instantiate the type argument outside JSX instead.
+  const Inner = TableInputInner<TData>;
+
+  // Branch 1: skeleton loading
+  if (skeleton) {
+    return <Inner rows={[]} commit={emitChange} {...innerProps} />;
+  }
+
+  // Branch 2: standalone (controlled via data/onChange)
+  if (!resolvedForm || !name) {
+    return <Inner rows={data} commit={emitChange} {...innerProps} />;
+  }
+
+  // Branch 3: form-integrated (TanStack Form)
+  return (
+    <Field form={resolvedForm} name={name} validators={resolvedValidators}>
+      {(field) => (
+        <Inner
+          // Form state wins; the `data` fallback covers only the uninitialized
+          // instant before the field registers. A `data` prop diverging from
+          // form state is never load-bearing here (D-16 rider).
+          rows={(field.state.value as TData[] | undefined) ?? data}
+          commit={(next) => {
+            field.handleChange(next);
+            emitChange(next);
+          }}
+          {...innerProps}
+        />
+      )}
+    </Field>
+  );
+}
+
+interface TableInputInnerProps<TData extends DataTableData> {
+  rows: TData[];
+  commit: (next: TData[]) => void;
+  columns: DataTableColumn<TData>[];
+  onCellChange?: (rowIndex: number, columnId: string, value: unknown) => void;
+  skeleton: boolean;
+  readOnly: boolean;
+  showRowNumbers: boolean;
+  showAddRow: boolean;
+  showDeleteRow: boolean;
+  minRows?: number;
+  maxRows?: number;
+  defaultRow?: Partial<TData>;
+  emptyMessage: string;
+  ariaLabel: string;
+  t: (key: string, options?: Record<string, unknown>) => string;
+}
+
+function TableInputInner<TData extends DataTableData>({
+  rows,
+  commit,
+  columns,
+  onCellChange,
+  skeleton,
+  readOnly,
+  showRowNumbers,
+  showAddRow,
+  showDeleteRow,
+  minRows,
+  maxRows,
+  defaultRow,
+  emptyMessage,
+  ariaLabel,
+  t,
+}: TableInputInnerProps<TData>) {
   const handleCellChange = useCallback(
     (rowIndex: number, columnId: string, value: unknown) => {
-      if (onCellChange) {
-        onCellChange(rowIndex, columnId, value);
-      }
-      if (onDataChange) {
-        const newData = [...data];
-        newData[rowIndex] = {
-          ...newData[rowIndex],
-          [columnId]: value,
-        };
-        onDataChange(newData);
-      }
+      onCellChange?.(rowIndex, columnId, value);
+      const newData = [...rows];
+      newData[rowIndex] = {
+        ...newData[rowIndex],
+        [columnId]: value,
+      };
+      commit(newData);
     },
-    [data, onDataChange, onCellChange],
+    [rows, commit, onCellChange],
   );
 
   const handleAddRow = useCallback(() => {
-    if (maxRows && data.length >= maxRows) return;
+    if (maxRows && rows.length >= maxRows) return;
     const newRow = {
-      id: `row-${Date.now()}`,
-      idx: data.length + 1,
+      id: generateRowId(),
       ...defaultRow,
     } as unknown as TData;
-    onDataChange?.([...data, newRow]);
-  }, [data, onDataChange, defaultRow, maxRows]);
+    commit([...rows, newRow]);
+  }, [rows, commit, defaultRow, maxRows]);
 
   const handleDeleteRow = useCallback(
     (rowIndex: number) => {
-      if (minRows && data.length <= minRows) return;
-      const newData = data.filter((_, index) => index !== rowIndex);
-      onDataChange?.(newData);
+      if (minRows && rows.length <= minRows) return;
+      commit(rows.filter((_, index) => index !== rowIndex));
     },
-    [data, onDataChange, minRows],
+    [rows, commit, minRows],
   );
 
   const tableColumns = useMemo(() => {
@@ -137,6 +279,7 @@ export function TableInput<TData extends DataTableData = DataTableData>({
               fieldProps={fieldProps}
               readOnly={readOnly}
               columnId={columnId}
+              columnLabel={typeof col.header === "string" ? col.header : undefined}
               rowIndex={row.index}
               rowData={row.original}
             />
@@ -152,14 +295,16 @@ export function TableInput<TData extends DataTableData = DataTableData>({
         header: "",
         size: 50,
         cell: ({ row }) => {
-          const canDelete = !minRows || data.length > minRows;
+          const canDelete = !minRows || rows.length > minRows;
           return (
             <Button
               size="$2"
               outlined
               onPress={() => handleDeleteRow(row.index)}
               disabled={!canDelete}
-              aria-label="Delete row"
+              aria-label={withInterp(t("Delete row {{row}}", { row: row.index + 1 }), {
+                row: row.index + 1,
+              })}
             >
               <TrashIcon size={16} color="$red10" />
             </Button>
@@ -176,26 +321,51 @@ export function TableInput<TData extends DataTableData = DataTableData>({
     readOnly,
     handleCellChange,
     handleDeleteRow,
-    data.length,
+    rows.length,
     minRows,
+    t,
   ]);
 
   const table = useReactTable({
-    data,
+    data: rows,
     columns: tableColumns,
     getCoreRowModel: getCoreRowModel(),
+    // Stable row identity: keeps in-cell editor drafts pinned to their data
+    // row across deletes instead of following the positional index.
+    getRowId: (row, index) => String((row as DataTableData).id ?? index),
   });
 
-  const canAddRow = !maxRows || data.length < maxRows;
+  const canAddRow = !maxRows || rows.length < maxRows;
+  // The primitives table renders CSS-table boxes (divs), so colSpan cannot
+  // span the empty-state message across columns. With no body rows to align,
+  // the empty (and skeleton-free) state flips the table to flex layout where
+  // a single auto-width cell genuinely fills the row.
+  const isEmpty = !skeleton && rows.length === 0;
 
-  const renderContent = () => (
+  return (
     <YStack gap="$2">
-      <Table aria-label={ariaLabel}>
+      <Table
+        aria-label={ariaLabel}
+        aria-busy={skeleton || undefined}
+        {...(isEmpty ? { displayMode: "flex" as const } : null)}
+      >
         <Table.Head>
           {table.getHeaderGroups().map((headerGroup) => (
             <Table.Row key={headerGroup.id}>
               {headerGroup.headers.map((header) => (
-                <Table.HeaderCell key={header.id} style={{ width: header.getSize() }}>
+                <Table.HeaderCell
+                  key={header.id}
+                  style={{
+                    width: header.getSize(),
+                    // Flex-mode headers don't get fixed-layout stretch; let
+                    // data columns grow so the header strip fills the row.
+                    ...(isEmpty &&
+                    header.column.id !== "_rowNumber" &&
+                    header.column.id !== "_actions"
+                      ? { flexGrow: 1 }
+                      : null),
+                  }}
+                >
                   {header.isPlaceholder
                     ? null
                     : flexRender(header.column.columnDef.header, header.getContext())}
@@ -205,9 +375,25 @@ export function TableInput<TData extends DataTableData = DataTableData>({
           ))}
         </Table.Head>
         <Table.Body>
-          {table.getRowModel().rows.length === 0 ? (
+          {skeleton ? (
+            Array.from({ length: SKELETON_ROW_COUNT }, (_, rowIndex) => (
+              <Table.Row key={`skeleton-${rowIndex}`}>
+                {table.getAllLeafColumns().map((column) => (
+                  <Table.Cell key={column.id}>
+                    {column.id === "_actions" ? null : (
+                      <Skeleton
+                        variant="rounded"
+                        width={column.id === "_rowNumber" ? 16 : "70%"}
+                        height={16}
+                      />
+                    )}
+                  </Table.Cell>
+                ))}
+              </Table.Row>
+            ))
+          ) : isEmpty ? (
             <Table.Row>
-              <Table.Cell style={{ textAlign: "center" }}>
+              <Table.Cell cellWidth="auto" justifyContent="center">
                 <Text color="$gray11">{emptyMessage}</Text>
               </Table.Cell>
             </Table.Row>
@@ -225,7 +411,7 @@ export function TableInput<TData extends DataTableData = DataTableData>({
         </Table.Body>
       </Table>
 
-      {showAddRow && !readOnly && (
+      {showAddRow && !readOnly && !skeleton && (
         <XStack>
           <Button
             size="$2"
@@ -234,23 +420,17 @@ export function TableInput<TData extends DataTableData = DataTableData>({
             disabled={!canAddRow}
             icon={<PlusIcon size={16} />}
           >
-            Add Row
+            {t("Add Row")}
           </Button>
         </XStack>
       )}
+      {skeleton && showAddRow && !readOnly && (
+        <XStack>
+          <Skeleton variant="rounded" width={100} height={28} />
+        </XStack>
+      )}
     </YStack>
   );
-
-  // If form integration is requested, wrap with Field
-  if (form && name) {
-    return (
-      <Field name={name} form={form}>
-        {() => renderContent()}
-      </Field>
-    );
-  }
-
-  return renderContent();
 }
 
 export type { DataTableColumn, DataTableData, DataTableField, DataTableFieldProps };

package/src/components/TableInput/shared.ts

@@ -0,0 +1,20 @@
+/** Shared TableInput internals (web + native). */
+
+let rowIdCounter = 0;
+
+/**
+ * Collision-free generated row id. `Date.now()` alone collides when two rows
+ * are added in the same millisecond (double-click on Add Row); the monotonic
+ * suffix keeps ids unique within a session.
+ */
+export function generateRowId(): string {
+  rowIdCounter += 1;
+  return `row-${Date.now()}-${rowIdCounter}`;
+}
+
+/** Rows rendered by the skeleton branch. */
+export const SKELETON_ROW_COUNT = 3;
+
+/** Required-validator emptiness for row arrays (default only catches null/""). */
+export const isEmptyRows = (value: unknown): boolean =>
+  value === null || value === undefined || (Array.isArray(value) && value.length === 0);