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

package/README.md

@@ -4,6 +4,41 @@ Shared data editing APIs, state management, and React components for VUU UI.
 
 This package coordinates edit-session state with editable data sources (both in-memory and remote Vuu session tables) and provides React hooks and UI controls for table editing.
 
+## Quick start
+
+Most applications don't need to assemble the pieces in this package by hand.
+`@vuu-ui/vuu-table-extras` provides ready-made patterns built on it:
+
+```tsx
+import { EditableTable } from "@vuu-ui/vuu-table-extras";
+
+// Edit options live on the column descriptors, e.g. { name: "ric", editable: false }
+<EditableTable
+  allowDelete
+  config={{ columns }}
+  dataSource={dataSource}
+  showInlineAddRow
+/>
+
+// The selected row in a generated form beside the table
+<EditableTable config={{ columns }} dataSource={dataSource} editStrategy="form" />
+```
+
+See the Data Editing guides in the showcase (_Docs / DataEditing_, source in
+[`showcase/src/examples/Docs/DataEditing`](../../showcase/src/examples/Docs/DataEditing/)), starting
+with [Getting started](../../showcase/src/examples/Docs/DataEditing/01-GettingStarted.mdx), and the
+_DataEditing_ examples in the showcase.
+
+## Layers
+
+| Layer | Use it when | APIs |
+| ----- | ----------- | ---- |
+| Pattern components (`@vuu-ui/vuu-table-extras`) | A standard editing UI fits. | `EditableTable` (inline or form editing), `useBulkEditDialog` |
+| Composable hooks and components (this package) | You need your own layout or behaviour. | `useEditableTable`, `useEditableColumns`, `useEditForm`, `EditForm`, `CreateRowForm`, `EditButtons`, `useConfirmDiscard`, `useEditSessionState`, `useLookupOptions` |
+| Primitives (this package) | You are building a new pattern. | `EditSession`, `DirectEditSession`, `DataEditingProvider`, `EditModeProvider` |
+
+The rest of this document describes the primitives and how they work.
+
 ---
 
 ## Table of Contents
@@ -155,6 +190,7 @@ A cell is considered edited only when `originalValue !== editedValue && isValid
    - On success, extracts the row key directly from the response map (`response.data.key`) and records it in `#addedRowKeys`.
    - Increments `addCount`.
    - Resets new-row form draft and increments `draftRevision`.
+5. **Rejection**: if the server rejects the row, the draft is kept and the message is stored in `errors` under `rowErrorColumn` (the final column, where an inline add row shows it). Forms show it in their error banner. The next change to the draft clears it.
 
 ### Row Deletions (`deleteSelectedRows`)
 

package/package.json

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

package/src/DirectEditSession.js

@@ -1,9 +1,11 @@
 import { EventEmitter } from "@vuu-ui/vuu-utils";
 class DirectEditSession extends EventEmitter {
     #dataSource;
-    constructor({ dataSource }){
+    #validate;
+    constructor({ dataSource, validate }){
         super();
         this.#dataSource = dataSource;
+        this.#validate = validate;
     }
     get dataSource() {
         return this.#dataSource;
@@ -25,6 +27,11 @@ class DirectEditSession extends EventEmitter {
             errorMessage: "Invalid value",
             type: "ERROR_RESULT"
         };
+        const errorMessage = this.#validate?.(key, columnName, typedValue);
+        if (errorMessage) return {
+            errorMessage,
+            type: "ERROR_RESULT"
+        };
         const editCell = this.#dataSource.editCell;
         if (void 0 === editCell) throw Error("[DirectEditSession] datasource does not support editCell");
         const response = await editCell.call(this.#dataSource, key, columnName, typedValue);

package/src/EditButtons.js

@@ -1,10 +1,11 @@
 import { Fragment, jsx, jsxs } from "react/jsx-runtime";
 import { Button } from "@salt-ds/core";
 import { useCallback } from "react";
-import { useEditState } from "./useEditState.js";
-const EditButtons = ({ canCancel, canSave: _canSave, confirmCancel, confirmSave, editSession, hasSelection = false, onCancel, onDelete, onSave, saveLabel = "Save" })=>{
-    const editState = useEditState(editSession);
-    const isDirty = editSession?.isDirty ?? false;
+import { useEditSessionState } from "./useEditSessionState.js";
+const EditButtons = ({ canCancel: canCancelProp, canSave: canSaveProp, confirmCancel, confirmSave, editSession, hasSelection = false, onCancel, onDelete, onSave, saveLabel = "Save" })=>{
+    const { canCancel: sessionCanCancel, canSave: sessionCanSave, editState, isDirty } = useEditSessionState(editSession);
+    const canSave = false !== canSaveProp && sessionCanSave;
+    const canCancel = canCancelProp ?? sessionCanCancel;
     const handleSave = useCallback(async ()=>{
         if (confirmSave) {
             const confirmed = await confirmSave();
@@ -36,7 +37,7 @@ const EditButtons = ({ canCancel, canSave: _canSave, confirmCancel, confirmSave,
                 children: "Delete"
             }),
             /*#__PURE__*/ jsx(Button, {
-                disabled: !editSession?.canSave,
+                disabled: !canSave,
                 onClick: handleSave,
                 sentiment: "accented",
                 children: "stale" === editState ? `${saveLabel} (force)` : saveLabel

package/src/EditModeProvider.js

@@ -1,8 +1,14 @@
 import { jsx } from "react/jsx-runtime";
-import { createContext, useContext, useEffect, useState } from "react";
+import { createContext, useContext, useEffect, useMemo, useState } from "react";
+let warnedMissingProvider = false;
 const EditModeContext = /*#__PURE__*/ createContext({
     isEditMode: false,
-    setEditMode: ()=>"EditModeProvider in place"
+    setEditMode: ()=>{
+        if ("production" !== process.env.NODE_ENV && !warnedMissingProvider) {
+            warnedMissingProvider = true;
+            console.warn("[useEditMode] setEditMode called with no EditModeProvider in scope, edit mode will not change");
+        }
+    }
 });
 const EditModeProvider = ({ children, isEditMode: isEditModeProp = false })=>{
     const [isEditMode, setEditMode] = useState(isEditModeProp);
@@ -11,11 +17,14 @@ const EditModeProvider = ({ children, isEditMode: isEditModeProp = false })=>{
     }, [
         isEditModeProp
     ]);
-    return /*#__PURE__*/ jsx(EditModeContext.Provider, {
-        value: {
+    const value = useMemo(()=>({
             isEditMode,
             setEditMode
-        },
+        }), [
+        isEditMode
+    ]);
+    return /*#__PURE__*/ jsx(EditModeContext.Provider, {
+        value: value,
         children: children
     });
 };

package/src/EditSession.js

@@ -145,19 +145,31 @@ class EditSession extends EventEmitter {
         });
     }
     setNewRowValue(column, value) {
+        const { rowErrorColumn, ...newRowState } = this.#newRowState;
         const errors = {
-            ...this.#newRowState.errors
+            ...newRowState.errors
         };
         delete errors[column];
+        if (void 0 !== rowErrorColumn) delete errors[rowErrorColumn];
         this.#setNewRowState({
-            ...this.#newRowState,
+            ...newRowState,
             errors,
             values: {
-                ...this.#newRowState.values,
+                ...newRowState.values,
                 [column]: value
             }
         });
     }
+    clearNewRow() {
+        this.#setNewRowState({
+            columns: this.#newRowState.columns,
+            draftRevision: this.#newRowState.draftRevision + 1,
+            errors: {},
+            requiredColumns: this.#newRowState.requiredColumns,
+            submitting: false,
+            values: {}
+        });
+    }
     async addNewRow() {
         const requiredColumns = this.#newRowState.requiredColumns ?? this.#newRowState.columns;
         const missingErrors = Object.fromEntries(requiredColumns.filter((column)=>{
@@ -167,8 +179,13 @@ class EditSession extends EventEmitter {
                 column,
                 "Value required"
             ]));
-        const errors = {
-            ...this.#newRowState.errors,
+        const { rowErrorColumn, ...newRowState } = this.#newRowState;
+        const { [rowErrorColumn ?? ""]: _serverError, ...fieldErrors } = newRowState.errors;
+        const errors = void 0 === rowErrorColumn ? {
+            ...newRowState.errors,
+            ...missingErrors
+        } : {
+            ...fieldErrors,
             ...missingErrors
         };
         if (Object.keys(errors).length > 0) {
@@ -186,7 +203,8 @@ class EditSession extends EventEmitter {
             type: "SUCCESS_RESULT"
         };
         this.#setNewRowState({
-            ...this.#newRowState,
+            ...newRowState,
+            errors,
             submitting: true
         });
         try {
@@ -200,6 +218,7 @@ class EditSession extends EventEmitter {
                     errors: finalColumn ? {
                         [finalColumn]: response.errorMessage
                     } : this.#newRowState.errors,
+                    rowErrorColumn: finalColumn,
                     submitting: false
                 });
                 return response;
@@ -221,6 +240,7 @@ class EditSession extends EventEmitter {
                 errors: finalColumn ? {
                     [finalColumn]: errorMessage
                 } : this.#newRowState.errors,
+                rowErrorColumn: finalColumn,
                 submitting: false
             });
             return {
@@ -282,6 +302,14 @@ class EditSession extends EventEmitter {
     hasRowChanges(key) {
         return this.#rowEdits.has(key);
     }
+    getEditedValues(key) {
+        const cellEdits = this.#rowEdits.get(key)?.cellEdits;
+        if (!cellEdits) return {};
+        return Object.fromEntries(Array.from(cellEdits, ([column, { editedValue }])=>[
+                column,
+                editedValue
+            ]));
+    }
     isCellEdited(key, columnName) {
         const cellEdit = this.#rowEdits.get(key)?.cellEdits.get(columnName);
         return cellEdit?.isValid === true && cellEdit.originalValue !== cellEdit.editedValue;
@@ -424,6 +452,9 @@ class EditSession extends EventEmitter {
     get dataSource() {
         return this.#sessionDataSource ?? this.#sourceTableDataSource;
     }
+    get sourceDataSource() {
+        return this.#sourceTableDataSource;
+    }
     get sessionDataSource() {
         return this.#sessionDataSource;
     }

package/src/edit-control/EditControlCheckbox.js

@@ -0,0 +1,25 @@
+import { jsx } from "react/jsx-runtime";
+import { Checkbox } from "@salt-ds/core";
+import { useCallback, useEffect, useState } from "react";
+const isChecked = (value)=>true === value || "true" === value;
+const EditControlCheckbox = ({ className, onCommit, value })=>{
+    const [checked, setChecked] = useState(isChecked(value));
+    useEffect(()=>{
+        setChecked(isChecked(value));
+    }, [
+        value
+    ]);
+    const handleChange = useCallback((evt)=>{
+        setChecked(evt.target.checked);
+        onCommit(evt, evt.target.checked);
+    }, [
+        onCommit
+    ]);
+    return /*#__PURE__*/ jsx(Checkbox, {
+        checked: checked,
+        className: className,
+        "data-edit-control": true,
+        onChange: handleChange
+    });
+};
+export { EditControlCheckbox };

package/src/edit-control/EditControlDropdown.js

@@ -0,0 +1,34 @@
+import { jsx } from "react/jsx-runtime";
+import { Dropdown, Option } from "@salt-ds/core";
+import { useCallback } from "react";
+const toOption = (value)=>"string" == typeof value ? {
+        label: value,
+        value
+    } : value;
+const EditControlDropdown = ({ className, onCommit, value, values })=>{
+    const options = values.map(toOption);
+    const selectedValue = void 0 === value ? "" : String(value);
+    const selected = options.find((option)=>option.value === selectedValue);
+    const handleSelectionChange = useCallback((evt, [option])=>{
+        if (option) onCommit(evt, option.value);
+    }, [
+        onCommit
+    ]);
+    return /*#__PURE__*/ jsx(Dropdown, {
+        bordered: true,
+        className: className,
+        "data-edit-control": true,
+        "data-icon": "triangle-down",
+        onSelectionChange: handleSelectionChange,
+        placeholder: "Please select value",
+        selected: selected ? [
+            selected
+        ] : [],
+        value: selected?.label ?? selectedValue,
+        children: options.map((option)=>/*#__PURE__*/ jsx(Option, {
+                value: option,
+                children: option.label
+            }, option.value))
+    });
+};
+export { EditControlDropdown };

package/src/edit-control/EditControlLookupDropdown.js

@@ -0,0 +1,31 @@
+import { jsx } from "react/jsx-runtime";
+import { useMemo } from "react";
+import { useLookupValues } from "../lookup-values/useLookupValues.js";
+import { EditControlDropdown } from "./EditControlDropdown.js";
+const EditControlLookupDropdown = ({ className, lookup: { labelColumn, table, valueColumn }, onCommit, value })=>{
+    const optionMap = useMemo(()=>({
+            label: labelColumn,
+            value: valueColumn
+        }), [
+        labelColumn,
+        valueColumn
+    ]);
+    const lookupValues = useLookupValues({
+        enabled: true,
+        optionMap,
+        table
+    });
+    const values = useMemo(()=>lookupValues.map(({ label, value })=>({
+                label,
+                value: String(value)
+            })), [
+        lookupValues
+    ]);
+    return /*#__PURE__*/ jsx(EditControlDropdown, {
+        className: className,
+        onCommit: onCommit,
+        value: value,
+        values: values
+    });
+};
+export { EditControlLookupDropdown };

package/src/edit-control/get-data-item-edit-control.js

@@ -0,0 +1,139 @@
+import { jsx } from "react/jsx-runtime";
+import { VuuDatePicker, VuuInput, VuuTimePicker, VuuTypeaheadInput } from "@vuu-ui/vuu-ui-controls";
+import { EpochTimestamp, getTemporalInfo, isDataValueEditable, isTimeDataValueWithMilliseconds, isValidTimeString, isValidTimeStringMillis, parseTemporalInput } from "@vuu-ui/vuu-utils";
+import { EditControlCheckbox } from "./EditControlCheckbox.js";
+import { EditControlDropdown } from "./EditControlDropdown.js";
+import { EditControlLookupDropdown } from "./EditControlLookupDropdown.js";
+const VARIANT_MIN_CHARACTER_COUNT = {
+    default: void 0,
+    pick: 0,
+    search: 1
+};
+const isTypeaheadEditor = (editor)=>editor?.name === "typeahead";
+const isValueListEditor = (editor)=>Array.isArray(editor?.values);
+const isLookupEditor = (editor)=>editor?.lookup !== void 0;
+const isCheckboxEditor = (editor)=>editor?.name === "checkbox-cell" || editor?.name === "toggle-cell";
+const timeOfDayPattern = /^\d{2}:\d{2}(:\d{2}(\.\d{1,9})?)?$/;
+const toEpochTimestamp = (value, { encoding })=>{
+    if (("string" == typeof value || "number" == typeof value) && !timeOfDayPattern.test(`${value}`)) return EpochTimestamp.fromWire(value, encoding);
+};
+const pad = (n)=>`${n}`.padStart(2, "0");
+function toTimeString(value, timestamp, { timeZone }, milliseconds = false) {
+    if (timestamp) {
+        const { hour, minute, second, millisecond } = timestamp.getFields(timeZone);
+        const timeString = `${pad(hour)}:${pad(minute)}:${pad(second)}`;
+        return milliseconds ? `${timeString}.${`${millisecond}`.padStart(3, "0")}` : timeString;
+    }
+    if ("string" == typeof value) if (milliseconds) {
+        const timeString = 8 === value.length ? `${value}.000` : value.slice(0, 12);
+        if (isValidTimeStringMillis(timeString)) return timeString;
+    } else {
+        const timeString = value.slice(0, 8);
+        if (isValidTimeString(timeString)) return timeString;
+    }
+}
+const getDataItemEditControl = ({ InputProps, TypeaheadProps, className, commitOnBlur, commitWhenCleared, dataDescriptor, editOperation = "update", errorMessage, onCommit, purpose = "edit", table, variant })=>{
+    const { editor } = dataDescriptor;
+    const temporalInfo = getTemporalInfo(dataDescriptor);
+    const value = InputProps?.value ?? InputProps?.inputProps?.value;
+    if (!isDataValueEditable(dataDescriptor, editOperation, true)) return /*#__PURE__*/ jsx(VuuInput, {
+        variant: "secondary",
+        ...InputProps,
+        onCommit: onCommit,
+        readOnly: true,
+        "data-edit-control": true
+    });
+    if (temporalInfo?.kind === "time") {
+        const { value, onChange } = InputProps?.inputProps ?? {};
+        const baseValue = toEpochTimestamp(value, temporalInfo);
+        const handleCommitTime = (evt, timeString)=>{
+            if (baseValue) {
+                const timestamp = parseTemporalInput(timeString, temporalInfo, baseValue);
+                onCommit(evt, timestamp ? `${timestamp.toWire(temporalInfo.encoding)}` : "");
+            } else onCommit(evt, timeString);
+        };
+        return isTimeDataValueWithMilliseconds(dataDescriptor) ? /*#__PURE__*/ jsx(VuuTimePicker, {
+            className: className,
+            milliseconds: true,
+            value: "" === value ? "" : toTimeString(value, baseValue, temporalInfo, true),
+            onChange: onChange,
+            onCommit: handleCommitTime,
+            "data-edit-control": true
+        }) : /*#__PURE__*/ jsx(VuuTimePicker, {
+            className: className,
+            value: "" === value ? "" : toTimeString(value, baseValue, temporalInfo),
+            onChange: onChange,
+            onCommit: handleCommitTime,
+            "data-edit-control": true
+        });
+    }
+    if (temporalInfo) {
+        const baseValue = toEpochTimestamp(InputProps?.inputProps?.value, temporalInfo);
+        const handleCommitDate = (evt, startOfDayMillis)=>{
+            let timestamp = EpochTimestamp.fromMillis(startOfDayMillis);
+            if (baseValue && "datetime" === temporalInfo.kind) {
+                const { year, month, day } = timestamp.getFields(temporalInfo.timeZone);
+                const { hour, minute, second, millisecond } = baseValue.getFields(temporalInfo.timeZone);
+                timestamp = EpochTimestamp.fromFields({
+                    year,
+                    month,
+                    day,
+                    hour,
+                    minute,
+                    second,
+                    millisecond
+                }, temporalInfo.timeZone, baseValue.subMilliNanos);
+            }
+            onCommit(evt, `${timestamp.toWire(temporalInfo.encoding)}`);
+        };
+        return /*#__PURE__*/ jsx(VuuDatePicker, {
+            className: className,
+            onCommit: handleCommitDate,
+            timeZone: temporalInfo.timeZone,
+            value: baseValue,
+            "data-edit-control": true
+        });
+    }
+    if ("edit" === purpose && (isCheckboxEditor(editor) || void 0 === editor && "boolean" === dataDescriptor.serverDataType)) return /*#__PURE__*/ jsx(EditControlCheckbox, {
+        className: className,
+        onCommit: onCommit,
+        value: value
+    });
+    if (isLookupEditor(editor)) return /*#__PURE__*/ jsx(EditControlLookupDropdown, {
+        className: className,
+        lookup: editor.lookup,
+        onCommit: onCommit,
+        value: value
+    });
+    else if (isValueListEditor(editor)) return /*#__PURE__*/ jsx(EditControlDropdown, {
+        className: className,
+        onCommit: onCommit,
+        value: value,
+        values: editor.values
+    });
+    else if (table && (isTypeaheadEditor(editor) || "filter" === purpose && "string" === dataDescriptor.serverDataType)) {
+        const minCharacterCountToTriggerSuggestions = TypeaheadProps?.minCharacterCountToTriggerSuggestions ?? (isTypeaheadEditor(editor) ? editor.minCharacterCountToTriggerSuggestions : void 0) ?? VARIANT_MIN_CHARACTER_COUNT[variant ?? "default"];
+        return /*#__PURE__*/ jsx(VuuTypeaheadInput, {
+            ...InputProps,
+            ...TypeaheadProps,
+            className: className,
+            column: dataDescriptor.name,
+            "data-edit-control": true,
+            "data-variant": variant,
+            minCharacterCountToTriggerSuggestions: minCharacterCountToTriggerSuggestions,
+            onCommit: onCommit,
+            table: table
+        });
+    }
+    return /*#__PURE__*/ jsx(VuuInput, {
+        variant: "secondary",
+        ...InputProps,
+        className: className,
+        commitOnBlur: commitOnBlur,
+        commitWhenCleared: commitWhenCleared,
+        onCommit: onCommit,
+        errorMessage: errorMessage,
+        "data-edit-control": true
+    });
+};
+export { getDataItemEditControl };

package/src/edit-control/index.js

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

package/src/edit-errors.js

@@ -0,0 +1,7 @@
+const toError = (cause)=>cause instanceof Error ? cause : new Error(String(cause));
+const reportEditError = (source, onError, cause, operation)=>{
+    const error = toError(cause);
+    if (onError) onError(error, operation);
+    else console.error("[%s] %s edit session failed", source, operation, error);
+};
+export { reportEditError, toError };