@vuu-ui/vuu-data-editing 3.5.7 → 3.5.9

package/package.json

@@ -1,5 +1,5 @@
 {
-  "version": "3.5.7",
+  "version": "3.5.9",
   "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.7",
-    "@vuu-ui/vuu-utils": "3.5.7"
+    "@vuu-ui/vuu-ui-controls": "3.5.9",
+    "@vuu-ui/vuu-utils": "3.5.9"
   },
   "devDependencies": {
-    "@vuu-ui/vuu-data-types": "3.5.7",
-    "@vuu-ui/vuu-protocol-types": "3.5.7",
-    "@vuu-ui/vuu-table-types": "3.5.7"
+    "@vuu-ui/vuu-data-types": "3.5.9",
+    "@vuu-ui/vuu-protocol-types": "3.5.9",
+    "@vuu-ui/vuu-table-types": "3.5.9"
   },
   "peerDependencies": {
     "react": "^19.2.3"

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