wenay-react2 1.0.40 → 1.0.41

package/doc/wenay-react2.md

@@ -0,0 +1,475 @@
+# wenay-react2 - BRIEF cheat sheet (canonical UI/controller API)
+
+> Root import: `import { ... } from "wenay-react2"`.
+> Notation: `name(args) -> ret`. JSX examples show the intended public path, not every prop.
+> Short controller-style names are canonical. Removed names are recorded in
+> **WENAY_REACT2_RENAMES.md** for migration only; old aliases are not exported.
+
+## Standard
+```
+Hooks that own lifecycle/state return a small controller:
+  api.props / api.bind              // props to spread on an element
+  api.open() / close() / set()      // modal/menu-like state
+  api.update() / remove() / clean() // data buffers
+  api.fit() / flush() / sync()      // ag-grid lifecycle
+
+Components receive controllers when state must outlive the component.
+Library primitives never know app-specific terms, domain objects, or group policy.
+Put app-specific layout/build rules in an app wrapper above the primitive.
+```
+
+## Render Memory
+```
+updateBy(obj) / useUpdateBy(obj)                 // subscribe current component to renderBy(obj)
+renderBy(obj, ms?)                               // emit render for subscribers
+renderByRevers(obj, ms?, reverse?=true)
+renderByLast(obj, ms?)
+
+const state = { count: 0 }
+const api = createUpdateApi(state)
+api.use()                                        // hook subscription
+api.emit(ms?)                                    // renderBy(state)
+api.on(obj => {}) -> off
+
+const api2 = useUpdateByApi(state)               // hook + controller in one call
+```
+
+Persistent process memory:
+```
+memoryGetOrCreate(key, def, {abs?, deepAutoMerge?, reversDeep?}) -> def-or-stored
+memoryGetById(key, def, id) -> stored only while id is the same
+memorySet(key, data)
+memoryGet(key)
+memoryUpdate(key, mutate) -> cur?               // mutate + rerender + announce in one call
+memoryMarkDirty(key)                            // announce an in-place mutation of a memoryGetOrCreate object
+createSearchHistory({key, max?})                 // reusable small persisted search history controller
+memoryMaps                                       // rnd / resize / other maps
+```
+
+Persistence contract (memoryCache): the library NEVER writes storage by itself. The persisted maps
+(floatingWindowMap, mapResiReact, mapRightMenu, memoryProps) are `ObservableMap`s - set/delete/clear
+announce themselves, in-place mutations are announced at the commit points (drag/resize stop,
+menu drag end, setPlace). memoryCache observes the maps it owns; the app owns the write policy:
+```
+memoryCache.load()                                      // once on start; remembers the saved snapshot
+memoryCache.onDirty((scope?, key?) => ...) -> off       // dirty channel (coalesced, async)
+memoryCache.saveDebounced(ms?) / save() / flush()       // write only payloads that differ from the snapshot
+memoryCache.isDirty()                                   // cheap hint, e.g. a beforeunload guard
+
+memoryCache.load()
+const off = memoryCache.onDirty(() => memoryCache.saveDebounced(800))
+document.addEventListener("visibilitychange",
+    () => { if (document.visibilityState == "hidden") void memoryCache.flush() })
+window.addEventListener("pagehide", () => { void memoryCache.flush() })  // backstop: flush is async
+```
+
+## Outside Click / Buttons
+```
+const outside = useOutside({onOutside, enabled?})
+<div {...outside.props} />
+outside.enable()
+outside.disable()
+outside.contains(event.target)
+
+<OutsideClickArea outsideClick={close} status={open}>...</OutsideClickArea>
+
+<Button button={<button>Open</button>} outClick>{...}</Button>
+<OutsideButton button={...}>{...}</OutsideButton>
+<HoverButton button={...}>{...}</HoverButton>
+<AbsoluteButton button={...}>{...}</AbsoluteButton>
+```
+
+## Drag / Floating Windows
+```
+const drag = useDraggableApi({initialPosition, holdMs?, onDragStart?, onDragEnd?})
+<div {...drag.bind} style={{transform: `translate(${drag.position.x}px, ${drag.position.y}px)`}} />
+drag.setPosition({x, y})
+drag.resetPosition()
+drag.cancelDrag()
+
+const r = useReorder({order, commit, move?, canDrag?, preview?, holdMs?})   // mini reorder-by-drag
+<div ref={r.listRef}>{order.map(k => {                                      // children 1:1 with order
+    const it = r.item(k)                                                    // it.dragging / it.active
+    return <div key={k} {...it.props} style={{...own, ...it.style}} />      // ONE commit(next) on drop
+})}</div>
+
+const b = useReorderBoard({columns: [{key, items}], commit,                 // drag between vertical columns
+    canDrag?, holdMs?, onDragStart?, onDragMove?, onOverChange?, onDragEnd?})
+<div ref={b.columnRef('todo')}>{items.map(k => ...b.item(k)...)}</div>      // one div per column, any count
+b.over                                                                      // {col, index} | null - live target
+// column gravity is YOUR CSS: justify-content flex-start packs up, flex-end packs down
+
+<FloatingWindow keyForSave="tool" size={{width: 320, height: 240}} header={<div>Tool</div>}>
+    <Panel />
+</FloatingWindow>
+
+const wnd = useFloatingWindowController({keyForSave: "custom-tool", size: {width: 320, height: 240}})
+wnd.position                 // {x,y}; bind wnd.onHeaderMouseDown/onHeaderTouchStart for custom chrome
+```
+
+## Modal / Input
+```
+<ModalProvider>
+    <App />
+</ModalProvider>
+
+const modal = useModal()
+modal.open(<Dialog />)
+modal.set(<Dialog />)
+modal.close()
+modal(null)                                      // callable shortcut for clearing
+```
+
+Input helpers:
+```
+const text = useTextInputPanel({callback: txt => {}, txt: ""})  // headless value + submit API
+const file = useFileInputPanel({callback: file => {}})          // headless file + submit API
+<TextInputPanel callback={txt => {}} name="Name" txt="" />     // thin visual wrapper over hook
+<FileInputPanel callback={file => {}} name="File" />            // thin visual wrapper over hook
+<TextInputModal callback={...} outClick={modal.close} />
+<FileInputModal callback={...} outClick={modal.close} />
+<FreeModal outClick={modal.close} size={{width: 400, height: 260}}>...</FreeModal>
+```
+
+## Settings Dialog
+```
+<SettingsDialog trigger={<span>settings</span>} sections={[{key, name, render, children?, parentKey?, searchText?, keywords?}]} defaultSection? /> // searchable tree + persisted search history; history closes when search focus leaves
+const settings = useSettingsDialogController({sections, defaultSection?}) // open/search/tree/history/resize actions for custom chrome
+registerSettingsSection({key, name, render, parentKey?, searchText?, keywords?}) -> unregister
+```
+
+## UI Slot
+```
+const slot = createUiSlot({key, places: {top: "Top bar", side: "Sidebar"}, def: "top"})
+
+<slot.Slot place="top">{content}</slot.Slot>     // each mount point decides by itself
+<slot.PlacementSetting />                        // segmented place switcher; setPlace marks memoryCache dirty
+```
+
+## Toolbar
+```
+const tb = createToolbar({key, items: [{key, title, icon?, short?, render?, onClick?, defaultVisible?, fixed?}], def?, settingsItem?, resetItem?, source?, sourceMode?})
+
+<tb.Bar settings reset? />   // the live bar; settings adds a gear; reset is hidden by default; item moves animate
+<tb.Settings />              // the PURE config editor - same element drops into a settings section
+tb.api.useConfig() / getConfig() / setConfig(next) / setOrder(order) / show(key,on) / setDensity(key) / reset()
+tb.api.showSettings(on) / showReset(on)             // pseudo-controls visibility
+tb.api.useItems()            // headless bar: ordered visible [{item, density, content}] - custom markup
+tb.api.onChange.on(cfg => ...) -> off        // fires on every edit
+
+registerToolbarDensity({key, name, renderItem?}) -> unregister   // built-ins: 'icon', 'label'
+toolbarItemIcon(item)        // the item's icon, or its first letters as a text pseudo-icon
+```
+Config `{order, visible, density}` is serializable and persisted like createUiSlot
+(memoryGetOrCreate -> memoryCache, the app owns the write policy). Items added in an app update are merged
+into a stale persisted config (appended, default-visible), removed ones are ignored. `icon` is
+optional: in icon density an icon-less item renders the first letters of its short/title.
+The gear and reset button are pseudo-items: `settingsItem: {title?, icon?}` and `resetItem` re-skin them,
+and the editor has separated toggle rows for them (`visible['__settings']` / `visible['__reset']`, no order slots - they always sit at the bar edge). Settings is visible by default; reset is hidden by default unless `resetItem.defaultVisible: true` or `api.showReset(true)` enables it. `resetItem: false` removes the reset feature.
+
+`source?` makes the toolbar a VIEW over an external `UiListSource`. Default `sourceMode:"orderVisible"`
+means the source owns item order and item visibility, so one config can drive a grid, its icon menu
+AND the toolbar together (`columnState.api.listSource`, QA card 31). `sourceMode:"order"` shares only
+the source-key order; item membership, density, pseudo-controls, and extra non-source item positions
+stay in the toolbar store (QA card 30). Without `source` the toolbar keeps its own store (standalone mode).
+
+## Callback Hub
+```
+const hub = createCallbackHub<[Args]>(emit => api.onX(emit))  // one slot -> many subscribers
+hub.on(cb) -> off
+```
+
+## Params
+```
+<ParamsEditor
+    params={params}
+    onChange={next => setParams(next)}
+    onExpand={next => setParams(next)}
+    expandStatus?
+    expandStatusLvl?
+/>
+
+const controller = useParamsEditorController({params, onChange, onExpand?})
+
+<ParamsEdit params={params} onSave={next => save(next)} />
+<ParamRow name="Name">...</ParamRow>
+```
+
+## Menu
+```
+type MenuItem = { name, actionKey?, onClick?, next?, func?, status? } | false | null | undefined
+
+<Menu data={items} coordinate={{x: 0, y: 0}} />
+
+<contextMenu.Layer>{children}</contextMenu.Layer>
+contextMenu.openAt(event, [{name: "Copy", actionKey: "grid.copy", onClick: copy}], {source: "grid"})
+contextMenu.stats.getSnapshot()   // local counters: opens, source/layer usage, actionTotals, keyed actions
+contextMenu.close()
+```
+
+Use `contextMenu.openAt(e, items, {source?})` for new right-click integrations. `contextMenu.map` still exists as a legacy Layer queue, but it is not the recommended path for new code. `contextMenu.stats` is an in-memory diagnostics API; it never persists data, never reports over the network, and records per-action counters only for explicit `actionKey` values. Unkeyed items are counted in aggregate totals without storing labels.
+
+`Menu` keeps the hovered/open item in internal React state. `status` is only an initial open hint and a compatibility field passed to custom renderers; menu objects are not mutated.
+
+Floating right menu:
+```
+<DropdownMenu elements={items} trigger={iconOrRender} classNames={...} styles={...} />
+const menu = useRightMenuController({elements, keyForSave?})
+```
+
+`DropdownMenu` is a floating action menu with caller-owned trigger/content styling, not the main context-menu primitive. `useRightMenuController` exposes the same open/fixed/select/submenu/drag state for custom views; `DropdownMenu` remains the compatible visual wrapper.
+
+## agGrid4
+Plain declarative rows:
+```
+<AgGridTable<Row> rowData={rows} columnDefs={cols} />
+```
+
+Buffered mirror table:
+```
+const grid = useAgGrid<Row>({getId: row => row.id})
+<AgGridTable<Row> controller={grid} columnDefs={cols} />
+
+grid.update({newData: rows})
+grid.remove([{id}])
+grid.clean()
+grid.fit()
+grid.flush()
+```
+
+Shared module store:
+```
+export const mainTable = createGridBuffer<Row>({getId, externalBuffer})
+
+const grid = useAgGrid({core: mainTable})
+<AgGridTable<Row> controller={grid} columnDefs={cols} />
+```
+
+Overlay patches over React-owned `rowData`:
+```
+const core = createGridBuffer<Row>({getId, mode: "overlay", pushDefaults: {add: false}})
+const grid = useAgGrid({core})
+
+<AgGridTable<Row> controller={grid} rowData={rows} columnDefs={cols} getRowId={p => getId(p.data)} />
+```
+
+Dynamic columns are pure names + lifecycle replay:
+```
+const columns = createColumnBuffer<Row>()
+
+columns.api.setNames(["a", "b"])
+columns.control.attach(api, {
+    apply: ({api, names}) => api.setGridOption("columnDefs", buildColumnDefs(names)),
+})
+columns.api.apply()
+columns.control.detach()
+```
+
+`createColumnBuffer()` knows nothing about groups, `columnDefs`, business names, or where columns live.
+
+
+## columnState
+A persisted column layer over a keyed column set - order / visibility / width / sort / filter in a
+standalone config store, with an OPTIONAL two-way ag-grid adapter. Mobile card views consume the
+SAME config with no ag-grid at all. agGrid4 wrappers are never modified: this is the app-level
+column wrapper `WRAPPER.md` postulates, packaged as a primitive.
+```
+const cs = createColumnState({key, columns: [{key, title, short?, icon?, group?, fixed?, defaultVisible?, cardRole?}], def?, saveMs?})
+
+cs.columns                                       // the descriptors (UI renders from these + config)
+cs.api.useConfig() / getConfig() / setConfig(next) / reset()
+cs.api.show(key, on) / move(order) / setSort({key, dir} | null) / toggleSort(key)   // asc->desc->off
+cs.api.visibleKeys()                             // keys to render, in order (group-gated)
+cs.api.onChange.on(cfg => ...) -> off
+cs.api.usePresent() / isPresent(key) / setPresent(keys | null)   // live-grid presence
+cs.api.getPresentGate() / setPresentGate(keys | null)           // app runtime availability gate, not persisted
+cs.api.listSource                                // {order, visible} slice as a Toolbar `source`
+```
+Config `{v, order, visible, width, sort, filter, groups}` is serializable and persisted like
+createToolbar (memoryGetOrCreate(key) -> memoryCache, the app owns the write policy); a stale config migrates
+softly (unknown keys dropped, new columns appended default-visible, `fixed` pinned). `sort` is
+STICKY: independent of visibility/selection, may point at a hidden or grid-absent column, changes
+only by an explicit toggle/header click.
+
+Two-way ag-grid adapter (opt-in, agGrid4 untouched):
+```
+<AgGridTable columnDefs={cols} autoSizeColumns={false}
+    onGridReady={e => cs.grid.attach(e.api)}          // restore saved layout, then watch the grid
+    onGridPreDestroyed={() => cs.grid.detach()} />     // config survives remounts
+```
+Grid drag/resize/hide/sort/filter fold back into the config; UI edits apply to the grid; a column
+removed from the live grid (dynamic defs) keeps its config entry and reads `isPresent==false`.
+
+Icon menu - a 1:1 grid mirror (reorder in the grid <-> reorder the buttons):
+```
+<ColumnsMenu state={cs} compact? marks? tail? onItem? onTail? reorder? />      // default click = toggle visibility
+<MenuStrip items={[{key, title, state:'on'|'off'|'disabled', marks?, fixed?}]} onItem? onMove? tail? compact? />
+```
+`ColumnsMenu` binds `MenuStrip` - a presentation-only layer that reports clicks/drags but never
+interprets them - to the config. `compact` = icon-only buttons; an item with no icon shows its
+first letters. `tail` = trailing non-column buttons (a table-standards cycler etc.). For new
+settings-integrated toolbar/grid surfaces prefer `createToolbar({source: cs.api.listSource})`;
+keep `ColumnsMenu` for compact button strips or custom presentation-only menus.
+
+Mobile (no ag-grid): dots selector + card rows over the same config:
+```
+<ColumnDots state={cs} max?=8 />                 // track of marks; dots = shown columns; tap empty=add,
+                                                 //   drag=replace, swipe up=remove, tap dot=select, sort button cycles
+<CardList<Row> state={cs} data={rows} getId? renderValue? />   // visible cols -> card fields; cardRole:'title'/'accent'
+```
+QA cards 28 (grid layer + F5 restore), 29 (mobile dots + cards), 30 (toolbar icon menu + grouped sub-column mode button), 31 (Toolbar over the same config).
+
+
+## Observe React Adapter
+`wenay-common2` owns the store/listen/RPC primitives. `wenay-react2` owns React lifecycle hooks around them.
+
+```ts
+import { Observe } from "wenay-common2"
+import { useStoreMirror, useStoreNode, useStoreKeys, useStoreSelect, useStoreChangedPaths, useListenEffect, useListenValue } from "wenay-react2"
+```
+
+Node subscription:
+```
+const price = useStoreNode(store.node.data.BTC)
+price.value
+price.exists
+price.replace(123)
+price.refresh()
+```
+
+Selection subscription:
+```
+const sel = useStoreSelect(store.update({data: {BTC: true}, meta: {status: true}}))
+sel.value
+sel.get()
+```
+
+Network mirror is explicit:
+```
+const mirror = useStoreMirror(remoteStore, {data: {}, meta: {}}, {
+    mask: {data: {BTC: true}, meta: {status: true}},
+    current: true,
+    drain: 250,
+})
+
+mirror.value
+mirror.ready
+mirror.sync()
+mirror.stop()
+```
+
+Per-key feed (`store.each()` of common2 — one cb per CHANGED top-level key):
+```
+useStoreEach(store, (key, value, ctx) => {
+    value === undefined ? removeRow(key) : upsertRow(key, value)
+}, {enabled?})
+```
+`undefined` = key deleted; a root replace (store.replace / mirror keyframe) expands into one call per key. The fold target should live outside React state (ref/Map/grid api) — the hook renders nothing itself. The wire counterpart is `useStoreReplayEach` below.
+
+Listen helpers:
+```
+useListenEffect(listen, (...args) => {})
+const value = useListenValue(listen, {initial})
+const args = useListenArgs(listen)
+```
+
+The hook does not choose transport. `remoteStore` needs `{ get(mask?), changed }` and may also provide `changedPaths`; apps may implement it with RPC, WebSocket, SSE, or test HTTP. `changedPaths` is used as a transport optimization: mirror pulls `mask ∩ paths` instead of the whole mask. `initial` is only the local mirror seed; changing it does not reset an existing mirror. `mask` is treated as a small declarative StoreMask, so structurally equal inline masks do not resubscribe. For add/delete keys, subscribe to the parent object node with `useStoreKeys(node)`; this also covers deep objects. If a state key conflicts with StoreNode methods such as `count`, use `store.node.at("count")`.
+
+## Replay React Adapter
+Client-side hooks over the wenay-common2 Replay stack (snapshot + sequenced delta line). Server parts (`conflateReplay`, `archiveReplay`, `createRpcServerAuto` replayOpts) are per-connection and stay hook-free by design.
+
+```ts
+import { useReplaySubscribe, useReplayRouteSubscribe, useStoreReplaySync, useStoreReplayMirror, useStoreReplayRouteSync, useStoreReplayRouteMirror, useStoreReplayEach, useReplayFrame, useReplayHistory } from "wenay-react2"
+
+// any replay line ({line, since, keyframe, frame?, frameLine?} remote)
+const sub = useReplaySubscribe(remote, (frame) => draw(frame), {onSeq?, onError?, since?, enabled?, staleMs?, onStale?, policy?, hint?})
+sub.ready; sub.error; sub.seq(); sub.restart()
+sub.stale; sub.lastTs()   // freshness (needs staleMs): stale re-renders on fresh<->stale transitions ONLY; lastTs() is a getter like seq()
+// policy: 'queue' (default, nothing skipped) | 'frame' (rides the server frameLine when present: on lag the
+// server drops and recovers with a mini-frame; old servers/in-proc degrade to 'queue'). hint -> the line's frame condenser.
+
+// explicit route hand-off over the same logical replay line (relay <-> direct, etc.)
+const routed = useReplayRouteSubscribe(relayRemote, (frame) => draw(frame), {label: "relay", onRoute?})
+await routed.switchRoute(directRemote, {label: "direct"})
+routed.ready; routed.switching; routed.route; routed.seq(); routed.label(); routed.active()
+// route hooks do not expose stale/lastTs yet; use non-route hooks when freshness is required.
+// store patch line (Observe.exposeStoreReplay(...).api.replay)
+const mirror = useStoreReplayMirror(remote, initial, {enabled?})   // creates the mirror store; same staleMs/stale/policy surface
+mirror.store; mirror.ready; mirror.seq(); mirror.restart()
+const sync = useStoreReplaySync(existingStore, remote)              // same, store supplied by the app
+const routedSync = useStoreReplayRouteSync(existingStore, relayRemote, {label: "relay"})   // same store, switchRoute() replaces the route after catch-up
+const routedMirror = useStoreReplayRouteMirror(relayRemote, initial, {label: "relay"}) // mirror store + route hand-off controller
+
+// per-key fold over the same line (Observe.syncStoreReplayEach counterpart): cb per CHANGED top-level key,
+// first delivery = keyframe expanded per key, (key, undefined) = deleted — grid rows without special cases
+const feed = useStoreReplayEach<Rows>(remote, (key, row) => row === undefined ? removeRow(key) : upsertRow(key, row), {drain?, initial?})
+feed.store; feed.ready; feed.stale; feed.seq(); feed.restart()      // same controller surface as the mirror
+// the mirror store lives in a ref: in-mount resubscribes (StrictMode/restart/enabled) reconnect by tail ON TOP of
+// kept state — the consumer sees only the diff. After a full unmount: {since: prev.seq(), initial: prev.store.snapshot()}
+
+// pull at YOUR pace (frame model): timer around remote.frame(seq, hint) — server condenses, no backlog, no live socket sub
+const pf = useReplayFrame(remote, (quote) => apply(quote), {intervalMs: 500, hint?})
+pf.ready; pf.error; pf.seq(); pf.pull(); pf.restart()               // error (e.g. sacred line evicted) STOPS pulling until restart()
+
+// time machine over Replay.openHistory(storage, live?)
+const tt = useReplayHistory(history, (frame) => draw(frame), {head: () => replay.head()})
+tt.live; tt.seq; tt.head; tt.pause(); tt.play(); tt.seek({seq})
+```
+
+Contract: `off()` on unmount, StrictMode-safe; seq survives resubscribes inside one mount (keepSeq, default on) — a resubscribe reconnects with `{since}` and gets the journal tail, not a keyframe. Across a FULL unmount/remount keep the position outside via `onSeq` and pass it back as `since`. `seq()` is a getter — high-frequency lines (video frames, ticks) do not re-render per event; draw to canvas via ref, bypassing VDOM. Freshness: detection lives in wenay-common2 (`staleMs` watchdog); the non-route hooks mirror its edge-triggered `onStale` into `stale`, so a fresh 100 ev/s line causes zero extra renders. Route hand-off is explicit through `switchRoute(nextRemote, {label?, since?, reset?, policy?, hint?})`: old route stays live while the replacement catches up by `seq`, then closes. `useReplayHistory` is archive playback — staleness does not apply. QA cards 23 (video line + conflation + time travel + freshness), 24 (store sync), 25 (per-key feed), and 26 (route hand-off) are the live examples.
+
+## Logs
+```
+logsApi.addLogs({id: "api", time: new Date(), txt: "done", var: 1})
+<logsApi.React.Message />
+<logsApi.React.PageLogs />
+<logsApi.React.Setting />
+
+const customLogs = getLogsApi<MyFields>({limitPer: 500, limit?: 50, varMin?: 0})
+const headless = createLogsController<MyFields>({options: {limitPer: 500, limit: 50}})
+
+const messageNotifications = useMessageEventLogsController({maxVisible: 4})
+<MessageEventLogsView controller={messageNotifications} zIndex={80} />
+
+const contextTable = useLogsTableController()
+const contextNotifications = useLogsNotificationsController()
+
+const mini = useMiniLogsTable({data: rows, onClick: e => console.log(e.data)})
+<AgGridTable {...mini.props} />
+<MiniLogsTable data={rows} />
+```
+
+Logger notification/tabs chrome uses `--logs-*` CSS variables; apps can theme it without forking logger components. `createLogsController` owns the headless append/limit/settings state for custom integrations. `useMessageEventLogsController` owns the global notification queue/timers/settings, `MessageEventLogsView` draws it, and `MessageEventLogs` / `logsApi.React.Message` remain compatibility wrappers. `MiniLogs` remains the compatibility wrapper; new compact-table code can use `useMiniLogsTable` or `MiniLogsTable`.
+
+## Styles / Theme
+```
+tokens.color.bgDark
+tokens.menu.outlineColor
+tokens.logs.notificationAccent
+tokens.zIndex.modal
+
+GridStyleDefault()                               // inject legacy grid CSS vars/classes
+StyleGridDefault                                 // common ag-grid style object
+buildAgTheme("dark" | "light")
+useAgGridTheme("dark" | "light")
+colDefCentered / colDefWrap / numericComparator
+```
+
+Shared CSS variables include `--menu-outline-color`, `--logs-*`, `--dlg-*`, `--wnd-*`, `--tb-*`, `--cols-menu-*`, `--cols-dots-*`, and `--cols-card-*`.
+
+## Charts
+```
+<MyChartEngine style={{height: 400}} />
+createChartCanvas(config) -> canvas controller
+```
+
+The chart engine surface is still mostly low-level. Keep product-specific chart wrappers in the app.
+
+## QA Stand
+```
+npm run testReact                                // http://localhost:3010/
+```
+
+The stand lives in `src/common/testUseReact/qa.tsx`. Use it for visual checks; agGrid4 overlay/dynamic-column demos are dedicated QA cards.
+Two tabs: Active checks (current work) and Verified archive (`#archive`) - verified/fixed cards move
+there and stay runnable for regression re-checks.

package/lib/common/src/logs/logs.d.ts

@@ -1,3 +1,4 @@
+import React from "react";
 import { getSettingLogs, type LogEntry, type LogsApiOptions } from "./logsController";
 export { createLogsController, createLogsControllerState, getSettingLogs, } from "./logsController";
 export type { CreateLogsControllerOptions, LogsApiOptions, LogsController, LogsControllerState, LogsFullState, LogsMiniState, } from "./logsController";
@@ -38,6 +39,32 @@ declare function InputSettingLogs({}: {
 export declare function PageLogs({ update }: {
     update?: number;
 }): import("react/jsx-runtime").JSX.Element;
+export type MessageEventLogsItem = {
+    key: string;
+    logs: LogEntry;
+};
+export type UseMessageEventLogsControllerOptions = {
+    maxVisible?: number;
+};
+export type MessageEventLogsController = {
+    show: boolean;
+    setShow(value: boolean): void;
+    toggleShow(): void;
+    notifications: MessageEventLogsItem[];
+    visibleNotifications: MessageEventLogsItem[];
+    maxVisible: number;
+};
+export type MessageEventLogsViewProps = {
+    controller: MessageEventLogsController;
+    zIndex?: number;
+    className?: string;
+    style?: React.CSSProperties;
+};
+export declare function MessageEventLogCard({ logs }: {
+    logs: LogEntry;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useMessageEventLogsController(options?: UseMessageEventLogsControllerOptions): MessageEventLogsController;
+export declare function MessageEventLogsView({ controller, zIndex, className, style }: MessageEventLogsViewProps): import("react/jsx-runtime").JSX.Element;
 export declare function MessageEventLogs({ zIndex }: {
     zIndex?: number;
 }): import("react/jsx-runtime").JSX.Element;

package/lib/common/src/logs/logs.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useEffect, useRef } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { copyToClipboard, Params, timeLocalToStr_hhmmss } from "wenay-common2";
 import { renderBy, updateBy } from "../../updateBy";
 import { contextMenu } from "../menu/menuMouse";
@@ -153,7 +153,7 @@ export function PageLogs({ update }) {
     }, [true]);
     return _jsx(Main, {});
 }
-function Message({ logs }) {
+export function MessageEventLogCard({ logs }) {
     return _jsxs("div", { className: "testAnime", style: { width: "200px", color: logStyleTokens.text, height: "auto", marginTop: "10px", borderRight: `5px solid ${logStyleTokens.accent}`, background: logSeverityBackground(logs.var) }, children: [_jsx("p", { style: { textAlign: "center", fontSize: "10px", marginBottom: "1px" }, children: "notification" }), _jsx("hr", { style: {
                     backgroundImage: logDividerGradient(),
                     border: 0,
@@ -161,35 +161,84 @@ function Message({ logs }) {
                     margin: "0 0 0 0",
                     boxSizing: "content-box",
                     display: "block"
-                } }), _jsx("div", { style: { textAlign: "right", marginRight: "10px", height: "auto", overflowWrap: "break-word", textOverflow: "ellipsis" }, children: typeof logs.txt == "object" ? JSON.stringify(logs.txt) : logs.txt }), _jsx("p", { style: { float: "inline-end", textAlign: "right", marginRight: "10px" }, children: (new Date()).toLocaleDateString() })] });
+                } }), _jsx("div", { style: { textAlign: "right", marginRight: "10px", height: "auto", overflowWrap: "break-word", textOverflow: "ellipsis" }, children: typeof logs.txt == "object" ? JSON.stringify(logs.txt) : logs.txt }), _jsx("p", { style: { float: "inline-end", textAlign: "right", marginRight: "10px" }, children: (new Date(logs.time)).toLocaleDateString() })] });
 }
-const tt = {};
-let r = 0;
-export function MessageEventLogs({ zIndex }) {
+export function useMessageEventLogsController(options = {}) {
     const setting = memoryGetOrCreate("settingLogs", settingLogs);
-    updateBy(tt);
-    updateBy(datumMiniConst, () => {
-        const last = datumMiniConst.last[0];
-        if (!last)
+    const maxVisible = Math.max(1, options.maxVisible ?? 10);
+    const [notifications, setNotifications] = useState([]);
+    const counterRef = useRef(0);
+    const lastLogRef = useRef(null);
+    const timersRef = useRef(new Map());
+    updateBy(setting);
+    const addNotification = useCallback((last) => {
+        if ((last.var ?? 0) < (setting.params.minVarMessage ?? 0))
             return;
-        if (setting.params.minVarMessage && (!last.var || last.var < setting.params.minVarMessage))
+        const key = String(counterRef.current++);
+        const item = { key, logs: last };
+        const displayMs = (setting.params.timeShow ? setting.params.timeShow : 2) * 1000;
+        setNotifications(prev => [item, ...prev]);
+        const timer = setTimeout(() => {
+            timersRef.current.delete(key);
+            setNotifications(prev => prev.filter(e => e.key !== key));
+        }, displayMs);
+        timersRef.current.set(key, timer);
+    }, [setting]);
+    const onMiniChange = useCallback(() => {
+        const last = datumMiniConst.last[0];
+        if (!last || last === lastLogRef.current)
             return;
-        let key = String(r++);
-        tt[key] = _jsx("div", { className: "example-exit", children: _jsx(Message, { logs: last }) }, key);
-        setTimeout(() => {
-            if (tt[key]) {
-                delete tt[key];
-                renderBy(tt, 100);
-            }
-        }, setting.params.timeShow ? setting.params.timeShow * 1000 : 2000);
-        renderBy(tt);
-    });
-    const tr = [...Object.values(tt)].reverse().slice(0, 10);
-    return _jsxs("div", { style: { maxHeight: "50vh", position: "absolute", right: "1px", zIndex }, children: [_jsx("div", { onClick: () => { setting.params.show = !setting.params.show; renderBy(tt); }, style: { margin: 3, padding: 3, right: 0, position: "absolute", zIndex: 120,
-                    ...setting.params.show ?
-                        { background: logStyleTokens.toggleBg, fontSize: "25px" } :
-                        { background: logStyleTokens.toggleOffBg }
-                }, children: setting.params.show ? "X" : "log" }), _jsx("div", { children: setting.params.show ? tr : null })] });
+        lastLogRef.current = last;
+        addNotification(last);
+    }, [addNotification]);
+    updateBy(datumMiniConst, onMiniChange);
+    useEffect(() => () => {
+        timersRef.current.forEach(clearTimeout);
+        timersRef.current.clear();
+    }, []);
+    const setShow = useCallback((value) => {
+        setting.params.show = value;
+        renderBy(setting);
+    }, [setting]);
+    const toggleShow = useCallback(() => {
+        setShow(!setting.params.show);
+    }, [setShow, setting]);
+    return useMemo(() => ({
+        show: Boolean(setting.params.show),
+        setShow,
+        toggleShow,
+        notifications,
+        visibleNotifications: notifications.slice(0, maxVisible),
+        maxVisible,
+    }), [maxVisible, notifications, setShow, setting.params.show, toggleShow]);
+}
+export function MessageEventLogsView({ controller, zIndex, className, style }) {
+    const toggleTitle = controller.show ? "Hide log notifications" : "Show log notifications";
+    const toggleStyle = {
+        position: "absolute",
+        right: 0,
+        top: 0,
+        zIndex: 120,
+        minWidth: controller.show ? 24 : 42,
+        height: 24,
+        padding: controller.show ? 0 : "0 8px",
+        border: `1px solid ${logStyleTokens.accent}`,
+        borderRadius: 999,
+        background: controller.show ? logStyleTokens.toggleBg : logStyleTokens.toggleOffBg,
+        color: logStyleTokens.text,
+        cursor: "pointer",
+        display: "inline-flex",
+        alignItems: "center",
+        justifyContent: "center",
+        fontSize: controller.show ? 18 : 12,
+        lineHeight: 1,
+        boxShadow: "0 2px 8px rgba(0, 0, 0, 0.35)",
+    };
+    return _jsxs("div", { className: className, style: { maxHeight: "50vh", position: "absolute", right: "1px", zIndex, ...style }, children: [_jsx("button", { type: "button", "aria-label": toggleTitle, title: toggleTitle, onClick: controller.toggleShow, style: toggleStyle, children: controller.show ? "\u00d7" : "log" }), _jsx("div", { children: controller.show ? controller.visibleNotifications.map(e => (_jsx("div", { className: "example-exit", children: _jsx(MessageEventLogCard, { logs: e.logs }) }, e.key))) : null })] });
+}
+export function MessageEventLogs({ zIndex }) {
+    const controller = useMessageEventLogsController();
+    return _jsx(MessageEventLogsView, { controller: controller, zIndex: zIndex });
 }
 const defPageBase = {
     keyPage: "PageLogs"