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

package/src/useCustomEditField.js

@@ -0,0 +1,76 @@
+import { isRpcError } from "@vuu-ui/vuu-utils";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { useEditSession } from "./DataEditingProvider.js";
+import { toError } from "./edit-errors.js";
+import { useEditSessionState } from "./useEditSessionState.js";
+const useCustomEditField = ({ editSession: editSessionProp, equals = Object.is, name, onError, originalValue, rowKey, serialize })=>{
+    const contextEditSession = useEditSession();
+    const editSession = editSessionProp ?? contextEditSession;
+    const { inEditMode } = useEditSessionState(editSession);
+    const [value, setValueState] = useState(originalValue);
+    const [error, setError] = useState();
+    const [committing, setCommitting] = useState(false);
+    const onErrorRef = useRef(onError);
+    onErrorRef.current = onError;
+    const latestCommitRef = useRef(0);
+    useEffect(()=>{
+        if (!inEditMode) {
+            setValueState(originalValue);
+            setError(void 0);
+        }
+    }, [
+        inEditMode,
+        originalValue
+    ]);
+    const setValue = useCallback(async (nextValue)=>{
+        if (!editSession) throw Error("[useCustomEditField] no EditSession, pass editSession or use a DataEditingProvider");
+        const original = originalValue ?? nextValue;
+        const committedValue = void 0 !== originalValue && equals(nextValue, originalValue) ? originalValue : nextValue;
+        const commitId = ++latestCommitRef.current;
+        setValueState(committedValue);
+        setCommitting(true);
+        setError(void 0);
+        try {
+            const response = await editSession.commit(rowKey, name, original, committedValue, true, serialize ? {
+                dataSourceValue: serialize(committedValue)
+            } : {});
+            if (isRpcError(response) && commitId === latestCommitRef.current) {
+                const err = new Error(response.errorMessage);
+                setError(err);
+                onErrorRef.current?.(err);
+            }
+        } catch (cause) {
+            if (commitId === latestCommitRef.current) {
+                const err = toError(cause);
+                setError(err);
+                if (onErrorRef.current) onErrorRef.current(err);
+                else console.error("[useCustomEditField] commit %s failed", name, err);
+            }
+        } finally{
+            if (commitId === latestCommitRef.current) setCommitting(false);
+        }
+    }, [
+        editSession,
+        equals,
+        name,
+        originalValue,
+        rowKey,
+        serialize
+    ]);
+    const reset = useCallback(()=>{
+        setValueState(originalValue);
+        setError(void 0);
+    }, [
+        originalValue
+    ]);
+    const isDirty = void 0 !== value && void 0 !== originalValue && !equals(value, originalValue);
+    return {
+        committing,
+        error,
+        isDirty,
+        reset,
+        setValue,
+        value
+    };
+};
+export { useCustomEditField };

package/src/useEditForm.js

@@ -0,0 +1,306 @@
+import { isRpcError, isRpcSuccess } from "@vuu-ui/vuu-utils";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { EditSession } from "./EditSession.js";
+import { DirectEditSession } from "./DirectEditSession.js";
+import { useEditMode } from "./EditModeProvider.js";
+import { reportEditError, toError } from "./edit-errors.js";
+import { useEditSessionState } from "./useEditSessionState.js";
+const EMPTY_ERRORS = {};
+const NEW_ROW = {
+    key: EditSession.newRowKey
+};
+const getDataRowValues = (dataRow)=>{
+    const { toJSON } = dataRow;
+    const values = "function" == typeof toJSON ? toJSON.call(dataRow) : {
+        ...dataRow
+    };
+    return {
+        ...values,
+        key: dataRow.key
+    };
+};
+const isEmptyValue = (value)=>null == value || "string" == typeof value && "" === value.trim();
+const toRowSnapshot = (key, values)=>({
+        ...values,
+        key
+    });
+class FormDirectEditSession extends DirectEditSession {
+    #onCommitted;
+    constructor(props, onCommitted){
+        super(props);
+        this.#onCommitted = onCommitted;
+    }
+    async commit(key, columnName, originalValue, typedValue, isValid) {
+        const response = await super.commit(key, columnName, originalValue, typedValue, isValid);
+        if (isRpcSuccess(response)) this.#onCommitted(columnName, typedValue);
+        return response;
+    }
+}
+const hasErrors = (errors)=>null != errors && Object.keys(errors).length > 0;
+const useEditForm = ({ columns, dataRow, dataSource, deleteMode, editModel = "session", editSession: sharedEditSession, editSessionApi, isEditMode: isEditModeProp, mode = "edit", onCancelled, onError, onSaved, requiredColumns, rowDefaults, validate })=>{
+    const { isEditMode: isEditModeContext } = useEditMode();
+    const isCreate = "create" === mode;
+    const isDirect = !isCreate && "direct" === editModel;
+    const isShared = isCreate && void 0 !== sharedEditSession;
+    const ownsSession = !isDirect && !isShared;
+    const isEditMode = isCreate || (isEditModeProp ?? isEditModeContext);
+    const [saving, setSaving] = useState(false);
+    const [error, setError] = useState();
+    const [validationErrors, setValidationErrors] = useState(EMPTY_ERRORS);
+    const savingRef = useRef(false);
+    const rowAddedRef = useRef(false);
+    const [rowAdded, setRowAdded] = useState(false);
+    const markRowAdded = useCallback((added)=>{
+        rowAddedRef.current = added;
+        setRowAdded(added);
+    }, []);
+    const callbacksRef = useRef({
+        onCancelled,
+        onError,
+        onSaved,
+        validate
+    });
+    callbacksRef.current = {
+        onCancelled,
+        onError,
+        onSaved,
+        validate
+    };
+    const editSession = useMemo(()=>sharedEditSession ?? new EditSession({
+            dataSource,
+            deleteMode,
+            editSessionApi,
+            rowDefaults
+        }), [
+        dataSource,
+        deleteMode,
+        editSessionApi,
+        rowDefaults,
+        sharedEditSession
+    ]);
+    const [directValues, setDirectValues] = useState({});
+    const directRowKey = isDirect ? dataRow?.key : void 0;
+    useEffect(()=>{
+        setDirectValues({});
+    }, [
+        directRowKey
+    ]);
+    const directValuesRef = useRef(directValues);
+    directValuesRef.current = directValues;
+    const dataRowRef = useRef(dataRow);
+    dataRowRef.current = dataRow;
+    const requiredRef = useRef(requiredColumns);
+    requiredRef.current = requiredColumns;
+    const directEditSession = useMemo(()=>isDirect ? new FormDirectEditSession({
+            dataSource,
+            validate: (_key, columnName, value)=>{
+                if (requiredRef.current?.includes(columnName) && isEmptyValue(value)) return "A value is required";
+                const { current: row } = dataRowRef;
+                const values = {
+                    ...row ? getDataRowValues(row) : void 0,
+                    ...directValuesRef.current,
+                    [columnName]: value
+                };
+                return callbacksRef.current.validate?.(values)?.[columnName];
+            }
+        }, (columnName, value)=>setDirectValues((values)=>({
+                    ...values,
+                    [columnName]: value
+                }))) : void 0, [
+        dataSource,
+        isDirect
+    ]);
+    const sessionState = useEditSessionState(editSession);
+    const [, setValuesRevision] = useState(0);
+    const rowKey = dataRow?.key;
+    useEffect(()=>{
+        if (isCreate || void 0 === rowKey) return;
+        const onCellEditChanged = (key)=>{
+            if (key === rowKey) setValuesRevision((n)=>n + 1);
+        };
+        editSession.on("cellEditChanged", onCellEditChanged);
+        return ()=>{
+            editSession.removeListener("cellEditChanged", onCellEditChanged);
+        };
+    }, [
+        editSession,
+        isCreate,
+        rowKey
+    ]);
+    const fail = useCallback((cause, operation)=>{
+        const err = toError(cause);
+        setError(err);
+        reportEditError("useEditForm", callbacksRef.current.onError, err, operation);
+    }, []);
+    useEffect(()=>{
+        if (isCreate && columns) editSession.configureNewRow(columns, requiredColumns);
+    }, [
+        columns,
+        editSession,
+        isCreate,
+        requiredColumns
+    ]);
+    useEffect(()=>{
+        setError(void 0);
+        setValidationErrors(EMPTY_ERRORS);
+        markRowAdded(false);
+        if (!ownsSession) return;
+        const transition = isEditMode ? editSession.begin(isCreate ? "Empty" : "Selected") : editSession.end();
+        transition.catch((cause)=>fail(cause, isEditMode ? "begin" : "cancel"));
+    }, [
+        editSession,
+        fail,
+        isCreate,
+        isEditMode,
+        markRowAdded,
+        ownsSession
+    ]);
+    useEffect(()=>()=>{
+            if (isShared) editSession.clearNewRow();
+            else if (ownsSession) editSession.end().catch(()=>void 0);
+        }, [
+        editSession,
+        isShared,
+        ownsSession
+    ]);
+    const getValues = useCallback(()=>{
+        if (isCreate) return editSession.newRowState.values;
+        if (isDirect && dataRow) return {
+            ...getDataRowValues(dataRow),
+            ...directValuesRef.current
+        };
+        if (dataRow) return {
+            ...getDataRowValues(dataRow),
+            ...editSession.getEditedValues(dataRow.key)
+        };
+        return {};
+    }, [
+        dataRow,
+        editSession,
+        isCreate,
+        isDirect
+    ]);
+    const submit = useCallback(async (force = false)=>{
+        if (savingRef.current) return false;
+        setError(void 0);
+        if (isDirect) {
+            callbacksRef.current.onSaved?.();
+            return true;
+        }
+        if (!rowAddedRef.current) {
+            const errors = callbacksRef.current.validate?.(getValues());
+            if (hasErrors(errors)) {
+                setValidationErrors(errors);
+                return false;
+            }
+            setValidationErrors(EMPTY_ERRORS);
+        }
+        savingRef.current = true;
+        setSaving(true);
+        try {
+            if (isCreate && !rowAddedRef.current) {
+                const response = await editSession.addNewRow();
+                if (isRpcError(response)) {
+                    setError(new Error(response.errorMessage));
+                    return false;
+                }
+                if (hasErrors(editSession.newRowState.errors)) return false;
+                if (isShared) {
+                    callbacksRef.current.onSaved?.();
+                    return true;
+                }
+                markRowAdded(true);
+            }
+            await editSession.end(true, force);
+            markRowAdded(false);
+            callbacksRef.current.onSaved?.();
+            return true;
+        } catch (cause) {
+            fail(cause, "save");
+            return false;
+        } finally{
+            savingRef.current = false;
+            setSaving(false);
+        }
+    }, [
+        editSession,
+        fail,
+        getValues,
+        isCreate,
+        isDirect,
+        isShared,
+        markRowAdded
+    ]);
+    const cancel = useCallback(async ()=>{
+        try {
+            if (isShared) editSession.clearNewRow();
+            else if (ownsSession) await editSession.end();
+            markRowAdded(false);
+            setValidationErrors(EMPTY_ERRORS);
+            setError(void 0);
+            callbacksRef.current.onCancelled?.();
+        } catch (cause) {
+            fail(cause, "cancel");
+        }
+    }, [
+        editSession,
+        fail,
+        isShared,
+        markRowAdded,
+        ownsSession
+    ]);
+    const setValue = useCallback((name, value)=>{
+        editSession.setNewRowValue(name, value);
+        setValidationErrors((errors)=>{
+            if (void 0 === errors[name]) return errors;
+            const { [name]: _removed, ...rest } = errors;
+            return rest;
+        });
+    }, [
+        editSession
+    ]);
+    const { errors: newRowErrors, rowErrorColumn } = sessionState.newRowState;
+    const fieldErrors = useMemo(()=>{
+        if (!isCreate) return validationErrors;
+        const { [rowErrorColumn ?? ""]: _rowError, ...errors } = newRowErrors;
+        return {
+            ...errors,
+            ...validationErrors
+        };
+    }, [
+        isCreate,
+        newRowErrors,
+        rowErrorColumn,
+        validationErrors
+    ]);
+    const isDirty = isCreate ? Object.keys(sessionState.newRowState.values).length > 0 : isDirect ? false : sessionState.isDirty;
+    const formDataRow = useMemo(()=>isCreate ? NEW_ROW : dataRow && Object.keys(directValues).length > 0 ? toRowSnapshot(dataRow.key, {
+            ...getDataRowValues(dataRow),
+            ...directValues
+        }) : dataRow, [
+        dataRow,
+        directValues,
+        isCreate
+    ]);
+    return {
+        ...sessionState,
+        canSave: !saving && (isDirect ? isEditMode : isCreate ? rowAdded ? sessionState.inEditMode : sessionState.isActive && editSession.isNewRowComplete() : sessionState.canSave),
+        cancel,
+        dataRow: formDataRow,
+        editModel: isDirect ? "direct" : "session",
+        editSession,
+        isSharedSession: isShared,
+        fieldEditSession: directEditSession ?? editSession,
+        error: error ?? sessionState.error,
+        fieldErrors,
+        getValues,
+        isDirty,
+        isEditMode,
+        mode,
+        rowAdded,
+        saving,
+        setValue,
+        submit
+    };
+};
+export { getDataRowValues, useEditForm };

package/src/useEditSessionState.js

@@ -0,0 +1,72 @@
+import { useCallback, useRef, useSyncExternalStore } from "react";
+const IDLE_STATE = {
+    canCancel: false,
+    canSave: false,
+    editState: "clean",
+    inEditMode: false,
+    isActive: false,
+    isDirty: false,
+    isEnding: false,
+    isStarting: false,
+    lifecycle: {
+        status: "idle"
+    },
+    newRowState: {
+        columns: [],
+        draftRevision: 0,
+        errors: {},
+        submitting: false,
+        values: {}
+    }
+};
+const createSnapshot = (editSession)=>{
+    const { editState, lifecycle, newRowState } = editSession;
+    return {
+        canCancel: editSession.canCancel,
+        canSave: editSession.canSave,
+        editState,
+        error: "error" === lifecycle.status ? lifecycle.error : void 0,
+        inEditMode: editSession.inEditMode,
+        isActive: "active" === lifecycle.status,
+        isDirty: "clean" !== editState,
+        isEnding: "ending" === lifecycle.status,
+        isStarting: "starting" === lifecycle.status,
+        lifecycle,
+        newRowState
+    };
+};
+const useEditSessionState = (editSession)=>{
+    const snapshotRef = useRef({
+        snapshot: IDLE_STATE
+    });
+    const subscribe = useCallback((onStoreChange)=>{
+        if (!editSession) return ()=>void 0;
+        editSession.on("editState", onStoreChange);
+        editSession.on("lifecycle", onStoreChange);
+        editSession.on("newRow", onStoreChange);
+        return ()=>{
+            editSession.removeListener("editState", onStoreChange);
+            editSession.removeListener("lifecycle", onStoreChange);
+            editSession.removeListener("newRow", onStoreChange);
+        };
+    }, [
+        editSession
+    ]);
+    const getSnapshot = useCallback(()=>{
+        if (!editSession) return IDLE_STATE;
+        const cached = snapshotRef.current;
+        const { editState, lifecycle, newRowState } = editSession;
+        if (cached.editSession !== editSession || cached.editState !== editState || cached.lifecycle !== lifecycle || cached.newRowState !== newRowState) snapshotRef.current = {
+            editSession,
+            editState,
+            lifecycle,
+            newRowState,
+            snapshot: createSnapshot(editSession)
+        };
+        return snapshotRef.current.snapshot;
+    }, [
+        editSession
+    ]);
+    return useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+};
+export { useEditSessionState };

package/src/useEditable.js

@@ -1,19 +1,31 @@
+import { useCallback, useEffect, useMemo, useRef } from "react";
 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();
+import { reportEditError } from "./edit-errors.js";
+import { useEditSessionState } from "./useEditSessionState.js";
+const useEditable = ({ copyOption = "Selected", dataSource, deleteMode, editSessionApi, isEditMode: isEditModeProp, onCancel, onError, onSave, rowDefaults })=>{
+    const { isEditMode: isEditModeContext } = useEditMode();
+    const isEditMode = isEditModeProp ?? isEditModeContext;
+    const onErrorRef = useRef(onError);
+    onErrorRef.current = onError;
     const editSession = useMemo(()=>new EditSession({
-            dataSource
+            dataSource,
+            deleteMode,
+            editSessionApi,
+            rowDefaults
         }), [
-        dataSource
+        dataSource,
+        deleteMode,
+        editSessionApi,
+        rowDefaults
     ]);
+    const sessionState = useEditSessionState(editSession);
     const handleCancel = useCallback(async ()=>{
         try {
             await editSession.end();
             onCancel();
         } catch (error) {
-            console.error("[useEditable] cancel edit session failed", error);
+            reportEditError("useEditable", onErrorRef.current, error, "cancel");
         }
     }, [
         editSession,
@@ -24,7 +36,7 @@ const useEditable = ({ copyOption = "Selected", dataSource, onCancel, onSave })=
             await editSession.end(true, force);
             onSave();
         } catch (error) {
-            console.error("[useEditable] save edit session failed", error);
+            reportEditError("useEditable", onErrorRef.current, error, "save");
         }
     }, [
         editSession,
@@ -34,9 +46,9 @@ const useEditable = ({ copyOption = "Selected", dataSource, onCancel, onSave })=
         const transition = isEditMode ? editSession.begin(copyOption) : editSession.end();
         transition.catch((error)=>{
             if (isEditMode) {
-                console.error("[useEditable] begin edit session failed", error);
+                reportEditError("useEditable", onErrorRef.current, error, "begin");
                 handleCancel();
-            } else console.error("[useEditable] end edit session failed", error);
+            } else reportEditError("useEditable", onErrorRef.current, error, "cancel");
         });
     }, [
         copyOption,
@@ -45,7 +57,12 @@ const useEditable = ({ copyOption = "Selected", dataSource, onCancel, onSave })=
         handleCancel
     ]);
     return {
+        canCancel: sessionState.canCancel,
+        canSave: sessionState.canSave,
         editSession,
+        editState: sessionState.editState,
+        isEditMode,
+        lifecycle: sessionState.lifecycle,
         onCancel: handleCancel,
         onSave: handleSave
     };

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 };