@opencorestack/opengridx 3.3.0 → 3.5.0

package/lib/hooks/core/useGridUndoRedo.ts

@@ -0,0 +1,220 @@
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef } from 'react';
+import type { MutableRefObject, RefObject } from 'react';
+import type {
+    GridApi,
+    GridBatchEditResult,
+    GridColDef,
+    GridHistoryChangeParams,
+    GridRowId,
+    GridRowModel,
+} from '../../types';
+import { classifyKeyTarget } from '../../utils/focus';
+import type { FocusedCell } from '../../utils/focus';
+import { scrollColumnIntoView, scrollRowIntoView } from '../../utils/scroll';
+import { boundingTargetRect, buildEditTargetContext, rectCorners } from '../../utils/editing/targets';
+import type { GridCellChange } from '../../utils/editing/commit';
+import type { GridEditSource, UseGridBatchEditReturn } from '../features/useGridBatchEdit';
+import type { UseGridCellSelectionReturn } from './useGridCellSelection';
+import type { LayoutResult } from './useLayout';
+
+/** Default number of actions `undoRedo` keeps. */
+export const UNDO_HISTORY_LIMIT = 100;
+
+type CommitListener = (changes: GridCellChange[], source: GridEditSource) => void;
+
+export interface GridEditCommitChannel {
+    /** Passed to the commit paths (`useGridEditing`, `useGridBatchEdit`) as `onCommitted`. Stable. */
+    emit: CommitListener;
+    /** Set by `useGridUndoRedo`, which runs later in the hook order. Stable. */
+    setListener: (listener: CommitListener | null) => void;
+}
+
+/**
+ * Connects the commit paths, which run early in the hook order, to the history, which runs late
+ * (it needs the focus and selection hooks). Created before `useGridBatchEdit`.
+ */
+export function useGridEditCommitChannel(): GridEditCommitChannel {
+    const listenerRef = useRef<CommitListener | null>(null);
+    const emit = useCallback<CommitListener>((changes, source) => {
+        const listener = listenerRef.current;
+        if (listener) listener(changes, source);
+    }, []);
+    const setListener = useCallback((listener: CommitListener | null) => {
+        listenerRef.current = listener;
+    }, []);
+    return useMemo(() => ({ emit, setListener }), [emit, setListener]);
+}
+
+export interface UseGridUndoRedoParams<R extends GridRowModel> {
+    apiRef: MutableRefObject<GridApi>;
+    enabled: boolean;
+    limit: number;
+    onHistoryChange?: (params: GridHistoryChangeParams) => void;
+    channel: GridEditCommitChannel;
+    batchEdit: UseGridBatchEditReturn<R>;
+    isEditing: boolean;
+    containerRef: RefObject<HTMLDivElement | null>;
+    viewportRef: RefObject<HTMLDivElement | null>;
+    selection: UseGridCellSelectionReturn;
+    setFocusedCell: React.Dispatch<React.SetStateAction<FocusedCell | null>>;
+    allRenderableRows: R[];
+    getRowId: (row: R) => GridRowId;
+    navigationColumns: ReadonlyArray<GridColDef<R>>;
+    layout: LayoutResult<R>;
+    rowHeight: number;
+    pinnedTopRowCount: number;
+}
+
+const emptyResult = (): GridBatchEditResult => ({ updated: [], failed: [], skipped: [] });
+
+/** 'undo', 'redo' or null for a keydown. Ctrl/Cmd+Z, Ctrl/Cmd+Shift+Z, Ctrl+Y (also on non-Latin layouts). */
+function historyShortcut(event: KeyboardEvent): 'undo' | 'redo' | null {
+    if (event.altKey || !(event.ctrlKey || event.metaKey)) return null;
+    const key = (event.key ?? '').toLowerCase();
+    const latin = /^[a-z]$/.test(key);
+    const isZ = key === 'z' || (!latin && event.code === 'KeyZ');
+    const isY = key === 'y' || (!latin && event.code === 'KeyY');
+    if (isZ) return event.shiftKey ? 'redo' : 'undo';
+    if (isY && event.ctrlKey && !event.shiftKey) return 'redo';
+    return null;
+}
+
+/**
+ * Undo / redo of cell edits, pastes and range clears (`undoRedo`, v3.4). An action is recorded only
+ * after `processRowUpdate` succeeded, as the changed cells with their value before and the stored
+ * value after. Undo writes the `before` values as a batch edit (so `valueSetter` and
+ * `processRowUpdate` run); a cell that no longer holds its `after` value is skipped (`'changed'`), a
+ * row that is gone too (`'missing'`). Redo is the reverse. Runs after useGridClipboardPaste.
+ */
+export function useGridUndoRedo<R extends GridRowModel>(params: UseGridUndoRedoParams<R>): void {
+    const { apiRef, enabled, channel, containerRef } = params;
+    const latestRef = useRef(params);
+    useLayoutEffect(() => {
+        latestRef.current = params;
+    });
+
+    const undoStackRef = useRef<GridCellChange[][]>([]);
+    const redoStackRef = useRef<GridCellChange[][]>([]);
+    const lastEmittedRef = useRef<GridHistoryChangeParams>({ canUndo: false, canRedo: false, size: 0 });
+    // Undo and redo run one after the other, each on the rows the previous one stored.
+    const queueRef = useRef<Promise<unknown>>(Promise.resolve());
+
+    const notify = useCallback(() => {
+        const next = {
+            canUndo: undoStackRef.current.length > 0,
+            canRedo: redoStackRef.current.length > 0,
+            size: undoStackRef.current.length,
+        };
+        const last = lastEmittedRef.current;
+        if (last.canUndo === next.canUndo && last.canRedo === next.canRedo && last.size === next.size) return;
+        lastEmittedRef.current = next;
+        latestRef.current.onHistoryChange?.(next);
+    }, []);
+
+    const record = useCallback((changes: GridCellChange[]) => {
+        if (!latestRef.current.enabled || changes.length === 0) return;
+        const stack = undoStackRef.current;
+        stack.push(changes);
+        const limit = Math.max(1, latestRef.current.limit);
+        if (stack.length > limit) stack.splice(0, stack.length - limit);
+        redoStackRef.current = [];
+        notify();
+    }, [notify]);
+
+    useLayoutEffect(() => {
+        channel.setListener(enabled ? record : null);
+        return () => channel.setListener(null);
+    }, [channel, enabled, record]);
+
+    const clearHistory = useCallback(() => {
+        undoStackRef.current = [];
+        redoStackRef.current = [];
+        notify();
+    }, [notify]);
+
+    // Turning undoRedo off forgets the history.
+    useEffect(() => {
+        if (!enabled) clearHistory();
+    }, [enabled, clearHistory]);
+
+    /** Selects the affected cells (their bounding rectangle) and scrolls its first cell into view. */
+    const reveal = useCallback((cells: GridCellChange[]) => {
+        const p = latestRef.current;
+        const ctx = buildEditTargetContext(p.allRenderableRows, p.getRowId, p.navigationColumns);
+        const rect = boundingTargetRect(ctx, cells);
+        if (!rect) return;
+        const { anchor, head } = rectCorners(ctx, rect);
+        if (p.selection.enabled) p.selection.setModel([{ anchor, head }], 'keyboard');
+        else p.setFocusedCell({ id: anchor.id, field: anchor.field, rowIndex: rect.top });
+        const viewport = p.viewportRef.current;
+        if (!viewport) return;
+        scrollRowIntoView(viewport, rect.top - p.pinnedTopRowCount, p.layout.cumulativeHeights, p.layout.pinnedBottomHeight, p.rowHeight);
+        scrollColumnIntoView(viewport, p.layout.unpinnedColsWithWidth.findIndex(c => c.field === anchor.field), p.layout);
+    }, []);
+
+    /** Replays the top action of one stack onto the other. */
+    const replay = useCallback((direction: 'undo' | 'redo'): Promise<GridBatchEditResult> => {
+        const run = async (): Promise<GridBatchEditResult> => {
+            if (!latestRef.current.enabled) return emptyResult();
+            const from = direction === 'undo' ? undoStackRef : redoStackRef;
+            const to = direction === 'undo' ? redoStackRef : undoStackRef;
+            const action = from.current.pop();
+            if (!action) return emptyResult();
+            notify();
+            // Undo writes `before` where `after` still holds; redo writes `after` where `before` holds.
+            const edits = action.map(change => direction === 'undo'
+                ? { id: change.id, field: change.field, value: change.before, expect: { value: change.after } }
+                : { id: change.id, field: change.field, value: change.after, expect: { value: change.before } });
+            const outcome = await latestRef.current.batchEdit.applyEdits(edits, direction);
+            if (outcome.committed.length > 0) {
+                // The opposite action: for an undo, `before` is what it stored and `after` what it replaced.
+                to.current.push(direction === 'undo'
+                    ? outcome.committed.map(c => ({ id: c.id, field: c.field, before: c.after, after: c.before }))
+                    : outcome.committed);
+            }
+            // Rows whose processRowUpdate failed keep their part of the action, to try again.
+            const failedIds = new Set<GridRowId>(outcome.result.failed.map(f => f.id));
+            if (failedIds.size > 0) {
+                const remainder = action.filter(change => failedIds.has(change.id));
+                if (remainder.length > 0) from.current.push(remainder);
+            }
+            notify();
+            if (outcome.committed.length > 0) reveal(outcome.committed);
+            return outcome.result;
+        };
+        const next = queueRef.current.then(run, run);
+        queueRef.current = next;
+        return next;
+    }, [notify, reveal]);
+
+    const undo = useCallback(() => replay('undo'), [replay]);
+    const redo = useCallback(() => replay('redo'), [replay]);
+
+    useEffect(() => {
+        const root = containerRef.current;
+        if (!root || !enabled) return;
+        const onKeyDown = (event: KeyboardEvent) => {
+            if (event.defaultPrevented) return;
+            const shortcut = historyShortcut(event);
+            if (!shortcut) return;
+            const viewport = latestRef.current.viewportRef.current;
+            if (!viewport || latestRef.current.isEditing) return;
+            // Inside an editor or a text field the input's own undo wins.
+            const kind = classifyKeyTarget(event.target, viewport);
+            if (kind !== 'grid' && kind !== 'control') return;
+            event.preventDefault();
+            void (shortcut === 'undo' ? undo() : redo());
+        };
+        root.addEventListener('keydown', onKeyDown);
+        return () => root.removeEventListener('keydown', onKeyDown);
+    }, [containerRef, enabled, undo, redo]);
+
+    useLayoutEffect(() => {
+        const api = apiRef.current;
+        api.undo = undo;
+        api.redo = redo;
+        api.canUndo = () => latestRef.current.enabled && undoStackRef.current.length > 0;
+        api.canRedo = () => latestRef.current.enabled && redoStackRef.current.length > 0;
+        api.clearHistory = clearHistory;
+    }, [apiRef, undo, redo, clearHistory]);
+}

package/lib/hooks/features/useGridAiAssistant.ts

@@ -0,0 +1,284 @@
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react';
+import type { MutableRefObject } from 'react';
+import type {
+    GridAiAssistantOptions,
+    GridAiAssistantPanelProps,
+    GridAiAssistantStatus,
+    GridAiHistoryEntry,
+    GridAiPromptResult,
+    GridAiState,
+    GridAiValidationError,
+    GridApi,
+    GridColDef,
+} from '../../types';
+import { attempt } from '../../utils/attempt';
+import { isGridAiValidated } from '../../utils/aiBrand';
+import {
+    AI_PARTS,
+    applyGridAiState,
+    buildAiChips,
+    dropEmptiedParts,
+    effectiveState,
+    pickAllowedParts,
+    removeAiChip,
+    snapshotParts,
+} from '../../utils/aiAssistant';
+
+export interface UseGridAiAssistantParams {
+    apiRef: MutableRefObject<GridApi>;
+    /** The `aiAssistant` prop. Without it the hook is inert. */
+    options: GridAiAssistantOptions | undefined;
+    /** Columns, for the chip labels (header names). */
+    columns: readonly GridColDef[];
+    onApply?: (result: GridAiPromptResult) => void;
+    onError?: (error: unknown) => void;
+}
+
+export interface UseGridAiAssistantResult {
+    enabled: boolean;
+    open: boolean;
+    /** Opens the panel; focus returns to `trigger` (default: the focused element) when it closes. */
+    openPanel: (trigger?: HTMLElement | null) => void;
+    /** Opens the panel, or closes it when it is open. */
+    togglePanel: (trigger?: HTMLElement | null) => void;
+    closePanel: () => void;
+    /** Props of the panel while it is open, else null. */
+    panelProps: GridAiAssistantPanelProps | null;
+    /** The status line for the grid's live region. */
+    announcement: string;
+}
+
+const DEFAULT_PLACEHOLDER = 'Ask about this table…';
+const NO_SUGGESTIONS: string[] = [];
+const NO_ERRORS: GridAiValidationError[] = [];
+const NOT_VALIDATED = 'The reply was not validated';
+
+interface Applied {
+    /** The reply's parts the grid applied (chips are built from it). */
+    state: GridAiState;
+    /** The same parts as they were before: what Undo restores. */
+    previous: GridAiState;
+}
+
+/** Whether this browser has speech recognition. The microphone is never asked for here. */
+export function hasSpeechRecognition(): boolean {
+    return typeof window !== 'undefined' && ('SpeechRecognition' in window || 'webkitSpeechRecognition' in window);
+}
+
+function isAbortError(error: unknown): boolean {
+    return typeof error === 'object' && error !== null && (error as { name?: unknown }).name === 'AbortError';
+}
+
+function errorText(error: unknown): string {
+    return error instanceof Error && error.message ? error.message : 'Unknown error';
+}
+
+function changesText(count: number, ignored: number): string {
+    const applied = count === 0 ? 'No changes' : `Applied ${count} ${count === 1 ? 'change' : 'changes'}`;
+    return ignored > 0 ? `${applied}, ${ignored} ignored` : applied;
+}
+
+/** Calls a consumer callback; a throw is warned about (development) and otherwise ignored. */
+function notify<T>(callback: ((value: T) => void) | undefined, value: T, name: string): void {
+    if (!callback) return;
+    const result = attempt(() => callback(value));
+    if (!result.ok && process.env.NODE_ENV !== 'production') console.warn(`[OpenGridX] ${name} threw.`, result.error);
+}
+
+/**
+ * The `aiAssistant` prompt panel: open state, the request (with Stop), applying a validated reply as
+ * one undoable step, chips, Undo, the session's prompts and the status line. Results are applied only
+ * when their `state` carries the brand of `validateGridAiState`. Installs `apiRef.openAiAssistant` /
+ * `closeAiAssistant`.
+ */
+export function useGridAiAssistant(params: UseGridAiAssistantParams): UseGridAiAssistantResult {
+    const { apiRef, options, columns } = params;
+    const enabled = Boolean(options);
+    const [open, setOpen] = useState(false);
+    const [status, setStatus] = useState<GridAiAssistantStatus>('idle');
+    const [statusText, setStatusText] = useState('');
+    const [message, setMessage] = useState<string | null>(null);
+    const [errors, setErrors] = useState<GridAiValidationError[]>(NO_ERRORS);
+    const [applied, setApplied] = useState<Applied | null>(null);
+    const [history, setHistory] = useState<GridAiHistoryEntry[]>([]);
+
+    const controllerRef = useRef<AbortController | null>(null);
+    const returnFocusRef = useRef<HTMLElement | null>(null);
+    const latestRef = useRef({ params, applied, history, open });
+    useLayoutEffect(() => {
+        latestRef.current = { params, applied, history, open };
+    });
+
+    const labelOf = useMemo(() => {
+        const byField = new Map(columns.map((col) => [col.field, col.headerName || col.field]));
+        return (field: string) => byField.get(field) ?? field;
+    }, [columns]);
+    const chips = useMemo(() => (applied ? buildAiChips(applied.state, labelOf) : []), [applied, labelOf]);
+
+    const abortRequest = useCallback(() => {
+        const controller = controllerRef.current;
+        controllerRef.current = null;
+        if (controller) controller.abort();
+    }, []);
+
+    // Abort a running request when the grid unmounts.
+    useEffect(() => abortRequest, [abortRequest]);
+
+    const openPanel = useCallback((trigger?: HTMLElement | null) => {
+        if (!latestRef.current.params.options) return;
+        const active = typeof document === 'undefined' ? null : document.activeElement;
+        returnFocusRef.current = trigger ?? (active instanceof HTMLElement ? active : null);
+        setOpen(true);
+    }, []);
+
+    const closePanel = useCallback(() => {
+        if (controllerRef.current) {
+            abortRequest();
+            setStatus('stopped');
+            setStatusText('Stopped');
+        }
+        setOpen(false);
+        const target = returnFocusRef.current;
+        returnFocusRef.current = null;
+        if (target && target.isConnected) target.focus();
+    }, [abortRequest]);
+
+    const togglePanel = useCallback((trigger?: HTMLElement | null) => {
+        if (latestRef.current.open) closePanel();
+        else openPanel(trigger);
+    }, [openPanel, closePanel]);
+
+    const fail = useCallback((text: string, error: unknown) => {
+        setStatus('error');
+        setStatusText(text);
+        setMessage(null);
+        setErrors(NO_ERRORS);
+        notify(latestRef.current.params.onError, error, 'onAiAssistantError');
+    }, []);
+
+    const applyResult = useCallback((prompt: string, result: GridAiPromptResult) => {
+        const { params: current } = latestRef.current;
+        const isObject = typeof result === 'object' && result !== null;
+        if (!isObject || !isGridAiValidated(result.state)) {
+            if (process.env.NODE_ENV !== 'production') {
+                console.warn('[OpenGridX] aiAssistant: the onPrompt result was not applied because its state was not validated. Return the result of createGridAiPromptHandler, or pass the model reply through validateGridAiState (from @opencorestack/opengridx/ai) and return its state.');
+            }
+            fail(NOT_VALIDATED, new Error(NOT_VALIDATED));
+            return;
+        }
+        const allowed = pickAllowedParts(result.state, current.options?.parts ?? AI_PARTS);
+        const ignored = [...(Array.isArray(result.errors) ? result.errors : []), ...allowed.errors];
+        const state = dropEmptiedParts(allowed.state, ignored);
+        const api = apiRef.current;
+        const previous = snapshotParts(state, api.getGridAiState());
+        applyGridAiState(api, effectiveState(state, previous));
+        setApplied({ state, previous });
+        setErrors(ignored);
+        setMessage(typeof result.message === 'string' && result.message ? result.message : null);
+        setHistory((list) => [...list, { prompt, applied: state }]);
+        setStatus('applied');
+        setStatusText(changesText(buildAiChips(state, (f) => f).length, ignored.length));
+        notify(current.onApply, result, 'onAiAssistantApply');
+    }, [apiRef, fail]);
+
+    const submit = useCallback((text: string) => {
+        const prompt = text.trim();
+        const { params: current, history: earlier } = latestRef.current;
+        const onPrompt = current.options?.onPrompt;
+        if (!prompt || !onPrompt) return;
+        abortRequest();
+        const controller = new AbortController();
+        controllerRef.current = controller;
+        setStatus('running');
+        setStatusText('Thinking…');
+        setMessage(null);
+        setErrors(NO_ERRORS);
+        const context = { currentState: apiRef.current.getGridAiState(), history: earlier, signal: controller.signal };
+        const call = attempt(() => onPrompt(prompt, context));
+        const pending = call.ok ? Promise.resolve(call.value) : Promise.reject(call.error);
+        pending.then(
+            (result) => {
+                if (controllerRef.current !== controller) return;
+                controllerRef.current = null;
+                applyResult(prompt, result);
+            },
+            (error: unknown) => {
+                if (controllerRef.current !== controller) return;
+                controllerRef.current = null;
+                if (controller.signal.aborted || isAbortError(error)) {
+                    setStatus('stopped');
+                    setStatusText('Stopped');
+                    return;
+                }
+                fail(`The assistant could not answer: ${errorText(error)}`, error);
+            },
+        );
+    }, [apiRef, abortRequest, applyResult, fail]);
+
+    const stop = useCallback(() => {
+        if (!controllerRef.current) return;
+        abortRequest();
+        setStatus('stopped');
+        setStatusText('Stopped');
+    }, [abortRequest]);
+
+    const undo = useCallback(() => {
+        const last = latestRef.current.applied;
+        if (!last) return;
+        applyGridAiState(apiRef.current, last.previous);
+        setApplied(null);
+        setErrors(NO_ERRORS);
+        setMessage(null);
+        setStatus('idle');
+        setStatusText('Undone');
+    }, [apiRef]);
+
+    const removeChip = useCallback((id: string) => {
+        const last = latestRef.current.applied;
+        if (!last) return;
+        const state = removeAiChip(last.state, id);
+        applyGridAiState(apiRef.current, effectiveState(state, last.previous));
+        setApplied({ state, previous: last.previous });
+        setStatusText('Change removed');
+    }, [apiRef]);
+
+    useLayoutEffect(() => {
+        const api = apiRef.current;
+        api.openAiAssistant = () => openPanel();
+        api.closeAiAssistant = () => {
+            if (latestRef.current.open) closePanel();
+        };
+    }, [apiRef, openPanel, closePanel]);
+
+    const isOpen = enabled && open;
+    const panelProps = useMemo<GridAiAssistantPanelProps | null>(() => {
+        if (!isOpen || !options) return null;
+        return {
+            status,
+            statusText,
+            message,
+            errors,
+            chips,
+            history,
+            suggestions: options.suggestions ?? NO_SUGGESTIONS,
+            placeholder: options.placeholder ?? DEFAULT_PLACEHOLDER,
+            voiceAvailable: options.voice !== false && hasSpeechRecognition(),
+            canUndo: applied !== null,
+            submit,
+            stop,
+            undo,
+            removeChip,
+            close: closePanel,
+        };
+    }, [isOpen, options, status, statusText, message, errors, chips, history, applied, submit, stop, undo, removeChip, closePanel]);
+
+    return {
+        enabled,
+        open: isOpen,
+        openPanel,
+        togglePanel,
+        closePanel,
+        panelProps,
+        announcement: enabled ? statusText : '',
+    };
+}