wenay-react2 1.0.46 → 1.0.47

package/README.md

@@ -2,7 +2,8 @@
 
 Documentation index only.
 
-- Brief API guide: [doc/wenay-react2.md](doc/wenay-react2.md)
+- Brief API guide: [doc/wenay-react2.md](doc/wenay-react2.md)
+- React Native/headless entrypoint: [doc/native.md](doc/native.md)
 - Detailed / rare API guide: [doc/wenay-react2-rare.md](doc/wenay-react2-rare.md)
 - Project functionality map: [doc/PROJECT_FUNCTIONALITY.md](doc/PROJECT_FUNCTIONALITY.md)
 - Example usage standards: [doc/EXAMPLE_USAGE.md](doc/EXAMPLE_USAGE.md)
@@ -16,4 +17,5 @@ Feature-specific docs may also live next to their code, for example agGrid4 docs
 
 ## Shipped examples
 
-- [doc/examples/stand.tsx](doc/examples/stand.tsx) — весь интерактивный стенд (`wenay-react2/demo/stand`); Active = канон, Archive = regression/compat.`r`n- [doc/examples/peer-call-media.tsx](doc/examples/peer-call-media.tsx) — Peer calls, presence, camera and microphone relay with server-owned ACL.
+- [doc/examples/stand.tsx](doc/examples/stand.tsx) — весь интерактивный стенд (`wenay-react2/demo/stand`); Active = канон, Archive = regression/compat.
+- [doc/examples/peer-call-media.tsx](doc/examples/peer-call-media.tsx) — Peer calls, presence, camera and microphone relay with server-owned ACL.

package/doc/changes/v1.0.47.md

@@ -0,0 +1,9 @@
+# 1.0.47
+
+- Added the platform-neutral `wenay-react2/native` entrypoint.
+- Added `createNativeColumnState`: an AsyncStorage-compatible controller for order, visibility, width, sorting, filters and groups without DOM, CSS, React DOM or ag-grid dependencies.
+- Added `createNativeColumnDots`: a renderer-independent gesture model with live replacement, reorder, visibility, sorting and tear-off behavior.
+- Added focused hydration, persistence, gesture and dependency-boundary tests.
+- Fixed the shipped examples list formatting in README.
+
+Verification: Jest, TypeScript build, package archive inspection and runtime import of `wenay-react2/native` from the packed artifact.

package/doc/native.md

@@ -0,0 +1,37 @@
+# React Native entrypoint
+
+Import the renderer-neutral API from `wenay-react2/native`. It has no React DOM,
+CSS, browser-global or ag-grid dependency.
+
+```ts
+import AsyncStorage from '@react-native-async-storage/async-storage'
+import {createNativeColumnDots, createNativeColumnState} from 'wenay-react2/native'
+
+const columns = createNativeColumnState({
+    key: 'super-admin.columns',
+    columns: [
+        {key: 'server', title: 'Server', fixed: true},
+        {key: 'status', title: 'Status'},
+        {key: 'panic', title: 'Panic'},
+    ],
+    storage: AsyncStorage,
+})
+await columns.ready
+
+const dots = createNativeColumnDots({state: columns, max: 8})
+dots.begin('status', 40, 0)
+dots.move(120, 0, {start: 0, length: 240})
+dots.end()
+```
+
+The persisted `v/order/visible/width/sort/filter/groups` shape matches the web
+`ColumnsConfig`. Writes are serialized and local edits made while hydration is
+pending win over stale storage.
+
+`createNativeColumnDots` is a view-independent interaction model. Connect its
+`begin/move/end` coordinates to PanResponder or Gesture Handler. Set `removeDirection` to `up`, `down` or `either` (the renderer-neutral default). It supports
+live field replacement along the slider, explicit reorder and toggle, sticky
+`asc -> desc -> off` sorting, and upward tear-off.
+
+Call `dots.dispose()` and `columns.dispose()` with the owning screen. Use
+`columns.api.flush()` when the latest AsyncStorage write must be awaited.

package/lib/native/columnDots.d.ts

@@ -0,0 +1,41 @@
+import type { NativeColumnStateController } from './columnState.js';
+export type NativeColumnDotsGeometry = {
+    start: number;
+    length: number;
+};
+export type NativeColumnDotsSnapshot = {
+    selected: string | null;
+    visible: string[];
+    sort: {
+        key: string;
+        dir: 'asc' | 'desc';
+    } | null;
+    drag: null | {
+        origin: string;
+        shown: string;
+        index: number;
+        removing: boolean;
+    };
+};
+/** Coordinate-driven interaction model for PanResponder, Gesture Handler or another native view. */
+export declare function createNativeColumnDots(opts: {
+    state: NativeColumnStateController;
+    max?: number;
+    moveSlop?: number;
+    removeDistance?: number;
+    /** Native coordinate systems and designs differ. Default 'either' is renderer-neutral. */
+    removeDirection?: 'up' | 'down' | 'either';
+}): {
+    getSnapshot: () => NativeColumnDotsSnapshot;
+    subscribe: (listener: (snapshot: NativeColumnDotsSnapshot) => void) => () => void;
+    select: (key: string | null) => void;
+    toggle: (key: string) => void;
+    reorder: (key: string, to: number) => void;
+    toggleSelectedSort: () => void;
+    begin: (key: string, primary: number, cross: number) => boolean;
+    move: (primary: number, cross: number, geometry: NativeColumnDotsGeometry) => void;
+    end: () => void;
+    cancel: () => void;
+    dispose: () => void;
+};
+export type NativeColumnDotsController = ReturnType<typeof createNativeColumnDots>;

package/lib/native/columnDots.js

@@ -0,0 +1,104 @@
+/** Coordinate-driven interaction model for PanResponder, Gesture Handler or another native view. */
+export function createNativeColumnDots(opts) {
+    const listeners = new Set();
+    const byKey = new Map(opts.state.columns.map(column => [column.key, column]));
+    let selected = null;
+    let drag = null;
+    function getSnapshot() {
+        const config = opts.state.api.getConfig();
+        return {
+            selected,
+            visible: opts.state.api.visibleKeys(),
+            sort: config.sort,
+            drag: drag ? { origin: drag.origin, shown: drag.shown, index: drag.index, removing: drag.removing } : null,
+        };
+    }
+    function emit() {
+        const snapshot = getSnapshot();
+        for (const listener of listeners)
+            listener(snapshot);
+    }
+    const stopState = opts.state.api.subscribe(emit);
+    const subscribe = (listener) => {
+        listeners.add(listener);
+        return function unsubscribe() { listeners.delete(listener); };
+    };
+    function select(key) {
+        selected = key && byKey.has(key) ? key : null;
+        emit();
+    }
+    function toggle(key) {
+        const config = opts.state.api.getConfig();
+        if (!byKey.has(key) || byKey.get(key)?.fixed)
+            return;
+        const isVisible = config.visible[key] != false;
+        if (isVisible && opts.state.api.visibleKeys().length <= 1)
+            return;
+        if (!isVisible && opts.state.api.visibleKeys().length >= (opts.max ?? 8))
+            return;
+        selected = !isVisible ? key : selected == key ? null : selected;
+        opts.state.api.show(key, !isVisible);
+    }
+    const reorder = (key, to) => opts.state.api.moveKey(key, to);
+    const toggleSelectedSort = () => { if (selected)
+        opts.state.api.toggleSort(selected); };
+    function begin(key, primary, cross) {
+        const config = opts.state.api.getConfig();
+        if (!byKey.has(key) || config.visible[key] == false)
+            return false;
+        drag = { origin: key, shown: key, startPrimary: primary, startCross: cross, moved: false,
+            index: config.order.indexOf(key), removing: false };
+        emit();
+        return true;
+    }
+    function move(primary, cross, geometry) {
+        if (!drag)
+            return;
+        const config = opts.state.api.getConfig();
+        const dx = primary - drag.startPrimary;
+        const dy = cross - drag.startCross;
+        if (!drag.moved && Math.hypot(dx, dy) < (opts.moveSlop ?? 4))
+            return;
+        drag.moved = true;
+        const last = Math.max(0, config.order.length - 1);
+        const relative = geometry.length > 0 ? (primary - geometry.start) / geometry.length : 0;
+        drag.index = Math.max(0, Math.min(last, Math.round(relative * last)));
+        const removeDelta = opts.removeDirection == 'up' ? -dy
+            : opts.removeDirection == 'down' ? dy : Math.abs(dy);
+        drag.removing = removeDelta > (opts.removeDistance ?? 32) && removeDelta > Math.abs(dx);
+        if (!drag.removing && !byKey.get(drag.origin)?.fixed) {
+            const target = config.order[drag.index];
+            if (target && target != drag.shown && config.visible[target] == false) {
+                opts.state.api.setConfig({ ...config, visible: { ...config.visible, [drag.shown]: false, [target]: true } });
+                drag.shown = target;
+            }
+        }
+        emit();
+    }
+    function end() {
+        const current = drag;
+        drag = null;
+        if (!current)
+            return;
+        if (!current.moved)
+            selected = current.origin;
+        else if (current.removing && !byKey.get(current.shown)?.fixed && opts.state.api.visibleKeys().length > 1) {
+            opts.state.api.show(current.shown, false);
+            if (selected == current.origin || selected == current.shown)
+                selected = null;
+        }
+        else if (current.shown != current.origin && selected == current.origin)
+            selected = current.shown;
+        emit();
+    }
+    function cancel() {
+        drag = null;
+        emit();
+    }
+    function dispose() {
+        stopState();
+        listeners.clear();
+        drag = null;
+    }
+    return { getSnapshot, subscribe, select, toggle, reorder, toggleSelectedSort, begin, move, end, cancel, dispose };
+}

package/lib/native/columnState.d.ts

@@ -0,0 +1,69 @@
+export type NativeColumnMeta = {
+    key: string;
+    title: string;
+    short?: string;
+    icon?: unknown;
+    group?: string;
+    fixed?: boolean;
+    defaultVisible?: boolean;
+    cardRole?: 'title' | 'accent';
+};
+export type NativeColumnsSort = {
+    key: string;
+    dir: 'asc' | 'desc';
+};
+export type NativeColumnsConfig = {
+    v: number;
+    order: string[];
+    visible: {
+        [key: string]: boolean;
+    };
+    width: {
+        [key: string]: number;
+    };
+    sort: NativeColumnsSort | null;
+    filter: {
+        [key: string]: unknown;
+    };
+    groups: {
+        [group: string]: string[];
+    };
+};
+export type NativeColumnStorage = {
+    getItem(key: string): Promise<string | null>;
+    setItem(key: string, value: string): Promise<unknown>;
+    removeItem?(key: string): Promise<unknown>;
+};
+export type NativeColumnStateError = {
+    phase: 'read' | 'parse' | 'write';
+    error: unknown;
+};
+/** Headless, platform-neutral column controller. AsyncStorage satisfies storage directly. */
+export declare function createNativeColumnState(opts: {
+    key: string;
+    columns: readonly NativeColumnMeta[];
+    def?: Partial<NativeColumnsConfig>;
+    storage?: NativeColumnStorage;
+    saveMs?: number;
+    onError?: (event: NativeColumnStateError) => void;
+}): {
+    columns: readonly NativeColumnMeta[];
+    ready: Promise<NativeColumnsConfig>;
+    api: {
+        getConfig: () => NativeColumnsConfig;
+        setConfig: (next: NativeColumnsConfig) => void;
+        subscribe: (listener: (config: NativeColumnsConfig) => void) => () => void;
+        show: (key: string, visible: boolean) => void;
+        move: (order: string[]) => void;
+        moveKey: (key: string, to: number) => void;
+        setSort: (sort: NativeColumnsSort | null) => void;
+        toggleSort: (key: string) => void;
+        setFilter: (key: string, value: unknown) => void;
+        setGroup: (group: string, keys: string[]) => void;
+        visibleKeys: () => string[];
+        reset: () => void;
+        flush: () => Promise<void>;
+    };
+    dispose: () => void;
+};
+export type NativeColumnStateController = ReturnType<typeof createNativeColumnState>;

package/lib/native/columnState.js

@@ -0,0 +1,209 @@
+const SCHEMA_V = 1;
+function copy(config) {
+    return {
+        ...config,
+        order: config.order.slice(),
+        visible: { ...config.visible },
+        width: { ...config.width },
+        sort: config.sort ? { ...config.sort } : null,
+        filter: { ...config.filter },
+        groups: Object.fromEntries(Object.entries(config.groups).map(([group, keys]) => [group, keys.slice()])),
+    };
+}
+function pinFixed(order, columns) {
+    const fixed = new Set(columns.filter(column => column.fixed).map(column => column.key));
+    const result = order.filter(key => !fixed.has(key));
+    columns.forEach(function pin(column, index) {
+        if (column.fixed)
+            result.splice(Math.min(index, result.length), 0, column.key);
+    });
+    return result;
+}
+/** Headless, platform-neutral column controller. AsyncStorage satisfies storage directly. */
+export function createNativeColumnState(opts) {
+    const columns = opts.columns.slice();
+    const byKey = new Map(columns.map(column => [column.key, column]));
+    const known = new Set(byKey.keys());
+    const groupKeys = [...new Set(columns.map(column => column.group).filter((group) => !!group))];
+    const listeners = new Set();
+    let revision = 0;
+    let hydrated = !opts.storage;
+    let disposed = false;
+    let timer;
+    let writes = Promise.resolve();
+    const members = (group) => columns.filter(column => column.group == group).map(column => column.key);
+    function defaults() {
+        return {
+            v: SCHEMA_V,
+            order: opts.def?.order?.slice() ?? columns.map(column => column.key),
+            visible: opts.def?.visible ? { ...opts.def.visible } : Object.fromEntries(columns.map(column => [column.key, column.defaultVisible != false])),
+            width: opts.def?.width ? { ...opts.def.width } : {},
+            sort: opts.def?.sort ? { ...opts.def.sort } : null,
+            filter: opts.def?.filter ? { ...opts.def.filter } : {},
+            groups: opts.def?.groups ? { ...opts.def.groups } : Object.fromEntries(groupKeys.map(group => [group, members(group)])),
+        };
+    }
+    function normalize(value) {
+        const base = defaults();
+        const order = (Array.isArray(value?.order) ? value.order : base.order)
+            .filter(key => known.has(key) && !byKey.get(key)?.fixed);
+        for (const column of columns)
+            if (!column.fixed && !order.includes(column.key))
+                order.push(column.key);
+        const rawVisible = value?.visible && typeof value.visible == 'object' ? value.visible : base.visible;
+        const visible = {};
+        for (const column of columns)
+            visible[column.key] = column.fixed ? true : (rawVisible[column.key] ?? column.defaultVisible != false);
+        const width = {};
+        for (const [key, item] of Object.entries(value?.width ?? {}))
+            if (known.has(key) && typeof item == 'number' && isFinite(item) && item > 0)
+                width[key] = item;
+        const sort = value?.sort && known.has(value.sort.key) && (value.sort.dir == 'asc' || value.sort.dir == 'desc')
+            ? { key: value.sort.key, dir: value.sort.dir } : null;
+        const filter = {};
+        for (const [key, item] of Object.entries(value?.filter ?? {}))
+            if (known.has(key))
+                filter[key] = item;
+        const groups = {};
+        for (const group of groupKeys) {
+            const allowed = members(group);
+            const raw = value?.groups?.[group];
+            groups[group] = Array.isArray(raw) ? raw.filter(key => allowed.includes(key)) : allowed;
+        }
+        return { v: SCHEMA_V, order: pinFixed(order, columns), visible, width, sort, filter, groups };
+    }
+    let config = normalize(defaults());
+    const emit = () => {
+        const snapshot = copy(config);
+        for (const listener of listeners)
+            listener(snapshot);
+    };
+    const report = (phase, error) => opts.onError?.({ phase, error });
+    function enqueue(snapshot) {
+        if (!opts.storage || disposed)
+            return;
+        writes = writes.then(async function save() {
+            try {
+                await opts.storage.setItem(opts.key, JSON.stringify(snapshot));
+            }
+            catch (error) {
+                report('write', error);
+            }
+        });
+    }
+    function schedule() {
+        if (!opts.storage || !hydrated || disposed)
+            return;
+        clearTimeout(timer);
+        timer = setTimeout(function saveLater() {
+            timer = undefined;
+            enqueue(copy(config));
+        }, opts.saveMs ?? 100);
+    }
+    function commit(next) {
+        if (disposed)
+            return;
+        config = normalize(next);
+        revision++;
+        emit();
+        schedule();
+    }
+    const ready = (async function hydrate() {
+        if (!opts.storage)
+            return copy(config);
+        const before = revision;
+        try {
+            const raw = await opts.storage.getItem(opts.key);
+            if (raw != null && revision == before) {
+                try {
+                    config = normalize(JSON.parse(raw));
+                    emit();
+                }
+                catch (error) {
+                    report('parse', error);
+                }
+            }
+        }
+        catch (error) {
+            report('read', error);
+        }
+        finally {
+            hydrated = true;
+            if (revision != before)
+                schedule();
+        }
+        return copy(config);
+    })();
+    const getConfig = () => copy(config);
+    const subscribe = (listener) => {
+        listeners.add(listener);
+        return function unsubscribe() { listeners.delete(listener); };
+    };
+    function show(key, visible) {
+        if (!known.has(key) || byKey.get(key)?.fixed)
+            return;
+        commit({ ...config, visible: { ...config.visible, [key]: visible } });
+    }
+    function move(order) { commit({ ...config, order }); }
+    function moveKey(key, to) {
+        if (!known.has(key) || byKey.get(key)?.fixed)
+            return;
+        const order = config.order.slice();
+        const from = order.indexOf(key);
+        if (from == -1)
+            return;
+        order.splice(from, 1);
+        order.splice(Math.max(0, Math.min(order.length, to)), 0, key);
+        move(order);
+    }
+    function setSort(sort) { commit({ ...config, sort }); }
+    function toggleSort(key) {
+        if (!known.has(key))
+            return;
+        const current = config.sort;
+        setSort(current?.key != key ? { key, dir: 'asc' } : current.dir == 'asc' ? { key, dir: 'desc' } : null);
+    }
+    function setFilter(key, value) {
+        if (!known.has(key))
+            return;
+        const filter = { ...config.filter };
+        if (value == null)
+            delete filter[key];
+        else
+            filter[key] = value;
+        commit({ ...config, filter });
+    }
+    function setGroup(group, keys) {
+        if (!groupKeys.includes(group))
+            return;
+        commit({ ...config, groups: { ...config.groups, [group]: keys } });
+    }
+    function visibleKeys() {
+        return config.order.filter(key => {
+            if (config.visible[key] == false)
+                return false;
+            const group = byKey.get(key)?.group;
+            return !group || config.groups[group]?.includes(key);
+        });
+    }
+    function reset() { commit(defaults()); }
+    async function flush() {
+        clearTimeout(timer);
+        timer = undefined;
+        await ready;
+        enqueue(copy(config));
+        await writes;
+    }
+    function dispose() {
+        disposed = true;
+        clearTimeout(timer);
+        listeners.clear();
+    }
+    return {
+        columns: columns,
+        ready,
+        api: { getConfig, setConfig: (next) => commit(next), subscribe, show, move, moveKey,
+            setSort, toggleSort, setFilter, setGroup, visibleKeys, reset, flush },
+        dispose,
+    };
+}

package/lib/native/index.d.ts

@@ -0,0 +1,3 @@
+/** DOM/CSS/ag-grid/react-dom-free React Native entrypoint. */
+export * from './columnState.js';
+export * from './columnDots.js';

package/lib/native/index.js

@@ -0,0 +1,3 @@
+/** DOM/CSS/ag-grid/react-dom-free React Native entrypoint. */
+export * from './columnState.js';
+export * from './columnDots.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wenay-react2",
-  "version": "1.0.46",
+  "version": "1.0.47",
   "description": "Common react",
   "strict": true,
   "main": "dist/index.js",
@@ -45,6 +45,7 @@
   },
   "exports": {
     ".": "./lib/index.js",
+    "./native": "./lib/native/index.js",
     "./package.json": "./package.json",
     "./demo/peer-media": "./lib/common/demo/peerMedia.js",
     "./demo/stand": "./lib/common/testUseReact/qa.js"