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

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
     ]);
@@ -120,9 +131,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 +141,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 +153,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";
@@ -79,10 +85,17 @@ export declare class EditSession extends EventEmitter<EditSessionEvents> impleme
     isNewRowComplete(): boolean;
     configureNewRow(columns: readonly string[], requiredColumns?: readonly string[]): void;
     setNewRowValue(column: string, value: VuuRowDataItemType): 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 +105,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

@@ -11,6 +11,7 @@ export interface EditFieldHookProps<T extends VuuRowDataItemType = VuuRowDataIte
     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) => 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) => void;
+    submit: (force?: boolean) => Promise<boolean>;
+} | undefined;

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

@@ -0,0 +1,4 @@
+export { CreateRowForm, type CreateRowFormField, type CreateRowFormProps, } from "./CreateRowForm";
+export { EditForm, type EditFormProps } from "./EditForm";
+export { EditFormButtons, type EditFormButtonsProps, } from "./EditFormButtons";
+export { useEditFormContext } from "./EditFormContext";

package/types/form-fields.d.ts

@@ -0,0 +1,32 @@
+import type { DataValueDescriptor, TableSchema } from "@vuu-ui/vuu-data-types";
+export interface FormFieldsOptions {
+    /**
+     * Table columns, e.g. `config.columns`. Their `label`, `editor`, `type`
+     * and `editable` carry over to the fields, and they come first, in this
+     * order.
+     */
+    columns?: readonly DataValueDescriptor[];
+    /**
+     * Choose the fields, in order, rather than generating one per schema
+     * column. Each is still overlaid on its schema column (and table column).
+     */
+    fields?: readonly DataValueDescriptor[];
+    /**
+     * `insert` for a create form: fields that can't be set on a new row are
+     * left out. @default "update"
+     */
+    operation?: "insert" | "update";
+    /** The server schema, usually `dataSource.tableSchema`. */
+    schema?: TableSchema;
+}
+/**
+ * The fields of a generated form: one per schema column, except the
+ * server-maintained `vuuCreatedTimestamp`, `vuuUpdatedTimestamp` and
+ * `vuuMsg`. Columns also in `columns` come first, in that order, then the
+ * rest in schema order. Each field is the schema column overlaid with the
+ * matching table column, so a column's `label`, `editor` and `type` carry
+ * over, and its `editable` can narrow, never widen, the server's.
+ *
+ * Without a schema, the fields are generated from `columns`.
+ */
+export declare const getFormFields: ({ columns, fields, operation, schema, }: FormFieldsOptions) => DataValueDescriptor[];

package/types/index.d.ts

@@ -1,17 +1,27 @@
 export { DataEditingProvider, useEditSession, useTableEditSession, } from "./DataEditingProvider";
-export { DirectEditSession, type DirectEditSessionConstructorProps, } from "./DirectEditSession";
+export { DirectEditSession, type DirectEditSessionConstructorProps, type DirectEditValidator, } from "./DirectEditSession";
 export type { TableEditSession, TableEditSessionEvents, } from "./TableEditSession";
 export { useCellEdited } from "./useCellEdited";
 export { useEditState } from "./useEditState";
+export { useEditSessionState, type EditSessionStateSnapshot, } from "./useEditSessionState";
+export type { EditErrorHandler, EditOperation } from "./edit-errors";
 export { getVuuEditMessage, isInlineEditingSession, isEditRowReadOnly, withDataRowEditErrors, } from "./edit-utils";
 export { EditButtons, type EditButtonProps } from "./EditButtons";
 export { EditField, type DropdownEditFieldProps, type EditFieldProps, type EditFieldType, type TextFieldType, } from "./edit-field/EditField";
 export { useEditField, type EditFieldHookProps, } from "./edit-field/useEditField";
 export { EditModeProvider, useEditMode, type EditModeContextProps, } from "./EditModeProvider";
-export { EditError, EditSession, SupersededEditError, type AddRowResultData, type DeleteSelectedRowsResultData, type EditActionType, type EditCommitOptions, type EditLifecycle, type EditSessionConstructorProps, type EditSessionValue, type NewRowState, type EditState, type RowDefaultDataItemValues, } from "./EditSession";
+export { EditError, EditSession, SupersededEditError, type AddRowResultData, type DeleteSelectedRowsResultData, type EditActionType, type EditCommitOptions, type EditLifecycle, type EditSessionApi, type EditSessionConstructorProps, type EditSessionValue, type NewRowState, type EditState, type RowDefaultDataItemValues, } from "./EditSession";
 export { StaleUpdateError } from "@vuu-ui/vuu-utils";
 export { lookupOptionsFromRows, useLookupValues, type LookupOption, type LookupValuedHookProps, type OptionMap, } from "./lookup-values/useLookupValues";
 export { useEditable, type EditableHookProps } from "./useEditable";
 export { EDIT_ACTION_ROW_CLASS_NAME_GENERATOR, editActionRowClassNameGenerator, } from "./editActionRowClassNameGenerator";
 export { getUndoButtonContent, getUndoTooltipContent, UNDO_CELL_RENDERER, UndoCellRenderer, type UndoCellRendererComponentProps, } from "./UndoCellRenderer";
 export { useEditableTable, type EditableTableHookProps, type EditMode, } from "./useEditableTable";
+export { DEFAULT_READ_ONLY_COLUMNS, getEditableColumns, UNDO_COLUMN, useEditableColumns, narrowEditable, type EditableColumnsHookProps, } from "./useEditableColumns";
+export { getDataRowValues, useEditForm, type EditFormFieldErrors, type EditFormHookProps, type EditFormHookResult, type EditFormMode, type EditFormValidator, type EditFormValues, } from "./useEditForm";
+export { useLookupOptions, type LookupOptionsHookProps, type LookupOptionsHookResult, type LookupRow, } from "./lookup-values/useLookupOptions";
+export { useCustomEditField, type CustomEditFieldHookProps, } from "./useCustomEditField";
+export { useConfirmDiscard, type ConfirmDiscardHookProps, } from "./useConfirmDiscard";
+export * from "./edit-form";
+export * from "./edit-control";
+export { type FormFieldsOptions, getFormFields } from "./form-fields";

package/types/lookup-values/useLookupOptions.d.ts

@@ -0,0 +1,35 @@
+import type { VuuRowDataItemType, VuuTable } from "@vuu-ui/vuu-protocol-types";
+import { type LookupOption, type OptionMap } from "./useLookupValues";
+export type LookupRow = Readonly<Record<string, VuuRowDataItemType>>;
+export interface LookupOptionsHookProps<T = LookupOption> {
+    /** @default true */
+    enabled?: boolean;
+    /** The lookup table. */
+    table?: VuuTable;
+    /**
+     * Maps rows to `LookupOption` (`{ value, label, metadata }`). Either
+     * `optionMap` or `columns` plus `mapRow` is required.
+     */
+    optionMap?: OptionMap;
+    /** Columns to subscribe to. Defaults to the columns named in `optionMap`. */
+    columns?: readonly string[];
+    /** Maps a row (column name to value) to an option. Overrides `optionMap`. */
+    mapRow?: (row: LookupRow) => T;
+    /** A Vuu filter expression, e.g. `ccy = "EUR"`. */
+    filter?: string;
+    /** @default 100 */
+    maxRows?: number;
+}
+export interface LookupOptionsHookResult<T> {
+    options: T[];
+    loading: boolean;
+    error?: Error;
+}
+/**
+ * Subscribes to a (typically small) lookup table and maps its rows to
+ * options, e.g. for a dropdown. Unlike `useLookupValues`, this supports any
+ * row mapping, a filter and a row limit, and reports `loading` and `error`.
+ *
+ * Pass stable (memoized) values for `optionMap`, `columns` and `mapRow`.
+ */
+export declare const useLookupOptions: <T = LookupOption>({ columns: columnsProp, enabled, filter, mapRow, maxRows, optionMap, table, }: LookupOptionsHookProps<T>) => LookupOptionsHookResult<T>;