wenay-react2 1.0.28 → 1.0.29

package/lib/common/api.d.ts

@@ -25,6 +25,8 @@ export * from "./src/components/ParametersEngine";
 export * from "./src/components/Input";
 export * from "./src/components/Modal";
 export * from "./src/components/Menu";
+export * from "./src/components/Settings";
+export * from "./src/components/UiSlot";
 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

@@ -37,6 +37,9 @@ export * from "./src/components/Input";
 export * from "./src/components/Modal";
 // 11. Menu - depends on hooks, Dnd, and Modal
 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";
 // 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/Settings/SettingsDialog.d.ts

@@ -0,0 +1,22 @@
+import React from "react";
+export type tSettingsSection = {
+    key: string;
+    name: string;
+    render: () => React.ReactNode;
+};
+/** Register an external section. Re-register with the same key replaces the previous one.
+ *  The returned function removes exactly this registration (a no-op if it was replaced). */
+export declare function registerSettingsSection(s: tSettingsSection): () => void;
+/** Current external sections (static props sections are not included). */
+export declare function getSettingsSections(): readonly tSettingsSection[];
+/** Centered settings dialog: sections column on the left, active section content on the right.
+ *  Sections = props.sections (first) + everything from registerSettingsSection.
+ *  Look is themed via --dlg-* CSS variables (dark defaults), same contract as --wnd-*. */
+export declare function SettingsDialog(props: {
+    trigger: React.ReactNode;
+    sections?: tSettingsSection[];
+    defaultSection?: string;
+    /** Section buttons: apps pass their own .chip / .chipActive; defaults are minimal library styles */
+    sectionClassName?: string;
+    sectionActiveClassName?: string;
+}): import("react/jsx-runtime").JSX.Element;

package/lib/common/src/components/Settings/SettingsDialog.js

@@ -0,0 +1,55 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { useEffect, useState } from "react";
+import { createPortal } from "react-dom";
+import { renderBy, updateBy } from "../../../updateBy";
+// Module singleton (closure + updateBy subscription, no React context): any module
+// registers a section on mount and removes it on unmount; the dialog re-renders on changes.
+const registry = { list: [] };
+/** Register an external section. Re-register with the same key replaces the previous one.
+ *  The returned function removes exactly this registration (a no-op if it was replaced). */
+export function registerSettingsSection(s) {
+    const i = registry.list.findIndex(e => e.key == s.key);
+    if (i == -1)
+        registry.list.push(s);
+    else
+        registry.list.splice(i, 1, s);
+    renderBy(registry);
+    return () => {
+        const j = registry.list.indexOf(s);
+        if (j != -1) {
+            registry.list.splice(j, 1);
+            renderBy(registry);
+        }
+    };
+}
+/** Current external sections (static props sections are not included). */
+export function getSettingsSections() {
+    return registry.list;
+}
+/** Centered settings dialog: sections column on the left, active section content on the right.
+ *  Sections = props.sections (first) + everything from registerSettingsSection.
+ *  Look is themed via --dlg-* CSS variables (dark defaults), same contract as --wnd-*. */
+export function SettingsDialog(props) {
+    const [open, setOpen] = useState(false);
+    const [active, setActive] = useState(props.defaultSection);
+    updateBy(registry);
+    useEffect(() => {
+        if (!open)
+            return;
+        const onKeyDown = (e) => {
+            if (e.key == 'Escape')
+                setOpen(false);
+        };
+        document.addEventListener('keydown', onKeyDown);
+        return () => document.removeEventListener('keydown', onKeyDown);
+    }, [open]);
+    const sections = [...(props.sections ?? []), ...registry.list];
+    // fall back to the first section when active was never set or its section unmounted
+    const current = sections.find(s => s.key == active) ?? sections[0];
+    const base = props.sectionClassName ?? "wenayDlgSection";
+    const activeCls = props.sectionActiveClassName ?? "wenayDlgSectionActive";
+    return _jsxs(_Fragment, { children: [_jsx("span", { onClick: () => setOpen(true), style: { display: "inline-block", cursor: "pointer" }, children: props.trigger }), open && createPortal(_jsx("div", { className: "wenayDlgScrim", onClick: e => {
+                    if (e.target == e.currentTarget)
+                        setOpen(false);
+                }, children: _jsxs("div", { className: "wenayDlg", children: [_jsx("div", { className: "wenayDlgNav", children: sections.map(s => (_jsx("div", { className: s.key == current?.key ? `${base} ${activeCls}` : base, onClick: () => setActive(s.key), children: s.name }, s.key))) }), _jsx("div", { className: "wenayDlgContent", children: current?.render() }), _jsx("div", { className: "wenayCloseBtn wenayDlgClose", title: "Close", onClick: () => setOpen(false), children: _jsx("svg", { width: "12", height: "12", viewBox: "0 0 12 12", "aria-hidden": "true", children: _jsx("path", { d: "M2 2 L10 10 M10 2 L2 10", stroke: "currentColor", strokeWidth: "1.6", strokeLinecap: "round" }) }) })] }) }), document.body)] });
+}

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

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

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

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

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

@@ -0,0 +1,24 @@
+import React from "react";
+/** One UI block shown in exactly one of several mount points; the point is a persisted setting.
+ *  Persistence rides the existing staticProps -> Cash mechanics: the app calls Cash.load()/save()
+ *  the same way it does for window state (ExRNDMap3 etc.).
+ *  Mount points render <Slot place="..."> themselves and decide nothing: the slot compares
+ *  the persisted place with its own and renders children only on a match. */
+export declare function createUiSlot<Places extends string>(opts: {
+    key: string;
+    places: {
+        [P in Places]: string;
+    };
+    def: NoInfer<Places>;
+}): {
+    Slot: (p: {
+        place: Places;
+        children: React.ReactNode;
+    }) => React.JSX.Element | null;
+    PlacementSetting: (p?: {
+        className?: string;
+        activeClassName?: string;
+    }) => import("react/jsx-runtime").JSX.Element;
+    getPlace: () => Places;
+    setPlace: (p: Places) => void;
+};

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

@@ -0,0 +1,33 @@
+import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
+import { renderBy, updateBy } from "../../../updateBy";
+import { staticGetAdd } from "../../utils/mapMemory";
+/** One UI block shown in exactly one of several mount points; the point is a persisted setting.
+ *  Persistence rides the existing staticProps -> Cash mechanics: the app calls Cash.load()/save()
+ *  the same way it does for window state (ExRNDMap3 etc.).
+ *  Mount points render <Slot place="..."> themselves and decide nothing: the slot compares
+ *  the persisted place with its own and renders children only on a match. */
+export function createUiSlot(opts) {
+    const st = staticGetAdd(opts.key, { place: opts.def });
+    // a stored place may no longer exist after an app update - fall back to def
+    const isPlace = (p) => typeof p == "string" && p in opts.places;
+    const getPlace = () => isPlace(st.place) ? st.place : opts.def;
+    const setPlace = (p) => {
+        if (st.place == p)
+            return;
+        st.place = p;
+        renderBy(st);
+    };
+    function Slot(p) {
+        updateBy(st);
+        return getPlace() == p.place ? _jsx(_Fragment, { children: p.children }) : null;
+    }
+    /** Segmented row over opts.places; apps pass their own .chip / .chipActive classes */
+    function PlacementSetting(p = {}) {
+        updateBy(st);
+        const cur = getPlace();
+        const base = p.className ?? "wenaySegBtn";
+        const activeCls = p.activeClassName ?? "wenaySegBtnActive";
+        return _jsx("div", { style: { display: "inline-flex", gap: 4, flexWrap: "wrap" }, children: Object.keys(opts.places).map(key => (_jsx("div", { className: key == cur ? `${base} ${activeCls}` : base, onClick: () => setPlace(key), children: opts.places[key] }, key))) });
+    }
+    return { Slot, PlacementSetting, getPlace, setPlace };
+}

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

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

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

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

package/lib/common/src/styles/tokens.d.ts

@@ -44,6 +44,19 @@ export declare const tokens: {
         readonly closeHover: "#fff";
         readonly closeHoverBg: "#e5484d";
     };
+    /** SettingsDialog chrome (--dlg-*). Dark defaults; apps re-skin via :root[data-theme]. */
+    readonly dlg: {
+        readonly scrim: "rgba(0, 0, 0, 0.5)";
+        /** var(--color-bg-dark) in CSS */
+        readonly bg: "#131821";
+        /** var(--color-border-common) in CSS */
+        readonly border: "1px solid rgb(50, 62, 71)";
+        readonly radius: "10px";
+        readonly shadow: "0 12px 40px rgba(0, 0, 0, 0.5)";
+        /** var(--color-bg-light) in CSS */
+        readonly navBg: "#17202e";
+        readonly navWidth: "168px";
+    };
     readonly font: {
         readonly family: "Roboto";
         readonly sizeBase: "12px";

package/lib/common/src/styles/tokens.js

@@ -46,6 +46,19 @@ export const tokens = {
         closeHover: '#fff',
         closeHoverBg: '#e5484d',
     },
+    /** SettingsDialog chrome (--dlg-*). Dark defaults; apps re-skin via :root[data-theme]. */
+    dlg: {
+        scrim: 'rgba(0, 0, 0, 0.5)',
+        /** var(--color-bg-dark) in CSS */
+        bg: '#131821',
+        /** var(--color-border-common) in CSS */
+        border: '1px solid rgb(50, 62, 71)',
+        radius: '10px',
+        shadow: '0 12px 40px rgba(0, 0, 0, 0.5)',
+        /** var(--color-bg-light) in CSS */
+        navBg: '#17202e',
+        navWidth: '168px',
+    },
     font: {
         family: 'Roboto',
         sizeBase: '12px',

package/lib/common/src/utils/cache.d.ts

@@ -20,12 +20,16 @@ export declare const ObjectStringToDate: (obj: unknown) => void;
 export declare function CacheFuncMapBase(arr: [k: string, v: Map<string, unknown>][], Save: IServerSaveBasePromise): {
     load(): Promise<void>;
     save(): Promise<void>;
+    saveDebounced(delay?: number): void;
+    flush(): Promise<void>;
     clear(): Promise<void>;
     getArr: [k: string, v: Map<string, unknown>][];
 };
 export declare function CacheFuncMap(arr: [k: string, v: Map<string, unknown>][]): {
     load(): Promise<void>;
     save(): Promise<void>;
+    saveDebounced(delay?: number): void;
+    flush(): Promise<void>;
     clear(): Promise<void>;
     getArr: [k: string, v: Map<string, unknown>][];
 };

package/lib/common/src/utils/cache.js

@@ -99,6 +99,43 @@ function isDate(_date) {
     return ISO_DATE_RE.test(_date);
 }
 export function CacheFuncMapBase(arr, Save) {
+    const savedPayloadByKey = new Map();
+    let saveTimer = null;
+    let runningSave = null;
+    const getPayloads = () => arr.map(([key, map]) => [key, JSON.stringify([...map.entries()])]);
+    const rememberCurrentPayloads = () => {
+        savedPayloadByKey.clear();
+        for (const [key, payload] of getPayloads())
+            savedPayloadByKey.set(key, payload);
+    };
+    const cancelDebouncedSave = () => {
+        if (saveTimer === null)
+            return;
+        clearTimeout(saveTimer);
+        saveTimer = null;
+    };
+    const saveChangedPayloads = async () => {
+        for (const [key, payload] of getPayloads()) {
+            if (savedPayloadByKey.get(key) === payload)
+                continue;
+            if (await Save.set(key, JSON.parse(payload))) {
+                savedPayloadByKey.set(key, payload);
+            }
+        }
+    };
+    const trackSave = (savePromise) => {
+        const trackedPromise = savePromise.catch(() => undefined).finally(() => {
+            if (runningSave === trackedPromise)
+                runningSave = null;
+        });
+        runningSave = trackedPromise;
+        return savePromise;
+    };
+    const queueSave = () => {
+        if (runningSave === null)
+            return trackSave(saveChangedPayloads());
+        return trackSave(runningSave.then(saveChangedPayloads, saveChangedPayloads));
+    };
     return {
         async load() {
             for (let [k, v] of arr) {
@@ -108,13 +145,25 @@ export function CacheFuncMapBase(arr, Save) {
                 ObjectStringToDate(t);
                 addDataToMap(t, v);
             }
+            rememberCurrentPayloads();
         },
         async save() {
-            for (let [k, v] of arr) {
-                await Save.set(k, [...v.entries()]);
-            }
+            await queueSave();
+        },
+        saveDebounced(delay = 800) {
+            cancelDebouncedSave();
+            saveTimer = setTimeout(() => {
+                saveTimer = null;
+                void queueSave();
+            }, delay);
+        },
+        async flush() {
+            cancelDebouncedSave();
+            await queueSave();
         },
         async clear() {
+            cancelDebouncedSave();
+            savedPayloadByKey.clear();
             for (let [k, v] of arr) {
                 await Save.delete(k);
             }

package/lib/common/src/utils/callbackHub.d.ts

@@ -0,0 +1,10 @@
+/** Multiplexer for a single-slot callback API (onX(cb | null)): many subscribers share
+ *  one slot instead of silently overwriting each other.
+ *  bind(emit) is called lazily, ONCE, on the first on() - not at creation time, because
+ *  the slot may still be taken by app initialization. */
+export declare function createCallbackHub<Args extends any[]>(bind: (emit: (...a: Args) => void) => void): {
+    /** Subscribe; the returned function unsubscribes without touching other subscribers.
+     *  The callback is registered BEFORE bind runs, so it also catches synchronous emits. */
+    on(cb: (...a: Args) => void): () => void;
+    count: () => number;
+};

package/lib/common/src/utils/callbackHub.js

@@ -0,0 +1,23 @@
+/** Multiplexer for a single-slot callback API (onX(cb | null)): many subscribers share
+ *  one slot instead of silently overwriting each other.
+ *  bind(emit) is called lazily, ONCE, on the first on() - not at creation time, because
+ *  the slot may still be taken by app initialization. */
+export function createCallbackHub(bind) {
+    const subs = new Set();
+    let bound = false;
+    // copy before iterating: an unsubscribe from inside a callback must not skip the rest
+    const emit = (...a) => { [...subs].forEach(cb => cb(...a)); };
+    return {
+        /** Subscribe; the returned function unsubscribes without touching other subscribers.
+         *  The callback is registered BEFORE bind runs, so it also catches synchronous emits. */
+        on(cb) {
+            subs.add(cb);
+            if (!bound) {
+                bound = true;
+                bind(emit);
+            }
+            return () => { subs.delete(cb); };
+        },
+        count: () => subs.size,
+    };
+}

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

@@ -1,6 +1,7 @@
 export * from './applyTransactionAsyncUpdate';
 export * from './arrayPromise';
 export * from './cache';
+export * from './callbackHub';
 export * from './inputAutoStep';
 export * from './mapMemory';
 export * from './pageVisibilityContext';

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

@@ -1,6 +1,7 @@
 export * from './applyTransactionAsyncUpdate';
 export * from './arrayPromise';
 export * from './cache';
+export * from './callbackHub';
 export * from './inputAutoStep';
 export * from './mapMemory';
 export * from './pageVisibilityContext';

package/lib/common/src/utils/mapMemory.d.ts

@@ -10,6 +10,8 @@ export declare function staticGetById<T extends object>(key: any, def: T, id: st
 export declare const Cash: {
     load(): Promise<void>;
     save(): Promise<void>;
+    saveDebounced(delay?: number): void;
+    flush(): Promise<void>;
     clear(): Promise<void>;
     getArr: [k: string, v: Map<string, unknown>][];
 };

package/lib/style/style.css

@@ -385,3 +385,72 @@ body {
   top: var(--wnd-close-top, -12px);
   right: var(--wnd-close-right, -12px);
 }
+
+/* Settings dialog (SettingsDialog). Themed via --dlg-* (tokens.css), dark defaults. */
+.wenayDlgScrim {
+  position: fixed;
+  inset: 0;
+  z-index: var(--wenay-z-modal, 9999);
+  background: var(--dlg-scrim, rgba(0, 0, 0, 0.5));
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+.wenayDlg {
+  position: relative;
+  display: flex;
+  width: 640px;
+  height: 420px;
+  max-width: 92vw;
+  max-height: 82vh;
+  background: var(--dlg-bg, var(--color-bg-dark));
+  border: var(--dlg-border, 1px solid var(--color-border-common));
+  border-radius: var(--dlg-radius, 10px);
+  box-shadow: var(--dlg-shadow, 0 12px 40px rgba(0, 0, 0, 0.5));
+  color: var(--color-text-base);
+  overflow: hidden;
+}
+.wenayDlgNav {
+  width: var(--dlg-nav-width, 168px);
+  flex: none;
+  background: var(--dlg-nav-bg, var(--color-bg-light));
+  padding: 10px 8px;
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  overflow-y: auto;
+}
+.wenayDlgContent {
+  position: relative;
+  flex: 1;
+  min-width: 0;
+  padding: 14px 40px 14px 16px;
+  overflow: auto;
+}
+/* Positioning of the close button in the dialog's top-right corner (over the content column).
+   A direct child of .wenayDlg, NOT of the scrollable content, so it does not scroll away. */
+.wenayDlgClose {
+  position: absolute;
+  top: 8px;
+  right: 8px;
+}
+/* Minimal default section/segment buttons; apps override via sectionClassName /
+   sectionActiveClassName (SettingsDialog) and className / activeClassName (PlacementSetting) */
+.wenayDlgSection,
+.wenaySegBtn {
+  padding: 6px 10px;
+  border-radius: 6px;
+  cursor: pointer;
+  user-select: none;
+  text-align: left;
+  color: inherit;
+}
+.wenayDlgSection:hover,
+.wenaySegBtn:hover {
+  background: rgba(255, 255, 255, 0.08);
+}
+.wenayDlgSectionActive,
+.wenaySegBtnActive {
+  background: rgba(255, 255, 255, 0.16);
+  color: #fff;
+}

package/lib/style/tokens.css

@@ -62,6 +62,16 @@
   --wnd-close-hover: #fff;
   --wnd-close-hover-bg: #e5484d;
 
+  /* Settings dialog (SettingsDialog). Dark defaults close to current apps;
+     apps re-skin via :root[data-theme='...'] overrides, same contract as --wnd-*. */
+  --dlg-scrim: rgba(0, 0, 0, 0.5);
+  --dlg-bg: var(--color-bg-dark);
+  --dlg-border: 1px solid var(--color-border-common);
+  --dlg-radius: 10px;
+  --dlg-shadow: 0 12px 40px rgba(0, 0, 0, 0.5);
+  --dlg-nav-bg: var(--color-bg-light);
+  --dlg-nav-width: 168px;
+
   /* Layers */
   --wenay-z-modal: 9999;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wenay-react2",
-  "version": "1.0.28",
+  "version": "1.0.29",
   "description": "Common react",
   "strict": true,
   "main": "dist/index.js",