@vuu-ui/vuu-data-editing 3.5.0-beta.4 → 3.5.1

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.5.0-beta.4",
+  "version": "3.5.1",
   "description": "Shared data editing APIs and React components for VUU UI",
   "main": "./src/index.js",
   "author": "heswell",
@@ -12,13 +12,13 @@
   },
   "dependencies": {
     "@salt-ds/core": "1.54.1",
-    "@vuu-ui/vuu-ui-controls": "3.5.0-beta.4",
-    "@vuu-ui/vuu-utils": "3.5.0-beta.4"
+    "@vuu-ui/vuu-ui-controls": "3.5.1",
+    "@vuu-ui/vuu-utils": "3.5.1"
   },
   "devDependencies": {
-    "@vuu-ui/vuu-data-types": "3.5.0-beta.4",
-    "@vuu-ui/vuu-protocol-types": "3.5.0-beta.4",
-    "@vuu-ui/vuu-table-types": "3.5.0-beta.4"
+    "@vuu-ui/vuu-data-types": "3.5.1",
+    "@vuu-ui/vuu-protocol-types": "3.5.1",
+    "@vuu-ui/vuu-table-types": "3.5.1"
   },
   "peerDependencies": {
     "react": "^19.2.3"

package/src/EditModeProvider.js

@@ -1,11 +1,16 @@
 import { jsx } from "react/jsx-runtime";
-import { createContext, useContext, useState } from "react";
+import { createContext, useContext, useEffect, useState } from "react";
 const EditModeContext = /*#__PURE__*/ createContext({
     isEditMode: false,
     setEditMode: ()=>"EditModeProvider in place"
 });
-const EditModeProvider = ({ children })=>{
-    const [isEditMode, setEditMode] = useState(false);
+const EditModeProvider = ({ children, isEditMode: isEditModeProp = false })=>{
+    const [isEditMode, setEditMode] = useState(isEditModeProp);
+    useEffect(()=>{
+        setEditMode(isEditModeProp);
+    }, [
+        isEditModeProp
+    ]);
     return /*#__PURE__*/ jsx(EditModeContext.Provider, {
         value: {
             isEditMode,

package/src/EditSession.js

@@ -69,6 +69,12 @@ class EditSession extends EventEmitter {
     get isDirty() {
         return "clean" !== this.editState;
     }
+    get canCancel() {
+        return "active" === this.lifecycle.status || "error" === this.lifecycle.status && "end" === this.lifecycle.operation;
+    }
+    get canSave() {
+        return this.canCancel && ("dirty" === this.editState || "stale" === this.editState) && 0 === this.invalidCount;
+    }
     #emitEditStateChange(oldState, force = false) {
         const newState = this.editState;
         if (force || newState !== oldState) this.emit("editState", newState);
@@ -480,15 +486,17 @@ class EditSession extends EventEmitter {
             type: "SUCCESS_RESULT"
         };
     }
-    async commit(key, columnName, originalValue, typedValue, isValid) {
+    async commit(key, columnName, originalValue, typedValue, isValid, { dataSourceValue, syncToDataSource = true } = {}) {
         if ("active" !== this.#lifecycle.status && !("error" === this.#lifecycle.status && "end" === this.#lifecycle.operation)) throw new Error("No edit session in progress");
         const revision = this.#setCellCommitRevision(key, columnName);
         const rowEditDetails = this.#getOrCreateRowEdits(key);
         const { cellEdits } = rowEditDetails;
         if (isValid) {
             const cellEdit = this.#storeCellEdit(key, cellEdits, columnName, originalValue, typedValue, isValid);
-            if (this.dataSource?.editCell) {
-                const response = await this.dataSource.editCell(key, columnName, typedValue);
+            if (syncToDataSource && this.dataSource?.editCell) {
+                const valueForDataSource = dataSourceValue ?? typedValue;
+                if ("object" == typeof valueForDataSource && null !== valueForDataSource) throw new Error("Custom edit values require a scalar dataSourceValue.");
+                const response = await this.dataSource.editCell(key, columnName, valueForDataSource);
                 if (!this.inEditMode) return {
                     data: void 0,
                     type: "SUCCESS_RESULT"

package/src/edit-field/EditField.css.js

@@ -0,0 +1,13 @@
+const css = `
+.vuuEditField {
+  & .saltDropdown {
+    --vuu-icon-height: 15px;
+    --vuu-icon-left: calc(100% - var(--salt-spacing-300));
+    --vuu-icon-size: 8px;
+    --vuu-icon-top: -3px;
+  }
+}
+
+
+`;
+export default css;

package/src/edit-field/EditField.js

@@ -0,0 +1,105 @@
+import { jsx, jsxs } from "react/jsx-runtime";
+import { Checkbox, Dropdown, FormField, FormFieldLabel, Input, Option } from "@salt-ds/core";
+import { useCallback } from "react";
+import { useEditField } from "./useEditField.js";
+import { useEditSession } from "../DataEditingProvider.js";
+import { dataDescriptorTypeToVuuRowDataItemType } from "@vuu-ui/vuu-utils";
+import { useEditMode } from "../EditModeProvider.js";
+import { useLookupValues } from "../lookup-values/useLookupValues.js";
+import "./EditField.css";
+const classBase = "vuuEditField";
+const EditField = ({ dataRow, deferNewRow = false, label, name, readOnly = false, required, type, ...options })=>{
+    const editSession = useEditSession();
+    const { isEditMode } = useEditMode();
+    const lookupValues = useLookupValues({
+        enabled: "dropdown" === type,
+        ...options
+    });
+    const onEdit = useCallback(async (editState, editPhase)=>{
+        const { isValid = true, previousValue = "", value } = editState;
+        if ("commit" === editPhase && editSession) {
+            if (editSession.isNewRow(dataRow.key)) {
+                const isEmptyValue = "string" == typeof value && "" === value.trim();
+                if (!isValid && !isEmptyValue) return {
+                    errorMessage: "Invalid value",
+                    type: "ERROR_RESULT"
+                };
+                editSession.setNewRowValue(name, value);
+                if (!deferNewRow && (editSession.isNewRowFinalColumn(name) || editSession.isNewRowComplete())) return editSession.addNewRow();
+                return {
+                    data: void 0,
+                    type: "SUCCESS_RESULT"
+                };
+            }
+            return editSession.commit(dataRow.key, name, previousValue, value, isValid);
+        }
+        if ("change" === editPhase && deferNewRow && editSession?.isNewRow(dataRow.key)) {
+            editSession.setNewRowValue(name, value);
+            return {
+                data: void 0,
+                type: "SUCCESS_RESULT"
+            };
+        }
+    }, [
+        dataRow,
+        deferNewRow,
+        editSession,
+        name
+    ]);
+    const onCommit = useCallback(()=>{
+        console.log("onCommit");
+    }, []);
+    const necessity = required ? "asterisk" : void 0;
+    const dataValue = dataRow?.[name] ?? "";
+    const column = {
+        label,
+        name,
+        serverDataType: "string"
+    };
+    const { inputProps, onChange, onDropdownSelectionChange, onKeyDown, value } = useEditField({
+        column,
+        textType: "checkbox" !== type && "dropdown" !== type ? type : void 0,
+        onEdit,
+        type: dataDescriptorTypeToVuuRowDataItemType(column),
+        value: dataValue
+    });
+    return /*#__PURE__*/ jsxs(FormField, {
+        className: classBase,
+        "data-field": name,
+        necessity: necessity,
+        children: [
+            /*#__PURE__*/ jsx(FormFieldLabel, {
+                children: label
+            }),
+            false === isEditMode ? /*#__PURE__*/ jsx(Input, {
+                bordered: true,
+                inputProps: {
+                    readOnly: true
+                },
+                value: String(dataValue)
+            }) : "checkbox" === type ? /*#__PURE__*/ jsx(Checkbox, {
+                checked: Boolean(dataValue),
+                onChange: onCommit
+            }) : "dropdown" === type ? /*#__PURE__*/ jsx(Dropdown, {
+                "data-icon": "triangle-down",
+                onSelectionChange: onDropdownSelectionChange,
+                placeholder: "Please select value",
+                value: value,
+                children: lookupValues.map((listOption)=>/*#__PURE__*/ jsx(Option, {
+                        value: listOption,
+                        children: listOption.label
+                    }, listOption.value))
+            }) : /*#__PURE__*/ jsx(Input, {
+                bordered: true,
+                inputProps: {
+                    ...inputProps,
+                    onChange
+                },
+                onKeyDown: onKeyDown,
+                readOnly: readOnly,
+                value: value
+            })
+        ]
+    });
+};
+export { EditField };

package/src/edit-field/useEditField.js

@@ -0,0 +1,218 @@
+import { DataValidationError, dispatchCustomEvent, getTypedValue, isRpcError, isRpcSuccess } from "@vuu-ui/vuu-utils";
+import { useCallback, useEffect, useRef, useState } from "react";
+const stringValueOf = (value)=>value?.toString() ?? "";
+const useEditField = ({ column, value, onEdit, textType, type = "string" })=>{
+    const [editState, setEditState] = useState({
+        editing: false,
+        value: stringValueOf(value)
+    });
+    const initialValueRef = useRef(value?.toString() ?? "");
+    const isDirtyRef = useRef(false);
+    useEffect(()=>{
+        const nextValue = stringValueOf(value);
+        if (initialValueRef.current !== nextValue) {
+            initialValueRef.current = nextValue;
+            isDirtyRef.current = false;
+            setEditState((editState)=>({
+                    ...editState,
+                    message: void 0,
+                    value: nextValue
+                }));
+        }
+    }, [
+        value
+    ]);
+    const commit = useCallback(async (value = editState.value)=>{
+        const result = column.clientSideEditValidationCheck?.(value, "*");
+        if (result?.ok === false) setEditState((state)=>({
+                ...state,
+                message: result?.messages?.join(",")
+            }));
+        else {
+            const { current: initialValue } = initialValueRef;
+            const previousValue = getTypedValue(initialValue, type);
+            try {
+                const typedValue = getTypedValue(value, type, true);
+                const response = await onEdit?.({
+                    editType: "commit",
+                    isValid: true,
+                    previousValue,
+                    value: typedValue
+                }, "commit");
+                if (isRpcSuccess(response)) {
+                    isDirtyRef.current = false;
+                    setEditState((state)=>({
+                            editing: false,
+                            previousValue: state.previousValue === value ? void 0 : void 0 === state.previousValue ? initialValue : state.previousValue,
+                            value
+                        }));
+                } else if (isRpcError(response)) {
+                    setEditState((state)=>({
+                            ...state,
+                            message: response.errorMessage
+                        }));
+                    return false;
+                }
+                initialValueRef.current = value;
+                return true;
+            } catch (e) {
+                if (e instanceof DataValidationError) {
+                    const { actualType, expectedType, message } = e;
+                    if (column) {
+                        const { name, label = name } = column;
+                        const message = `${label} is a ${expectedType} value, data entered is ${actualType} `;
+                        setEditState((state)=>({
+                                ...state,
+                                message
+                            }));
+                        onEdit?.({
+                            editType: "commit",
+                            isValid: false,
+                            previousValue,
+                            value
+                        }, "commit");
+                    } else setEditState((state)=>({
+                            ...state,
+                            message
+                        }));
+                }
+            }
+        }
+        return false;
+    }, [
+        column,
+        editState,
+        onEdit,
+        type
+    ]);
+    const toggleActivation = useCallback(async (input, cancel = false)=>{
+        if (editState.editing) if (isDirtyRef.current) if (cancel) {
+            const { value: previousValue } = editState;
+            isDirtyRef.current = false;
+            setEditState({
+                editing: false,
+                value: initialValueRef.current,
+                message: void 0
+            });
+            onEdit?.({
+                editType: "cancel",
+                isValid: true,
+                previousValue,
+                value: getTypedValue(initialValueRef.current, type, true)
+            }, "commit");
+        } else {
+            const commitSuccessful = await commit();
+            if (commitSuccessful) {
+                setEditState((editState)=>({
+                        ...editState,
+                        editing: false
+                    }));
+                dispatchCustomEvent(input, "vuu-commit");
+            }
+        }
+        else setEditState((editState)=>({
+                ...editState,
+                editing: false
+            }));
+        else if (!cancel) {
+            setEditState((editState)=>({
+                    ...editState,
+                    editing: true
+                }));
+            input.select();
+        }
+    }, [
+        commit,
+        editState,
+        onEdit,
+        type
+    ]);
+    const handleKeyDown = useCallback(async (evt)=>{
+        const { key, target } = evt;
+        const input = target;
+        if ("Enter" === key) toggleActivation(input);
+        else if ("ArrowRight" === key || "ArrowLeft" === key || "ArrowUp" === key || "ArrowDown" === key) {
+            if (editState.editing) evt.stopPropagation();
+        } else if ("Escape" === evt.key) toggleActivation(input, true);
+    }, [
+        editState,
+        toggleActivation
+    ]);
+    const handleFocus = useCallback((e)=>{
+        const input = e.target;
+        const source = e.relatedTarget;
+        if (source?.classList.contains("vuuTableCell") && source.contains(input)) toggleActivation(input);
+    }, [
+        toggleActivation
+    ]);
+    const handleBlur = useCallback(async ()=>{
+        if (editState.editing) {
+            if (isDirtyRef.current) await commit();
+            setEditState((editState)=>({
+                    ...editState,
+                    editing: false
+                }));
+        }
+    }, [
+        commit,
+        editState
+    ]);
+    const handleChange = useCallback((evt)=>{
+        const { value } = evt.target;
+        isDirtyRef.current = value !== initialValueRef.current;
+        const result = column.clientSideEditValidationCheck?.(value, "change");
+        setEditState({
+            editing: true,
+            value
+        });
+        onEdit?.({
+            editType: "change",
+            isValid: result?.ok !== false,
+            previousValue: initialValueRef.current,
+            value
+        }, "change");
+        if (result?.ok === false) setEditState({
+            editing: true,
+            value,
+            message: result.messages?.join(",")
+        });
+    }, [
+        column,
+        onEdit
+    ]);
+    const handleDropdownSelectionChange = useCallback((_evt, [selectedOption])=>{
+        if (!selectedOption) return;
+        const value = String(selectedOption.value);
+        isDirtyRef.current = value !== initialValueRef.current;
+        setEditState((state)=>({
+                ...state,
+                editing: true,
+                message: void 0,
+                value
+            }));
+        commit(value).then((committed)=>{
+            if (committed) setEditState((state)=>({
+                    ...state,
+                    editing: false,
+                    value
+                }));
+        });
+    }, [
+        commit
+    ]);
+    return {
+        editing: editState.editing,
+        inputProps: {
+            onBlur: handleBlur,
+            onFocus: handleFocus,
+            type: textType
+        },
+        onKeyDown: handleKeyDown,
+        previousValue: editState.previousValue,
+        value: editState.value,
+        warningMessage: editState.message,
+        onChange: handleChange,
+        onDropdownSelectionChange: handleDropdownSelectionChange
+    };
+};
+export { useEditField };

package/src/index.js

@@ -4,9 +4,13 @@ export { useCellEdited } from "./useCellEdited.js";
 export { useEditState } from "./useEditState.js";
 export { getVuuEditMessage, isEditRowReadOnly, isInlineEditingSession, withDataRowEditErrors } from "./edit-utils.js";
 export { EditButtons } from "./EditButtons.js";
+export { EditField } from "./edit-field/EditField.js";
+export { useEditField } from "./edit-field/useEditField.js";
 export { EditModeProvider, useEditMode } from "./EditModeProvider.js";
 export { EditError, EditSession, SupersededEditError } from "./EditSession.js";
 export { StaleUpdateError } from "@vuu-ui/vuu-utils";
+export { lookupOptionsFromRows, useLookupValues } from "./lookup-values/useLookupValues.js";
+export { useEditable } from "./useEditable.js";
 export { EDIT_ACTION_ROW_CLASS_NAME_GENERATOR, editActionRowClassNameGenerator } from "./editActionRowClassNameGenerator.js";
 export { UNDO_CELL_RENDERER, UndoCellRenderer, getUndoButtonContent, getUndoTooltipContent } from "./UndoCellRenderer.js";
 export { useEditableTable } from "./useEditableTable.js";

package/src/lookup-values/useLookupValues.js

@@ -0,0 +1,78 @@
+import { Range, useData } from "@vuu-ui/vuu-utils";
+import { useEffect, useMemo, useState } from "react";
+const DATA_ROW_COLUMN_OFFSET = 10;
+const lookupOptionsFromRows = (columns, rows, optionMap)=>{
+    const requestedColumns = [
+        optionMap.value,
+        optionMap.label,
+        ...optionMap.additionalFields ?? []
+    ];
+    const missingColumns = requestedColumns.filter((column)=>!columns.includes(column));
+    if (missingColumns.length > 0) throw Error(`[useLookupValues] lookup columns not found: ${requestedColumns.join(", ")}`);
+    return rows.map((row)=>{
+        const metadata = Object.fromEntries((optionMap.additionalFields ?? []).map((field)=>[
+                field,
+                String(row[columns.indexOf(field) + DATA_ROW_COLUMN_OFFSET])
+            ]));
+        return {
+            value: String(row[columns.indexOf(optionMap.value) + DATA_ROW_COLUMN_OFFSET]),
+            label: String(row[columns.indexOf(optionMap.label) + DATA_ROW_COLUMN_OFFSET]),
+            ...Object.keys(metadata).length > 0 ? {
+                metadata
+            } : {}
+        };
+    });
+};
+const useLookupValues = ({ enabled, optionMap, table })=>{
+    if (enabled && (void 0 === optionMap || void 0 === table)) throw Error("[useLookupValues] optionsMap and Table must be provided");
+    const { VuuDataSource } = useData();
+    const [options, setOptions] = useState([]);
+    const lookupColumns = useMemo(()=>optionMap ? [
+            optionMap.value,
+            optionMap.label,
+            ...optionMap.additionalFields ?? []
+        ] : [], [
+        optionMap
+    ]);
+    const dataSource = useMemo(()=>enabled && optionMap && table ? new VuuDataSource({
+            columns: lookupColumns,
+            table
+        }) : void 0, [
+        VuuDataSource,
+        enabled,
+        lookupColumns,
+        optionMap,
+        table
+    ]);
+    useEffect(()=>{
+        setOptions([]);
+        if (!dataSource || !optionMap) return;
+        let active = true;
+        let columns;
+        const subscribe = (message)=>{
+            if (!active) return;
+            if ("subscribed" === message.type) {
+                const schemaColumns = new Set(message.tableSchema.columns.map(({ name })=>name));
+                if (!lookupColumns.every((column)=>message.columns.includes(column) && schemaColumns.has(column))) throw Error(`[useLookupValues] lookup columns not found: ${lookupColumns.join(", ")}`);
+                columns = message.columns;
+            } else if ("viewport-update" === message.type && columns) setOptions(lookupOptionsFromRows(columns, message.rows ?? [], optionMap));
+            else if ("subscribe-failed" === message.type) console.error(`Lookup table ${table?.table} subscription failed: ${message.msg}`);
+        };
+        dataSource.subscribe({
+            range: Range(0, 100)
+        }, subscribe).catch((cause)=>{
+            if (active) console.error("Role client dropdown subscription failed:", cause);
+        });
+        return ()=>{
+            active = false;
+            dataSource.unsubscribe();
+        };
+    }, [
+        dataSource,
+        lookupColumns,
+        optionMap,
+        table
+    ]);
+    return options;
+};
+export { lookupOptionsFromRows, useLookupValues };

package/src/useEditable.js

@@ -0,0 +1,53 @@
+import { EditSession } from "./EditSession.js";
+import { useEditMode } from "./EditModeProvider.js";
+import { useCallback, useEffect, useMemo } from "react";
+const useEditable = ({ copyOption = "Selected", dataSource, onCancel, onSave })=>{
+    const { isEditMode } = useEditMode();
+    const editSession = useMemo(()=>new EditSession({
+            dataSource
+        }), [
+        dataSource
+    ]);
+    const handleCancel = useCallback(async ()=>{
+        try {
+            await editSession.end();
+            onCancel();
+        } catch (error) {
+            console.error("[useEditable] cancel edit session failed", error);
+        }
+    }, [
+        editSession,
+        onCancel
+    ]);
+    const handleSave = useCallback(async (force = false)=>{
+        try {
+            await editSession.end(true, force);
+            onSave();
+        } catch (error) {
+            console.error("[useEditable] save edit session failed", error);
+        }
+    }, [
+        editSession,
+        onSave
+    ]);
+    useEffect(()=>{
+        const transition = isEditMode ? editSession.begin(copyOption) : editSession.end();
+        transition.catch((error)=>{
+            if (isEditMode) {
+                console.error("[useEditable] begin edit session failed", error);
+                handleCancel();
+            } else console.error("[useEditable] end edit session failed", error);
+        });
+    }, [
+        copyOption,
+        editSession,
+        isEditMode,
+        handleCancel
+    ]);
+    return {
+        editSession,
+        onCancel: handleCancel,
+        onSave: handleSave
+    };
+};
+export { useEditable };

package/types/EditModeProvider.d.ts

@@ -1,4 +1,4 @@
-import { ReactNode } from "react";
+import { type ReactNode } from "react";
 export interface EditModeContextProps {
     isEditMode: boolean;
     setEditMode: (inEditMode: boolean) => void;
@@ -7,7 +7,8 @@ export interface EditModeContextProps {
  * Implemented as a standalone Provider so that EditMode cna be implemented
  * at higher level than individual edit controls.
  */
-export declare const EditModeProvider: ({ children }: {
+export declare const EditModeProvider: ({ children, isEditMode: isEditModeProp, }: {
     children: ReactNode;
+    isEditMode?: boolean;
 }) => import("react/jsx-runtime").JSX.Element;
 export declare const useEditMode: () => EditModeContextProps;

package/types/EditSession.d.ts

@@ -4,6 +4,11 @@ import { EventEmitter } from "@vuu-ui/vuu-utils";
 import type { TableEditSession } from "./TableEditSession";
 export type EditState = "clean" | "dirty" | "invalid" | "stale";
 export type EditActionType = "deleteRow" | "addRow" | "editCell";
+export type EditSessionValue = VuuRowDataItemType | object;
+export type EditCommitOptions = {
+    dataSourceValue?: VuuRowDataItemType;
+    syncToDataSource?: boolean;
+};
 /** Column name to default value mapping applied to every addRow call when a column is absent from the row data. */
 export type RowDefaultDataItemValues = Record<string, VuuRowDataItemType>;
 export type EditSessionApi = "createSessionDataSource" | "beginEditSession";
@@ -60,6 +65,8 @@ export declare class EditSession extends EventEmitter<EditSessionEvents> impleme
     get addCount(): number;
     get editState(): EditState;
     get isDirty(): boolean;
+    get canCancel(): boolean;
+    get canSave(): boolean;
     get newRowState(): NewRowState;
     isNewRow(key: string): key is "__vuu_new_row__";
     isNewRowFinalColumn(columnName: string): boolean;
@@ -84,6 +91,6 @@ export declare class EditSession extends EventEmitter<EditSessionEvents> impleme
     get lifecycle(): EditLifecycle;
     get inEditMode(): boolean;
     cancel(key: string, columnName: string, restoredValue: VuuRowDataItemType): Promise<RpcResult>;
-    commit(key: string, columnName: string, originalValue: VuuRowDataItemType, typedValue: string | number | boolean, isValid: boolean): Promise<RpcResult>;
+    commit(key: string, columnName: string, originalValue: EditSessionValue, typedValue: EditSessionValue, isValid: boolean, { dataSourceValue, syncToDataSource }?: EditCommitOptions): Promise<RpcResult>;
 }
 export {};

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

@@ -0,0 +1,21 @@
+import type { DataRow } from "@vuu-ui/vuu-table-types";
+import type { 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;
+    deferNewRow?: boolean;
+    label: string;
+    name: string;
+    readOnly?: boolean;
+    required?: boolean;
+    type?: EditFieldType;
+}
+export interface DropdownEditFieldProps extends EditFieldProps {
+    type: "dropdown";
+    optionMap: OptionMap;
+    table: VuuTable;
+}
+export declare const EditField: ({ dataRow, deferNewRow, label, name, readOnly, required, type, ...options }: EditFieldProps | DropdownEditFieldProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,26 @@
+import type { VuuRowDataItemType } from "@vuu-ui/vuu-protocol-types";
+import type { RuntimeColumnDescriptor, TableCellEditHandler } from "@vuu-ui/vuu-table-types";
+import { type ChangeEventHandler, type FocusEventHandler, type KeyboardEvent, type SyntheticEvent } from "react";
+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">;
+    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>) => {
+    editing: boolean;
+    inputProps: {
+        onBlur: FocusEventHandler<HTMLElement>;
+        onFocus: FocusEventHandler<HTMLElement>;
+        type: TextFieldType | undefined;
+    };
+    onKeyDown: (evt: KeyboardEvent<HTMLElement>) => Promise<void>;
+    previousValue: string | undefined;
+    value: string;
+    warningMessage: string | undefined;
+    onChange: ChangeEventHandler<HTMLInputElement>;
+    onDropdownSelectionChange: (_evt: SyntheticEvent, [selectedOption]: LookupOption[]) => void;
+};

package/types/index.d.ts

@@ -5,9 +5,13 @@ export { useCellEdited } from "./useCellEdited";
 export { useEditState } from "./useEditState";
 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 EditActionType, type EditLifecycle, type EditSessionConstructorProps, type NewRowState, type EditState, type RowDefaultDataItemValues, } from "./EditSession";
+export { EditError, EditSession, SupersededEditError, type EditActionType, type EditCommitOptions, type EditLifecycle, 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";

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

@@ -0,0 +1,19 @@
+import type { DataSourceRow } from "@vuu-ui/vuu-data-types";
+import type { VuuTable } from "@vuu-ui/vuu-protocol-types";
+export type LookupOption = {
+    label: string;
+    metadata?: Record<string, string>;
+    value: number | string;
+};
+export type OptionMap = {
+    additionalFields?: readonly string[];
+    label: string;
+    value: string;
+};
+export interface LookupValuedHookProps {
+    enabled: boolean;
+    optionMap?: OptionMap;
+    table?: VuuTable;
+}
+export declare const lookupOptionsFromRows: (columns: string[], rows: DataSourceRow[], optionMap: OptionMap) => LookupOption[];
+export declare const useLookupValues: ({ enabled, optionMap, table, }: LookupValuedHookProps) => LookupOption[];

package/types/src/DataEditingProvider.d.ts

@@ -0,0 +1,8 @@
+import { type ReactNode } from "react";
+import type { EditSession } from "./EditSession";
+export declare const DataEditingProvider: ({ children, editSession, }: {
+    children: ReactNode;
+    editSession: EditSession;
+}) => import("react").JSX.Element;
+export declare function useEditSession(throwIfUnavailable?: false): EditSession | undefined;
+export declare function useEditSession(throwIfUnavailable: true): EditSession;

package/types/src/EditButtons.d.ts

@@ -0,0 +1,14 @@
+import type { EditSession } from "./EditSession";
+export interface EditButtonProps {
+    canCancel: boolean;
+    canSave: boolean;
+    editSession?: EditSession;
+    hasSelection?: boolean;
+    onCancel?: () => void;
+    onDelete?: () => void;
+    onSave: (force?: boolean) => void;
+    saveLabel?: string;
+    confirmSave?: () => boolean | Promise<boolean>;
+    confirmCancel?: () => boolean | Promise<boolean>;
+}
+export declare const EditButtons: ({ canCancel, canSave, confirmCancel, confirmSave, editSession, hasSelection, onCancel, onDelete, onSave, saveLabel, }: EditButtonProps) => import("react").JSX.Element;

package/types/src/EditModeProvider.d.ts

@@ -0,0 +1,13 @@
+import { ReactNode } from "react";
+export interface EditModeContextProps {
+    isEditMode: boolean;
+    setEditMode: (inEditMode: boolean) => void;
+}
+/**
+ * Implemented as a standalone Provider so that EditMode cna be implemented
+ * at higher level than individual edit controls.
+ */
+export declare const EditModeProvider: ({ children }: {
+    children: ReactNode;
+}) => import("react").JSX.Element;
+export declare const useEditMode: () => EditModeContextProps;

package/types/src/EditSession.d.ts

@@ -0,0 +1,86 @@
+import type { CopyOption, DataSource, DeleteRowMode, SessionType } from "@vuu-ui/vuu-data-types";
+import type { RpcResult, VuuRowDataItemType } from "@vuu-ui/vuu-protocol-types";
+import { EventEmitter } from "@vuu-ui/vuu-utils";
+export type EditState = "clean" | "dirty" | "invalid" | "stale";
+export type EditActionType = "deleteRow" | "addRow" | "editCell";
+/** Column name to default value mapping applied to every addRow call when a column is absent from the row data. */
+export type RowDefaultDataItemValues = Record<string, VuuRowDataItemType>;
+export type EditSessionApi = "createSessionDataSource" | "beginEditSession";
+export type EditSessionConstructorProps = {
+    dataSource: DataSource;
+    /** @default "soft" */
+    deleteMode?: DeleteRowMode;
+    /** @default "createSessionDataSource" */
+    editSessionApi?: EditSessionApi;
+    /** Default column values merged into every addRow call for absent columns. Pass a stable reference. */
+    rowDefaults?: RowDefaultDataItemValues;
+};
+export type NewRowState = {
+    columns: readonly string[];
+    requiredColumns?: readonly string[];
+    draftRevision: number;
+    errors: Readonly<Record<string, string>>;
+    submitting: boolean;
+    values: Readonly<Record<string, VuuRowDataItemType>>;
+};
+export type EditLifecycle = {
+    status: "idle";
+} | {
+    status: "starting";
+} | {
+    status: "active";
+    sessionDataSource: DataSource;
+} | {
+    status: "ending";
+    sessionDataSource: DataSource;
+} | {
+    status: "error";
+    operation: "begin" | "end";
+    error: Error;
+    sessionDataSource?: DataSource;
+};
+export declare class EditError extends Error {
+}
+export declare class SupersededEditError extends Error {
+}
+type EditSessionEvents = {
+    cellEditChanged: (key: string, columnName: string) => void;
+    editState: (editState: EditState) => void;
+    lifecycle: (lifecycle: EditLifecycle) => void;
+    newRow: (newRowState: NewRowState) => void;
+};
+export declare class EditSession extends EventEmitter<EditSessionEvents> {
+    #private;
+    static readonly newRowKey = "__vuu_new_row__";
+    constructor({ dataSource, deleteMode, editSessionApi, rowDefaults, }: EditSessionConstructorProps);
+    get editCount(): number;
+    get invalidCount(): number;
+    get deleteCount(): number;
+    get addCount(): number;
+    get editState(): EditState;
+    get newRowState(): NewRowState;
+    isNewRow(key: string): key is "__vuu_new_row__";
+    isNewRowFinalColumn(columnName: string): boolean;
+    isNewRowComplete(): boolean;
+    configureNewRow(columns: readonly string[], requiredColumns?: readonly string[]): void;
+    setNewRowValue(column: string, value: VuuRowDataItemType): void;
+    addNewRow(): Promise<RpcResult>;
+    deleteSelectedRows(): Promise<RpcResult>;
+    addRow(rowData?: Record<string, VuuRowDataItemType>): Promise<RpcResult>;
+    hasRowChanges(key: string): boolean;
+    isCellEdited(key: string, columnName: string): boolean;
+    undoRowChange(key: string, action: EditActionType): Promise<RpcResult | undefined>;
+    begin(copyOption?: CopyOption, sessionType?: SessionType): Promise<DataSource>;
+    /**
+     * Safe to call repeatedly - schema of a remote session table typically arrives
+     * after begin() resolves, so callers re-invoke this once 'subscribed' fires.
+     */
+    reconcileWithSessionSchema(): void;
+    get dataSource(): import("@vuu-ui/vuu-data-types").DataSourceBase<import("@vuu-ui/vuu-data-types").DataSourceRowWithBigint> | undefined;
+    get sessionDataSource(): DataSource | undefined;
+    end(saveChanges?: boolean, force?: boolean): Promise<void>;
+    get lifecycle(): EditLifecycle;
+    get inEditMode(): boolean;
+    commit(key: string, columnName: string, originalValue: VuuRowDataItemType, typedValue: string | number | boolean, isValid: boolean): Promise<RpcResult>;
+}
+export {};

package/types/src/UndoCellRenderer.d.ts

@@ -0,0 +1,12 @@
+import type { TableCellRendererProps } from "@vuu-ui/vuu-table-types";
+export declare const UNDO_CELL_RENDERER = "vuu.undo-cell";
+export interface UndoCellRendererComponentProps {
+    icon?: string;
+    text?: string | false;
+}
+export declare const getUndoButtonContent: (componentProps?: UndoCellRendererComponentProps) => {
+    icon: string | undefined;
+    text: string | undefined;
+};
+export declare const getUndoTooltipContent: (action: unknown) => "Undo delete row" | "Undo insert row" | "Undo row edits" | undefined;
+export declare const UndoCellRenderer: ({ column, dataRow, }: TableCellRendererProps) => import("react").JSX.Element | null;

package/types/src/edit-utils.d.ts

@@ -0,0 +1,5 @@
+import type { DataRow, RuntimeColumnDescriptor } from "@vuu-ui/vuu-table-types";
+export { isInlineEditingSession } from "@vuu-ui/vuu-utils";
+export declare const isEditRowReadOnly: (dataRow: DataRow) => boolean;
+export declare const withDataRowEditErrors: <T extends DataRow>(dataRow: T, errors: Record<string, string>) => T;
+export declare const getVuuEditMessage: (dataRow: DataRow, column: RuntimeColumnDescriptor, originalValue: string) => string | import("react").JSX.Element | undefined;

package/types/src/editActionRowClassNameGenerator.d.ts

@@ -0,0 +1,3 @@
+import type { DataRow } from "@vuu-ui/vuu-table-types";
+export declare const EDIT_ACTION_ROW_CLASS_NAME_GENERATOR = "vuu-edit-actions";
+export declare const editActionRowClassNameGenerator: (dataRow: DataRow) => "vuuTableRow-deleted" | "vuuTableRow-inserted" | undefined;

package/types/src/index.d.ts

@@ -0,0 +1,10 @@
+export { DataEditingProvider, useEditSession } from "./DataEditingProvider";
+export { useCellEdited } from "./useCellEdited";
+export { getVuuEditMessage, isInlineEditingSession, isEditRowReadOnly, withDataRowEditErrors, } from "./edit-utils";
+export { EditButtons, type EditButtonProps } from "./EditButtons";
+export { EditModeProvider, useEditMode, type EditModeContextProps, } from "./EditModeProvider";
+export { EditError, EditSession, SupersededEditError, type EditActionType, type EditLifecycle, type EditSessionConstructorProps, type NewRowState, type EditState, type RowDefaultDataItemValues, } from "./EditSession";
+export { StaleUpdateError } from "@vuu-ui/vuu-utils";
+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";

package/types/src/useCellEdited.d.ts

@@ -0,0 +1,2 @@
+import type { EditSession } from "./EditSession";
+export declare const useCellEdited: (editSession: EditSession | undefined, key: string, columnName: string) => boolean;

package/types/src/useEditableTable.d.ts

@@ -0,0 +1,44 @@
+import type { CopyOption, DataSource, DeleteRowMode } from "@vuu-ui/vuu-data-types";
+import type { VuuTable } from "@vuu-ui/vuu-protocol-types";
+import { EditSession, type EditActionType, type EditLifecycle, type EditSessionApi, type RowDefaultDataItemValues } from "./EditSession";
+export type EditMode = "edit" | "view";
+export interface EditableTableHookProps {
+    /**
+     * columns to be included in subscription. If not provided,
+     * default will be '*'. Ignored if dataSource prop present.
+     */
+    columns?: string[];
+    dataSource?: DataSource;
+    addRowsCount?: number;
+    deleteMode?: DeleteRowMode;
+    editSessionApi?: EditSessionApi;
+    copyOption?: CopyOption;
+    isEditMode: boolean;
+    onCancel: () => void;
+    onSave: () => void;
+    /** Default column values applied to every addRow call. Pass a stable reference — a new object triggers EditSession recreation. */
+    rowDefaults?: RowDefaultDataItemValues;
+    /**
+     * If dataSource not provided, new DataSource
+     * will be created using table and columns
+     */
+    table?: VuuTable;
+}
+export declare const useEditableTable: ({ columns, dataSource: dataSourceProp, deleteMode, editSessionApi, copyOption, isEditMode, onCancel, onSave, rowDefaults, table, }: EditableTableHookProps) => {
+    canCancel: boolean;
+    canSave: boolean;
+    columnsDiverge: boolean;
+    dataSource: DataSource;
+    editSchema: import("@vuu-ui/vuu-data-types").TableSchema | undefined;
+    editSession: EditSession;
+    lifecycle: EditLifecycle;
+    hasSelection: boolean;
+    isEditSessionReady: boolean;
+    onCancel: () => Promise<void>;
+    onDelete: () => Promise<void>;
+    onSave: (force?: boolean) => Promise<void>;
+    onUndoRowChange: (key: string, action: EditActionType) => undefined;
+    rowClassNameGenerators: string[] | undefined;
+    sessionDataSource: import("@vuu-ui/vuu-data-types").DataSourceBase<import("@vuu-ui/vuu-data-types").DataSourceRowWithBigint> | undefined;
+    sourceDataSource: DataSource;
+};

package/types/useEditable.d.ts

@@ -0,0 +1,13 @@
+import type { CopyOption, DataSource } from "@vuu-ui/vuu-data-types";
+import { EditSession } from "./EditSession";
+export interface EditableHookProps {
+    copyOption?: CopyOption;
+    dataSource: DataSource;
+    onCancel: () => void;
+    onSave: () => void;
+}
+export declare const useEditable: ({ copyOption, dataSource, onCancel, onSave, }: EditableHookProps) => {
+    editSession: EditSession;
+    onCancel: () => Promise<void>;
+    onSave: (force?: boolean) => Promise<void>;
+};