@design-edito/tools 0.4.5 → 0.4.6

package/components/Theatre/index.js

@@ -1,138 +1,90 @@
-// src/components/Theatre/index.tsx
-import {
-  useEffect,
-  useState,
-  useRef
-} from "react";
-
-// src/agnostic/css/clss/index.ts
-function clss(blockNames, options) {
-  const blockNamesArr = Array.isArray(blockNames) ? blockNames : [blockNames];
-  return (eltNames = null, modNames = []) => {
-    const eltNamesArr = Array.isArray(eltNames) ? eltNames : [eltNames];
-    const modNamesArr = (Array.isArray(modNames) ? modNames : [modNames]).map((modName) => {
-      if (typeof modName === "string") return modName;
-      const trueModNames = Object.entries(modName).filter((entry) => entry[1] === true).map(([key]) => key);
-      return trueModNames;
-    }).flat();
-    const outputClassesArr = [];
-    blockNamesArr.forEach((compName) => {
-      eltNamesArr.forEach((eltName) => {
-        const targetPublicClss = eltName === null ? compName : `${compName}__${eltName}`;
-        const targetPrivateClss = eltName === null ? options?.cssModule[options.cssModuleRoot ?? "root"] : options?.cssModule[eltName];
-        outputClassesArr.push(targetPublicClss);
-        if (targetPrivateClss !== void 0) outputClassesArr.push(targetPrivateClss);
-        modNamesArr.forEach((modName) => {
-          const targetModifiedPublicClss = `${targetPublicClss}--${modName}`;
-          const targetModifiedPrivateClss = eltName === null ? options?.cssModule[`${options.cssModuleRoot ?? "root"}--${modName}`] : options?.cssModule[`${eltName}--${modName}`];
-          outputClassesArr.push(targetModifiedPublicClss);
-          if (targetModifiedPrivateClss !== void 0) outputClassesArr.push(targetModifiedPrivateClss);
-        });
-      });
-    });
-    return outputClassesArr.join(" ");
-  };
-}
-
-// src/components/utils/index.tsx
-function mergeClassNames(...names) {
-  return names.map((name) => {
-    if (typeof name !== "string" && !Array.isArray(name)) return false;
-    if (Array.isArray(name)) return mergeClassNames(...name);
-    if (name.trim() === "") return false;
-    return name.trim();
-  }).filter((name) => typeof name === "string").join(" ");
-}
-
-// src/components/public-classnames.ts
-var theatre = "dsed-theatre";
-
-// src/components/Theatre/index.tsx
-import cssModule from "./styles.module.css";
-import { jsx, jsxs } from "react/jsx-runtime";
-var Theatre = ({
-  closeBtnContent,
-  openBtnContent,
-  isOn,
-  defaultIsOn,
-  exitOnEscape,
-  exitOnBgClick,
-  stateHandlers,
-  actionHandlers,
-  children,
-  className
-}) => {
-  const [internalIsOn, setInternalIsOn] = useState(defaultIsOn ?? false);
-  const stageRef = useRef(null);
-  const isTheatreOn = isOn ?? internalIsOn;
-  const prevIsTheatreOnRef = useRef(isTheatreOn);
-  const handleCloseBtnClick = () => {
-    actionHandlers?.toggleClick?.(isTheatreOn);
-    if (isOn === void 0) setInternalIsOn(false);
-  };
-  const handleOpenBtnClick = () => {
-    actionHandlers?.toggleClick?.(isTheatreOn);
-    if (isOn === void 0) setInternalIsOn(true);
-  };
-  const handleStageBgClick = (e) => {
-    if (exitOnBgClick !== true) return;
-    if (e.target !== stageRef.current) return;
-    actionHandlers?.toggleClick?.(isTheatreOn);
-    if (isOn === void 0) setInternalIsOn(false);
-  };
-  useEffect(() => {
-    if (prevIsTheatreOnRef.current !== isTheatreOn) {
-      stateHandlers?.toggled?.(isTheatreOn);
-      prevIsTheatreOnRef.current = isTheatreOn;
-    }
-  }, [isTheatreOn, stateHandlers]);
-  useEffect(() => {
-    if (exitOnEscape === true || !isTheatreOn || isOn !== void 0) return;
-    const listener = (e) => {
-      if (e.key !== "Escape") return;
-      actionHandlers?.toggleClick?.(isTheatreOn);
-      setInternalIsOn(false);
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useState, useRef } from 'react';
+import { clss } from '../../agnostic/css/clss/index.js';
+import { mergeClassNames } from '../utils/index.js';
+import { theatre as publicClassName } from '../public-classnames.js';
+import cssModule from './styles.module.css';
+/**
+ * Theatre mode component. Wraps content in a toggleable fullscreen-like "stage"
+ * overlay. Supports both controlled and uncontrolled usage.
+ *
+ * When `isOn` is not provided the component manages its own open/closed state
+ * internally. When `isOn` is provided it acts as the source of truth and the
+ * internal state is ignored.
+ *
+ * ### Root element modifiers
+ * The root `<div>` receives the public class name defined by `theatre` and the
+ * following BEM-style modifier classes:
+ * - `--on` — when theatre mode is active.
+ * - `--off` — when theatre mode is inactive.
+ *
+ * ### Child elements
+ * - `__stage` — container rendered inside the root that holds the duplicated
+ * `children` when theatre mode is active. Only mounted when `isOn` is `true`.
+ * - `__open-btn` — clickable element that activates theatre mode.
+ * - `__close-btn` — clickable element that deactivates theatre mode.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ * @returns A root `<div>` containing the children in their original position,
+ * a stage overlay with the duplicated children (when active), and the open/close
+ * toggle buttons.
+ */
+export const Theatre = ({ closeBtnContent, openBtnContent, isOn, defaultIsOn, exitOnEscape, exitOnBgClick, stateHandlers, actionHandlers, children, className }) => {
+    // State & refs
+    const [internalIsOn, setInternalIsOn] = useState(defaultIsOn ?? false);
+    const stageRef = useRef(null);
+    const isTheatreOn = isOn ?? internalIsOn;
+    const prevIsTheatreOnRef = useRef(isTheatreOn);
+    // Handlers
+    const handleCloseBtnClick = () => {
+        actionHandlers?.toggleClick?.(isTheatreOn);
+        if (isOn === undefined)
+            setInternalIsOn(false);
     };
-    window.addEventListener("keydown", listener);
-    return () => window.removeEventListener("keydown", listener);
-  }, [exitOnEscape, isTheatreOn, isOn]);
-  const c = clss(theatre, { cssModule });
-  const rootClss = mergeClassNames(c(null, {
-    "on": isTheatreOn,
-    "off": !isTheatreOn
-  }), className);
-  const stageClass = c("stage");
-  const openBtnClass = c("open-btn");
-  const closeBtnClass = c("close-btn");
-  return /* @__PURE__ */ jsxs("div", { className: rootClss, children: [
-    children,
-    /* @__PURE__ */ jsx(
-      "div",
-      {
-        className: stageClass,
-        onClick: handleStageBgClick,
-        ref: stageRef,
-        children: isTheatreOn && children
-      }
-    ),
-    /* @__PURE__ */ jsx(
-      "div",
-      {
-        className: closeBtnClass,
-        onClick: handleCloseBtnClick,
-        children: closeBtnContent
-      }
-    ),
-    /* @__PURE__ */ jsx(
-      "div",
-      {
-        className: openBtnClass,
-        onClick: handleOpenBtnClick,
-        children: openBtnContent
-      }
-    )
-  ] });
-};
-export {
-  Theatre
+    const handleOpenBtnClick = () => {
+        actionHandlers?.toggleClick?.(isTheatreOn);
+        if (isOn === undefined)
+            setInternalIsOn(true);
+    };
+    const handleStageBgClick = e => {
+        if (exitOnBgClick !== true)
+            return;
+        if (e.target !== stageRef.current)
+            return;
+        actionHandlers?.toggleClick?.(isTheatreOn);
+        if (isOn === undefined)
+            setInternalIsOn(false);
+    };
+    // Effects
+    useEffect(() => {
+        if (prevIsTheatreOnRef.current !== isTheatreOn) {
+            stateHandlers?.toggled?.(isTheatreOn);
+            prevIsTheatreOnRef.current = isTheatreOn;
+        }
+    }, [isTheatreOn, stateHandlers]);
+    useEffect(() => {
+        if (exitOnEscape === true
+            || !isTheatreOn
+            || isOn !== undefined)
+            return;
+        const listener = (e) => {
+            if (e.key !== 'Escape')
+                return;
+            actionHandlers?.toggleClick?.(isTheatreOn);
+            setInternalIsOn(false);
+        };
+        window.addEventListener('keydown', listener);
+        return () => window.removeEventListener('keydown', listener);
+    }, [exitOnEscape, isTheatreOn, isOn]);
+    // Render
+    const c = clss(publicClassName, { cssModule });
+    const rootClss = mergeClassNames(c(null, {
+        'on': isTheatreOn,
+        'off': !isTheatreOn
+    }), className);
+    const stageClass = c('stage');
+    const openBtnClass = c('open-btn');
+    const closeBtnClass = c('close-btn');
+    return _jsxs("div", { className: rootClss, children: [children, _jsx("div", { className: stageClass, onClick: handleStageBgClick, ref: stageRef, children: isTheatreOn && children }), _jsx("div", { className: closeBtnClass, onClick: handleCloseBtnClick, children: closeBtnContent }), _jsx("div", { className: openBtnClass, onClick: handleOpenBtnClick, children: openBtnContent })] });
 };

package/components/UIModule/index.js

@@ -1,202 +1,159 @@
-// src/components/UIModule/index.tsx
-import {
-  useEffect,
-  useRef,
-  useState
-} from "react";
-
-// src/agnostic/css/clss/index.ts
-function clss(blockNames, options) {
-  const blockNamesArr = Array.isArray(blockNames) ? blockNames : [blockNames];
-  return (eltNames = null, modNames = []) => {
-    const eltNamesArr = Array.isArray(eltNames) ? eltNames : [eltNames];
-    const modNamesArr = (Array.isArray(modNames) ? modNames : [modNames]).map((modName) => {
-      if (typeof modName === "string") return modName;
-      const trueModNames = Object.entries(modName).filter((entry) => entry[1] === true).map(([key]) => key);
-      return trueModNames;
-    }).flat();
-    const outputClassesArr = [];
-    blockNamesArr.forEach((compName) => {
-      eltNamesArr.forEach((eltName) => {
-        const targetPublicClss = eltName === null ? compName : `${compName}__${eltName}`;
-        const targetPrivateClss = eltName === null ? options?.cssModule[options.cssModuleRoot ?? "root"] : options?.cssModule[eltName];
-        outputClassesArr.push(targetPublicClss);
-        if (targetPrivateClss !== void 0) outputClassesArr.push(targetPrivateClss);
-        modNamesArr.forEach((modName) => {
-          const targetModifiedPublicClss = `${targetPublicClss}--${modName}`;
-          const targetModifiedPrivateClss = eltName === null ? options?.cssModule[`${options.cssModuleRoot ?? "root"}--${modName}`] : options?.cssModule[`${eltName}--${modName}`];
-          outputClassesArr.push(targetModifiedPublicClss);
-          if (targetModifiedPrivateClss !== void 0) outputClassesArr.push(targetModifiedPrivateClss);
-        });
-      });
-    });
-    return outputClassesArr.join(" ");
-  };
-}
-
-// src/agnostic/errors/unknown-to-string/index.ts
-function unknownToString(unk, encoding) {
-  if (unk instanceof Error) return unk.message;
-  if (unk instanceof Buffer) return unk.toString(encoding ?? "utf-8");
-  if (typeof unk === "string") return unk;
-  if (typeof unk === "object" && unk !== null) return JSON.stringify(unk);
-  return `${unk}`;
-}
-
-// src/agnostic/objects/is-object/index.ts
-function isObject(unk) {
-  return typeof unk === "object";
-}
-function isNonNullObject(unk) {
-  return unk !== null && isObject(unk);
-}
-
-// src/agnostic/random/hex-char/index.ts
-var hexChars = ["0", "1", "2", "3", "4", "5", "6", "7", "8", "9", "a", "b", "c", "d", "e", "f"];
-function randomHexChar() {
-  const nbr = Math.floor(Math.random() * 16);
-  const char = hexChars[nbr];
-  return char;
-}
-
-// src/agnostic/random/uuid/index.ts
-function randomHash(length = 4) {
-  return new Array(length).fill(null).map(randomHexChar).join("");
-}
-
-// src/components/utils/index.tsx
-function mergeClassNames(...names) {
-  return names.map((name) => {
-    if (typeof name !== "string" && !Array.isArray(name)) return false;
-    if (Array.isArray(name)) return mergeClassNames(...name);
-    if (name.trim() === "") return false;
-    return name.trim();
-  }).filter((name) => typeof name === "string").join(" ");
-}
-
-// src/components/public-classnames.ts
-var uiModule = "dsed-ui-module";
-
-// src/components/UIModule/index.tsx
-import cssModule from "./styles.module.css";
-import { jsx, jsxs } from "react/jsx-runtime";
-var UIModule = ({
-  src,
-  props,
-  stateHandlers,
-  className
-}) => {
-  const [id] = useState(`f${randomHash(10)}`);
-  const [loading, setLoading] = useState(false);
-  const [loadedModule, _setLoadedModule] = useState(null);
-  const [moduleTarget, _setModuleTarget] = useState(null);
-  const rootRef = useRef(null);
-  const loadedModuleRef = useRef(null);
-  const moduleTargetRef = useRef(null);
-  const setLoadedModule = (data) => {
-    loadedModuleRef.current = data;
-    _setLoadedModule(data);
-  };
-  const setModuleTarget = (data) => {
-    moduleTargetRef.current = data;
-    _setModuleTarget(data);
-  };
-  useEffect(() => {
-    stateHandlers?.idChanged?.(id);
-  }, [id, stateHandlers]);
-  useEffect(() => {
-    stateHandlers?.isLoadingChanged?.(loading);
-  }, [loading, stateHandlers]);
-  useEffect(() => {
-    stateHandlers?.loadedModuleChanged?.(loadedModule);
-  }, [loadedModule, stateHandlers]);
-  useEffect(() => {
-    stateHandlers?.moduleTargetChanged?.(moduleTarget);
-  }, [moduleTarget, stateHandlers]);
-  useEffect(() => {
-    if (src === void 0) return;
-    try {
-      setLoading(true);
-      import(src).then((data) => {
-        setLoading(false);
-        const errs = {
-          notMod: new Error("Not a module"),
-          initFunc: new Error("Module exported member `init` must be a function"),
-          destroyFunc: new Error("Module exported member `destroy` must be a function"),
-          cssStrArr: new Error("Module exported member `css` must be an array of strings"),
-          updFunc: new Error("Module exported member `update` must be a function"),
-          initRetElt: new Error("Module exported function `init` must return an Element"),
-          initRetFirstElt: new Error("Module exported function `init` must return an array containing an Element in its first position")
-        };
-        if (!isNonNullObject(data)) return setLoadedModule(errs.notMod);
-        if (!("init" in data)) return setLoadedModule(errs.initFunc);
-        if (typeof data.init !== "function") return setLoadedModule(errs.initFunc);
-        if (!("destroy" in data) || typeof data.destroy !== "function") return setLoadedModule(errs.destroyFunc);
-        if ("css" in data) {
-          if (!Array.isArray(data.css)) return setLoadedModule(errs.cssStrArr);
-          if (data.css.some((i) => typeof i !== "string")) return setLoadedModule(errs.cssStrArr);
-        }
-        if ("update" in data && typeof data.update !== "function") return setLoadedModule(errs.updFunc);
-        const module = data;
-        setLoadedModule(module);
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useRef, useState } from 'react';
+import { clss } from '../../agnostic/css/clss/index.js';
+import { unknownToString } from '../../agnostic/errors/unknown-to-string/index.js';
+import { isNonNullObject } from '../../agnostic/objects/is-object/index.js';
+import { randomHash } from '../../agnostic/random/uuid/index.js';
+import { mergeClassNames } from '../utils/index.js';
+import { uiModule as publicClassName } from '../public-classnames.js';
+import cssModule from './styles.module.css';
+/**
+ * Dynamic UI module host component. Asynchronously imports an ES module by URL,
+ * validates its exported interface, calls its `init` lifecycle to obtain a DOM
+ * `Element`, and appends that element to its own root `<div>`. Handles loading,
+ * error, and teardown states automatically.
+ *
+ * The imported module is expected to conform to the {@link ModuleData} interface.
+ * Any violation (missing exports, wrong types, `init` not returning an `Element`)
+ * transitions the component into the `--error` state and logs to `console.error`.
+ *
+ * ### Root element modifiers
+ * The root `<div>` receives the public class name defined by `uiModule` and
+ * the following BEM-style modifier classes reflecting the current load lifecycle:
+ * - `--loading` — the module fetch is in progress.
+ * - `--no-module` — no module has been loaded yet (`src` is undefined or the
+ * effect has not run).
+ * - `--error` — the import, validation, or `init` call failed.
+ * - `--loaded` — the module passed validation and `init` returned successfully.
+ * - `--initialized` — the `Element` returned by `init` has been appended to the
+ * host `<div>`.
+ *
+ * ### Root element attributes
+ * - `id` — a stable randomly generated ID (prefixed `f`) assigned once on mount.
+ * Used to scope the module's `css` entries to this specific instance.
+ *
+ * @param props - Component properties.
+ * @see {@link Props}
+ * @see {@link ModuleData}
+ * @returns A host `<div>` into which the module's root `Element` is appended,
+ * along with any `<style>` blocks exported by the module.
+ */
+export const UIModule = ({ src, props, stateHandlers, className }) => {
+    // State & refs
+    const [id] = useState(`f${randomHash(10)}`);
+    const [loading, setLoading] = useState(false);
+    const [loadedModule, _setLoadedModule] = useState(null);
+    const [moduleTarget, _setModuleTarget] = useState(null);
+    const rootRef = useRef(null);
+    const loadedModuleRef = useRef(null);
+    const moduleTargetRef = useRef(null);
+    const setLoadedModule = (data) => {
+        loadedModuleRef.current = data;
+        _setLoadedModule(data);
+    };
+    const setModuleTarget = (data) => {
+        moduleTargetRef.current = data;
+        _setModuleTarget(data);
+    };
+    // State changes dispatch
+    useEffect(() => { stateHandlers?.idChanged?.(id); }, [id, stateHandlers]);
+    useEffect(() => { stateHandlers?.isLoadingChanged?.(loading); }, [loading, stateHandlers]);
+    useEffect(() => { stateHandlers?.loadedModuleChanged?.(loadedModule); }, [loadedModule, stateHandlers]);
+    useEffect(() => { stateHandlers?.moduleTargetChanged?.(moduleTarget); }, [moduleTarget, stateHandlers]);
+    // Fx dep. `src` - load & init module effect
+    useEffect(() => {
+        if (src === undefined)
+            return;
         try {
-          const target = module.init(props ?? {});
-          if (!(target instanceof Element)) return setLoadedModule(errs.initRetElt);
-          setModuleTarget(target);
-        } catch (err) {
-          setModuleTarget(null);
-          const e = err instanceof Error ? err : new Error(unknownToString(err));
-          setLoadedModule(e);
+            setLoading(true);
+            import(src)
+                .then(data => {
+                setLoading(false);
+                const errs = {
+                    notMod: new Error('Not a module'),
+                    initFunc: new Error('Module exported member `init` must be a function'),
+                    destroyFunc: new Error('Module exported member `destroy` must be a function'),
+                    cssStrArr: new Error('Module exported member `css` must be an array of strings'),
+                    updFunc: new Error('Module exported member `update` must be a function'),
+                    initRetElt: new Error('Module exported function `init` must return an Element'),
+                    initRetFirstElt: new Error('Module exported function `init` must return an array containing an Element in its first position')
+                };
+                if (!isNonNullObject(data))
+                    return setLoadedModule(errs.notMod);
+                if (!('init' in data))
+                    return setLoadedModule(errs.initFunc);
+                if (typeof data.init !== 'function')
+                    return setLoadedModule(errs.initFunc);
+                if (!('destroy' in data) || typeof data.destroy !== 'function')
+                    return setLoadedModule(errs.destroyFunc);
+                if ('css' in data) {
+                    if (!Array.isArray(data.css))
+                        return setLoadedModule(errs.cssStrArr);
+                    if (data.css.some(i => typeof i !== 'string'))
+                        return setLoadedModule(errs.cssStrArr);
+                }
+                if ('update' in data && typeof data.update !== 'function')
+                    return setLoadedModule(errs.updFunc);
+                const module = data;
+                setLoadedModule(module);
+                try {
+                    const target = module.init(props ?? {});
+                    if (!(target instanceof Element))
+                        return setLoadedModule(errs.initRetElt);
+                    setModuleTarget(target);
+                }
+                catch (err) {
+                    setModuleTarget(null);
+                    const e = err instanceof Error
+                        ? err
+                        : new Error(unknownToString(err));
+                    setLoadedModule(e);
+                }
+            }).catch(err => {
+                setLoading(false);
+                setLoadedModule(err instanceof Error ? err : new Error(unknownToString(err)));
+                setModuleTarget(null);
+            });
         }
-      }).catch((err) => {
-        setLoading(false);
-        setLoadedModule(err instanceof Error ? err : new Error(unknownToString(err)));
-        setModuleTarget(null);
-      });
-    } catch (err) {
-      if (err instanceof Error) return setLoadedModule(err);
-      const errStr = unknownToString(err);
-      return setLoadedModule(new Error(errStr));
-    }
-    return () => {
-      if (moduleTargetRef.current === null) return;
-      if (loadedModuleRef.current instanceof Error) return;
-      if (loadedModuleRef.current === null) return;
-      loadedModuleRef.current.destroy(moduleTargetRef.current);
-    };
-  }, [src]);
-  useEffect(() => {
-    if (loadedModule instanceof Error) console.error(loadedModule);
-  }, [loadedModule]);
-  useEffect(() => {
-    if (moduleTarget === null) return;
-    if (rootRef.current === null) return;
-    rootRef.current.appendChild(moduleTarget);
-  }, [moduleTarget]);
-  const c = clss(uiModule, { cssModule });
-  const rootClss = mergeClassNames(
-    c(null, {
-      loading,
-      "no-module": loadedModule === null,
-      "error": loadedModule instanceof Error,
-      "loaded": !loading && loadedModule !== null && !(loadedModule instanceof Error),
-      "initialized": moduleTarget !== null
-    }),
-    className
-  );
-  return /* @__PURE__ */ jsxs(
-    "div",
-    {
-      className: rootClss,
-      ref: rootRef,
-      id,
-      children: [
-        loadedModule === null && "",
-        loadedModule !== null && !(loadedModule instanceof Error) && loadedModule.css?.map((css) => /* @__PURE__ */ jsx("style", { children: `.${uiModule}#${id} { ${css} }` }))
-      ]
-    }
-  );
-};
-export {
-  UIModule
+        catch (err) {
+            if (err instanceof Error)
+                return setLoadedModule(err);
+            const errStr = unknownToString(err);
+            return setLoadedModule(new Error(errStr));
+        }
+        return () => {
+            if (moduleTargetRef.current === null)
+                return;
+            if (loadedModuleRef.current instanceof Error)
+                return;
+            if (loadedModuleRef.current === null)
+                return;
+            loadedModuleRef.current.destroy(moduleTargetRef.current);
+        };
+    }, [src]);
+    // Fx dep. `loadedModule` - log load errors
+    useEffect(() => {
+        if (loadedModule instanceof Error)
+            console.error(loadedModule);
+    }, [loadedModule]);
+    // Fx dep. `moduleTarget` - append the rendered module
+    useEffect(() => {
+        if (moduleTarget === null)
+            return;
+        if (rootRef.current === null)
+            return;
+        rootRef.current.appendChild(moduleTarget);
+    }, [moduleTarget]);
+    // Rendering
+    const c = clss(publicClassName, { cssModule });
+    const rootClss = mergeClassNames(c(null, {
+        loading,
+        'no-module': loadedModule === null,
+        'error': loadedModule instanceof Error,
+        'loaded': !loading && loadedModule !== null && !(loadedModule instanceof Error),
+        'initialized': moduleTarget !== null
+    }), className);
+    return _jsxs("div", { className: rootClss, ref: rootRef, id: id, children: [loadedModule === null && '', loadedModule !== null
+                && !(loadedModule instanceof Error)
+                && loadedModule.css?.map(css => _jsx("style", { children: `.${publicClassName}#${id} { ${css} }` }))] });
 };