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

package/src/lookup-values/useLookupOptions.js

@@ -0,0 +1,106 @@
+import { Range, useData } from "@vuu-ui/vuu-utils";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { lookupOptionsFromRows } from "./useLookupValues.js";
+const DATA_ROW_COLUMN_OFFSET = 10;
+const rowToRecord = (columns, row)=>Object.fromEntries(columns.map((column, i)=>[
+            column,
+            row[i + DATA_ROW_COLUMN_OFFSET]
+        ]));
+const useLookupOptions = ({ columns: columnsProp, enabled = true, filter, mapRow, maxRows = 100, optionMap, table })=>{
+    const { VuuDataSource } = useData();
+    const [state, setState] = useState({
+        loading: false,
+        options: []
+    });
+    const mapRowRef = useRef(mapRow);
+    mapRowRef.current = mapRow;
+    const columns = useMemo(()=>{
+        if (columnsProp) return [
+            ...columnsProp
+        ];
+        if (optionMap) return [
+            optionMap.value,
+            optionMap.label,
+            ...optionMap.additionalFields ?? []
+        ];
+        return [];
+    }, [
+        columnsProp,
+        optionMap
+    ]);
+    const dataSource = useMemo(()=>enabled && table && columns.length > 0 ? new VuuDataSource({
+            columns,
+            filterSpec: filter ? {
+                filter
+            } : void 0,
+            table
+        }) : void 0, [
+        VuuDataSource,
+        columns,
+        enabled,
+        filter,
+        table
+    ]);
+    useEffect(()=>{
+        if (!dataSource) return void setState({
+            loading: false,
+            options: []
+        });
+        if (!mapRowRef.current && !optionMap) return void setState({
+            error: new Error("[useLookupOptions] either optionMap or mapRow must be provided"),
+            loading: false,
+            options: []
+        });
+        setState({
+            loading: true,
+            options: []
+        });
+        let active = true;
+        let subscribedColumns;
+        const fail = (error)=>{
+            if (active) setState({
+                error,
+                loading: false,
+                options: []
+            });
+        };
+        const subscribe = (message)=>{
+            if (!active) return;
+            if ("subscribed" === message.type) subscribedColumns = message.columns;
+            else if ("viewport-update" === message.type && subscribedColumns) {
+                if (void 0 === message.rows) {
+                    if (0 === message.size) setState({
+                        loading: false,
+                        options: []
+                    });
+                    return;
+                }
+                try {
+                    const rows = message.rows.slice(0, maxRows);
+                    const mapper = mapRowRef.current;
+                    const options = mapper ? rows.map((row)=>mapper(rowToRecord(subscribedColumns, row))) : lookupOptionsFromRows(subscribedColumns, rows, optionMap);
+                    setState({
+                        loading: false,
+                        options
+                    });
+                } catch (cause) {
+                    fail(cause instanceof Error ? cause : new Error(String(cause)));
+                }
+            } else if ("subscribe-failed" === message.type) fail(new Error(`[useLookupOptions] subscription to ${table?.table} failed: ${message.msg}`));
+        };
+        dataSource.subscribe({
+            range: Range(0, maxRows)
+        }, subscribe).catch((cause)=>fail(cause instanceof Error ? cause : new Error(String(cause))));
+        return ()=>{
+            active = false;
+            dataSource.unsubscribe();
+        };
+    }, [
+        dataSource,
+        maxRows,
+        optionMap,
+        table
+    ]);
+    return state;
+};
+export { useLookupOptions };

package/src/useConfirmDiscard.js

@@ -0,0 +1,34 @@
+import { useModal } from "@vuu-ui/core";
+import { createElement, useCallback } from "react";
+const useConfirmDiscard = ({ cancelButtonLabel = "Keep editing", confirmButtonLabel = "Discard", message = "You have unsaved changes. Discard them?", title = "Discard changes?" } = {})=>{
+    const { closePrompt, showPrompt } = useModal();
+    return useCallback(()=>new Promise((resolve)=>{
+            let resolved = false;
+            const settle = (confirmed)=>{
+                if (!resolved) {
+                    resolved = true;
+                    resolve(confirmed);
+                }
+            };
+            showPrompt(createElement("span", null, message), {
+                cancelButtonLabel,
+                confirmButtonLabel,
+                initialFocusedItem: "cancel",
+                onCancel: ()=>settle(false),
+                onConfirm: ()=>settle(true),
+                onOpenChange: (open)=>{
+                    if (!open) settle(false);
+                },
+                status: "warning",
+                title
+            });
+        }).finally(closePrompt), [
+        cancelButtonLabel,
+        closePrompt,
+        confirmButtonLabel,
+        message,
+        showPrompt,
+        title
+    ]);
+};
+export { useConfirmDiscard };

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