@rovula/ui 0.1.28 → 0.1.29

package/src/components/DataTable/DataTable.editing.types.ts

@@ -0,0 +1,192 @@
+import type { ColumnDef, Row, RowData } from "@tanstack/react-table";
+import type { Options } from "@/components/Dropdown/Dropdown";
+
+// ---------------------------------------------------------------------------
+// Editing display / trigger modes
+// ---------------------------------------------------------------------------
+
+export type EditDisplayMode = "cell" | "row";
+export type EditTrigger = "click" | "doubleClick";
+
+// ---------------------------------------------------------------------------
+// Column-level editing extensions
+// ---------------------------------------------------------------------------
+
+export type EditableColumnDef<
+  TData extends RowData = RowData,
+  TValue = unknown,
+> = ColumnDef<TData, TValue> & {
+  /**
+   * Enable inline editing for this column.
+   * - `true` — always editable
+   * - `(row) => boolean` — conditionally editable (e.g. dependent fields)
+   */
+  enableEditing?: boolean | ((row: Row<TData>) => boolean);
+
+  /**
+   * Which built-in editor to render.
+   * - `"text"` — `TextInput` (default when `enableEditing` is truthy)
+   * - `"select"` — `Dropdown`
+   * - `"number"` — `NumberInput`
+   * - `"checkbox"` — `Checkbox`
+   * - `"custom"` — user-provided renderer via `editCustomCell`
+   */
+  editVariant?: "text" | "select" | "number" | "checkbox" | "custom";
+
+  /** Props forwarded to the `TextInput` editor (variant `"text"`). */
+  editTextProps?: {
+    placeholder?: string;
+  };
+
+  /** Props forwarded to the `Dropdown` editor (variant `"select"`). */
+  editSelectProps?: {
+    options: Options[] | ((row: Row<TData>) => Options[]);
+    placeholder?: string;
+  };
+
+  /** Props forwarded to the `NumberInput` editor (variant `"number"`). */
+  editNumberProps?: {
+    placeholder?: string;
+    min?: number;
+    max?: number;
+    step?: number;
+    precision?: number;
+    allowDecimal?: boolean;
+    allowNegative?: boolean;
+  };
+
+  /** Props forwarded to the `Checkbox` editor (variant `"checkbox"`). */
+  editCheckboxProps?: {
+    label?: string;
+  };
+
+  /**
+   * Render function for a fully custom edit cell (variant `"custom"`).
+   *
+   * Receives the current row and a `commit` callback. Call `commit(rawValue)`
+   * to persist the change — the engine will run `onCommit` / `buildPatch`
+   * as usual.
+   *
+   * ```tsx
+   * editCustomCell: (row, { commit, errorMessage }) => (
+   *   <MyColorPicker
+   *     value={row.original.color}
+   *     onChange={(c) => commit(c)}
+   *     error={errorMessage}
+   *   />
+   * )
+   * ```
+   */
+  editCustomCell?: (
+    row: Row<TData>,
+    ctx: {
+      /** Persist the edited value — runs `onCommit` / `buildPatch` as usual. */
+      commit: (rawValue: string) => void;
+      /** Exit edit mode without committing (same as pressing Escape). */
+      blur: () => void;
+      columnId: string;
+      autoFocus: boolean;
+      errorMessage?: string;
+      onKeyDown?: (e: React.KeyboardEvent<HTMLElement>) => void;
+    },
+  ) => React.ReactNode;
+
+  /**
+   * Return an error message for the current cell value to display inline
+   * validation feedback. Return `undefined` or empty string when valid.
+   */
+  editError?: (row: Row<TData>) => string | undefined;
+
+  /**
+   * Build a custom `Partial<TData>` patch from the raw committed value.
+   * When omitted the engine defaults to `{ [columnId]: rawValue }`.
+   *
+   * Use this for dependent-field resets, value transforms, etc.
+   *
+   * ```ts
+   * onCommit: (_row, value) => ({
+   *   dataCategory: value,
+   *   dataType: "", format: "", source: "",
+   * })
+   * ```
+   */
+  onCommit?: (row: Row<TData>, value: string) => Partial<TData>;
+
+  /**
+   * When `true`, a cell whose `enableEditing` returns `false` renders a
+   * **disabled** TextInput / Dropdown (matching `editVariant`) instead of
+   * falling back to `displayCell` or plain text.
+   */
+  editShowDisabledField?: boolean;
+
+  /**
+   * Custom preview renderer shown when the cell is **not** in edit mode.
+   * Defaults to the plain string value of `row.original[key]`.
+   */
+  displayCell?: (row: Row<TData>) => React.ReactNode;
+};
+
+// ---------------------------------------------------------------------------
+// Table-level editing props (merged into DataTableProps)
+// ---------------------------------------------------------------------------
+
+export interface DataTableEditingProps<TData extends RowData = RowData> {
+  /** Master switch — set `true` to enable editing features. */
+  enableEditing?: boolean;
+
+  /** How editing is activated visually. @default "cell" */
+  editDisplayMode?: EditDisplayMode;
+
+  /** Gesture that enters edit mode. @default "click" */
+  editTrigger?: EditTrigger;
+
+  /**
+   * Called every time a cell commits a new value.  The `patch` object is
+   * built from the column's `commitResets` / `mapCommitValue` or defaults
+   * to `{ [columnId]: rawValue }`.
+   */
+  onCellCommit?: (
+    rowId: string,
+    columnId: string,
+    patch: Partial<TData>,
+  ) => void;
+
+  /**
+   * Rows that return `true` render their editable columns in edit mode
+   * **permanently** (e.g. an "add" footer row).
+   */
+  alwaysEditing?: (row: Row<TData>) => boolean;
+
+  /**
+   * When `true` (the default when `enableEditing` is set), Tab / Shift+Tab
+   * inside an editing cell moves focus to the next / previous editable
+   * column in the same row.
+   */
+  enableCellTabTraversal?: boolean;
+
+  /**
+   * Explicit ordered list of column ids for Tab traversal.  When omitted
+   * the engine auto-detects editable columns in definition order.
+   */
+  editableColumnIds?: string[];
+}
+
+// ---------------------------------------------------------------------------
+// Internal editing context (shared between engine and DataTable render)
+// ---------------------------------------------------------------------------
+
+export interface EditingState {
+  editingRowId: string | null;
+  editingCell: { rowId: string; columnId: string } | null;
+  editDisplayMode: EditDisplayMode;
+  editTrigger: EditTrigger;
+  requestRowEdit: (rowId: string) => void;
+  requestCellEdit: (rowId: string, columnId: string) => void;
+  clearEdit: () => void;
+  onFieldBlur: (rowId: string, columnId: string) => void;
+  moveCellEdit: (
+    rowId: string,
+    fromColumnId: string,
+    delta: -1 | 1,
+  ) => "moved" | "exited";
+}