@vuu-ui/vuu-data-editing 5.0.0-alpha.2 → 5.0.0-alpha.3

package/types/useConfirmDiscard.d.ts

@@ -0,0 +1,23 @@
+export interface ConfirmDiscardHookProps {
+    /** @default "Discard changes?" */
+    title?: string;
+    /** @default "You have unsaved changes. Discard them?" */
+    message?: string;
+    /** @default "Discard" */
+    confirmButtonLabel?: string;
+    /** @default "Keep editing" */
+    cancelButtonLabel?: string;
+}
+/**
+ * Returns a function that asks the user to confirm discarding unsaved
+ * changes. Resolves true if the user confirms. Pass it to
+ * `EditButtons.confirmCancel`, or call it before changing selection or
+ * closing a form.
+ *
+ * Requires a `ModalProvider` in scope.
+ *
+ * @example
+ * const confirmDiscard = useConfirmDiscard();
+ * <EditButtons confirmCancel={confirmDiscard} ... />
+ */
+export declare const useConfirmDiscard: ({ cancelButtonLabel, confirmButtonLabel, message, title, }?: ConfirmDiscardHookProps) => () => Promise<boolean>;

package/types/useCustomEditField.d.ts

@@ -0,0 +1,51 @@
+import type { VuuRowDataItemType } from "@vuu-ui/vuu-protocol-types";
+import type { EditSession, EditSessionValue } from "./EditSession";
+export interface CustomEditFieldHookProps<T extends EditSessionValue> {
+    /** Key of the row being edited. */
+    rowKey: string;
+    /** The column the value is saved to. */
+    name: string;
+    /**
+     * The saved value. The field resets to this value when it changes, and
+     * when the edit session ends.
+     */
+    originalValue: T | undefined;
+    /**
+     * Compares an edited value with `originalValue`. When equal, the edit is
+     * reverted rather than committed, so the session is no longer dirty.
+     * @default Object.is
+     */
+    equals?: (a: T, b: T) => boolean;
+    /**
+     * Converts the value to the scalar sent to the server. Required when `T`
+     * is an object.
+     */
+    serialize?: (value: T) => VuuRowDataItemType;
+    /** Defaults to the session from the enclosing DataEditingProvider. */
+    editSession?: EditSession;
+    /** Called when a commit fails. */
+    onError?: (error: Error) => void;
+}
+/**
+ * Adapts a non-standard editor (a picker, a list editor, any custom control)
+ * to an EditSession. Tracks the current and original values, reverts the
+ * edit when the user restores the original value, and commits to the session
+ * table with `serialize(value)`.
+ *
+ * @example
+ * const { value, setValue, isDirty } = useCustomEditField({
+ *   rowKey: dataRow.key,
+ *   name: "permissions",
+ *   originalValue: permissions,
+ *   equals: (a, b) => a.equals(b),
+ *   serialize: (p) => JSON.stringify(p.toJSON()),
+ * });
+ */
+export declare const useCustomEditField: <T extends EditSessionValue>({ editSession: editSessionProp, equals, name, onError, originalValue, rowKey, serialize, }: CustomEditFieldHookProps<T>) => {
+    committing: boolean;
+    error: Error | undefined;
+    isDirty: boolean;
+    reset: () => void;
+    setValue: (nextValue: T) => Promise<void>;
+    value: T | undefined;
+};

package/types/useEditForm.d.ts

@@ -0,0 +1,127 @@
+import type { DataSource, DeleteRowMode } from "@vuu-ui/vuu-data-types";
+import type { VuuRowDataItemType } from "@vuu-ui/vuu-protocol-types";
+import type { DataRow } from "@vuu-ui/vuu-table-types";
+import { EditSession, type EditSessionApi, type EditSessionValue, type RowDefaultDataItemValues } from "./EditSession";
+import { DirectEditSession } from "./DirectEditSession";
+import { type EditErrorHandler } from "./edit-errors";
+export type EditFormMode = "edit" | "create";
+/**
+ * Edit mode only.
+ * - `session`: edits are staged in a session table and applied on Save.
+ * - `direct`: each field is validated and sent to `dataSource` as it is
+ *   committed. There is nothing to save; `submit` just ends editing.
+ */
+export type EditFormEditModel = "session" | "direct";
+export type EditFormValues = Readonly<Record<string, EditSessionValue | undefined>>;
+/** Field name to error message. Return an empty object (or nothing) when valid. */
+export type EditFormFieldErrors = Readonly<Record<string, string>>;
+/**
+ * Cross-field validation run before the form is saved. Return error messages
+ * keyed by field name.
+ */
+export type EditFormValidator = (values: EditFormValues) => EditFormFieldErrors | undefined;
+export interface EditFormHookProps {
+    /** Source table data source. */
+    dataSource: DataSource;
+    /**
+     * The row being edited (edit mode). Its values, merged with any edits, are
+     * passed to `validate`.
+     */
+    dataRow?: DataRow;
+    /**
+     * `"edit"` edits the selected row(s) of `dataSource`. `"create"` adds a
+     * new row via an empty session table.
+     * @default "edit"
+     */
+    mode?: EditFormMode;
+    /** Create mode: the form's fields, in tab order. */
+    columns?: readonly string[];
+    /**
+     * Fields that must have a value. In create mode, defaults to `columns`. In
+     * direct edit mode, an empty value for one of these is not sent.
+     */
+    requiredColumns?: readonly string[];
+    /** @default "session" */
+    editModel?: EditFormEditModel;
+    /**
+     * Create mode only: add the new row to this session, owned by someone else
+     * (e.g. a table's edit session), rather than to a session of the form's
+     * own. Create then adds the row to the session without saving it; the
+     * owner saves or cancels the session.
+     */
+    editSession?: EditSession;
+    /**
+     * Edit mode only: whether the edit session is active. When omitted, edit
+     * mode is read from the nearest EditModeProvider. Create mode is always
+     * active while the form is mounted.
+     */
+    isEditMode?: boolean;
+    /** @default "soft" */
+    deleteMode?: DeleteRowMode;
+    /** @default "createSessionDataSource" */
+    editSessionApi?: EditSessionApi;
+    /** Default column values merged into the new row. Pass a stable reference. */
+    rowDefaults?: RowDefaultDataItemValues;
+    validate?: EditFormValidator;
+    /** Called once changes have been saved. */
+    onSaved?: () => void;
+    /** Called once the form has been cancelled. */
+    onCancelled?: () => void;
+    /** Called when begin, save or cancel fails. Defaults to console.error. */
+    onError?: EditErrorHandler;
+}
+/**
+ * Plain column values of a row. Table DataRows are Proxies with no own
+ * keys, so they cannot be spread; they serialize via `toJSON`.
+ */
+export declare const getDataRowValues: (dataRow: DataRow) => Record<string, VuuRowDataItemType>;
+/**
+ * Owns an EditSession for a form that edits one entity, or creates one.
+ *
+ * - edit mode copies the selected row into a session table (`"Selected"`).
+ * - create mode begins an empty session table (`"Empty"`) and stages field
+ *   values as a new-row draft. Render fields with
+ *   `dataRow={{ key: EditSession.newRowKey }}` and `deferNewRow`.
+ *
+ * Call `submit()` to validate and save, `cancel()` to discard. Wrap the form
+ * in a `DataEditingProvider` with the returned `fieldEditSession`.
+ *
+ * With `editModel: "direct"` each field is validated and sent as it is
+ * committed. With a shared `editSession` (create mode), Create adds the row
+ * to that session, which its owner saves.
+ */
+export declare const useEditForm: ({ columns, dataRow, dataSource, deleteMode, editModel, editSession: sharedEditSession, editSessionApi, isEditMode: isEditModeProp, mode, onCancelled, onError, onSaved, requiredColumns, rowDefaults, validate, }: EditFormHookProps) => {
+    canCancel: boolean;
+    editState: import("./EditSession").EditState;
+    inEditMode: boolean;
+    isActive: boolean;
+    isEnding: boolean;
+    isStarting: boolean;
+    lifecycle: import("./EditSession").EditLifecycle;
+    newRowState: import("./EditSession").NewRowState;
+    canSave: boolean;
+    cancel: () => Promise<void>;
+    /**
+     * The row being edited, a new-row placeholder in create mode. With
+     * direct editing, includes the values sent so far.
+     */
+    dataRow: DataRow | undefined;
+    editModel: "direct" | "session";
+    editSession: EditSession;
+    /** Create mode: rows are added to a session owned by someone else. */
+    isSharedSession: boolean;
+    /** The session fields commit their edits to. */
+    fieldEditSession: DirectEditSession | EditSession;
+    error: Error | undefined;
+    fieldErrors: Readonly<Record<string, string>>;
+    getValues: () => EditFormValues;
+    isDirty: boolean;
+    isEditMode: boolean;
+    mode: EditFormMode;
+    /** Create mode: the row was added, saving the session failed. */
+    rowAdded: boolean;
+    saving: boolean;
+    setValue: (name: string, value: VuuRowDataItemType) => void;
+    submit: (force?: boolean) => Promise<boolean>;
+};
+export type EditFormHookResult = ReturnType<typeof useEditForm>;

package/types/useEditSessionState.d.ts

@@ -0,0 +1,27 @@
+import type { EditLifecycle, EditSession, EditState, NewRowState } from "./EditSession";
+export interface EditSessionStateSnapshot {
+    /** True when the session can be cancelled (active, or a failed save). */
+    canCancel: boolean;
+    /** True when there are valid, unsaved changes (or a stale save to force). */
+    canSave: boolean;
+    editState: EditState;
+    /** The error from the most recent failed begin or end, if any. */
+    error?: Error;
+    /** True while a session is active, including while it is ending. */
+    inEditMode: boolean;
+    isActive: boolean;
+    isDirty: boolean;
+    isEnding: boolean;
+    isStarting: boolean;
+    lifecycle: EditLifecycle;
+    newRowState: NewRowState;
+}
+/**
+ * Subscribes to an EditSession and returns a single, render-safe snapshot of
+ * its state: editState, lifecycle, new-row draft and the derived flags most
+ * UIs need (canSave, canCancel, isDirty etc).
+ *
+ * Prefer this to adding `editState`/`lifecycle`/`newRow` listeners by hand.
+ * Returns an idle, clean snapshot when no session is provided.
+ */
+export declare const useEditSessionState: (editSession: EditSession | undefined) => EditSessionStateSnapshot;

package/types/useEditable.d.ts

@@ -1,13 +1,40 @@
-import type { CopyOption, DataSource } from "@vuu-ui/vuu-data-types";
-import { EditSession } from "./EditSession";
+import type { CopyOption, DataSource, DeleteRowMode } from "@vuu-ui/vuu-data-types";
+import { EditSession, type EditSessionApi, type RowDefaultDataItemValues } from "./EditSession";
+import { type EditErrorHandler } from "./edit-errors";
 export interface EditableHookProps {
+    /** @default "Selected" */
     copyOption?: CopyOption;
     dataSource: DataSource;
+    /** @default "soft" */
+    deleteMode?: DeleteRowMode;
+    /** @default "createSessionDataSource" */
+    editSessionApi?: EditSessionApi;
+    /**
+     * Controls the edit session. When omitted, edit mode is read from the
+     * nearest EditModeProvider.
+     */
+    isEditMode?: boolean;
     onCancel: () => void;
+    /** Called when begin, save or cancel fails. Defaults to console.error. */
+    onError?: EditErrorHandler;
     onSave: () => void;
+    /** Default column values applied to every addRow call. Pass a stable reference. */
+    rowDefaults?: RowDefaultDataItemValues;
 }
-export declare const useEditable: ({ copyOption, dataSource, onCancel, onSave, }: EditableHookProps) => {
+/**
+ * Owns an EditSession for a form (or any non-table editor). The session is
+ * begun when edit mode is entered and ended (without saving) when it is left.
+ * Wrap the editor in a DataEditingProvider with the returned editSession.
+ *
+ * For a higher level API, with create mode and validation, see `useEditForm`.
+ */
+export declare const useEditable: ({ copyOption, dataSource, deleteMode, editSessionApi, isEditMode: isEditModeProp, onCancel, onError, onSave, rowDefaults, }: EditableHookProps) => {
+    canCancel: boolean;
+    canSave: boolean;
     editSession: EditSession;
+    editState: import("./EditSession").EditState;
+    isEditMode: boolean;
+    lifecycle: import("./EditSession").EditLifecycle;
     onCancel: () => Promise<void>;
     onSave: (force?: boolean) => Promise<void>;
 };

package/types/useEditableColumns.d.ts

@@ -0,0 +1,79 @@
+import type { DataEditable, TableSchema } from "@vuu-ui/vuu-data-types";
+import type { ColumnDescriptor } from "@vuu-ui/vuu-table-types";
+/** Columns maintained by the Vuu server, never editable by default. */
+export declare const DEFAULT_READ_ONLY_COLUMNS: readonly ["vuuCreatedTimestamp", "vuuUpdatedTimestamp", "vuuMsg"];
+/** The client-side column that hosts the `UndoCellRenderer`. */
+export declare const UNDO_COLUMN: ColumnDescriptor;
+export interface EditableColumnsHookProps {
+    /**
+     * Column descriptors used in view mode and as the base for edit mode. A
+     * column's `editable` narrows what the server schema allows, its `editor`
+     * is used as the cell editor in edit mode.
+     */
+    columns: readonly ColumnDescriptor[];
+    /**
+     * Whether the table is currently showing the edit session. Typically
+     * `isEditSessionReady` from `useEditableTable`. When false, editing is
+     * switched off for every column.
+     */
+    isEditing: boolean;
+    /**
+     * The schema of the table being edited. A column the schema marks as not
+     * editable can never be edited, whatever the column descriptor says.
+     * Columns with no `editable` flag in the schema are editable.
+     */
+    schema?: TableSchema;
+    /**
+     * Append the client-side undo column while editing. Pass a partial
+     * descriptor to override defaults such as width.
+     */
+    undoColumn?: boolean | Partial<ColumnDescriptor>;
+    /**
+     * Append the session table's `vuuAction` column while editing, either
+     * hidden (it still drives row styling) or visible.
+     */
+    actionColumn?: "hidden" | "visible" | false;
+    /**
+     * When true, edit-mode columns are built from `editSchema` rather than
+     * `columns`. Pass `columnsDiverge` and `editSchema` from `useEditableTable`.
+     * Descriptors in `columns` with a matching name are used as a base so that
+     * labels, widths and formatting are preserved.
+     */
+    columnsDiverge?: boolean;
+    editSchema?: TableSchema;
+}
+/**
+ * Combines the schema and column `editable` values. The column can only
+ * narrow what the schema allows.
+ */
+export declare const narrowEditable: (schemaEditable?: DataEditable, columnEditable?: DataEditable) => DataEditable;
+/**
+ * Builds edit-mode column descriptors. Exposed for use outside React, e.g. in
+ * tests or when composing a TableConfig by hand. Most code should use
+ * `useEditableColumns`.
+ */
+export declare const getEditableColumns: ({ actionColumn, columns, columnsDiverge, editSchema, isEditing, schema, undoColumn, }: EditableColumnsHookProps) => readonly ColumnDescriptor[];
+/**
+ * Maps view-mode column descriptors to edit-mode descriptors and adds the
+ * action and undo columns. Editability comes from the schema, narrowed by
+ * each column's `editable`; a column's `editor` becomes its cell editor.
+ *
+ * When `isEditing` is false, editing is switched off for every column.
+ *
+ * @example
+ * const columns = useEditableColumns({
+ *   columns: [
+ *     { name: "ric", editable: { insert: true, update: false } },
+ *     {
+ *       name: "currency",
+ *       editor: { name: "dropdown-cell", values: ["EUR", "GBP", "USD"] },
+ *     },
+ *     { name: "lastUpdate", editable: false },
+ *   ],
+ *   isEditing: isEditSessionReady,
+ *   schema: dataSource.tableSchema,
+ *   undoColumn: true,
+ *   actionColumn: "hidden",
+ * });
+ */
+export declare const useEditableColumns: ({ actionColumn, columns, columnsDiverge, editSchema, isEditing, schema, undoColumn, }: EditableColumnsHookProps) => readonly ColumnDescriptor[];

package/types/useEditableTable.d.ts

@@ -1,7 +1,8 @@
 import type { CopyOption, DataSource, DeleteRowMode } from "@vuu-ui/vuu-data-types";
 import type { VuuTable } from "@vuu-ui/vuu-protocol-types";
 import type { DataRow } from "@vuu-ui/vuu-table-types";
-import { EditSession, type EditActionType, type EditLifecycle, type EditSessionApi, type RowDefaultDataItemValues } from "./EditSession";
+import { EditSession, type EditActionType, type EditLifecycle, type EditSessionApi, type EditState, type RowDefaultDataItemValues } from "./EditSession";
+import { type EditErrorHandler } from "./edit-errors";
 export type EditMode = "edit" | "view";
 export interface EditableTableHookProps {
     /**
@@ -11,11 +12,23 @@ export interface EditableTableHookProps {
     columns?: string[];
     dataSource?: DataSource;
     addRowsCount?: number;
+    /** @default "soft" */
     deleteMode?: DeleteRowMode;
+    /** @default "createSessionDataSource" */
     editSessionApi?: EditSessionApi;
+    /** Rows copied into the session table when editing begins. @default "All" */
     copyOption?: CopyOption;
-    isEditMode: boolean;
+    /**
+     * Begins (true) or ends (false) the edit session. When omitted, edit mode
+     * is read from the nearest EditModeProvider.
+     */
+    isEditMode?: boolean;
     onCancel: () => void;
+    /**
+     * Called when begin, save, cancel or delete fails. Defaults to
+     * console.error. Use this to surface errors, e.g. as a notification.
+     */
+    onError?: EditErrorHandler;
     onSave: () => void;
     /** Default column values applied to every addRow call. Pass a stable reference — a new object triggers EditSession recreation. */
     rowDefaults?: RowDefaultDataItemValues;
@@ -25,13 +38,15 @@ export interface EditableTableHookProps {
      */
     table?: VuuTable;
 }
-export declare const useEditableTable: ({ columns, dataSource: dataSourceProp, deleteMode, editSessionApi, copyOption, isEditMode, onCancel, onSave, rowDefaults, table, }: EditableTableHookProps) => {
+export declare const useEditableTable: ({ columns, dataSource: dataSourceProp, deleteMode, editSessionApi, copyOption, isEditMode: isEditModeProp, onCancel, onError, onSave, rowDefaults, table, }: EditableTableHookProps) => {
     canCancel: boolean;
     canSave: boolean;
     columnsDiverge: boolean;
     dataSource: DataSource;
     editSchema: import("@vuu-ui/vuu-data-types").TableSchema | undefined;
     editSession: EditSession;
+    editState: EditState;
+    isEditMode: boolean;
     lifecycle: EditLifecycle;
     hasSelection: boolean;
     isEditSessionReady: boolean;