wenay-react2 1.0.33 → 1.0.34

package/lib/common/api.d.ts

@@ -27,6 +27,7 @@ export * from "./src/components/Modal";
 export * from "./src/components/Menu";
 export * from "./src/components/Settings";
 export * from "./src/components/UiSlot";
+export * from "./src/components/Toolbar";
 export { MenuBase, TimeNum, MenuElement as LegacyMenuElement } from "./src/menu/menu";
 export type { tMenuReact, tMenuReactStrictly } from "./src/menu/menu";
 export * from "./src/menu/menuMouse";

package/lib/common/api.js

@@ -40,6 +40,9 @@ export * from "./src/components/Menu";
 // 11b. Settings dialog + section registry; UI slot with configurable placement
 export * from "./src/components/Settings";
 export * from "./src/components/UiSlot";
+// 11c. Customizable toolbar (createToolbar): config persisted like createUiSlot,
+// pure Settings editor works both in the bar's gear popover and in a settings section
+export * from "./src/components/Toolbar";
 // 12. MENU - depends on components
 export { MenuBase, TimeNum, MenuElement as LegacyMenuElement } from "./src/menu/menu";
 export * from "./src/menu/menuMouse";

package/lib/common/src/components/Toolbar/Toolbar.d.ts

@@ -0,0 +1,105 @@
+import React from 'react';
+/** createToolbar - a customizable, self-describing toolbar primitive.
+ *  Three decoupled layers: config (plain serializable data, persisted via
+ *  staticProps -> Cash, same mechanics as createUiSlot), Bar (renders visible
+ *  items in config order at config density) and Settings (a pure editor that
+ *  only reads/writes config) - so the SAME Settings element works both in the
+ *  Bar's own gear popover and in a global settings section.
+ *  v1 non-goals: no overflow/"more" menu (an overflow hook would live in Bar,
+ *  right after the visible-items map), no grouping, no cross-bar drag. */
+export type tToolbarItem = {
+    /** stable id (persist key) */
+    key: string;
+    /** full human name - shown in the Settings list */
+    title: string;
+    /** short caption for 'label' density (falls back to title) */
+    short?: string;
+    /** compact glyph/icon for 'icon' density */
+    icon: React.ReactNode;
+    /** full custom render; default = icon [+ short] by the density registry */
+    render?: (density: string) => React.ReactNode;
+    /** convenience for plain action buttons; interactive items can also handle clicks inside render() */
+    onClick?: (e: React.MouseEvent) => void;
+    /** default true */
+    defaultVisible?: boolean;
+    /** cannot be hidden or reordered (pinned to its index in opts.items) */
+    fixed?: boolean;
+};
+export type tToolbarConfig = {
+    /** item keys, display order */
+    order: string[];
+    visible: {
+        [key: string]: boolean;
+    };
+    /** a key from the density registry ('icon' | 'label' | registered extras) */
+    density: string;
+};
+export type tToolbarDensity = {
+    key: string;
+    /** human name for the Settings segmented control */
+    name: string;
+    /** how one item renders at this density; absent = icon + (short ?? title) */
+    renderItem?: (item: tToolbarItem) => React.ReactNode;
+};
+/** Register an extra density level. Re-register with the same key replaces the
+ *  previous one. The returned function removes exactly this registration. */
+export declare function registerToolbarDensity(d: tToolbarDensity): () => void;
+/** Current density registry (built-ins + registered). */
+export declare function getToolbarDensities(): readonly tToolbarDensity[];
+export declare function createToolbar(opts: {
+    /** persistence key (staticProps -> Cash), like createUiSlot */
+    key: string;
+    /** item descriptors; the config only ever references them by key */
+    items: tToolbarItem[];
+    /** defaults; missing fields are derived from items */
+    def?: Partial<tToolbarConfig>;
+    /** the gear button's face: icon/title default to a plain gear svg. The gear
+     *  renders only when Bar mounts with settings, AND visible['__settings'] is
+     *  not false - the Settings editor shows a separated toggle row for it. */
+    settingsItem?: {
+        title?: string;
+        icon?: React.ReactNode;
+    };
+}): {
+    Bar: (p?: {
+        className?: string;
+        settings?: boolean;
+        popAlign?: "left" | "right";
+    }) => import("react/jsx-runtime").JSX.Element;
+    Settings: (p?: {
+        className?: string;
+        activeClassName?: string;
+    }) => import("react/jsx-runtime").JSX.Element;
+    api: {
+        useConfig: () => tToolbarConfig;
+        useItems: () => {
+            item: tToolbarItem;
+            density: string;
+            content: string | number | bigint | boolean | Iterable<React.ReactNode> | Promise<string | number | bigint | boolean | React.ReactPortal | React.ReactElement<unknown, string | React.JSXElementConstructor<any>> | Iterable<React.ReactNode> | null | undefined> | import("react/jsx-runtime").JSX.Element | null | undefined;
+        }[];
+        getConfig: () => tToolbarConfig;
+        setConfig: (next: tToolbarConfig) => void;
+        reset: () => void;
+        onChange: {
+            func: import("wenay-common2").Listener<[tToolbarConfig]>;
+            isRun: () => boolean;
+            run: () => void;
+            close: () => void;
+            eventClose: (cb: () => void) => () => void;
+            onClose: (cb: () => void) => () => void;
+            removeEventClose: (cb: () => void) => void;
+            on: import("wenay-common2").ListenOn<[tToolbarConfig]>;
+            off: (k: import("wenay-common2").Listener<[tToolbarConfig]> | (string | symbol) | null) => void;
+            addListen: (cb: import("wenay-common2").Listener<[tToolbarConfig]>, opts?: {
+                cbClose?: () => void;
+                key?: string | symbol;
+            }) => () => void;
+            removeListen: (k: import("wenay-common2").Listener<[tToolbarConfig]> | (string | symbol) | null) => void;
+            once: (cb: import("wenay-common2").Listener<[tToolbarConfig]>, opts?: {
+                key?: string | symbol;
+            }) => () => void;
+            count: () => number;
+            readonly getAllKeys: (string | symbol)[];
+        };
+    };
+};

package/lib/common/src/components/Toolbar/Toolbar.js

@@ -0,0 +1,210 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { useState } from 'react';
+import { UseListen } from 'wenay-common2';
+import { renderBy, updateBy } from '../../../updateBy';
+import { staticGetAdd, staticMarkDirty } from '../../utils/mapMemory';
+import { DivOutsideClick } from '../../hooks/useOutside';
+import { useReorder } from '../../hooks/useReorder';
+// Module singleton (closure + updateBy subscription, no React context) - same
+// pattern as the settings-section registry. Two built-in levels; a third
+// ("full" text etc.) is just one more registration.
+const densities = { list: [
+        { key: 'icon', name: 'Icons', renderItem: itemIconOnly },
+        { key: 'label', name: 'Icons + labels' },
+    ] };
+function itemIconOnly(item) {
+    return item.icon;
+}
+/** Register an extra density level. Re-register with the same key replaces the
+ *  previous one. The returned function removes exactly this registration. */
+export function registerToolbarDensity(d) {
+    const i = densities.list.findIndex(e => e.key == d.key);
+    if (i == -1)
+        densities.list.push(d);
+    else
+        densities.list.splice(i, 1, d);
+    renderBy(densities);
+    return function offToolbarDensity() {
+        const j = densities.list.indexOf(d);
+        if (j != -1) {
+            densities.list.splice(j, 1);
+            renderBy(densities);
+        }
+    };
+}
+/** Current density registry (built-ins + registered). */
+export function getToolbarDensities() {
+    return densities.list;
+}
+function itemContent(item, densityKey) {
+    if (item.render)
+        return item.render(densityKey);
+    const d = densities.list.find(e => e.key == densityKey);
+    if (d?.renderItem)
+        return d.renderItem(item);
+    return _jsxs(_Fragment, { children: [_jsx("span", { className: 'wenayTbIcon', children: item.icon }), _jsx("span", { className: 'wenayTbLabel', children: item.short ?? item.title })] });
+}
+/** Reserved visible-map key for the bar's settings (gear) button: not part of
+ *  order (the gear always sits at the bar edge), but toggleable like an item. */
+const SETTINGS_KEY = '__settings';
+export function createToolbar(opts) {
+    const defConfig = () => ({
+        order: opts.def?.order?.slice() ?? opts.items.map(i => i.key),
+        visible: opts.def?.visible ? { ...opts.def.visible } : Object.fromEntries(opts.items.map(i => [i.key, i.defaultVisible != false])),
+        density: opts.def?.density ?? densities.list[0].key,
+    });
+    const st = staticGetAdd(opts.key, defConfig());
+    const [emitChange, onChange] = UseListen();
+    /** The persisted state may be stale or partial (older app version, removed
+     *  items, an unregistered density) - never crash, never drop user data that
+     *  still applies: unknown keys are filtered out, missing items are appended
+     *  (default-visible), fixed items are pinned back to their descriptor index. */
+    function normalize() {
+        const known = new Set(opts.items.map(i => i.key));
+        const rawOrder = Array.isArray(st.order) ? st.order : [];
+        const order = rawOrder.filter(k => known.has(k) && !opts.items.find(i => i.key == k)?.fixed);
+        for (const it of opts.items)
+            if (!it.fixed && order.indexOf(it.key) == -1)
+                order.push(it.key);
+        opts.items.forEach(function pinFixed(it, i) {
+            if (it.fixed)
+                order.splice(Math.min(i, order.length), 0, it.key);
+        });
+        const rawVisible = st.visible && typeof st.visible == 'object' ? st.visible : {};
+        const visible = {};
+        for (const it of opts.items)
+            visible[it.key] = it.fixed ? true : (rawVisible[it.key] ?? it.defaultVisible != false);
+        visible[SETTINGS_KEY] = typeof rawVisible[SETTINGS_KEY] == 'boolean' ? rawVisible[SETTINGS_KEY] : true;
+        const density = typeof st.density == 'string' && densities.list.some(d => d.key == st.density)
+            ? st.density : (opts.def?.density ?? densities.list[0].key);
+        return { order, visible, density };
+    }
+    /** Every edit funnels through here: mutate the persisted object in place
+     *  (identity is the updateBy/renderBy subscription key), announce, mark the
+     *  cache dirty, emit outward. */
+    function setConfig(next) {
+        st.order = next.order.slice();
+        st.visible = { ...next.visible };
+        st.density = next.density;
+        renderBy(st);
+        staticMarkDirty(opts.key);
+        emitChange(normalize());
+    }
+    const getConfig = () => normalize();
+    function useConfig() {
+        updateBy(st);
+        return normalize();
+    }
+    /** Headless bar: the ordered, visibility-filtered items plus their rendered
+     *  content at the current density - build fully custom bar markup on top,
+     *  while the same Settings editor still drives order/visibility/density.
+     *  (Refs are the wrong contract here: the ORDER lives in the config, so the
+     *  consumer re-renders from this list rather than the library re-parenting
+     *  someone else's nodes.) */
+    function useItems() {
+        updateBy(st);
+        updateBy(densities);
+        const cfg = normalize();
+        const byKey = new Map(opts.items.map(i => [i.key, i]));
+        return cfg.order
+            .map(k => byKey.get(k))
+            .filter((it) => !!it && cfg.visible[it.key] != false)
+            .map(it => ({ item: it, density: cfg.density, content: itemContent(it, cfg.density) }));
+    }
+    const reset = () => setConfig(defConfig());
+    const settingsTitle = () => opts.settingsItem?.title ?? 'Toolbar settings';
+    const settingsIcon = () => opts.settingsItem?.icon ??
+        _jsx("svg", { width: '14', height: '14', viewBox: '0 0 16 16', "aria-hidden": 'true', children: _jsx("path", { d: 'M8 5.2 A2.8 2.8 0 1 0 8 10.8 A2.8 2.8 0 1 0 8 5.2 M8 1.2 L8.6 3.4 A4.8 4.8 0 0 1 10.6 4.2 L12.8 3.2 L14 5.6 L12.2 7 A4.8 4.8 0 0 1 12.2 9 L14 10.4 L12.8 12.8 L10.6 11.8 A4.8 4.8 0 0 1 8.6 12.6 L8 14.8 L7.4 12.6 A4.8 4.8 0 0 1 5.4 11.8 L3.2 12.8 L2 10.4 L3.8 9 A4.8 4.8 0 0 1 3.8 7 L2 5.6 L3.2 3.2 L5.4 4.2 A4.8 4.8 0 0 1 7.4 3.4 Z', fill: 'none', stroke: 'currentColor', strokeWidth: '1.2', strokeLinejoin: 'round' }) });
+    function moveKey(cfg, key, to) {
+        const order = cfg.order.slice();
+        const from = order.indexOf(key);
+        if (from == -1)
+            return;
+        to = Math.max(0, Math.min(order.length - 1, to));
+        if (to == from)
+            return;
+        order.splice(from, 1);
+        order.splice(to, 0, key);
+        setConfig({ ...cfg, order });
+    }
+    /** The live bar. settings=true adds a built-in gear opening Settings in a
+     *  local popover - optional, some consumers mount Settings only in the
+     *  global settings menu. popAlign: which bar edge the popover sticks to -
+     *  'right' (default, for bars in a top-right corner) or 'left'. */
+    function Bar(p = {}) {
+        updateBy(st);
+        updateBy(densities);
+        const cfg = normalize();
+        const [open, setOpen] = useState(false);
+        const byKey = new Map(opts.items.map(i => [i.key, i]));
+        return _jsxs("div", { className: p.className ?? 'wenayTb', children: [cfg.order.map(k => {
+                    const it = byKey.get(k);
+                    if (!it || cfg.visible[k] == false)
+                        return null;
+                    return _jsx("div", { className: 'wenayTbItem', title: cfg.density == 'icon' ? it.title : undefined, onClick: it.onClick, children: itemContent(it, cfg.density) }, k);
+                }), p.settings && cfg.visible[SETTINGS_KEY] != false && _jsxs(DivOutsideClick, { className: 'wenayTbGear', status: open, outsideClick: () => setOpen(false), children: [_jsx("div", { className: 'wenayTbItem', title: settingsTitle(), onClick: () => setOpen(v => !v), children: settingsIcon() }), open && _jsx("div", { className: p.popAlign == 'left' ? 'wenayTbPop wenayTbPopLeft' : 'wenayTbPop', children: _jsx(Settings, {}) })] })] });
+    }
+    /** The pure editor over config: density segments + one row per item
+     *  (visibility checkbox, icon preview, title, drag handle). Reorder rides the
+     *  library's useReorder (this editor is its first consumer): the whole row
+     *  drags (mouse and touch; the checkbox is excluded), and `move` is the SAME
+     *  simulated commit as normalize() (splice + fixed pinning), so fixed rows
+     *  never move in the preview and a drop never lands elsewhere than shown.
+     *  Plus arrow keys on the focused handle; fixed rows have neither. */
+    function Settings(p = {}) {
+        updateBy(st);
+        updateBy(densities);
+        const cfg = normalize();
+        const base = p.className ?? 'wenaySegBtn';
+        const activeCls = p.activeClassName ?? 'wenaySegBtnActive';
+        const byKey = new Map(opts.items.map(i => [i.key, i]));
+        /** Simulated commit: splice + the same fixed pinning as normalize(). */
+        function movedOrder(order, key, to) {
+            const next = order.slice();
+            const from = next.indexOf(key);
+            if (from == -1)
+                return next;
+            next.splice(from, 1);
+            next.splice(Math.max(0, Math.min(next.length, to)), 0, key);
+            const res = next.filter(k => !byKey.get(k)?.fixed);
+            opts.items.forEach(function pinFixed(it, i) {
+                if (it.fixed)
+                    res.splice(Math.min(i, res.length), 0, it.key);
+            });
+            return res;
+        }
+        const reorder = useReorder({
+            order: cfg.order,
+            commit: order => setConfig({ ...cfg, order }),
+            move: movedOrder,
+            canDrag: k => !byKey.get(k)?.fixed,
+        });
+        function onHandleKey(key, e) {
+            const step = { ArrowUp: -1, ArrowLeft: -1, ArrowDown: 1, ArrowRight: 1 }[e.key];
+            if (!step)
+                return;
+            e.preventDefault();
+            moveKey(cfg, key, cfg.order.indexOf(key) + step);
+        }
+        return _jsxs("div", { className: 'wenayTbSettings', children: [_jsx("div", { className: 'wenayTbDensity', children: densities.list.map(d => (_jsx("div", { className: d.key == cfg.density ? `${base} ${activeCls}` : base, onClick: () => setConfig({ ...cfg, density: d.key }), children: d.name }, d.key))) }), _jsx("div", { className: 'wenayTbRows', ref: reorder.listRef, children: cfg.order.map(k => {
+                        const it = byKey.get(k);
+                        if (!it)
+                            return null;
+                        const r = reorder.item(k);
+                        let cls = it.fixed ? 'wenayTbRow' : 'wenayTbRow wenayTbRowGrab';
+                        if (r.active)
+                            cls += r.dragging ? ' wenayTbRowDrag' : ' wenayTbRowShift'; // Shift is transitioned, so displaced rows glide
+                        return _jsxs("div", { className: cls, style: r.style, onMouseDown: it.fixed ? undefined : e => {
+                                // the drag hook preventDefaults mousedown, which suppresses native focus
+                                if (!e.target.closest('input'))
+                                    e.currentTarget.querySelector('.wenayTbHandle')?.focus();
+                                r.props.onMouseDown(e);
+                            }, onTouchStart: it.fixed ? undefined : r.props.onTouchStart, children: [_jsx("input", { type: 'checkbox', disabled: it.fixed, checked: cfg.visible[k] != false, onChange: () => setConfig({ ...cfg, visible: { ...cfg.visible, [k]: !(cfg.visible[k] != false) } }) }), _jsx("span", { className: 'wenayTbIcon', children: it.icon }), _jsx("span", { className: 'wenayTbRowTitle', children: it.title }), !it.fixed && _jsx("div", { className: 'wenayTbHandle', tabIndex: 0, title: 'Drag or arrow keys to reorder', onKeyDown: e => onHandleKey(k, e), children: "\u283F" })] }, k);
+                    }) }), _jsxs("div", { className: 'wenayTbRow wenayTbRowMeta', children: [_jsx("input", { type: 'checkbox', checked: cfg.visible[SETTINGS_KEY] != false, onChange: () => setConfig({ ...cfg, visible: { ...cfg.visible, [SETTINGS_KEY]: !(cfg.visible[SETTINGS_KEY] != false) } }) }), _jsx("span", { className: 'wenayTbIcon', children: settingsIcon() }), _jsx("span", { className: 'wenayTbRowTitle', children: settingsTitle() })] })] });
+    }
+    return {
+        Bar,
+        Settings,
+        api: { useConfig, useItems, getConfig, setConfig, reset, onChange },
+    };
+}

package/lib/common/src/components/Toolbar/index.d.ts

@@ -0,0 +1 @@
+export * from './Toolbar';

package/lib/common/src/components/Toolbar/index.js

@@ -0,0 +1 @@
+export * from './Toolbar';

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

@@ -1,5 +1,7 @@
 export * from './useAddDownAnyKey';
 export * from './useDraggable';
+export * from './useReorder';
+export * from './useReorderBoard';
 export * from './useObserveStore';
 export * from './useReplay';
 export * from './useOutside';

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

@@ -1,5 +1,7 @@
 export * from './useAddDownAnyKey';
 export * from './useDraggable';
+export * from './useReorder';
+export * from './useReorderBoard';
 export * from './useObserveStore';
 export * from './useReplay';
 export * from './useOutside';

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

@@ -0,0 +1,49 @@
+import React from 'react';
+/** useReorder - a deliberately small reorder-by-drag for keyed blocks laid out
+ *  by CSS (vertical list, horizontal bar, wrapped grid - the hook never knows
+ *  which). The DOM order does NOT change mid-drag: the dragged block follows
+ *  the pointer via transform, the rest glide to their preview position, ONE
+ *  commit fires on drop. The consumer renders children in `order`, 1:1 with
+ *  the container's children.
+ *  NOT a dnd framework: no nesting, no cross-container moves, no spans or
+ *  collision packing - when that day comes, take a ready-made library. */
+export type tReorderOptions = {
+    /** keys in render order; the container's children must correspond 1:1 */
+    order: string[];
+    /** ONE commit on drop; skipped when nothing moved */
+    commit: (next: string[]) => void;
+    /** simulated commit - the preview shows EXACTLY what commit will produce.
+     *  Default: plain splice. Consumers with pinning rules (fixed items etc.)
+     *  pass their own so preview == drop by construction. */
+    move?: (order: string[], key: string, to: number) => string[];
+    /** false = this key cannot start a drag (default: all can) */
+    canDrag?: (key: string) => boolean;
+    /** 'slots' (default): blocks glide between the slot centers measured at
+     *  drag start - exact when all blocks are equal-sized.
+     *  'measure': FLIP - the preview order is applied via CSS `order`, the real
+     *  layout is read and reverted in one synchronous pass (the intermediate
+     *  state never paints) - exact for ANY block sizes and wrapping, requires
+     *  a flex/grid container. */
+    preview?: 'slots' | 'measure';
+    /** hold before the drag starts (touch-friendly fields); default 0 */
+    holdMs?: number;
+};
+export type tReorderItem = {
+    /** spread on the block element */
+    props: {
+        onMouseDown: React.MouseEventHandler<HTMLElement>;
+        onTouchStart: React.TouchEventHandler<HTMLElement>;
+    };
+    /** transform while a drag is active (undefined otherwise) */
+    style?: React.CSSProperties;
+    /** this block is the one under the pointer */
+    dragging: boolean;
+    /** some drag is active - the consumer adds its transition class/style on non-dragged blocks */
+    active: boolean;
+};
+export declare function useReorder<E extends HTMLElement = HTMLDivElement>(o: tReorderOptions): {
+    listRef: React.RefObject<E | null>;
+    item: (key: string) => tReorderItem;
+    dragKey: string | null;
+    preview: string[] | null;
+};

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

@@ -0,0 +1,134 @@
+import { useRef, useState } from 'react';
+import { useDraggableApi } from './useDraggable';
+export function useReorder(o) {
+    const listRef = useRef(null);
+    const [dragKey, setDragKey] = useState(null);
+    const slotsRef = useRef([]); // child centers at drag start (local px)
+    const startRef = useRef([]); // child top-lefts at drag start (local px)
+    // Pointer deltas are viewport px, layout is local px: under a scaled ancestor
+    // (client styling, zoomed containers) they diverge - normalize by the ratio.
+    const scaleRef = useRef(1);
+    const measureRef = useRef(null);
+    const move = o.move ?? function plainSplice(order, key, to) {
+        const next = order.slice();
+        const from = next.indexOf(key);
+        if (from == -1)
+            return next;
+        next.splice(from, 1);
+        next.splice(Math.max(0, Math.min(next.length, to)), 0, key);
+        return next;
+    };
+    const kids = () => Array.from(listRef.current?.children ?? []);
+    /** viewport px -> local px */
+    const local = (v) => v / scaleRef.current;
+    /** Nearest START-slot center to the dragged block's center. Targeting always
+     *  runs against the slots measured at drag start - computing it against a
+     *  live-reflowing layout oscillates at boundaries; that failure mode is
+     *  designed out. */
+    function dragTarget(from, dx, dy) {
+        const slots = slotsRef.current;
+        const start = slots[from];
+        if (!start)
+            return from;
+        const x = start.x + dx, y = start.y + dy;
+        let best = from, bestD = Infinity;
+        slots.forEach((c, i) => {
+            const d = (c.x - x) ** 2 + (c.y - y) ** 2;
+            if (d < bestD) {
+                bestD = d;
+                best = i;
+            }
+        });
+        return best;
+    }
+    const drag = useDraggableApi({ holdMs: o.holdMs ?? 0, onDragEnd: function commitOrder(final) {
+            setDragKey(null);
+            measureRef.current = null;
+            if (dragKey == null)
+                return;
+            const from = o.order.indexOf(dragKey);
+            if (from == -1)
+                return;
+            const next = move(o.order, dragKey, dragTarget(from, local(final.x), local(final.y)));
+            if (next.some((k, i) => k != o.order[i]))
+                o.commit(next);
+        } });
+    function beginDrag(key, e) {
+        if (o.canDrag && !o.canDrag(key))
+            return false;
+        // interactive children stay clickable (checkboxes in rows etc.)
+        if (e.target.closest('input, button, select, textarea, a'))
+            return false;
+        const list = listRef.current;
+        if (!list)
+            return false;
+        scaleRef.current = list.offsetWidth ? list.getBoundingClientRect().width / list.offsetWidth : 1;
+        // offsetLeft/Top, NOT getBoundingClientRect: offsets are pure layout-box
+        // positions - transforms (incl. mid-flight transitions) never leak in
+        const els = kids();
+        slotsRef.current = els.map(el => ({ x: el.offsetLeft + el.offsetWidth / 2, y: el.offsetTop + el.offsetHeight / 2 }));
+        startRef.current = els.map(el => ({ x: el.offsetLeft, y: el.offsetTop }));
+        measureRef.current = null;
+        setDragKey(key);
+        return true;
+    }
+    /** FLIP: apply the preview order via CSS `order`, read the real layout,
+     *  revert - one synchronous pass between frames, so the intermediate state
+     *  never paints and CSS does the wrapping math for us. Cached per target
+     *  (targets change rarely, not per mousemove). Positions are read via
+     *  offsetLeft/Top, NEVER getBoundingClientRect: rects include transforms,
+     *  and mid-drag the blocks carry mid-flight transition values (setting
+     *  style.transform='none' does not stop a running transition within the
+     *  same synchronous pass) - measuring through them accumulates the previous
+     *  preview's offsets on every re-measure and the blocks fly apart. Offsets
+     *  are pure layout-box positions, immune to all of that. */
+    function measuredPositions(preview, target) {
+        if (measureRef.current?.target == target)
+            return measureRef.current.pos;
+        const els = kids();
+        const saved = els.map(el => el.style.order);
+        els.forEach((el, i) => el.style.order = String(preview.indexOf(o.order[i])));
+        const pos = els.map(el => ({ x: el.offsetLeft, y: el.offsetTop }));
+        els.forEach((el, i) => el.style.order = saved[i]);
+        measureRef.current = { target, pos };
+        return pos;
+    }
+    const from = dragKey != null ? o.order.indexOf(dragKey) : -1;
+    const target = from != -1 ? dragTarget(from, local(drag.position.x), local(drag.position.y)) : -1;
+    const preview = from != -1 && dragKey != null ? move(o.order, dragKey, target) : null;
+    function item(key) {
+        const active = preview != null;
+        const dragging = key == dragKey;
+        let style;
+        if (active) {
+            const i = o.order.indexOf(key);
+            if (dragging) {
+                style = { transform: `translate(${local(drag.position.x)}px, ${local(drag.position.y)}px)` };
+            }
+            else if (o.preview == 'measure') {
+                const pos = measuredPositions(preview, target);
+                const a = startRef.current[i], b = pos[i];
+                if (a && b && (a.x != b.x || a.y != b.y))
+                    style = { transform: `translate(${b.x - a.x}px, ${b.y - a.y}px)` };
+            }
+            else {
+                const pi = preview.indexOf(key);
+                const a = slotsRef.current[i], b = slotsRef.current[pi];
+                if (pi != i && a && b)
+                    style = { transform: `translate(${b.x - a.x}px, ${b.y - a.y}px)` };
+            }
+        }
+        return {
+            props: {
+                onMouseDown(e) { if (e.button == 0 && beginDrag(key, e))
+                    drag.props.onMouseDown(e); },
+                onTouchStart(e) { if (beginDrag(key, e))
+                    drag.props.onTouchStart(e); },
+            },
+            style,
+            dragging,
+            active,
+        };
+    }
+    return { listRef, item, dragKey, preview };
+}

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

@@ -0,0 +1,61 @@
+import { tReorderItem } from './useReorder';
+/** useReorderBoard - the columns extension of useReorder: keyed blocks live in
+ *  VERTICAL columns (plain consumer divs), one block drags between/within them,
+ *  ONE commit on drop. Column "gravity" is pure consumer CSS (justify-content:
+ *  flex-start packs up, flex-end packs down) - the hook never knows it, it
+ *  measures the real layout. Columns can appear/disappear between drags (the
+ *  ref callback registry is live); the set is frozen for the duration of one
+ *  drag. Children of a column div must be exactly its items, 1:1, in order.
+ *  Same non-goals as useReorder: no nesting, no spans/collision packing, no
+ *  autoscroll - that day is a ready-made dnd library. */
+export type tBoardPos = {
+    col: string;
+    index: number;
+};
+export type tBoardColumn = {
+    key: string;
+    items: string[];
+};
+export type tReorderBoardOptions = {
+    /** columns in board order; each column's div children must render items 1:1 */
+    columns: tBoardColumn[];
+    /** ONE commit on drop; skipped when nothing moved */
+    commit: (next: tBoardColumn[]) => void;
+    /** false = this key cannot start a drag (default: all can) */
+    canDrag?: (key: string) => boolean;
+    /** hold before the drag starts; default 0 */
+    holdMs?: number;
+    /** the block was grabbed */
+    onDragStart?: (e: {
+        key: string;
+        from: tBoardPos;
+    }) => void;
+    /** every pointer move while dragging; position = pointer delta in local px */
+    onDragMove?: (e: {
+        key: string;
+        over: tBoardPos;
+        position: {
+            x: number;
+            y: number;
+        };
+    }) => void;
+    /** the target slot changed (compare prev.col != over.col for column crossings) */
+    onOverChange?: (e: {
+        key: string;
+        over: tBoardPos;
+        prev: tBoardPos | null;
+    }) => void;
+    /** drop; committed=false when nothing moved (plain click) */
+    onDragEnd?: (e: {
+        key: string;
+        from: tBoardPos;
+        over: tBoardPos;
+        committed: boolean;
+    }) => void;
+};
+export declare function useReorderBoard(o: tReorderBoardOptions): {
+    columnRef: (col: string) => (el: HTMLElement | null) => void;
+    item: (key: string) => tReorderItem;
+    dragKey: string | null;
+    over: tBoardPos | null;
+};