wenay-react2 1.0.23 → 1.0.25

package/README.md

@@ -1,384 +1,58 @@
-Here is an expanded API guide with typings and usage examples. This format is suitable for documentation so other developers or AI assistants can quickly understand which props a component accepts and how to integrate it.
+# wenay-react2
 
----
+Common React UI primitives for wenay apps.
 
-## API Reference (Components & Hooks)
+Use the new concise API guide first:
 
-### Modal and Floating Windows (MDI)
+- [wenay-react2.md](./wenay-react2.md) - canonical everyday API.
+- [wenay-react2-rare.md](./wenay-react2-rare.md) - old names, low-level exports, migration notes.
+- [agGrid4 README](./src/common/src/grid/agGrid4/README.md) - table buffer/controller details.
+- [agGrid4 wrapper boundary](./src/common/src/grid/agGrid4/WRAPPER.md) - where generic primitives end and app wrappers begin.
 
-#### `DivRnd3`
-Wrapper for creating freely movable, resizable windows with state persistence.
+## Import
 
-**Typing:**
-```typescript
-type tDivRndBase = {
-    children: React.ReactElement | ((update: number) => React.ReactElement);
-    position?: { x: number; y: number };
-    size?: { height: number | string; width: number | string };
-    keyForSave?: string;        // Key for caching the position/size in memory
-    limit?: { x?: { max?: number; min?: number }, y?: { max?: number; min?: number } };
-    onCLickClose?: () => void;  // Adds a close button to the window
-    header?: React.ReactElement | boolean; // Drag handle header; otherwise the whole block is draggable
-    zIndex?: number;
-}
+```ts
+import { useModal, useAgGrid, createGridBuffer, createColumnBuffer, useStoreMirror } from "wenay-react2"
 ```
 
-**Example:**
-```textmate
-<DivRnd3
-    keyForSave="my_tool_window"
-    size={{ width: 300, height: 200 }}
-    onCLickClose={() => setOpen(false)}
-    header={<div>My tool</div>}
->
-    <div>Window content</div>
-</DivRnd3>
-```
-
-
-#### `GetModalJSX()`
-Factory for global modal windows. It lets business logic open windows without being tied to local component state.
-
-**Example:**
-```textmate
-const myModal = GetModalJSX();
-
-// 1. In the app root file (App.tsx):
-<myModal.Render />
-
-// 2. Anywhere in the logic:
-myModal.set(<div onClick={() => myModal.set(null)}>Close me</div>);
-// For multiple windows: myModal.addJSX(<Component/>)
-```
-
-
----
-
-### Drag-and-Drop and Interaction (Hooks & Wrappers)
-
-#### `useOutside` / `DivOutsideClick`
-Tracks clicks outside an element, useful for closing dropdowns and menus.
-
-**Typing:**
-```typescript
-// Hook
-function useOutside(params: { outsideClick: () => void, status?: boolean, ref?: RefObject }): RefObject;
-
-// Component
-type Props = { outsideClick: () => void, status?: boolean, zIndex?: number } & HTMLAttributes;
-```
-
-**Example:**
-```textmate
-<DivOutsideClick outsideClick={() => setDropdownOpen(false)} status={isOpen}>
-    <div className="dropdown-menu">...</div>
-</DivOutsideClick>
-```
-
-
-#### `Drag22`
-Tracks mouse/finger movement and returns new coordinates without touching CSS directly.
-
-**Typing:**
-```typescript
-type Drag2Props = {
-    x?: number; y?: number;               // Start/current coordinates
-    onX?: (val: number) => void;          // X change callback
-    onY?: (val: number) => void;          // Y change callback
-    onStart?: () => void; onStop?: () => void;
-    children: ReactNode;
-};
-```
-
-
----
-
-### Context Menus (`MenuR` / `mouseMenuApi`)
-
-Smart context menus. They open on desktop via right click and on mobile via long tap / double tap. They support asynchronous item generation.
-
-**Menu item typing (`tMenuReactStrictly`):**
-```typescript
-type tMenuReactStrictly = {
-    name: string | ((status?: any) => string);
-    onClick?: (e: any) => void | Promise<any> | Promise<any>[]; // Promise support with ok/error counters
-    status?: boolean; // Whether the submenu is expanded
-    next?: () => tMenuReact[] | Promise<tMenuReact[]>; // Nested menu
-    func?: () => React.ReactElement | Promise<React.ReactElement>; // Custom hover render
-};
-```
-
-**Examples:**
-```textmate
-// 1. Using the wrapper component
-const menuItems = () => [
-    { name: "Copy", onClick: () => copy() },
-    { name: "Options", next: () => [{ name: "Option 1", onClick: () => {} }] }
-];
-
-<MenuR other={menuItems}>
-    <div className="item">Right-click me</div>
-</MenuR>
-
-// 2. Global call through the API
-mouseMenuApi.map.set("global_action", [{ name: "Global action", onClick: () => {} }]);
-```
-
-
----
-
-### Ag-Grid Table Updates (`applyTransactionAsyncUpdate2`)
-
-Function for safe batched asynchronous table data updates synchronized with a local buffer/cache.
-
-**Typing:**
-```typescript
-type Params<T> = {
-    gridRef?: React.RefObject<GridReadyEvent<T, any>>;
-    newData: Partial<T>[];                         // New data array
-    getId: (row: Partial<T>) => string;            // ID getter
-    bufTable: { [id: string]: Partial<T> };        // Local cache dictionary
-    option?: { update?: boolean, add?: boolean, updateBuffer?: boolean, sync?: boolean };
-};
-```
-
-**Example:**
-```textmate
-// Immediately updates the cache and sends a transaction to Ag-Grid
-applyTransactionAsyncUpdate2({
-    gridRef: apiGrid,
-    newData: [{ id: "user_1", balance: 500 }],
-    getId: (e) => e.id,
-    bufTable: myLocalBuffer,
-    option: { update: true, add: true }
-});
-```
-
-
----
-
-### UI Settings Autogeneration (`ParametersReact`)
-
-Engine that accepts an object with a data schema and renders a ready-to-use control form with inputs, sliders, and selects.
-
-**Typing:**
-The schema is built from `Params.IParamsExpandableReadonly` types.
-Supported types: `number`, `string`, `boolean`, `Date`, arrays, and nested objects.
-
-**Example:**
-```textmate
-const mySettings = {
-    showGrid: true, // Generates a Checkbox
-    opacity: {
-        value: 0.5,
-        range: { min: 0, max: 1, step: 0.1 },
-        name: "Opacity"
-    }, // Generates a Range Slider + Number Input
-    theme: {
-        value: "dark",
-        range: ["dark", "light", "system"]
-    } // Generates a Select
-};
+The root export is still flat. A grouped namespace is also exported for large files:
 
-<ParametersReact
-    params={mySettings}
-    onChange={(newParams) => {
-        console.log("New value:", newParams.opacity.value);
-    }}
-/>
-```
-
-
----
-
-### Logging System (`logsApi`)
-
-Log registration, log viewer table, and toast notification system.
-
-**API:**
-```typescript
-// 1. Adding a log
-logsApi.addLogs({
-    id: "system",
-    var: 10,           // Severity, important for notification filtering
-    time: new Date(),
-    txt: "Connection lost"
-});
-
-// 2. Rendering components, usually somewhere near the root:
-<logsApi.React.Message zIndex={9999} /> // Toast notifications in the top-right corner
-<logsApi.React.PageLogs />              // Ag-Grid table with all logs
-```
-
-There are several other important architectural patterns and UI components actively used in the codebase. They should be documented so another developer or AI assistant can understand how interfaces are built in this project.
-
-Here is the second part of the `README.md` additions:
-
----
-
-### Sidebar Navigation
-
-#### `ApiLeftMenu`
-Ready-made API for controlling the left slide-out sidebar menu. It supports swipes, smooth snap scrolling, and imperative tab control.
-
-**API and Typing:**
-```typescript
-type MenuItem = {
-    el: () => React.JSX.Element;   // Tab component
-    button?: React.JSX.Element;    // Custom button, optional
-    color?: ColorString;           // Background color
-    textB?: string;                // Default button text
-};
-
-// Register menu items:
-ApiLeftMenu.setMenu(items: MenuItem[], key?: string);
-```
-
-**Usage example:**
-```textmate
-// 1. Register tabs, can be done anywhere in the logic:
-ApiLeftMenu.setMenu([
-    { textB: "Dashboard", el: () => <Dashboard />, color: "rgb(92,50,213)" },
-    { textB: "Settings", el: () => <Settings /> }
-], "main_menu");
-
-// 2. Render the menu itself in the root Layout:
-export function AppLayout() {
-    return <ApiLeftMenu.Modal2 zIndex={20} />;
-}
-```
-
-
----
-
-### Interactive Elements and Buttons
+```ts
+import { v2 } from "wenay-react2"
 
-#### `Button` (from `useOutside.tsx`) / `MiniButton`
-Advanced button components that encapsulate dropdown logic, popover panels, and outside-click tracking for automatic closing.
-
-**`Button` typing:**
-```typescript
-type tButton = {
-    button: ReactElement | ((status: boolean) => ReactElement); // The button itself; can change by status
-    children: ReactNode | ((api: {onClose: () => void}) => ReactNode); // Dropdown content
-    outClick?: boolean | (() => void); // Whether to close on outside click; true by default
-    statusDef?: boolean; // Initial state, open/closed
-};
-```
-
-**Example:**
-```textmate
-<Button
-    outClick={true}
-    button={(isOpen) => <div className={isOpen ? "active" : ""}>Options</div>}
->
-    {({ onClose }) => (
-        <div className="dropdown-panel">
-            <div onClick={() => { doSomething(); onClose(); }}>Action 1</div>
-        </div>
-    )}
-</Button>
+v2.grid.useAgGrid(...)
+v2.modal.useModal()
 ```
 
+## API Standard
 
-#### `FResizableReact`
-Wrapper over `re-resizable`. It creates resizable panels, for example columns or lower log panes, and stores their size in cache.
-
-**Example:**
-```textmate
-<FResizableReact
-    keyForSave="bottom_panel_size"
-    size={{ height: 200, width: "100%" }}
-    moveWith={false} // Allow resize only by height
->
-    <LogsTable />
-</FResizableReact>
-```
-
-
----
-
-### Global Reactivity (`renderBy` / `updateBy` Pattern)
-
-*(Note: this is a key project concept used instead of classic `useState` / `Redux` for complex business logic.)*
-
-Many places in the project use a mutable state approach: you mutate properties of a plain JS object and call `renderBy(obj)` to force an update of all components subscribed to that object through `updateBy(obj)`.
-
-**Pattern example:**
-```textmate
-import { renderBy, updateBy } from "./updateBy";
+New code should use the short controller-style surface:
 
-// 1. Global or local state, a plain object
-const myState = {
-    count: 0,
-    text: "hello"
-};
+```tsx
+const modal = useModal()
+modal.open(<Dialog />)
+modal.close()
 
-// 2. Consumer component
-function CounterViewer() {
-    // The component subscribes to myState changes
-    updateBy(myState);
+const grid = useAgGrid<Row>({getId: row => row.id})
+grid.update({newData})
+grid.clean()
+grid.flush()
 
-    return <div>{myState.count}</div>;
-}
-
-// 3. State change, anywhere, even outside React
-function increment() {
-    myState.count += 1;
-    renderBy(myState); // Triggers a CounterViewer rerender
-}
+const mirror = useStoreMirror(remoteStore, initialState, {mask, current: true})
 ```
 
+Old `Get*`, `*2/*3`, `FuncJSX`, and legacy grid helper names remain documented in `wenay-react2-rare.md` for existing code, but they are not the teaching path for new code.
 
----
-
-### Useful Ag-Grid Utilities
-
-#### `GridStyleDefault` and `StyleCSSHeadGrid`
-Quickly apply the common corporate style to all application tables.
+## QA Stand
 
-**Root integration example:**
-```typescript
-import { GridStyleDefault, StyleCSSHeadGrid } from "./styleGrid";
-
-// Applies the dark theme, compresses spacing, and centers headers
-GridStyleDefault();
-StyleCSSHeadGrid();
+```sh
+npm run testReact -- --host 127.0.0.1 --port 3002
 ```
 
+The stand source is `src/common/testUseReact/qa.tsx`. Use it for visual checks after changing UI primitives.
 
-#### `getComparatorGrid`
-Factory for creating custom Ag-Grid column sort functions that correctly handle `undefined`, `NaN`, and inversion.
-**Example:**
-```textmate
-const columnDefs = [
-    {
-        field: "price",
-        comparator: getComparatorGrid() // Safe numeric sorting
-    }
-];
-```
-
-
----
-
-### Global Hooks
-
-#### `useAddDownAnyKey`
-Registers a global keyboard listener and stores the last pressed key in the exported reactive object `KeyDown`.
-
-**Usage example:**
-```textmate
-import { KeyDown, useAddDownAnyKey } from "./useAddDownAnyKey";
-import { updateBy } from "./updateBy";
-
-function HotkeyListener() {
-    useAddDownAnyKey(); // Hook initialization
-    updateBy(KeyDown);  // Subscribe to key presses
+## Build
 
-    if (KeyDown.key === "Escape") {
-        return <div>Escape pressed!</div>;
-    }
-    return null;
-}
+```sh
+npm run build
 ```

package/lib/common/src/grid/agGrid4/agGrid4.d.ts

@@ -1,25 +1,34 @@
 import React from 'react';
 import { AgGridReactProps } from 'ag-grid-react';
 import type { GridApi, GetRowIdParams, GridPreDestroyedEvent, GridReadyEvent } from 'ag-grid-community';
-import { type BufferTable, type GetId } from './core';
+import { type BufferTable, type GetId, type GridBufferCore, type GridBufferMode, type PushOptions } from './core';
 export type UseAgGridOptions<T> = {
     /** How to get a row id. Defaults to the `id` field. Captured once (first render). */
     getId?: GetId<T>;
     /** External buffer: a plain object above the component (like datum.tableArr) that survives route remounts. */
     externalBuffer?: BufferTable<T>;
+    /** mirror (default): buffer owns rows. overlay: rowData owns rows and sync only refreshes intersection. */
+    mode?: GridBufferMode;
+    /** Default delivery policy for updateData. Useful for overlay streams: { add: false }. */
+    pushDefaults?: PushOptions;
+    /** Ready-made module-level core/store; getId/externalBuffer/mode are already captured inside it. */
+    core?: GridBufferCore<T>;
 };
 /**
  * Headless table hook. All race handling lives in the core; the hook only binds it
  * to the React and grid lifecycle:
  *
  *   const grid = useAgGrid<Row>({ getId })
+ *   const grid = useAgGrid({ core: mainTable })
  *   <AgGridMy<Row> controller={grid} columnDefs={cols} />
  *   grid.update({ newData })
  */
 export declare function useAgGrid<T>(options?: UseAgGridOptions<T>): {
     update: (args: import("./core").UpdateArgs<T>) => void;
     remove(rows: Partial<T>[]): void;
+    clean: (args?: import("./core").CleanArgs) => void;
     fit: () => boolean;
+    flush: () => boolean;
     updateData: (args: import("./core").UpdateArgs<T>) => void;
     sync: () => void;
     getId: GetId<T>;
@@ -38,6 +47,7 @@ export declare function useAgGrid<T>(options?: UseAgGridOptions<T>): {
     getApi(): GridApi<T> | null;
     withApi<R>(fn: (api: GridApi<T>) => R): R | undefined;
     sizeColumnsToFit: () => boolean;
+    flushAsyncTransactions: () => boolean;
 };
 export type AgGridController<T> = ReturnType<typeof useAgGrid<T>>;
 export type AgGridMyProps<T> = AgGridReactProps<T> & {

package/lib/common/src/grid/agGrid4/agGrid4.js

@@ -23,6 +23,7 @@ function ensureAgGridModules() {
  * to the React and grid lifecycle:
  *
  *   const grid = useAgGrid<Row>({ getId })
+ *   const grid = useAgGrid({ core: mainTable })
  *   <AgGridMy<Row> controller={grid} columnDefs={cols} />
  *   grid.update({ newData })
  */
@@ -31,8 +32,15 @@ export function useAgGrid(options) {
     const apiRef = useRef(null);
     // The core is created once; dependencies live in its closure, with no useCallback chains.
     const [core] = useState(function createCore() {
+        if (options?.core)
+            return options.core;
         const getId = options?.getId ?? (data => String(data?.id));
-        return createGridBuffer({ getId, externalBuffer: options?.externalBuffer });
+        return createGridBuffer({
+            getId,
+            externalBuffer: options?.externalBuffer,
+            mode: options?.mode,
+            pushDefaults: options?.pushDefaults,
+        });
     });
     const gridProps = useMemo(() => ({
         getRowId(params) {
@@ -55,12 +63,21 @@ export function useAgGrid(options) {
             api.sizeColumnsToFit();
             return true;
         };
+        const flush = () => {
+            const api = apiRef.current;
+            if (!api)
+                return false;
+            api.flushAsyncTransactions();
+            return true;
+        };
         return {
             update: core.api.updateData,
             remove(rows) {
                 core.api.updateData({ removeData: rows });
             },
+            clean: core.api.clean,
             fit,
+            flush,
             updateData: core.api.updateData,
             sync: core.api.sync,
             getId: core.api.getId,
@@ -76,6 +93,7 @@ export function useAgGrid(options) {
                 return api ? fn(api) : undefined;
             },
             sizeColumnsToFit: fit,
+            flushAsyncTransactions: flush,
         };
     }, [core, gridProps]);
 }
@@ -85,14 +103,18 @@ export function useAgGrid(options) {
 const ROW_SELECTION = { mode: 'multiRow' };
 function AgGridMyInner(props) {
     const { controller, data, autoSizeColumns = true, defaultColDef, theme, getRowId, onGridReady, onGridPreDestroyed, ...rest } = props;
-    // Own controller for declarative mode (without an external controller); the hook is unconditional.
-    const own = useAgGrid();
+    // Own controller is overlay-safe: rowData grids without a controller must not be cleared on attach.
+    const own = useAgGrid({
+        getId: getRowId ? data => getRowId({ data: data }) : undefined,
+        mode: 'overlay',
+        pushDefaults: { add: false, remove: false },
+    });
     const grid = controller ?? own;
     const defaultTheme = useAgGridTheme();
     const containerRef = useRef(null);
     useEffect(function pushData() {
         if (data)
-            grid.update({ newData: data });
+            grid.update({ newData: data, option: { add: true } });
     }, [data, grid]);
     useEffect(function observeResize() {
         if (!containerRef.current || !autoSizeColumns)
@@ -114,10 +136,11 @@ function AgGridMyInner(props) {
         };
     }, [autoSizeColumns, grid]);
     const mergedColDef = useMemo(() => ({ sortable: true, resizable: true, filter: true, ...defaultColDef }), [defaultColDef]);
+    const wiredGetRowId = getRowId ?? (controller || data ? grid.props.getRowId : undefined);
     return (_jsx("div", { ref: containerRef, style: { height: '100%', width: '100%', overflow: 'hidden' }, children: _jsx(AgGridReact, { theme: theme ?? defaultTheme, asyncTransactionWaitMillis: 50, suppressCellFocus: true, rowSelection: ROW_SELECTION, ...rest, defaultColDef: mergedColDef, 
             // getRowId after the spread: undefined from rest must not erase the wiring,
             // otherwise the grid falls back to index-based row identity.
-            getRowId: getRowId ?? grid.props.getRowId, onGridReady: function ready(event) {
+            getRowId: wiredGetRowId, onGridReady: function ready(event) {
                 grid.props.onGridReady(event);
                 if (autoSizeColumns)
                     event.api.sizeColumnsToFit();

package/lib/common/src/grid/agGrid4/columnBuffer.d.ts

@@ -0,0 +1,26 @@
+import type { GridApi } from 'ag-grid-community';
+export type ColumnApplyContext<TData = any> = {
+    api: GridApi<TData>;
+    names: readonly string[];
+};
+export type ColumnAttach<TData = any> = {
+    /** Project/page wrapper decides how names affect the grid. */
+    apply: (context: ColumnApplyContext<TData>) => void;
+};
+/**
+ * Buffer for the exact set of dynamic column names.
+ * setNames() means exactly this dynamic set; attach() applies the saved set; detach() keeps names.
+ * This utility deliberately knows nothing about groups, columnDefs shape, or business names.
+ */
+export declare function createColumnBuffer<TData = any>(): {
+    control: {
+        attach: (gridApi: GridApi<TData>, opts: ColumnAttach<TData>) => void;
+        detach: () => void;
+    };
+    api: {
+        setNames: (list: string[]) => void;
+        apply: () => void;
+        readonly names: string[];
+    };
+};
+export type ColumnBuffer<TData = any> = ReturnType<typeof createColumnBuffer<TData>>;

package/lib/common/src/grid/agGrid4/columnBuffer.js

@@ -0,0 +1,37 @@
+/**
+ * Buffer for the exact set of dynamic column names.
+ * setNames() means exactly this dynamic set; attach() applies the saved set; detach() keeps names.
+ * This utility deliberately knows nothing about groups, columnDefs shape, or business names.
+ */
+export function createColumnBuffer() {
+    let names = [];
+    let attachOptions = null;
+    let api = null;
+    function apply() {
+        if (api && attachOptions)
+            attachOptions.apply({ api, names });
+    }
+    function attach(gridApi, opts) {
+        api = gridApi;
+        attachOptions = opts;
+        apply();
+    }
+    function detach() {
+        api = null;
+        attachOptions = null;
+    }
+    function setNames(list) {
+        names = [...new Set(list)];
+        apply();
+    }
+    return {
+        control: { attach, detach },
+        api: {
+            setNames,
+            apply,
+            get names() {
+                return names;
+            },
+        },
+    };
+}

package/lib/common/src/grid/agGrid4/core.d.ts

@@ -9,15 +9,21 @@ export type GridTransaction<T> = {
 };
 /** Minimal grid api contract (the real GridApi is structurally compatible). */
 export type GridApiLike<T> = {
+    /** Used by overlay mode: row ownership belongs to rowData, not to this buffer. */
+    getRowNode?(id: RowId): {
+        data?: T;
+    } | undefined;
     forEachNode(callback: (node: {
         data?: T;
     }) => void): void;
     applyTransaction(tx: GridTransaction<T>): unknown;
     applyTransactionAsync(tx: GridTransaction<T>): void;
 };
+export type GridBufferMode = 'mirror' | 'overlay';
 export type PushOptions = {
     add?: boolean;
     update?: boolean;
+    remove?: boolean;
     /** add+update in one SYNCHRONOUS transaction. Default: add is sync, update is async (batched). */
     sync?: boolean;
 };
@@ -28,23 +34,36 @@ export type UpdateArgs<T> = {
     onlyMemo?: boolean;
     option?: PushOptions;
 };
+export type CleanArgs = {
+    /** Only clear the buffer; do not remove rows from a mirror-owned grid. */
+    onlyMemo?: boolean;
+};
+export type CreateGridBufferOptions<T> = {
+    getId: GetId<T>;
+    /** External buffer (object above the component) survives route remounts. Otherwise use an internal one. */
+    externalBuffer?: BufferTable<T>;
+    /**
+     * mirror (default): the buffer is the source of truth; sync adds, updates and removes grid rows.
+     * overlay: external rowData owns rows; sync only refreshes rows that already exist in the grid.
+     */
+    mode?: GridBufferMode;
+    /** Delivery defaults for updateData, e.g. { add: false } for rowData-owned streaming overlays. */
+    pushDefaults?: PushOptions;
+};
 /**
  * Table core: buffer + delivery to the grid. Lifecycle:
  *  1. updateData at any time: the buffer is always updated, the grid only if attached;
  *  2. attach(api) on onGridReady: sync catches up with everything that arrived earlier;
  *  3. detach() on grid destroy: the core accumulates in the buffer again until the next attach.
  */
-export declare function createGridBuffer<T>(deps: {
-    getId: GetId<T>;
-    /** External buffer (object above the component) survives route remounts. Otherwise use an internal one. */
-    externalBuffer?: BufferTable<T>;
-}): {
+export declare function createGridBuffer<T>(deps: CreateGridBufferOptions<T>): {
     control: {
         attach: (gridApi: GridApiLike<T>) => void;
         detach: () => void;
     };
     api: {
         updateData: (args: UpdateArgs<T>) => void;
+        clean: (args?: CleanArgs) => void;
         sync: () => void;
         getId: GetId<T>;
         buffer: BufferTable<T>;

package/lib/common/src/grid/agGrid4/core.js

@@ -6,7 +6,7 @@
 //    updateData, instead of duplicating buffer/grid branching in the hook;
 //  - in-place row merge (Object.assign), with no new object allocated for each update
 //    (important on streams: less garbage for GC);
-//  - add vs update is decided by a Set of delivered ids, without api.getRowNode per row.
+//  - mirror add vs update is decided by a Set of delivered ids; overlay checks the grid by row id.
 /**
  * Table core: buffer + delivery to the grid. Lifecycle:
  *  1. updateData at any time: the buffer is always updated, the grid only if attached;
@@ -14,10 +14,25 @@
  *  3. detach() on grid destroy: the core accumulates in the buffer again until the next attach.
  */
 export function createGridBuffer(deps) {
-    const { getId } = deps;
+    const { getId, mode = 'mirror', pushDefaults } = deps;
     const buf = deps.externalBuffer ?? {};
     const inGrid = new Set(); // ids already delivered to the grid
     let api = null;
+    function gridHas(id) {
+        if (!api)
+            return false;
+        if (mode == 'mirror')
+            return inGrid.has(id);
+        const node = api.getRowNode?.(id);
+        if (node)
+            return !!node.data;
+        let found = false;
+        api.forEachNode(rowNode => {
+            if (!found && rowNode.data && getId(rowNode.data) == id)
+                found = true;
+        });
+        return found;
+    }
     // --- Buffer ----------------------------------------------------------------
     function upsert(rows) {
         for (const row of rows) {
@@ -36,13 +51,17 @@ export function createGridBuffer(deps) {
                 delete buf[getId(row)];
         if (onlyMemo || !api)
             return;
-        const opt = { add: true, update: true, sync: false, ...option };
+        const opt = { add: true, update: true, remove: true, sync: false, ...pushDefaults, ...option };
         const toAdd = [];
         const toUpdate = [];
+        const seen = new Set();
         for (const row of newData ?? []) {
             const id = getId(row);
+            if (seen.has(id))
+                continue;
+            seen.add(id);
             const merged = buf[id];
-            if (inGrid.has(id))
+            if (gridHas(id))
                 toUpdate.push(merged);
             else
                 toAdd.push(merged);
@@ -53,7 +72,13 @@ export function createGridBuffer(deps) {
         for (const row of add)
             inGrid.add(getId(row));
         // ag-grid finds rows for remove through getRowId, so partial data is enough.
-        const remove = removeData?.filter(row => inGrid.delete(getId(row)));
+        const remove = opt.remove
+            ? removeData?.filter(row => {
+                const id = getId(row);
+                const delivered = inGrid.delete(id);
+                return mode == 'overlay' ? gridHas(id) : delivered;
+            })
+            : undefined;
         if (opt.sync) {
             api.applyTransaction({ add, update, remove });
             return;
@@ -67,10 +92,24 @@ export function createGridBuffer(deps) {
     /**
      * Bring the whole grid in line with the buffer (the buffer is the source of truth).
      * Missing from the buffer -> remove; missing from the grid -> add; everything else -> update.
+     * In overlay mode, rowData is the source of truth, so sync only updates row intersection.
      */
     function sync() {
         if (!api)
             return;
+        if (mode == 'overlay') {
+            const update = [];
+            api.forEachNode(function refresh(node) {
+                if (!node.data)
+                    return;
+                const id = getId(node.data);
+                if (buf[id])
+                    update.push(buf[id]);
+            });
+            if (update.length)
+                api.applyTransaction({ update });
+            return;
+        }
         const add = [];
         const update = [];
         const remove = [];
@@ -94,6 +133,21 @@ export function createGridBuffer(deps) {
         if (add.length || update.length || remove.length)
             api.applyTransaction({ add, update, remove });
     }
+    /** Clear the buffer. In mirror mode, also remove all current grid rows unless onlyMemo is set. */
+    function clean(args = {}) {
+        const remove = [];
+        if (!args.onlyMemo && api && mode == 'mirror') {
+            api.forEachNode(node => {
+                if (node.data)
+                    remove.push(node.data);
+            });
+        }
+        for (const id in buf)
+            delete buf[id];
+        inGrid.clear();
+        if (remove.length)
+            api?.applyTransaction({ remove });
+    }
     // --- Lifecycle -------------------------------------------------------------
     function attach(gridApi) {
         api = gridApi;
@@ -107,7 +161,7 @@ export function createGridBuffer(deps) {
         // for the React binding (or another grid owner)
         control: { attach, detach },
         // public consumer api
-        api: { updateData, sync, getId, buffer: buf },
+        api: { updateData, clean, sync, getId, buffer: buf },
     };
 }
 /** Column comparator: numbers as numbers, empty/NaN values last (respecting inversion). */

package/lib/common/src/grid/agGrid4/gridUtils.d.ts

@@ -0,0 +1,25 @@
+export { numericComparator } from './core';
+export type { NumberPair } from './core';
+/** Centered cells + sort/filter defaults for dense data tables. */
+export declare const colDefCentered: {
+    headerClass: () => string;
+    resizable: true;
+    cellStyle: {
+        textAlign: string;
+    };
+    sortable: true;
+    filter: boolean;
+};
+/** Wrapped text cells for list/selection grids. */
+export declare const colDefWrap: {
+    headerClass: () => string;
+    resizable: true;
+    cellClass: string;
+    cellStyle: {
+        fontFamily: string;
+        fontStyle: string;
+        fontWeight: string;
+        fontSize: string;
+        textAlign: string;
+    };
+};

package/lib/common/src/grid/agGrid4/gridUtils.js

@@ -0,0 +1,17 @@
+import { StyleGridDefault } from '../../styles/styleGrid';
+export { numericComparator } from './core';
+/** Centered cells + sort/filter defaults for dense data tables. */
+export const colDefCentered = {
+    headerClass: () => 'gridTable-header',
+    resizable: true,
+    cellStyle: { textAlign: 'center' },
+    sortable: true,
+    filter: true,
+};
+/** Wrapped text cells for list/selection grids. */
+export const colDefWrap = {
+    headerClass: () => 'gridTable-header',
+    resizable: true,
+    cellClass: 'cell-wrap-text',
+    cellStyle: { ...StyleGridDefault },
+};

package/lib/common/src/grid/agGrid4/index.d.ts

@@ -1,6 +1,10 @@
-export { createGridBuffer, numericComparator } from './core';
-export type { BufferTable, GetId, GridApiLike, GridBufferCore, GridTransaction, NumberPair, PushOptions, RowId, UpdateArgs, } from './core';
+export { createGridBuffer } from './core';
+export type { BufferTable, CleanArgs, CreateGridBufferOptions, GetId, GridApiLike, GridBufferCore, GridBufferMode, GridTransaction, PushOptions, RowId, UpdateArgs, } from './core';
+export { createColumnBuffer } from './columnBuffer';
+export type { ColumnApplyContext, ColumnAttach, ColumnBuffer } from './columnBuffer';
 export { useAgGrid, AgGridMy } from './agGrid4';
 export type { AgGridController, AgGridMyProps, UseAgGridOptions } from './agGrid4';
+export { numericComparator, colDefCentered, colDefWrap } from './gridUtils';
+export type { NumberPair } from './gridUtils';
 export { useAgGridTheme, buildAgTheme } from './theme';
 export type { tThemeMode } from './theme';

package/lib/common/src/grid/agGrid4/index.js

@@ -1,3 +1,5 @@
-export { createGridBuffer, numericComparator } from './core';
+export { createGridBuffer } from './core';
+export { createColumnBuffer } from './columnBuffer';
 export { useAgGrid, AgGridMy } from './agGrid4';
+export { numericComparator, colDefCentered, colDefWrap } from './gridUtils';
 export { useAgGridTheme, buildAgTheme } from './theme';

package/lib/common/src/hooks/index.d.ts

@@ -1,3 +1,4 @@
 export * from './useAddDownAnyKey';
 export * from './useDraggable';
+export * from './useObserveStore';
 export * from './useOutside';

package/lib/common/src/hooks/index.js

@@ -1,3 +1,4 @@
 export * from './useAddDownAnyKey';
 export * from './useDraggable';
+export * from './useObserveStore';
 export * from './useOutside';

package/lib/common/src/hooks/useObserveStore.d.ts

@@ -0,0 +1,105 @@
+import { ObserveAll2 } from "wenay-common2";
+type StoreChange = ObserveAll2.StoreChange;
+type StoreSubOpts = ObserveAll2.StoreSubOpts;
+type StoreSyncOpts = ObserveAll2.StoreSyncOpts;
+type StoreDrain = ObserveAll2.StoreDrain;
+type StoreMask<T> = ObserveAll2.StoreMask<T>;
+type StorePick<T, M> = ObserveAll2.StorePick<T, M>;
+type StoreNode<T> = ObserveAll2.StoreNode<T>;
+type StoreSelection<T, M> = ObserveAll2.StoreSelection<T, M>;
+export type ListenLike<TArgs extends readonly unknown[] = readonly unknown[]> = {
+    on(cb: (...args: TArgs) => void, opts?: {
+        key?: string | symbol;
+        current?: boolean | (() => TArgs | undefined);
+    }): () => void;
+};
+export type UseStoreNodeOptions<T> = StoreSubOpts & {
+    mode?: "get" | "snapshot";
+    fallback?: T;
+};
+export type StoreNodeController<T> = {
+    readonly node: StoreNode<T>;
+    readonly value: T;
+    readonly exists: boolean;
+    readonly path: PropertyKey[];
+    readonly pathString: string;
+    refresh(): void;
+    get(): T;
+    snapshot(): T;
+    has(): boolean;
+    set(value: T): void;
+    replace(value: T): void;
+    update<M extends StoreMask<T>>(mask: M, opts?: StoreSubOpts): StoreSelection<T, M>;
+};
+export declare function useStoreNode<T>(node: StoreNode<T>, options?: UseStoreNodeOptions<T>): StoreNodeController<T>;
+export type UseStoreSelectOptions<TValue> = StoreSubOpts & {
+    fallback?: TValue;
+};
+export type StoreSelectionController<T, M extends StoreMask<T>> = {
+    readonly selection: StoreSelection<T, M>;
+    readonly value: StorePick<T, M>;
+    readonly mask: M;
+    readonly paths: PropertyKey[][];
+    refresh(): void;
+    get(): StorePick<T, M>;
+};
+export type StoreKeysController<T extends object = any> = {
+    readonly node: StoreNode<T>;
+    readonly keys: PropertyKey[];
+    readonly stringKeys: string[];
+    readonly value: T;
+    readonly exists: boolean;
+    refresh(): void;
+    has(key: PropertyKey): boolean;
+    get<K extends keyof T>(key: K): T[K];
+};
+export declare function useStoreKeys<T extends object>(node: StoreNode<T>, options?: Omit<UseStoreNodeOptions<T>, "mode">): StoreKeysController<T>;
+export declare function useStoreSelect<T, M extends StoreMask<T>>(selection: StoreSelection<T, M>, options?: UseStoreSelectOptions<StorePick<T, M>>): StoreSelectionController<T, M>;
+export type RemoteStoreLike<T extends object> = {
+    get(mask?: any): T | Promise<T>;
+    changed: ListenLike<readonly []>;
+    changedPaths?: ListenLike<readonly [StoreChange]>;
+};
+export type UseStoreMirrorOptions<T extends object, M extends StoreMask<T>> = StoreSyncOpts & {
+    mask: M;
+    auto?: boolean;
+};
+export type StoreMirrorController<T extends object, M extends StoreMask<T>> = {
+    readonly store: ObserveAll2.Store<T> & {
+        sync(mask: M, subOpts?: StoreSyncOpts): Promise<() => void>;
+    };
+    readonly value: StorePick<T, M>;
+    readonly selection: StoreSelectionController<T, M>;
+    readonly ready: boolean;
+    readonly syncing: boolean;
+    readonly error: unknown;
+    sync(mask?: M, opts?: StoreSyncOpts): Promise<() => void>;
+    stop(): void;
+};
+export declare function useStoreMirror<T extends object, M extends StoreMask<T>>(remote: RemoteStoreLike<T>, initial: T, options: UseStoreMirrorOptions<T, M>): StoreMirrorController<T, M>;
+export declare function useListenEffect<TArgs extends readonly unknown[]>(listen: ListenLike<TArgs> | null | undefined, cb: (...args: TArgs) => void, opts?: {
+    key?: string | symbol;
+    current?: boolean | (() => TArgs | undefined);
+}): void;
+export type StoreChangedPathsController = {
+    readonly change: StoreChange | undefined;
+    readonly paths: PropertyKey[][];
+    readonly count: number;
+    reset(): void;
+};
+export declare function useStoreChangedPaths(listen: ListenLike<readonly [StoreChange]> | null | undefined, opts?: {
+    initial?: StoreChange;
+    key?: string | symbol;
+}): StoreChangedPathsController;
+export declare function useListenArgs<TArgs extends readonly unknown[]>(listen: ListenLike<TArgs> | null | undefined, opts?: {
+    initial?: TArgs;
+    key?: string | symbol;
+    current?: boolean | (() => TArgs | undefined);
+}): TArgs | undefined;
+export declare function useListenValue<T, TArgs extends readonly unknown[] = readonly [T]>(listen: ListenLike<TArgs> | null | undefined, opts?: {
+    initial?: T;
+    key?: string | symbol;
+    current?: boolean | (() => TArgs | undefined);
+    map?: (...args: TArgs) => T;
+}): T | undefined;
+export type { StoreChange, StoreDrain, StoreMask, StoreNode, StorePick, StoreSelection, StoreSubOpts, StoreSyncOpts };

package/lib/common/src/hooks/useObserveStore.js

@@ -0,0 +1,224 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { ObserveAll2 } from "wenay-common2";
+function readNode(node, options) {
+    if (!node.has())
+        return options?.fallback;
+    return (options?.mode == "snapshot" ? node.snapshot() : node.get());
+}
+function isSameStoreMask(a, b) {
+    if (a === b)
+        return true;
+    if (a === true || b === true)
+        return false;
+    if (!a || !b || typeof a != "object" || typeof b != "object")
+        return false;
+    const keysA = Reflect.ownKeys(a);
+    const keysB = Reflect.ownKeys(b);
+    if (keysA.length != keysB.length)
+        return false;
+    for (const key of keysA) {
+        if (!keysB.includes(key))
+            return false;
+        if (!isSameStoreMask(a[key], b[key]))
+            return false;
+    }
+    return true;
+}
+function useStableStoreMask(mask) {
+    const ref = useRef(mask);
+    if (!isSameStoreMask(ref.current, mask))
+        ref.current = mask;
+    return ref.current;
+}
+function useLatestRef(value) {
+    const ref = useRef(value);
+    ref.current = value;
+    return ref;
+}
+export function useStoreNode(node, options = {}) {
+    const { current, drain, key, mode = "get", fallback } = options;
+    const [version, setVersion] = useState(0);
+    const refresh = useCallback(() => setVersion(v => v + 1), []);
+    useEffect(() => {
+        return node.on(() => refresh(), { current, drain, key });
+    }, [node, current, drain, key, refresh]);
+    const value = useMemo(() => readNode(node, { mode, fallback }), [node, version, mode, fallback]);
+    const exists = useMemo(() => node.has(), [node, version]);
+    return useMemo(() => ({
+        node,
+        value,
+        exists,
+        path: node.path,
+        pathString: node.pathString,
+        refresh,
+        get: () => node.get(),
+        snapshot: () => node.snapshot(),
+        has: () => node.has(),
+        set: (next) => node.set(next),
+        replace: (next) => node.replace(next),
+        update: (mask, opts) => node.update(mask, opts),
+    }), [node, value, exists, refresh]);
+}
+export function useStoreKeys(node, options = {}) {
+    const state = useStoreNode(node, { ...options, mode: "snapshot" });
+    const keys = useMemo(() => {
+        const value = state.value;
+        return value != null && typeof value == "object" ? Reflect.ownKeys(value) : [];
+    }, [state.value]);
+    return useMemo(() => ({
+        node,
+        keys,
+        stringKeys: keys.map(String),
+        value: state.value,
+        exists: state.exists,
+        refresh: state.refresh,
+        has: (key) => state.value != null && typeof state.value == "object" && key in state.value,
+        get: (key) => state.value[key],
+    }), [node, keys, state]);
+}
+export function useStoreSelect(selection, options = {}) {
+    const { current, drain, key, fallback } = options;
+    const [version, setVersion] = useState(0);
+    const refresh = useCallback(() => setVersion(v => v + 1), []);
+    useEffect(() => {
+        return selection.on(() => refresh(), { current, drain, key });
+    }, [selection, current, drain, key, refresh]);
+    const value = useMemo(() => {
+        const next = selection.get();
+        return next === undefined ? fallback : next;
+    }, [selection, version, fallback]);
+    return useMemo(() => ({
+        selection,
+        value,
+        mask: selection.mask,
+        paths: selection.paths,
+        refresh,
+        get: () => selection.get(),
+    }), [selection, value, refresh]);
+}
+export function useStoreMirror(remote, initial, options) {
+    const { mask, auto = true, current = true, drain, key, partial, onError } = options;
+    const stableMask = useStableStoreMask(mask);
+    const syncOptionsRef = useLatestRef({ current, drain, key, partial, onError });
+    const mountedRef = useRef(false);
+    const stopRef = useRef(null);
+    const [ready, setReady] = useState(false);
+    const [syncing, setSyncing] = useState(false);
+    const [error, setError] = useState(null);
+    const storeRef = useRef(null);
+    if (!storeRef.current || storeRef.current.remote !== remote) {
+        storeRef.current = {
+            remote,
+            store: ObserveAll2.createStoreMirror(remote, initial),
+        };
+    }
+    const store = storeRef.current.store;
+    const selectionRaw = useMemo(() => store.update(stableMask), [store, stableMask]);
+    const selection = useStoreSelect(selectionRaw, { drain });
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+            stopRef.current?.();
+            stopRef.current = null;
+        };
+    }, []);
+    const stop = useCallback(() => {
+        stopRef.current?.();
+        stopRef.current = null;
+        if (mountedRef.current)
+            setReady(false);
+    }, []);
+    const sync = useCallback(async (nextMask = stableMask, opts) => {
+        stopRef.current?.();
+        stopRef.current = null;
+        if (mountedRef.current) {
+            setSyncing(true);
+            setError(null);
+        }
+        try {
+            const latest = syncOptionsRef.current;
+            const overrideOnError = opts?.onError;
+            const off = await store.sync(nextMask, {
+                current: latest.current,
+                drain: latest.drain,
+                key: latest.key,
+                partial: latest.partial,
+                ...opts,
+                onError(error) {
+                    if (mountedRef.current)
+                        setError(error);
+                    (overrideOnError ?? syncOptionsRef.current.onError)?.(error);
+                },
+            });
+            stopRef.current = off;
+            if (mountedRef.current)
+                setReady(true);
+            return off;
+        }
+        catch (e) {
+            if (mountedRef.current)
+                setError(e);
+            throw e;
+        }
+        finally {
+            if (mountedRef.current)
+                setSyncing(false);
+        }
+    }, [store, stableMask, syncOptionsRef]);
+    useEffect(() => {
+        if (!auto)
+            return;
+        sync().catch(() => { });
+        return () => {
+            stopRef.current?.();
+            stopRef.current = null;
+        };
+    }, [auto, sync, current, drain, key, partial]);
+    return useMemo(() => ({
+        store,
+        value: selection.value,
+        selection,
+        ready,
+        syncing,
+        error,
+        sync,
+        stop,
+    }), [store, selection, ready, syncing, error, sync, stop]);
+}
+export function useListenEffect(listen, cb, opts) {
+    const cbRef = useRef(cb);
+    cbRef.current = cb;
+    const key = opts?.key;
+    const current = opts?.current;
+    useEffect(() => {
+        if (!listen)
+            return;
+        return listen.on((...args) => cbRef.current(...args), { key, current });
+    }, [listen, key, current]);
+}
+export function useStoreChangedPaths(listen, opts) {
+    const [state, setState] = useState({ change: opts?.initial, count: 0 });
+    useListenEffect(listen, (change) => {
+        setState(prev => ({ change, count: prev.count + 1 }));
+    }, { key: opts?.key });
+    return useMemo(() => ({
+        change: state.change,
+        paths: state.change?.paths ?? [],
+        count: state.count,
+        reset: () => setState({ change: opts?.initial, count: 0 }),
+    }), [state, opts?.initial]);
+}
+export function useListenArgs(listen, opts) {
+    const [value, setValue] = useState(opts?.initial);
+    useListenEffect(listen, (...args) => setValue(args), { key: opts?.key, current: opts?.current });
+    return value;
+}
+export function useListenValue(listen, opts) {
+    const [value, setValue] = useState(opts?.initial);
+    const map = opts?.map;
+    useListenEffect(listen, (...args) => {
+        setValue(map ? map(...args) : args[0]);
+    }, { key: opts?.key, current: opts?.current });
+    return value;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wenay-react2",
-  "version": "1.0.23",
+  "version": "1.0.25",
   "description": "Common react",
   "strict": true,
   "main": "dist/index.js",
@@ -23,7 +23,7 @@
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
     "react-rnd": "^10.5.3",
-    "wenay-common2": "^1.0.52"
+    "wenay-common2": "^1.0.53"
   },
   "peerDependencies": {
     "react": "^19.2.0",