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

package/src/useEditableColumns.js

@@ -0,0 +1,105 @@
+import { isDataValueEditable } from "@vuu-ui/vuu-utils";
+import { useMemo } from "react";
+import { UNDO_CELL_RENDERER } from "./UndoCellRenderer.js";
+const DEFAULT_READ_ONLY_COLUMNS = [
+    "vuuCreatedTimestamp",
+    "vuuUpdatedTimestamp",
+    "vuuMsg"
+];
+const UNDO_COLUMN = {
+    name: "undo",
+    source: "client",
+    width: 80,
+    type: {
+        name: "string",
+        renderer: {
+            name: UNDO_CELL_RENDERER
+        }
+    }
+};
+const typeName = (column)=>{
+    if ("string" == typeof column.type) return column.type;
+    if (column.type) return column.type.name;
+    return "string";
+};
+const isReadOnlyColumn = (name)=>DEFAULT_READ_ONLY_COLUMNS.includes(name);
+const narrowEditable = (schemaEditable = true, columnEditable = true)=>{
+    if (true === schemaEditable) return columnEditable;
+    if (false === schemaEditable || false === columnEditable) return false;
+    const insert = isDataValueEditable({
+        editable: schemaEditable
+    }, "insert") && isDataValueEditable({
+        editable: columnEditable
+    }, "insert");
+    const update = isDataValueEditable({
+        editable: schemaEditable
+    }, "update") && isDataValueEditable({
+        editable: columnEditable
+    }, "update");
+    return insert === update ? insert : {
+        insert,
+        update
+    };
+};
+const withEditor = (column, editor)=>{
+    if (void 0 === editor || "typeahead" === editor.name) return column;
+    return {
+        ...column,
+        type: {
+            name: typeName(column),
+            renderer: editor
+        }
+    };
+};
+const toViewColumn = (column)=>void 0 === column.editable || false === column.editable ? column : {
+        ...column,
+        editable: false
+    };
+const getEditableColumns = ({ actionColumn = false, columns, columnsDiverge = false, editSchema, isEditing, schema = editSchema, undoColumn = false })=>{
+    if (!isEditing) return columns.some((c)=>void 0 !== c.editable && false !== c.editable) ? columns.map(toViewColumn) : columns;
+    const baseColumns = columnsDiverge && editSchema ? editSchema.columns.filter(({ name })=>"vuuAction" !== name).map((schemaColumn)=>columns.find(({ name })=>name === schemaColumn.name) ?? {
+            name: schemaColumn.name,
+            serverDataType: schemaColumn.serverDataType
+        }) : columns;
+    const editColumns = baseColumns.map((column)=>{
+        if ("client" === column.source) return column;
+        if (isReadOnlyColumn(column.name)) return void 0 === column.editable ? column : {
+            ...column,
+            editable: false
+        };
+        const schemaColumn = schema?.columns.find(({ name })=>name === column.name);
+        const editable = narrowEditable(schemaColumn?.editable, column.editable);
+        return withEditor({
+            ...column,
+            editable
+        }, column.editor);
+    });
+    if (actionColumn) editColumns.push({
+        hidden: "hidden" === actionColumn,
+        name: "vuuAction",
+        serverDataType: "string"
+    });
+    if (undoColumn) editColumns.push(true === undoColumn ? UNDO_COLUMN : {
+        ...UNDO_COLUMN,
+        ...undoColumn
+    });
+    return editColumns;
+};
+const useEditableColumns = ({ actionColumn, columns, columnsDiverge, editSchema, isEditing, schema, undoColumn })=>useMemo(()=>getEditableColumns({
+            actionColumn,
+            columns,
+            columnsDiverge,
+            editSchema,
+            isEditing,
+            schema,
+            undoColumn
+        }), [
+        actionColumn,
+        columns,
+        columnsDiverge,
+        editSchema,
+        isEditing,
+        schema,
+        undoColumn
+    ]);
+export { DEFAULT_READ_ONLY_COLUMNS, UNDO_COLUMN, getEditableColumns, narrowEditable, useEditableColumns };

package/src/useEditableTable.js

@@ -3,14 +3,20 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { EditSession } from "./EditSession.js";
 import { EDIT_ACTION_ROW_CLASS_NAME_GENERATOR } from "./editActionRowClassNameGenerator.js";
 import { isEditRowReadOnly } from "./edit-utils.js";
+import { useEditMode } from "./EditModeProvider.js";
+import { reportEditError } from "./edit-errors.js";
 const EDIT_ACTION_ROW_CLASS_NAME_GENERATORS = [
     EDIT_ACTION_ROW_CLASS_NAME_GENERATOR
 ];
-const useEditableTable = ({ columns, dataSource: dataSourceProp, deleteMode = "soft", editSessionApi = "createSessionDataSource", copyOption = "All", isEditMode, onCancel, onSave, rowDefaults, table })=>{
+const useEditableTable = ({ columns, dataSource: dataSourceProp, deleteMode = "soft", editSessionApi = "createSessionDataSource", copyOption = "All", isEditMode: isEditModeProp, onCancel, onError, onSave, rowDefaults, table })=>{
     const { VuuDataSource } = useData();
+    const { isEditMode: isEditModeContext } = useEditMode();
+    const isEditMode = isEditModeProp ?? isEditModeContext;
     const [selectionCount, setSelectionCount] = useState(0);
+    const onErrorRef = useRef(onError);
+    onErrorRef.current = onError;
     useLayoutEffectSkipFirst(()=>{
-        console.warn("[useEditableTable] columns and or table changed");
+        if ("production" !== process.env.NODE_ENV && !dataSourceProp) console.warn("[useEditableTable] columns or table changed, a new DataSource and EditSession will be created. Pass stable (memoized) values.");
     }, [
         columns,
         table
@@ -52,7 +58,7 @@ const useEditableTable = ({ columns, dataSource: dataSourceProp, deleteMode = "s
             setSelectionCount(0);
             onCancel();
         } catch (error) {
-            console.error("[useEditableTable] cancel edit session failed", error);
+            reportEditError("useEditableTable", onErrorRef.current, error, "cancel");
         }
     }, [
         editSession,
@@ -64,14 +70,19 @@ const useEditableTable = ({ columns, dataSource: dataSourceProp, deleteMode = "s
             setSelectionCount(0);
             onSave();
         } catch (error) {
-            console.error("[useEditableTable] save edit session failed", error);
+            reportEditError("useEditableTable", onErrorRef.current, error, "save");
         }
     }, [
         editSession,
         onSave
     ]);
     const handleDelete = useCallback(async ()=>{
-        await editSession.deleteSelectedRows();
+        try {
+            const response = await editSession.deleteSelectedRows();
+            if ("ERROR_RESULT" === response.type) reportEditError("useEditableTable", onErrorRef.current, new Error(response.errorMessage), "delete");
+        } catch (error) {
+            reportEditError("useEditableTable", onErrorRef.current, error, "delete");
+        }
     }, [
         editSession
     ]);
@@ -90,10 +101,20 @@ const useEditableTable = ({ columns, dataSource: dataSourceProp, deleteMode = "s
             editSession.reconcileWithSessionSchema();
             setSubscribedSessionDataSource(sessionDataSource);
         };
+        const handleUnsubscribed = ()=>{
+            if (editSession.canCancel) editSession.end().then(()=>{
+                setSelectionCount(0);
+                onCancelRef.current();
+            });
+        };
         setSubscribedSessionDataSource(void 0);
         sessionDataSource.on("subscribed", handleSubscribed);
+        sessionDataSource.on("unsubscribed", handleUnsubscribed);
         if ("subscribed" === sessionDataSource.status && sessionDataSource.tableSchema) handleSubscribed();
-        return ()=>sessionDataSource.removeListener("subscribed", handleSubscribed);
+        return ()=>{
+            sessionDataSource.removeListener("subscribed", handleSubscribed);
+            sessionDataSource.removeListener("unsubscribed", handleUnsubscribed);
+        };
     }, [
         editSession,
         sessionDataSource
@@ -120,9 +141,9 @@ const useEditableTable = ({ columns, dataSource: dataSourceProp, deleteMode = "s
         const transition = isEditMode ? editSession.begin(copyOption) : editSession.end();
         transition.catch((error)=>{
             if (isEditMode) {
-                console.error("[useEditableTable] begin edit session failed", error);
+                reportEditError("useEditableTable", onErrorRef.current, error, "begin");
                 onCancelRef.current();
-            } else console.error("[useEditableTable] end edit session failed", error);
+            } else reportEditError("useEditableTable", onErrorRef.current, error, "cancel");
         });
     }, [
         copyOption,
@@ -130,7 +151,7 @@ const useEditableTable = ({ columns, dataSource: dataSourceProp, deleteMode = "s
         isEditMode
     ]);
     const canCancel = "active" === lifecycle.status || "error" === lifecycle.status && "end" === lifecycle.operation;
-    const canSave = canCancel && ("dirty" === editState || "stale" === editState) && 0 === editSession.invalidCount;
+    const canSave = canCancel && ("dirty" === editState || "stale" === editState);
     const isEditSessionReady = isEditMode && void 0 !== sessionDataSource && sessionDataSource === editSession.sessionDataSource && subscribedSessionDataSource === sessionDataSource && "subscribed" === sessionDataSource.status && void 0 !== sessionDataSource.tableSchema;
     const editSchema = subscribedSessionDataSource?.tableSchema;
     const viewSchema = sourceDataSource.tableSchema;
@@ -142,6 +163,8 @@ const useEditableTable = ({ columns, dataSource: dataSourceProp, deleteMode = "s
         dataSource,
         editSchema,
         editSession,
+        editState,
+        isEditMode,
         lifecycle,
         hasSelection: selectionCount > 0,
         isEditSessionReady,

package/types/DirectEditSession.d.ts

@@ -2,8 +2,13 @@ import type { DataSource } from "@vuu-ui/vuu-data-types";
 import type { RpcResult, VuuRowDataItemType } from "@vuu-ui/vuu-protocol-types";
 import { EventEmitter } from "@vuu-ui/vuu-utils";
 import type { TableEditSession, TableEditSessionEvents } from "./TableEditSession";
+/**
+ * Checks a value before it is sent. Return an error message to reject it.
+ */
+export type DirectEditValidator = (key: string, columnName: string, value: VuuRowDataItemType) => string | undefined;
 export type DirectEditSessionConstructorProps = {
     dataSource: DataSource;
+    validate?: DirectEditValidator;
 };
 /**
  * A lightweight edit session for services that allow cells to be edited
@@ -13,7 +18,7 @@ export type DirectEditSessionConstructorProps = {
  */
 export declare class DirectEditSession extends EventEmitter<TableEditSessionEvents> implements TableEditSession {
     #private;
-    constructor({ dataSource }: DirectEditSessionConstructorProps);
+    constructor({ dataSource, validate }: DirectEditSessionConstructorProps);
     get dataSource(): DataSource;
     get inEditMode(): boolean;
     isCellEdited(_key: string, _columnName: string): boolean;

package/types/EditButtons.d.ts

@@ -1,14 +1,31 @@
 import type { EditSession } from "./EditSession";
 export interface EditButtonProps {
-    canCancel: boolean;
-    canSave: boolean;
+    /**
+     * Enables the Cancel button. Defaults to `editSession.canCancel`, so only
+     * provide this to override the session-derived value.
+     */
+    canCancel?: boolean;
+    /**
+     * An extra condition for enabling Save. Save is only enabled when this is
+     * not false and `editSession.canSave` is true.
+     */
+    canSave?: boolean;
     editSession?: EditSession;
     hasSelection?: boolean;
     onCancel?: () => void;
     onDelete?: () => void;
     onSave: (force?: boolean) => void;
     saveLabel?: string;
+    /** Return false (or resolve false) to abort the save. */
     confirmSave?: () => boolean | Promise<boolean>;
+    /**
+     * Called before cancelling a session with unsaved changes. Return false
+     * (or resolve false) to keep editing. See `useConfirmDiscard`.
+     */
     confirmCancel?: () => boolean | Promise<boolean>;
 }
-export declare const EditButtons: ({ canCancel, canSave: _canSave, confirmCancel, confirmSave, editSession, hasSelection, onCancel, onDelete, onSave, saveLabel, }: EditButtonProps) => import("react").JSX.Element;
+/**
+ * Delete, Save and Cancel buttons for an edit session. Save switches to
+ * "Save (force)" when the last save was rejected as stale.
+ */
+export declare const EditButtons: ({ canCancel: canCancelProp, canSave: canSaveProp, confirmCancel, confirmSave, editSession, hasSelection, onCancel, onDelete, onSave, saveLabel, }: EditButtonProps) => import("react").JSX.Element;

package/types/EditModeProvider.d.ts

@@ -4,11 +4,19 @@ export interface EditModeContextProps {
     setEditMode: (inEditMode: boolean) => void;
 }
 /**
- * Implemented as a standalone Provider so that EditMode cna be implemented
- * at higher level than individual edit controls.
+ * Shares a view/edit mode flag between components that are rendered apart,
+ * e.g. a toolbar toggle and an edit form. Implemented as a standalone Provider
+ * so that edit mode can be controlled above the individual edit controls.
+ *
+ * `isEditMode` seeds (and resets) the mode; descendants can change it with
+ * `useEditMode().setEditMode`.
  */
 export declare const EditModeProvider: ({ children, isEditMode: isEditModeProp, }: {
     children: ReactNode;
     isEditMode?: boolean;
 }) => import("react").JSX.Element;
+/**
+ * Returns the edit mode from the nearest EditModeProvider. With no provider,
+ * `isEditMode` is always false.
+ */
 export declare const useEditMode: () => EditModeContextProps;

package/types/EditSession.d.ts

@@ -34,6 +34,12 @@ export type NewRowState = {
     errors: Readonly<Record<string, string>>;
     submitting: boolean;
     values: Readonly<Record<string, VuuRowDataItemType>>;
+    /**
+     * Set when the server rejected the row. The message is reported against
+     * this column (the final column, where an inline add row shows it) and is
+     * cleared by the next change to the draft.
+     */
+    rowErrorColumn?: string;
 };
 export type EditLifecycle = {
     status: "idle";
@@ -78,11 +84,20 @@ export declare class EditSession extends EventEmitter<EditSessionEvents> impleme
     isNewRowFinalColumn(columnName: string): boolean;
     isNewRowComplete(): boolean;
     configureNewRow(columns: readonly string[], requiredColumns?: readonly string[]): void;
-    setNewRowValue(column: string, value: VuuRowDataItemType): void;
+    setNewRowValue(column: string, value: VuuRowDataItemType | undefined): void;
+    setNewRowError(column: string, errorMessage?: string): void;
+    clearNewRowError(column: string): void;
+    /** Discards the new-row draft, leaving the rest of the session untouched. */
+    clearNewRow(): void;
     addNewRow(): Promise<RpcResult>;
     deleteSelectedRows(): Promise<RpcResult>;
     addRow(rowData?: Record<string, VuuRowDataItemType>): Promise<RpcResult>;
     hasRowChanges(key: string): boolean;
+    /**
+     * The edited values for a row, keyed by column name. Includes invalid
+     * edits. Returns an empty object when the row has no edits.
+     */
+    getEditedValues(key: string): Record<string, EditSessionValue>;
     isCellEdited(key: string, columnName: string): boolean;
     undoRowChange(key: string, action: EditActionType): Promise<RpcResult | undefined>;
     begin(copyOption?: CopyOption, sessionType?: SessionType): Promise<DataSource>;
@@ -92,6 +107,8 @@ export declare class EditSession extends EventEmitter<EditSessionEvents> impleme
      */
     reconcileWithSessionSchema(): void;
     get dataSource(): import("@vuu-ui/vuu-data-types").DataSourceBase<import("@vuu-ui/vuu-data-types").DataSourceRowWithBigint> | undefined;
+    /** The dataSource of the table being edited. */
+    get sourceDataSource(): DataSource | undefined;
     get sessionDataSource(): DataSource | undefined;
     end(saveChanges?: boolean, force?: boolean): Promise<void>;
     get lifecycle(): EditLifecycle;

package/types/edit-control/EditControlCheckbox.d.ts

@@ -0,0 +1,8 @@
+import type { CommitHandler } from "@vuu-ui/vuu-utils";
+export interface EditControlCheckboxProps {
+    className?: string;
+    onCommit: CommitHandler<HTMLElement>;
+    value?: unknown;
+}
+/** A checkbox that commits its value each time it is toggled. */
+export declare const EditControlCheckbox: ({ className, onCommit, value, }: EditControlCheckboxProps) => import("react").JSX.Element;

package/types/edit-control/EditControlDropdown.d.ts

@@ -0,0 +1,14 @@
+import type { CommitHandler } from "@vuu-ui/vuu-utils";
+export interface DropdownOption {
+    label: string;
+    value: string;
+}
+export interface EditControlDropdownProps {
+    className?: string;
+    onCommit: CommitHandler<HTMLElement>;
+    /** Either a list of values, or of options with distinct labels. */
+    values: readonly string[] | readonly DropdownOption[];
+    value?: unknown;
+}
+/** A dropdown that commits its value when an option is selected. */
+export declare const EditControlDropdown: ({ className, onCommit, value, values, }: EditControlDropdownProps) => import("react").JSX.Element;

package/types/edit-control/EditControlLookupDropdown.d.ts

@@ -0,0 +1,13 @@
+import type { LookupTableDetails } from "@vuu-ui/vuu-table-types";
+import type { CommitHandler } from "@vuu-ui/vuu-utils";
+export interface EditControlLookupDropdownProps {
+    className?: string;
+    lookup: LookupTableDetails;
+    onCommit: CommitHandler<HTMLElement>;
+    value?: unknown;
+}
+/**
+ * A dropdown offering the values of a lookup table, labelled with its
+ * `labelColumn`. Commits the `valueColumn` value of the selected row.
+ */
+export declare const EditControlLookupDropdown: ({ className, lookup: { labelColumn, table, valueColumn }, onCommit, value, }: EditControlLookupDropdownProps) => import("react").JSX.Element;

package/types/edit-control/get-data-item-edit-control.d.ts

@@ -0,0 +1,40 @@
+import type { DataValueDescriptor, TableSchemaTable } from "@vuu-ui/vuu-data-types";
+import { type VuuTypeaheadInputProps } from "@vuu-ui/vuu-ui-controls";
+import { type CommitHandler } from "@vuu-ui/vuu-utils";
+import type { InputProps } from "@salt-ds/core";
+/**
+ * A rendering hint for the typeahead used in filters, shorthand for
+ * `minCharacterCountToTriggerSuggestions`.
+ * 'search' needs a character typed before suggestions show (1),
+ * 'pick' shows them on focus, like a dropdown (0).
+ */
+export type DataItemEditControlVariant = "search" | "pick";
+/**
+ * - "edit" (default): editing a value. Booleans are edited with a checkbox,
+ *   and a typeahead is used only when the descriptor's `editor` asks for one.
+ * - "filter": entering a filter value. Every string column on a Vuu table
+ *   gets a typeahead, suggesting the values present in the table.
+ */
+export type DataItemEditControlPurpose = "edit" | "filter";
+export interface DataItemEditControlProps {
+    InputProps?: Partial<InputProps>;
+    TypeaheadProps?: Pick<VuuTypeaheadInputProps, "highlightFirstSuggestion" | "minCharacterCountToTriggerSuggestions" | "selectOnTab">;
+    className?: string;
+    commitOnBlur?: boolean;
+    commitWhenCleared?: boolean;
+    /**
+     * A table column or form field Descriptor. Its `editor`, when present,
+     * determines the control.
+     */
+    dataDescriptor: DataValueDescriptor;
+    editOperation?: "insert" | "update";
+    errorMessage?: string;
+    onCommit: CommitHandler<HTMLElement>;
+    /** @default "edit" */
+    purpose?: DataItemEditControlPurpose;
+    /** The table the value belongs to. Required for a typeahead. */
+    table?: TableSchemaTable;
+    variant?: DataItemEditControlVariant;
+}
+export type ValidationStatus = "initial" | true | string;
+export declare const getDataItemEditControl: ({ InputProps, TypeaheadProps, className, commitOnBlur, commitWhenCleared, dataDescriptor, editOperation, errorMessage, onCommit, purpose, table, variant, }: DataItemEditControlProps) => import("react").JSX.Element;

package/types/edit-control/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./EditControlCheckbox";
+export * from "./EditControlDropdown";
+export * from "./EditControlLookupDropdown";
+export * from "./get-data-item-edit-control";

package/types/edit-errors.d.ts

@@ -0,0 +1,9 @@
+/** The edit operation that failed, passed to an `EditErrorHandler`. */
+export type EditOperation = "begin" | "cancel" | "delete" | "save";
+/**
+ * Called when an edit session operation fails. When no handler is supplied,
+ * hooks log the error to the console.
+ */
+export type EditErrorHandler = (error: Error, operation: EditOperation) => void;
+export declare const toError: (cause: unknown) => Error;
+export declare const reportEditError: (source: string, onError: EditErrorHandler | undefined, cause: unknown, operation: EditOperation) => void;

package/types/edit-field/EditField.d.ts

@@ -1,16 +1,39 @@
 import type { DataRow } from "@vuu-ui/vuu-table-types";
-import type { VuuTable } from "@vuu-ui/vuu-protocol-types";
+import type { DataValueDescriptor, DataValueValidationChecker } from "@vuu-ui/vuu-data-types";
+import type { VuuColumnDataType, VuuTable } from "@vuu-ui/vuu-protocol-types";
 import { type OptionMap } from "../lookup-values/useLookupValues";
 import "./EditField.css";
 export type TextFieldType = "email" | "password";
 export type EditFieldType = "checkbox" | "dropdown" | TextFieldType;
 export interface EditFieldProps {
-    dataRow: DataRow;
+    /**
+     * Client side validation, run on change and before commit. Invalid values
+     * are not sent to the server.
+     */
+    clientSideEditValidationCheck?: DataValueValidationChecker;
+    /**
+     * The row being edited. Use `{ key: EditSession.newRowKey }` for a new row.
+     * Defaults to the row of the enclosing `EditForm`.
+     */
+    dataRow?: DataRow;
+    /**
+     * For new rows only. When true, values are staged in the EditSession draft
+     * and the row is not added until `editSession.addNewRow()` is called (e.g.
+     * from a form Save button). When false, the row is added as soon as the
+     * final (or last required) field is committed. Defaults to true inside a
+     * create-mode `EditForm`, otherwise false.
+     */
     deferNewRow?: boolean;
     label: string;
     name: string;
     readOnly?: boolean;
     required?: boolean;
+    /**
+     * The server data type of the column. Determines how typed values are
+     * converted before commit. Defaults to "boolean" for checkbox fields,
+     * otherwise "string".
+     */
+    serverDataType?: VuuColumnDataType;
     type?: EditFieldType;
 }
 export interface DropdownEditFieldProps extends EditFieldProps {
@@ -18,4 +41,15 @@ export interface DropdownEditFieldProps extends EditFieldProps {
     optionMap: OptionMap;
     table: VuuTable;
 }
-export declare const EditField: ({ dataRow, deferNewRow, label, name, readOnly, required, type, ...options }: EditFieldProps | DropdownEditFieldProps) => import("react").JSX.Element;
+/**
+ * A field described by a column descriptor, the same descriptor a Table
+ * column uses. The control is chosen by `getDataItemEditControl`, from the
+ * descriptor's `editor` and `serverDataType`. `editable` and `required` are
+ * respected.
+ */
+export interface ColumnEditFieldProps extends Omit<EditFieldProps, "label" | "name" | "readOnly" | "required" | "serverDataType" | "type"> {
+    column: DataValueDescriptor;
+    /** Defaults to `column.label`, then `column.name` */
+    label?: string;
+}
+export declare const EditField: (props: EditFieldProps | DropdownEditFieldProps | ColumnEditFieldProps) => import("react").JSX.Element;

package/types/edit-field/useEditField.d.ts

@@ -4,13 +4,14 @@ import { type ChangeEventHandler, type FocusEventHandler, type KeyboardEvent, ty
 import type { LookupOption } from "../lookup-values/useLookupValues";
 import type { TextFieldType } from "./EditField";
 export interface EditFieldHookProps<T extends VuuRowDataItemType = VuuRowDataItemType> {
-    column: Pick<RuntimeColumnDescriptor, "clientSideEditValidationCheck" | "label" | "name">;
+    column: Pick<RuntimeColumnDescriptor, "clientSideEditValidationCheck" | "label" | "name" | "required">;
     value?: T;
     onEdit?: TableCellEditHandler;
     textType?: TextFieldType;
     type?: "string" | "number" | "boolean";
 }
 export declare const useEditField: <T extends string | number | boolean = string>({ column, value, onEdit, textType, type, }: EditFieldHookProps<T>) => {
+    commit: (value?: string) => Promise<boolean>;
     editing: boolean;
     inputProps: {
         onBlur: FocusEventHandler<HTMLElement>;

package/types/edit-form/CreateRowForm.d.ts

@@ -0,0 +1,29 @@
+import type { DataValueDescriptor } from "@vuu-ui/vuu-data-types";
+import { type ReactNode } from "react";
+import { type EditFormProps } from "./EditForm";
+/**
+ * A create form field. The control is chosen from its `editor` and
+ * `serverDataType` by `getDataItemEditControl`. Required unless
+ * `required: false`.
+ */
+export type CreateRowFormField = DataValueDescriptor;
+export interface CreateRowFormProps extends Omit<EditFormProps, "children" | "columns" | "dataRow" | "isEditMode" | "mode" | "requiredColumns"> {
+    /** Rendered after the fields. */
+    children?: ReactNode;
+    /**
+     * Fields, in tab order. Every field is required unless it sets
+     * `required: false`. Omit to compose custom editors as `children`, which
+     * stage their values with `setValue` from `useEditFormContext`.
+     */
+    fields?: readonly CreateRowFormField[];
+}
+/**
+ * A form that adds one row to `dataSource`, or, given an `editSession`, to
+ * that session. Renders an `EditField` per entry in `fields`, stages the values as a new-row draft, and adds the row on
+ * Create. Required fields left empty, `validate` errors and server
+ * rejections are shown on the form; the row is only added once all pass.
+ *
+ * The form is single-use: close it from `onSaved`/`onCancelled`, or remount
+ * it (change its `key`) to create another row.
+ */
+export declare const CreateRowForm: ({ children, fields, ...props }: CreateRowFormProps) => import("react").JSX.Element;

package/types/edit-form/EditForm.d.ts

@@ -0,0 +1,36 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+import { type EditFormHookProps, type EditFormHookResult } from "../useEditForm";
+import "./EditForm.css";
+export interface EditFormProps extends EditFormHookProps, Omit<HTMLAttributes<HTMLFormElement>, "children" | "onError" | "onSubmit" | "title"> {
+    /**
+     * Form fields, typically `EditField`s. Pass a function to receive the form
+     * state, e.g. to render fields conditionally.
+     */
+    children: ReactNode | ((form: EditFormHookResult) => ReactNode);
+    /** Return false (or resolve false) to keep editing. See `useConfirmDiscard`. */
+    confirmCancel?: () => boolean | Promise<boolean>;
+    /** Hide the Cancel button. */
+    hideCancel?: boolean;
+    /**
+     * @default "Save" in edit mode, "Done" with direct editing, "Create" in
+     * create mode, or "Add" when adding to a shared `editSession`
+     */
+    saveLabel?: string;
+    /**
+     * Set false to render the buttons yourself, with `EditFormButtons`.
+     * @default true
+     */
+    showButtons?: boolean;
+    title?: ReactNode;
+}
+/**
+ * A form that edits one row of `dataSource`, or creates a new one. Owns the
+ * EditSession (via `useEditForm`), provides it to child `EditField`s, and
+ * renders an error banner plus Save/Cancel buttons.
+ *
+ * In edit mode, fields are editable while `isEditMode` is true (or the
+ * enclosing `EditModeProvider` is in edit mode). Create mode is always
+ * editable. `EditField`s pick up the form's row (a new-row placeholder in
+ * create mode), so need no `dataRow` prop.
+ */
+export declare const EditForm: ({ children, className, columns, confirmCancel, dataRow, dataSource, deleteMode, editModel, editSession: sharedEditSession, editSessionApi, hideCancel, isEditMode, mode, onCancelled, onError, onSaved, requiredColumns, rowDefaults, saveLabel, showButtons, title, validate, ...htmlAttributes }: EditFormProps) => import("react").JSX.Element;

package/types/edit-form/EditFormButtons.d.ts

@@ -0,0 +1,18 @@
+export interface EditFormButtonsProps {
+    /** Return false (or resolve false) to keep editing. See `useConfirmDiscard`. */
+    confirmCancel?: () => boolean | Promise<boolean>;
+    /** Hide the Cancel button. */
+    hideCancel?: boolean;
+    /**
+     * @default "Save" in edit mode, "Done" with direct editing, "Create" in
+     * create mode, or "Add" when adding to a shared session
+     */
+    saveLabel?: string;
+}
+/**
+ * Save (or Create) and Cancel buttons for the enclosing `EditForm`. The form
+ * renders these itself while editing; render them yourself, with
+ * `showButtons={false}` on the form, to place them elsewhere in the form or
+ * to show them, disabled, outside edit mode.
+ */
+export declare const EditFormButtons: ({ confirmCancel, hideCancel, saveLabel: saveLabelProp, }: EditFormButtonsProps) => import("react").JSX.Element;

package/types/edit-form/EditFormContext.d.ts

@@ -0,0 +1,59 @@
+export declare const EditFormContext: import("react").Context<{
+    canCancel: boolean;
+    editState: import("..").EditState;
+    inEditMode: boolean;
+    isActive: boolean;
+    isEnding: boolean;
+    isStarting: boolean;
+    lifecycle: import("..").EditLifecycle;
+    newRowState: import("..").NewRowState;
+    canSave: boolean;
+    cancel: () => Promise<void>;
+    dataRow: import("@vuu-ui/vuu-table-types").DataRow | undefined;
+    editModel: "direct" | "session";
+    editSession: import("..").EditSession;
+    isSharedSession: boolean;
+    fieldEditSession: import("..").DirectEditSession | import("..").EditSession;
+    error: Error | undefined;
+    fieldErrors: Readonly<Record<string, string>>;
+    getValues: () => import("..").EditFormValues;
+    isDirty: boolean;
+    isEditMode: boolean;
+    mode: import("..").EditFormMode;
+    rowAdded: boolean;
+    saving: boolean;
+    setValue: (name: string, value: import("@vuu-ui/vuu-protocol-types").VuuRowDataItemType | undefined) => void;
+    submit: (force?: boolean) => Promise<boolean>;
+} | undefined>;
+/**
+ * Returns the state of the enclosing `EditForm`, or undefined outside a form.
+ * Use it in custom field components to read `fieldErrors`, `mode`, `saving`
+ * etc.
+ */
+export declare const useEditFormContext: () => {
+    canCancel: boolean;
+    editState: import("..").EditState;
+    inEditMode: boolean;
+    isActive: boolean;
+    isEnding: boolean;
+    isStarting: boolean;
+    lifecycle: import("..").EditLifecycle;
+    newRowState: import("..").NewRowState;
+    canSave: boolean;
+    cancel: () => Promise<void>;
+    dataRow: import("@vuu-ui/vuu-table-types").DataRow | undefined;
+    editModel: "direct" | "session";
+    editSession: import("..").EditSession;
+    isSharedSession: boolean;
+    fieldEditSession: import("..").DirectEditSession | import("..").EditSession;
+    error: Error | undefined;
+    fieldErrors: Readonly<Record<string, string>>;
+    getValues: () => import("..").EditFormValues;
+    isDirty: boolean;
+    isEditMode: boolean;
+    mode: import("..").EditFormMode;
+    rowAdded: boolean;
+    saving: boolean;
+    setValue: (name: string, value: import("@vuu-ui/vuu-protocol-types").VuuRowDataItemType | undefined) => void;
+    submit: (force?: boolean) => Promise<boolean>;
+} | undefined;