@opencorestack/opengridx 3.8.1 → 3.9.0

package/lib/hooks/core/useGridVirtualization.ts

@@ -73,33 +73,23 @@ export function useGridVirtualization<R extends GridRowModel>(
         maxContentHeight = Infinity,
     } = params;
 
-    return useMemo<GridVirtualizationResult<R>>(() => {
-        const {
-            unpinnedAccWidths,
-            unpinnedColsWithWidth,
-            leftPinnedCols,
-            rightPinnedCols,
-            totalWidth,
-            leftWidth,
-            rightWidth,
-            unpinnedTotalWidth,
-            systemColumnsWidth,
-            cumulativeHeights,
-            pinnedTopHeight,
-            pinnedBottomHeight,
-            unpinnedRowsHeight,
-            rowHeights,
-            unpinnedRowsLength,
-        } = layout;
-
+    const {
+        unpinnedAccWidths,
+        unpinnedColsWithWidth,
+        leftPinnedCols,
+        rightPinnedCols,
+        leftWidth,
+        unpinnedTotalWidth,
+    } = layout;
+
+    // The column window has its own memo: it depends only on column widths and the horizontal scroll,
+    // so a row change (an edit) or a vertical scroll keeps the same `virtualColumns` array, and rows
+    // memoised on their columns do not re-render.
+    const columnWindow = useMemo(() => {
         const viewportWidth  = rawViewportWidth  || 1000;
-        const viewportHeight = autoHeight
-            ? pinnedTopHeight + unpinnedRowsHeight + pinnedBottomHeight + 50
-            : rawViewportHeight || 600;
-
-        const overscanCols = 6;
         const visibleLocalStart = Math.max(0, scrollLeft - leftWidth);
         const visibleLocalEnd   = scrollLeft + viewportWidth - leftWidth;
+        const overscanCols = 6;
 
         let firstUnpinnedIndex = 0;
         let lastUnpinnedIndex  = unpinnedColsWithWidth.length - 1;
@@ -129,6 +119,28 @@ export function useGridVirtualization<R extends GridRowModel>(
             ...(rightSpacerWidth > 0 ? [{ field: '__spacer_right__', width: rightSpacerWidth, isSpacer: true }] : []),
             ...rightPinnedCols,
         ];
+        return { firstUnpinnedIndex, lastUnpinnedIndex, virtualColumns };
+    }, [unpinnedAccWidths, unpinnedColsWithWidth, leftPinnedCols, rightPinnedCols, leftWidth, unpinnedTotalWidth, scrollLeft, rawViewportWidth]);
+
+    return useMemo<GridVirtualizationResult<R>>(() => {
+        const {
+            totalWidth,
+            rightWidth,
+            systemColumnsWidth,
+            cumulativeHeights,
+            pinnedTopHeight,
+            pinnedBottomHeight,
+            unpinnedRowsHeight,
+            rowHeights,
+            unpinnedRowsLength,
+        } = layout;
+
+        const viewportWidth  = rawViewportWidth  || 1000;
+        const viewportHeight = autoHeight
+            ? pinnedTopHeight + unpinnedRowsHeight + pinnedBottomHeight + 50
+            : rawViewportHeight || 600;
+
+        const { firstUnpinnedIndex, lastUnpinnedIndex, virtualColumns } = columnWindow;
 
         const hasHorizontalScroll = viewportWidth > 0 && totalWidth > viewportWidth;
         const scrollbarBuffer = hasHorizontalScroll ? 16 : 0;
@@ -192,8 +204,11 @@ export function useGridVirtualization<R extends GridRowModel>(
         };
     }, [
         layout,
+        columnWindow,
+        leftWidth,
+        unpinnedAccWidths,
+        unpinnedColsWithWidth,
         scrollTop,
-        scrollLeft,
         rawViewportWidth,
         rawViewportHeight,
         autoHeight,

package/lib/hooks/core/useShallowStableValue.ts

@@ -0,0 +1,29 @@
+import { useState } from 'react';
+
+/** Equal when both hold the same keys with `Object.is`-equal values, one level of plain records deep. */
+function isShallowEqual(a: unknown, b: unknown, depth = 1): boolean {
+    if (Object.is(a, b)) return true;
+    if (!a || !b || typeof a !== 'object' || typeof b !== 'object' || Array.isArray(a) || Array.isArray(b)) return false;
+    const ra = a as Record<string, unknown>;
+    const rb = b as Record<string, unknown>;
+    const keys = Object.keys(ra);
+    if (keys.length !== Object.keys(rb).length) return false;
+    return keys.every(key => Object.prototype.hasOwnProperty.call(rb, key)
+        && (Object.is(ra[key], rb[key]) || (depth > 0 && isShallowEqual(ra[key], rb[key], depth - 1))));
+}
+
+/**
+ * `value`, or the previous one while the new one holds the same entries. A consumer passing an
+ * inline object (`localeText={{ … }}`) then keeps one identity across renders, so what is memoised
+ * on it (the resolved locale, and every row that reads it) does not update needlessly. Functions
+ * inside are compared by identity: an inline function still counts as a change.
+ */
+export function useShallowStableValue<T>(value: T): T {
+    const [stable, setStable] = useState(value);
+    if (stable !== value && !isShallowEqual(stable, value)) {
+        // Adjusting state while rendering (React's documented pattern for derived state).
+        setStable(value);
+        return value;
+    }
+    return stable;
+}

package/lib/hooks/features/useGridAiAssistant.ts

@@ -10,7 +10,9 @@ import type {
     GridAiValidationError,
     GridApi,
     GridColDef,
+    GridLocaleText,
 } from '../../types';
+import { resolveGridLocale, type ResolvedGridLocale } from '../../utils/gridLocale';
 import { attempt } from '../../utils/attempt';
 import { isGridAiValidated } from '../../utils/aiBrand';
 import {
@@ -32,6 +34,8 @@ export interface UseGridAiAssistantParams {
     columns: readonly GridColDef[];
     onApply?: (result: GridAiPromptResult) => void;
     onError?: (error: unknown) => void;
+    /** The grid's `localeText`, for the status line and the placeholder. */
+    localeText?: GridLocaleText;
 }
 
 export interface UseGridAiAssistantResult {
@@ -48,7 +52,6 @@ export interface UseGridAiAssistantResult {
     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';
@@ -69,13 +72,38 @@ 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';
-}
+/** What the status line says, turned into text with the grid's locale at render time. */
+type StatusLine =
+    | { kind: 'none' }
+    | { kind: 'thinking' }
+    | { kind: 'stopped' }
+    | { kind: 'undone' }
+    | { kind: 'removed' }
+    | { kind: 'applied'; count: number; ignored: number }
+    | { kind: 'notValidated' }
+    | { kind: 'failed'; error: unknown };
+
+const NO_STATUS: StatusLine = { kind: 'none' };
+const THINKING: StatusLine = { kind: 'thinking' };
+const STOPPED: StatusLine = { kind: 'stopped' };
+const UNDONE: StatusLine = { kind: 'undone' };
+const REMOVED: StatusLine = { kind: 'removed' };
+const NOT_VALIDATED_STATUS: StatusLine = { kind: 'notValidated' };
 
-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;
+function statusLineText(line: StatusLine, locale: ResolvedGridLocale): string {
+    switch (line.kind) {
+        case 'none': return '';
+        case 'thinking': return locale.aiAssistantThinking;
+        case 'stopped': return locale.aiAssistantStopped;
+        case 'undone': return locale.aiAssistantUndone;
+        case 'removed': return locale.aiAssistantChangeRemoved;
+        case 'applied': return locale.aiAssistantApplied(line.count, line.ignored);
+        case 'notValidated': return locale.aiAssistantNotValidated;
+        case 'failed': {
+            const { error } = line;
+            return locale.aiAssistantFailed(error instanceof Error && error.message ? error.message : locale.aiAssistantUnknownError);
+        }
+    }
 }
 
 /** Calls a consumer callback; a throw is warned about (development) and otherwise ignored. */
@@ -92,11 +120,13 @@ function notify<T>(callback: ((value: T) => void) | undefined, value: T, name: s
  * `closeAiAssistant`.
  */
 export function useGridAiAssistant(params: UseGridAiAssistantParams): UseGridAiAssistantResult {
-    const { apiRef, options, columns } = params;
+    const { apiRef, options, columns, localeText } = params;
+    const locale = useMemo(() => resolveGridLocale(localeText), [localeText]);
     const enabled = Boolean(options);
     const [open, setOpen] = useState(false);
     const [status, setStatus] = useState<GridAiAssistantStatus>('idle');
-    const [statusText, setStatusText] = useState('');
+    const [statusLine, setStatusLine] = useState<StatusLine>(NO_STATUS);
+    const statusText = statusLineText(statusLine, locale);
     const [message, setMessage] = useState<string | null>(null);
     const [errors, setErrors] = useState<GridAiValidationError[]>(NO_ERRORS);
     const [applied, setApplied] = useState<Applied | null>(null);
@@ -135,7 +165,7 @@ export function useGridAiAssistant(params: UseGridAiAssistantParams): UseGridAiA
         if (controllerRef.current) {
             abortRequest();
             setStatus('stopped');
-            setStatusText('Stopped');
+            setStatusLine(STOPPED);
         }
         setOpen(false);
         const target = returnFocusRef.current;
@@ -148,9 +178,9 @@ export function useGridAiAssistant(params: UseGridAiAssistantParams): UseGridAiA
         else openPanel(trigger);
     }, [openPanel, closePanel]);
 
-    const fail = useCallback((text: string, error: unknown) => {
+    const fail = useCallback((line: StatusLine, error: unknown) => {
         setStatus('error');
-        setStatusText(text);
+        setStatusLine(line);
         setMessage(null);
         setErrors(NO_ERRORS);
         notify(latestRef.current.params.onError, error, 'onAiAssistantError');
@@ -163,7 +193,7 @@ export function useGridAiAssistant(params: UseGridAiAssistantParams): UseGridAiA
             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));
+            fail(NOT_VALIDATED_STATUS, new Error(NOT_VALIDATED));
             return;
         }
         const allowed = pickAllowedParts(result.state, current.options?.parts ?? AI_PARTS);
@@ -177,7 +207,7 @@ export function useGridAiAssistant(params: UseGridAiAssistantParams): UseGridAiA
         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));
+        setStatusLine({ kind: 'applied', count: buildAiChips(state, (f) => f).length, ignored: ignored.length });
         notify(current.onApply, result, 'onAiAssistantApply');
     }, [apiRef, fail]);
 
@@ -190,7 +220,7 @@ export function useGridAiAssistant(params: UseGridAiAssistantParams): UseGridAiA
         const controller = new AbortController();
         controllerRef.current = controller;
         setStatus('running');
-        setStatusText('Thinking…');
+        setStatusLine(THINKING);
         setMessage(null);
         setErrors(NO_ERRORS);
         const context = { currentState: apiRef.current.getGridAiState(), history: earlier, signal: controller.signal };
@@ -207,10 +237,10 @@ export function useGridAiAssistant(params: UseGridAiAssistantParams): UseGridAiA
                 controllerRef.current = null;
                 if (controller.signal.aborted || isAbortError(error)) {
                     setStatus('stopped');
-                    setStatusText('Stopped');
+                    setStatusLine(STOPPED);
                     return;
                 }
-                fail(`The assistant could not answer: ${errorText(error)}`, error);
+                fail({ kind: 'failed', error }, error);
             },
         );
     }, [apiRef, abortRequest, applyResult, fail]);
@@ -219,7 +249,7 @@ export function useGridAiAssistant(params: UseGridAiAssistantParams): UseGridAiA
         if (!controllerRef.current) return;
         abortRequest();
         setStatus('stopped');
-        setStatusText('Stopped');
+        setStatusLine(STOPPED);
     }, [abortRequest]);
 
     const undo = useCallback(() => {
@@ -230,7 +260,7 @@ export function useGridAiAssistant(params: UseGridAiAssistantParams): UseGridAiA
         setErrors(NO_ERRORS);
         setMessage(null);
         setStatus('idle');
-        setStatusText('Undone');
+        setStatusLine(UNDONE);
     }, [apiRef]);
 
     const removeChip = useCallback((id: string) => {
@@ -239,7 +269,7 @@ export function useGridAiAssistant(params: UseGridAiAssistantParams): UseGridAiA
         const state = removeAiChip(last.state, id);
         applyGridAiState(apiRef.current, effectiveState(state, last.previous));
         setApplied({ state, previous: last.previous });
-        setStatusText('Change removed');
+        setStatusLine(REMOVED);
     }, [apiRef]);
 
     useLayoutEffect(() => {
@@ -261,7 +291,7 @@ export function useGridAiAssistant(params: UseGridAiAssistantParams): UseGridAiA
             chips,
             history,
             suggestions: options.suggestions ?? NO_SUGGESTIONS,
-            placeholder: options.placeholder ?? DEFAULT_PLACEHOLDER,
+            placeholder: options.placeholder ?? locale.aiAssistantPlaceholder,
             voiceAvailable: options.voice !== false && hasSpeechRecognition(),
             canUndo: applied !== null,
             submit,
@@ -270,7 +300,7 @@ export function useGridAiAssistant(params: UseGridAiAssistantParams): UseGridAiA
             removeChip,
             close: closePanel,
         };
-    }, [isOpen, options, status, statusText, message, errors, chips, history, applied, submit, stop, undo, removeChip, closePanel]);
+    }, [isOpen, options, status, statusText, message, errors, chips, history, applied, submit, stop, undo, removeChip, closePanel, locale]);
 
     return {
         enabled,

package/lib/theme/DataGridThemeProvider.tsx

@@ -303,6 +303,10 @@ function themeToCSS(theme: GridTheme): Record<string, string> {
         set('--ogx-grid-pinned-right-shadow', g.pinnedRightShadow);
         set('--ogx-checkbox-bg', g.checkboxBg);
         set('--ogx-checkbox-border', g.checkboxBorder);
+        set('--ogx-checkbox-checked-bg', g.checkboxCheckedBackground);
+        set('--ogx-checkbox-checkmark', g.checkboxCheckmark);
+        set('--ogx-expand-icon-color', g.expandIconColor);
+        set('--ogx-expand-icon-hover-color', g.expandIconHoverColor);
     }
 
     if (theme.transitions) {
@@ -350,6 +354,11 @@ function themeToCSS(theme: GridTheme): Record<string, string> {
         set('--ogx-overlay-item-selected-text', o.itemSelectedText);
         set('--ogx-overlay-item-danger-bg', o.itemDangerBackground);
         set('--ogx-overlay-item-danger-text', o.itemDangerText);
+        set('--ogx-overlay-item-indicator', o.itemIndicatorColor);
+        set('--ogx-overlay-item-selected-icon', o.itemSelectedIcon);
+        set('--ogx-overlay-icon', o.iconColor);
+        set('--ogx-overlay-section-label-text', o.sectionLabelText);
+        set('--ogx-overlay-divider', o.dividerColor);
         set('--ogx-overlay-font-family', o.fontFamily);
         set('--ogx-overlay-font-weight', o.fontWeight);
         set('--ogx-overlay-font-size', o.fontSize);

package/lib/theme/types.ts

@@ -90,6 +90,16 @@ export interface GridThemeOverlays {
     itemSelectedText?: string;
     itemDangerBackground?: string;
     itemDangerText?: string;
+    /** The dot before the selected option of a menu group (`--ogx-overlay-item-indicator`). Default: `itemSelectedText`. @since v3.9 */
+    itemIndicatorColor?: string;
+    /** The icon of the selected option (`--ogx-overlay-item-selected-icon`). Default: the primary colour. @since v3.9 */
+    itemSelectedIcon?: string;
+    /** Menu item icons (`--ogx-overlay-icon`). Default: gray-400. @since v3.9 */
+    iconColor?: string;
+    /** Section labels such as "Pin column" (`--ogx-overlay-section-label-text`). Default: gray-400. @since v3.9 */
+    sectionLabelText?: string;
+    /** Lines between menu sections (`--ogx-overlay-divider`). Default: `border`. @since v3.9 */
+    dividerColor?: string;
 
     /** Font of column menus, header filter menus, toolbar panels and the AI panel (`--ogx-overlay-font-family`). Default: the grid font. @since v3.7 */
     fontFamily?: string;
@@ -200,6 +210,14 @@ export interface GridThemeGrid {
   pinnedRightShadow?: string;
     checkboxBg?: string;
   checkboxBorder?: string;
+    /** Fill and border of a checked or indeterminate checkbox (`--ogx-checkbox-checked-bg`). Default: the primary colour. @since v3.9 */
+    checkboxCheckedBackground?: string;
+    /** The check mark and indeterminate dash (`--ogx-checkbox-checkmark`). Default: white. @since v3.9 */
+    checkboxCheckmark?: string;
+    /** The expand / collapse chevron of group and tree rows (`--ogx-expand-icon-color`). Default: the header text colour. @since v3.9 */
+    expandIconColor?: string;
+    /** The chevron on hover (`--ogx-expand-icon-hover-color`). Default: the row text colour. @since v3.9 */
+    expandIconHoverColor?: string;
 }
 
 export interface GridThemeTransitions {