@multiplatform.one/table 6.1.0 → 6.3.0

package/src/components/TableInput/TableInput.stories.tsx

@@ -1,24 +1,282 @@
-import type { Meta } from "@storybook/react-native-web-vite";
-import { YStack, Text } from "tamagui";
+/**
+ * TableInput — the table itself is a field (Frappe child-table contract).
+ *
+ * Stories cover: controlled data flow (canonical onChange + deprecated
+ * onDataChange alias + onCellChange), row add/remove with min/max limits,
+ * mixed field types per column, read-only mode, empty state, skeleton
+ * branch, and TanStack Form integration with label/error/required wiring
+ * via FieldLayout.
+ *
+ * NOTE: TableInput is fully controlled in standalone mode — it has no
+ * internal data buffer. Without onChange, edits do not persist (see
+ * UncontrolledStatic). With `form`+`name` (or inside `<Form>`), the field
+ * branch binds rows to form state via field.handleChange; label and error
+ * presentation come from FieldLayout (see InsideForm, or use ChildTable).
+ */
 
-const meta: Meta = {
+import type { Meta, StoryObj } from "@storybook/react-native-web-vite";
+import { fn } from "storybook/test";
+import { useForm } from "@tanstack/react-form";
+import { FieldLayout } from "@multiplatform.one/forms";
+import React from "react";
+import { Text, View, YStack } from "tamagui";
+import type { DataTableColumn, DataTableData } from "../../types";
+import { TableInput } from "./index";
+
+interface LineItem extends DataTableData {
+  id: string;
+  item: string;
+  qty: number;
+  rate: number;
+  status: string;
+  urgent: boolean;
+  deliverBy: string;
+}
+
+const initialRows: LineItem[] = [
+  {
+    id: "row-1",
+    item: "Steel bracket",
+    qty: 12,
+    rate: 4.5,
+    status: "ordered",
+    urgent: false,
+    deliverBy: "2024-11-20",
+  },
+  {
+    id: "row-2",
+    item: "M6 bolts (100pk)",
+    qty: 3,
+    rate: 11.25,
+    status: "draft",
+    urgent: true,
+    deliverBy: "2024-11-12",
+  },
+  {
+    id: "row-3",
+    item: "Powder coat, black",
+    qty: 1,
+    rate: 89,
+    status: "received",
+    urgent: false,
+    deliverBy: "2024-12-01",
+  },
+];
+
+// DG-CTRL-01: >5 options so the per-row status Select doesn't trip the
+// `select-too-few-options` guardrail (UX-P19).
+const statusOptions = [
+  { label: "Draft", value: "draft" },
+  { label: "Ordered", value: "ordered" },
+  { label: "Received", value: "received" },
+  { label: "Cancelled", value: "cancelled" },
+  { label: "Shipped", value: "shipped" },
+  { label: "Returned", value: "returned" },
+];
+
+const basicColumns: DataTableColumn<LineItem>[] = [
+  { accessorKey: "item", header: "Item (input)", field: "input" },
+  { accessorKey: "qty", header: "Qty (stepper)", field: "stepper", fieldProps: { min: 0 } },
+  {
+    accessorKey: "rate",
+    header: "Rate (currency)",
+    field: "stepper",
+    fieldProps: { min: 0, step: 0.25, precision: 2, currency: "USD" },
+  },
+  {
+    accessorKey: "status",
+    header: "Status (select)",
+    field: "select",
+    fieldProps: { options: statusOptions },
+  },
+];
+
+const mixedColumns: DataTableColumn<LineItem>[] = [
+  ...basicColumns,
+  { accessorKey: "urgent", header: "Urgent (checkbox)", field: "checkbox" },
+  { accessorKey: "deliverBy", header: "Deliver by (date)", field: "datepicker" },
+];
+
+const meta: Meta<typeof TableInput> = {
   title: "Table/TableInput",
+  component: TableInput,
   parameters: {
     status: { type: "stable" },
+    layout: "fullscreen",
+  },
+  args: {
+    onChange: fn(),
+    onDataChange: fn(),
+    onCellChange: fn(),
+  },
+  argTypes: {
+    readOnly: { control: "boolean" },
+    showRowNumbers: { control: "boolean" },
+    showAddRow: { control: "boolean" },
+    showDeleteRow: { control: "boolean" },
+    minRows: { control: { type: "number", min: 0 } },
+    maxRows: { control: { type: "number", min: 0 } },
+    emptyMessage: { control: "text" },
   },
+  decorators: [
+    (Story) => (
+      <View flex={1} padding="$4" width="100%">
+        <Story />
+      </View>
+    ),
+  ],
 };
 
 export default meta;
+type Story = StoryObj<typeof TableInput>;
+
+// ── Controlled harness ────────────────────────────────────────
+
+interface HarnessProps {
+  columns?: DataTableColumn<LineItem>[];
+  rows?: LineItem[];
+  onChange?: (rows: LineItem[]) => void;
+  onDataChange?: (data: LineItem[]) => void;
+  onCellChange?: (rowIndex: number, columnId: string, value: unknown) => void;
+  [key: string]: any;
+}
 
-export const Default = {
+const ControlledTableInput = ({
+  columns = basicColumns,
+  rows = initialRows,
+  onChange,
+  onDataChange,
+  onCellChange,
+  ...rest
+}: HarnessProps) => {
+  const [data, setData] = React.useState<LineItem[]>(rows);
+  return (
+    <YStack gap="$3">
+      <TableInput<LineItem>
+        data={data}
+        columns={columns}
+        // Canonical onChange drives persistence; the deprecated onDataChange
+        // alias still fires from the same emit site (LC-14) and logs to the
+        // actions panel alongside it.
+        onChange={(next) => {
+          setData(next);
+          onChange?.(next);
+        }}
+        onDataChange={onDataChange}
+        onCellChange={onCellChange}
+        {...rest}
+      />
+      <Text testID="tableinput-data" fontSize="$2" color="$color10" fontFamily="$mono">
+        rows: {data.length} · data: {JSON.stringify(data)}
+      </Text>
+    </YStack>
+  );
+};
+
+/**
+ * Controlled TableInput — edits, row adds, and row deletes all commit through
+ * onDataChange. The committed data is echoed below the table (testID
+ * "tableinput-data") so persistence is verifiable.
+ */
+export const Default: Story = {
   name: "Main",
+  render: (args) => <ControlledTableInput {...(args as HarnessProps)} />,
+};
+
+/** Every column hosts a different field type — cells are fields. */
+export const MixedFieldTypes: Story = {
+  render: (args) => <ControlledTableInput {...(args as HarnessProps)} columns={mixedColumns} />,
+};
+
+/** Read-only mode: no add/delete affordances, cells render via FieldDisplay. */
+export const ReadOnly: Story = {
+  args: { readOnly: true },
+  render: (args) => <ControlledTableInput {...(args as HarnessProps)} columns={mixedColumns} />,
+};
+
+/** minRows=2 / maxRows=4: delete disables at 2 rows, add disables at 4. */
+export const RowLimits: Story = {
+  args: { minRows: 2, maxRows: 4 },
+  render: (args) => <ControlledTableInput {...(args as HarnessProps)} />,
+};
+
+/** Empty data renders emptyMessage; Add Row seeds the first row. */
+export const Empty: Story = {
+  args: { emptyMessage: "No line items yet" },
+  render: (args) => <ControlledTableInput {...(args as HarnessProps)} rows={[]} />,
+};
+
+/**
+ * TableInput has NO internal state — without onChange (or the deprecated
+ * onDataChange alias), cell edits and row add/delete are no-ops. This story
+ * documents that contract.
+ */
+export const UncontrolledStatic: Story = {
   render: () => (
-    <YStack padding="$4">
+    <YStack gap="$3">
+      <TableInput<LineItem> data={initialRows} columns={basicColumns} />
       <Text fontSize="$2" color="$color10">
-        TableInput is an editable table component backed by TanStack Form. It supports inline
-        editing, row add/remove, and field validation. See DataTable stories for integration
-        context.
+        No onChange wired: typing, Add Row, and Delete Row do not persist. TableInput is fully
+        controlled.
       </Text>
     </YStack>
   ),
 };
+
+/** Skeleton branch: placeholder rows in the real table geometry. */
+export const SkeletonLoading: Story = {
+  render: () => <TableInput<LineItem> skeleton data={[]} columns={basicColumns} />,
+};
+
+// ── Form integration: the table itself is a field ─────────────
+
+const InsideFormStory = () => {
+  const form = useForm({
+    defaultValues: { lineItems: initialRows },
+  });
+  const [rows, setRows] = React.useState<LineItem[]>(initialRows);
+  const error =
+    rows.length === 0
+      ? "At least one line item is required"
+      : rows.some((row) => !row.item)
+        ? "Every row needs an item name"
+        : undefined;
+
+  return (
+    <YStack gap="$4" maxWidth={900}>
+      <FieldLayout
+        id="line-items"
+        label="Line items"
+        required
+        error={error}
+        helperText="Child table field — every cell is a form field, and the table itself binds to the parent form."
+      >
+        <TableInput<LineItem>
+          form={form as any}
+          name="lineItems"
+          data={rows}
+          columns={basicColumns}
+          minRows={0}
+          // Form binding is built in: every mutation commits through
+          // field.handleChange. The canonical onChange fires alongside it —
+          // here it just mirrors rows into local state for the error demo.
+          onChange={(next) => setRows(next)}
+          aria-label="Line items"
+        />
+      </FieldLayout>
+      <Text testID="form-value" fontSize="$2" color="$color10" fontFamily="$mono">
+        form.lineItems: {JSON.stringify(form.state.values.lineItems?.map((row) => row.item))}
+      </Text>
+    </YStack>
+  );
+};
+
+/**
+ * TableInput as a field inside a TanStack form: label, required marker, and
+ * error wiring via FieldLayout; rows bind into form state through the
+ * built-in field branch (field.handleChange). Delete all rows to trigger
+ * the required error.
+ */
+export const InsideForm: Story = {
+  render: () => <InsideFormStory />,
+};

package/src/components/TableInput/index.native.tsx

@@ -1,8 +1,26 @@
+/**
+ * TableInput (native) — the child-table field (the forms↔table bridge).
+ *
+ * Mirrors the web contract exactly (see ./index.tsx):
+ * - Canonical `onChange(rows)` with deprecated `onDataChange` alias firing
+ *   from the same emit site (LC-14), `onCellChange` per-cell companion.
+ * - Three-branch render: skeleton → standalone → form-integrated `<Field>`
+ *   with `useFormField()` context resolution and resolved validators.
+ * - No Frappe-style `idx` bookkeeping — array order is row order.
+ */
+
 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 { FlashList } from "@shopify/flash-list";
-import { Button } from "@multiplatform.one/forms";
 import { TrashIcon, PlusIcon } from "@phosphor-icons/react";
+import { useTranslation } from "react-i18next";
 import { Text, View, XStack, YStack } from "tamagui";
 import type {
   DataTableColumn,
@@ -11,20 +29,30 @@ import type {
   DataTableField,
 } from "../../types";
 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 */
@@ -46,12 +74,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,
@@ -59,46 +91,143 @@ 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
+          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()}`,
+      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 canAddRow = !maxRows || data.length < maxRows;
-  const canDelete = !minRows || data.length > (minRows || 0);
+  const canAddRow = !maxRows || rows.length < maxRows;
+  const canDelete = !minRows || rows.length > (minRows || 0);
 
   const columnIds = useMemo(
     () =>
@@ -164,6 +293,7 @@ export function TableInput<TData extends DataTableData = DataTableData>({
               fieldProps={fieldProps}
               readOnly={readOnly}
               columnId={columnId}
+              columnLabel={typeof col.header === "string" ? col.header : undefined}
               rowIndex={index}
               rowData={item}
             />
@@ -177,7 +307,9 @@ export function TableInput<TData extends DataTableData = DataTableData>({
             outlined
             onPress={() => handleDeleteRow(index)}
             disabled={!canDelete}
-            aria-label="Delete row"
+            aria-label={withInterp(t("Delete row {{row}}", { row: index + 1 }), {
+              row: index + 1,
+            })}
           >
             <TrashIcon size={16} color="$red10" />
           </Button>
@@ -186,32 +318,62 @@ export function TableInput<TData extends DataTableData = DataTableData>({
     </XStack>
   );
 
+  const renderSkeletonRows = () => (
+    <YStack>
+      {Array.from({ length: SKELETON_ROW_COUNT }, (_, rowIndex) => (
+        <XStack
+          key={`skeleton-${rowIndex}`}
+          borderBottomWidth={1}
+          borderBottomColor="$borderColor"
+          paddingVertical="$2"
+          paddingHorizontal="$2"
+          alignItems="center"
+        >
+          {showRowNumbers && (
+            <View width={40} paddingHorizontal="$1">
+              <Skeleton variant="rounded" width={16} height={16} />
+            </View>
+          )}
+          {columns.map((_, colIndex) => (
+            <View key={columnIds[colIndex]} flex={1} paddingHorizontal="$1">
+              <Skeleton variant="rounded" width="70%" height={16} />
+            </View>
+          ))}
+          {showDeleteRow && !readOnly && <View width={50} />}
+        </XStack>
+      ))}
+    </YStack>
+  );
+
   const renderEmpty = () => (
     <View padding="$4" alignItems="center">
       <Text color="$gray11">{emptyMessage}</Text>
     </View>
   );
 
-  const renderContent = () => (
+  return (
     <YStack
       borderWidth={1}
       borderColor="$borderColor"
       borderRadius="$2"
       overflow="hidden"
       accessibilityLabel={ariaLabel}
+      aria-busy={skeleton || undefined}
     >
       {renderHeader()}
-      {data.length === 0 ? (
+      {skeleton ? (
+        renderSkeletonRows()
+      ) : rows.length === 0 ? (
         renderEmpty()
       ) : (
         <FlashList
-          data={data}
+          data={rows}
           renderItem={renderRow}
           drawDistance={200}
           keyExtractor={(item, index) => (item as DataTableData).id?.toString() || `row-${index}`}
         />
       )}
-      {showAddRow && !readOnly && (
+      {showAddRow && !readOnly && !skeleton && (
         <XStack padding="$2" borderTopWidth={1} borderTopColor="$borderColor">
           <Button
             size="$2"
@@ -220,23 +382,12 @@ export function TableInput<TData extends DataTableData = DataTableData>({
             disabled={!canAddRow}
             icon={<PlusIcon size={16} />}
           >
-            Add Row
+            {t("Add Row")}
           </Button>
         </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 };