@johnhenry/definable 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Henry
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# definable
+
+[![npm version](https://img.shields.io/npm/v/%40johnhenry%2Fdefinable.svg)](https://www.npmjs.com/package/@johnhenry/definable)
+[![CI](https://github.com/johnhenry/definable/actions/workflows/ci.yml/badge.svg)](https://github.com/johnhenry/definable/actions/workflows/ci.yml)
+[![license](https://img.shields.io/npm/l/%40johnhenry%2Fdefinable.svg)](LICENSE)
+
+Full documentation: [opensource.johnhenry.me/definable](https://opensource.johnhenry.me/definable/)
+
+> **Provenance:** extracted from [`johnhenry/lib`](https://github.com/johnhenry/lib)'s
+> `js/` directory. Briefly part of [`@johnhenry/domkit`](https://github.com/johnhenry/domkit)
+> (a toolkit of ~40 independent DOM/HTML-component modules), then split out
+> as its own package because this cluster has a real internal shape of its
+> own -- four ways of getting behavior onto a page declaratively, from four
+> different kinds of source.
+
+Five small modules for declaratively loading or defining custom elements
+and globals, without writing a `customElements.define(...)` call by hand:
+
+| Module | What it does |
+|---|---|
+| [`definetag`](src/definetag/readme.md) | Curried `customElements.define` wrapper: `(elementClass) => (name) => ...`. The low-level primitive the others build on. |
+| [`define-component.component`](src/define-component.component/readme.md) | `<define-component name="x" src="./x.mjs">` -- dynamically imports a module by URL and registers its export as a custom element. |
+| [`define-component-by-content.component`](src/define-component-by-content.component/readme.md) | `<define-component-by-content name="x" content="<p>Hi</p>">` -- defines a custom element from an inline HTML string instead of a separate module file. Built on [`@johnhenry/domable`](https://github.com/johnhenry/domable)'s `simple-element`. |
+| [`polyfill-window.component`](src/polyfill-window.component/readme.md) | `<polyfill-window name="x" src="./x.mjs">` -- the same URL-loading idea as `define-component`, but assigns the import to a `globalThis` key instead of registering a custom element. |
+| [`until-window-load`](src/until-window-load/readme.md) | Declarative "remove this loading class once `window` has loaded" helper -- used by `polyfill-window.component`'s own demo to avoid a flash of unstyled content. |
+
+## Install
+
+```sh
+npm install @johnhenry/definable
+```
+
+```js
+import definetag from "@johnhenry/definable/definetag/index.mjs";
+```
+
+or, in a browser with no build step, via a CDN:
+
+```html
+<script
+  type="module"
+  src="https://esm.sh/@johnhenry/definable/define-component.component/global.mjs"
+></script>
+<define-component name="my-widget" src="./my-widget.mjs"></define-component>
+<my-widget></my-widget>
+```
+
+## Which one do I want?
+
+| I have... | Use |
+|---|---|
+| A module file (default or named export is a custom-element class) | `define-component.component` |
+| A small HTML string I want to become a tag | `define-component-by-content.component` |
+| A module whose export should just be a global, not a tag | `polyfill-window.component` |
+| My own class already, just need to register it under a name | `definetag` directly |
+
+## Family
+
+- [`@johnhenry/domable`](https://github.com/johnhenry/domable) -- `define-component-by-content.component`
+  depends on its `simple-element` `constructSuperclass` for building the
+  actual custom-element class from an HTML string.
+- [`@johnhenry/domkit`](https://github.com/johnhenry/domkit) -- the toolkit
+  this package was originally part of. Several of its still-resident
+  modules (`animate-paths.component`, `chernoff-face`, `xy-grapher`) depend
+  on `definable` (`definetag`, `define-component.component`) to register
+  themselves.
+- [`@johnhenry/respondable`](https://github.com/johnhenry/respondable) --
+  `query-container.component`'s own demo bootstraps via this package's
+  `define-component.component`.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@johnhenry/definable",
+  "version": "0.0.0",
+  "description": "Load or define custom elements declaratively -- from a URL, from inline HTML content, or as a plain global polyfill.",
+  "type": "module",
+  "exports": {
+    "./*": "./src/*"
+  },
+  "files": [
+    "src/"
+  ],
+  "scripts": {
+    "test": "node scripts/check-syntax.mjs"
+  },
+  "keywords": [
+    "html",
+    "dom",
+    "web-components",
+    "custom-elements",
+    "define"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/johnhenry/definable.git"
+  },
+  "homepage": "https://opensource.johnhenry.me/definable/",
+  "engines": {
+    "node": ">=26.0.0"
+  },
+  "dependencies": {
+    "@johnhenry/domable": "^0.0.1"
+  }
+}

package/src/define-component-by-content.component/global.mjs

@@ -0,0 +1,3 @@
+import definetag from "../definetag/index.mjs";
+import DefineComponentByContent from "./index.mjs";
+definetag(DefineComponentByContent)("define-component-by-content");

package/src/define-component-by-content.component/index.mjs

@@ -0,0 +1,28 @@
+import { constructSuperclass } from "@johnhenry/domable/simple-element";
+
+export default class extends globalThis.HTMLElement {
+  constructor() {
+    super();
+  }
+  connectedCallback() {
+    const name = this.getAttribute("name");
+    const useShadow = this.getAttribute("shadow") || false;
+    const shadowMode = this.getAttribute("mode") || "open";
+    const content = this.getAttribute("content") || "";
+    const useDom = this.getAttribute("use-dom") || "";
+    // this.querySelector("slot").innerHTML = content;
+
+    globalThis.customElements.define(
+      name,
+      class extends constructSuperclass({
+        [useDom ? "HTML" : "shadowHTML"]: content,
+        useShadow,
+        shadowMode,
+      }) {
+        constructor() {
+          super();
+        }
+      }
+    );
+  }
+}

package/src/define-component-by-content.component/readme.md

@@ -0,0 +1,32 @@
+# Define Component By Content
+
+Defines a new custom element whose markup comes from an HTML string given
+directly as an attribute, rather than from a separate module file (compare
+[define-component.component](../define-component.component/readme.md),
+which loads markup/behavior from a URL instead).
+
+Built on [`@johnhenry/domable`](https://github.com/johnhenry/domable)'s
+`simple-element` `constructSuperclass`.
+
+## Attributes
+
+| Attribute | Description |
+|---|---|
+| `name` | Tag name to register (required) |
+| `content` | HTML string to render |
+| `use-dom` | If present, `content` renders as light DOM (`append`ed directly); if absent (default), `content` renders inside an open shadow root |
+| `mode` | Shadow root mode when `use-dom` is absent. Defaults to `"open"` |
+
+## Usage
+
+```html
+<script
+  type="module"
+  src="https://esm.sh/@johnhenry/definable/define-component-by-content.component/global.mjs"
+></script>
+<define-component-by-content
+  name="my-greeting"
+  content="<p>Hello!</p>"
+></define-component-by-content>
+<my-greeting></my-greeting>
+```

package/src/define-component.component/demo-widget.mjs

@@ -0,0 +1,5 @@
+export default class extends HTMLElement {
+  connectedCallback() {
+    this.textContent = "Hello from a dynamically defined component!";
+  }
+}

package/src/define-component.component/demo.html

@@ -0,0 +1,3 @@
+<script type="module" src="./global.mjs"></script>
+<define-component name="my-widget" src="./demo-widget.mjs"></define-component>
+<my-widget></my-widget>

package/src/define-component.component/global.mjs

@@ -0,0 +1,2 @@
+import DefineComponent from "./index.mjs";
+globalThis.customElements.define("define-component", DefineComponent);

package/src/define-component.component/index.mjs

@@ -0,0 +1,36 @@
+// Dynamically imports a module and registers its default (or named) export
+// as a custom element. Adapted from polyfill-window.component/index.mjs's
+// URL-resolution logic, but ends in customElements.define(...) instead of a
+// global assignment -- see readme.md.
+const define = async (src, name, imp, force) => {
+  const { href } = globalThis.location;
+  const indexQM = href.lastIndexOf("?");
+  const withoutQuery = indexQM === -1 ? href : href.substring(0, indexQM);
+  const indexS = withoutQuery.lastIndexOf("/");
+  const dirname =
+    indexS === -1 ? withoutQuery : withoutQuery.substring(0, indexS);
+  const url = new URL(src, dirname + "/");
+  if (globalThis.customElements.get(name) && force === null) {
+    return;
+  }
+  const module = await import(url.href);
+  const ElementClass = module[imp ?? "default"];
+  globalThis.customElements.define(name, ElementClass);
+};
+
+export default class extends globalThis.HTMLElement {
+  #name = "";
+  #src = "";
+  #import = null;
+  #force = false;
+  constructor() {
+    super();
+  }
+  connectedCallback() {
+    this.#name = this.getAttribute("name");
+    this.#src = this.getAttribute("src");
+    this.#import = this.getAttribute("import");
+    this.#force = this.getAttribute("force");
+    define(this.#src, this.#name, this.#import, this.#force);
+  }
+}

package/src/define-component.component/readme.md

@@ -0,0 +1,32 @@
+# Define Component
+
+Dynamically loads a module by URL and registers its export as a custom
+element — the generic "define a component from a URL" pattern referenced
+by [polyfill-window.component](../polyfill-window.component/readme.md)'s
+own demo, and by [`@johnhenry/respondable`](https://github.com/johnhenry/respondable)'s
+`query-container.component` and [`@johnhenry/domkit`](https://github.com/johnhenry/domkit)'s
+`animate-paths.component`, both of which bootstrap via this exact pattern.
+
+Compare [define-component-by-content.component](../define-component-by-content.component/readme.md),
+which defines a component from an inline HTML string instead of a separate
+module file.
+
+## Attributes
+
+| Attribute | Description |
+|---|---|
+| `name` | Tag name to register (required) |
+| `src` | URL of the module to import, resolved relative to the current document (required) |
+| `import` | Named export to use as the element class. Defaults to the module's default export |
+| `force` | If present, re-imports and re-registers even if `name` is already a registered custom element |
+
+## Usage
+
+```html
+<script
+  type="module"
+  src="https://esm.sh/@johnhenry/definable/define-component.component/global.mjs"
+></script>
+<define-component name="my-widget" src="./my-widget.mjs"></define-component>
+<my-widget></my-widget>
+```

package/src/definetag/index.mjs

@@ -0,0 +1,13 @@
+export default (elementClass) => (name) =>
+  globalThis.customElements.define(name, elementClass);
+
+// export default (elementClass) => (name) => {
+//   try {
+//     globalThis.customElements.define(name, elementClass);
+//   } catch (e) {
+//     console.error(e);
+//   } finally {
+//     console.log({ elementClass });
+//     console.log({ name });
+//   }
+// };

package/src/definetag/readme.md

@@ -0,0 +1,18 @@
+# Define Tag
+
+A curried `customElements.define` wrapper: `(elementClass) => (name) =>
+customElements.define(name, elementClass)`. Useful for separating "what a
+component's class is" from "what tag name it gets registered under" —
+several `.component` modules' `define.mjs`/`global.mjs` files use this
+instead of calling `customElements.define` directly. See
+[define-component-by-content.component](../define-component-by-content.component/readme.md)
+for a real consumer.
+
+## Usage
+
+```js
+import definetag from "../definetag/index.mjs";
+import MyComponent from "./my-component.mjs";
+
+definetag(MyComponent)("my-component");
+```

package/src/polyfill-window.component/broadcast-channel-polyfill.mjs

@@ -0,0 +1,89 @@
+// https://gist.github.com/sechel/e6aff22d9e56df02c5bd09c4afc516e6
+(function (global) {
+  var channels = [];
+
+  function BroadcastFlannel(channel) {
+    var $this = this;
+    channel = String(channel);
+
+    var id = "$BroadcastFlannel$" + channel + "$";
+
+    channels[id] = channels[id] || [];
+    channels[id].push(this);
+
+    this._name = channel;
+    this._id = id;
+    this._closed = false;
+    this._mc = new MessageChannel();
+    this._mc.port1.start();
+    this._mc.port2.start();
+
+    global.addEventListener("storage", function (e) {
+      if (e.storageArea !== global.localStorage) return;
+      if (e.newValue === null) return;
+      if (e.key.substring(0, id.length) !== id) return;
+      var data = JSON.parse(e.newValue);
+      $this._mc.port2.postMessage(data);
+    });
+  }
+
+  BroadcastFlannel.prototype = {
+    // BroadcastFlannel API
+    get name() {
+      return this._name;
+    },
+    postMessage: function (message) {
+      var $this = this;
+      if (this._closed) {
+        var e = new Error();
+        e.name = "InvalidStateError";
+        throw e;
+      }
+      var value = JSON.stringify(message);
+
+      // Broadcast to other contexts via storage events...
+      var key = this._id + String(Date.now()) + "$" + String(Math.random());
+      global.localStorage.setItem(key, value);
+      setTimeout(function () {
+        global.localStorage.removeItem(key);
+      }, 500);
+
+      // Broadcast to current context via ports
+      channels[this._id].forEach(function (bc) {
+        if (bc === $this) return;
+        bc._mc.port2.postMessage(JSON.parse(value));
+      });
+    },
+    close: function () {
+      if (this._closed) return;
+      this._closed = true;
+      this._mc.port1.close();
+      this._mc.port2.close();
+
+      var index = channels[this._id].indexOf(this);
+      channels[this._id].splice(index, 1);
+    },
+
+    // EventTarget API
+    get onmessage() {
+      return this._mc.port1.onmessage;
+    },
+    set onmessage(value) {
+      this._mc.port1.onmessage = value;
+    },
+    addEventListener: function (type, listener /*, useCapture*/) {
+      return this._mc.port1.addEventListener.apply(this._mc.port1, arguments);
+    },
+    removeEventListener: function (type, listener /*, useCapture*/) {
+      return this._mc.port1.removeEventListener.apply(
+        this._mc.port1,
+        arguments
+      );
+    },
+    dispatchEvent: function (event) {
+      return this._mc.port1.dispatchEvent.apply(this._mc.port1, arguments);
+    },
+  };
+
+  global.BroadcastFlannel = global.BroadcastFlannel || BroadcastFlannel;
+})(globalThis);

package/src/polyfill-window.component/demo.html

@@ -0,0 +1,21 @@
+<style>
+  .until-window-load {
+    visibility: hidden;
+  }
+</style>
+<script type="module" src="../until-window-load/index.mjs"></script>
+<script
+  type="module"
+  src="../define-component.component/global.mjs"
+></script>
+<define-component
+  class="until-window-load"
+  name="polyfill-window"
+  src="./index.mjs"
+></define-component>
+<polyfill-window name="shout" src="./shout-polyfill.mjs"></polyfill-window>
+<polyfill-window
+  name="BroadcastFhannel"
+  src="./broadcast-channel-polyfill.mjs"
+  no-import
+></polyfill-window>

package/src/polyfill-window.component/global.mjs

@@ -0,0 +1,2 @@
+import DefineComponent from "./index.mjs";
+globalThis.customElements.define("polyfill-window", DefineComponent);

package/src/polyfill-window.component/index.mjs

@@ -0,0 +1,35 @@
+const define = async (src, name, imp, force, noImport) => {
+  const { href } = globalThis.location;
+  const indexQM = href.lastIndexOf("?");
+  const withoutQuery = indexQM === -1 ? href : href.substring(0, indexQM);
+  const indexS = withoutQuery.lastIndexOf("/");
+  const dirname =
+    indexS === -1 ? withoutQuery : withoutQuery.substring(0, indexS);
+  const url = new URL(src, dirname + "/");
+  if (!globalThis[name] || force !== null) {
+    const module = await import(url.href);
+    if (!noImport) {
+      const E = module[imp ?? "default"];
+      globalThis[name] = E;
+    }
+  }
+};
+
+export default class extends globalThis.HTMLElement {
+  #name = "";
+  #src = "";
+  #import = null;
+  #force = false;
+  #noImport = false;
+  constructor() {
+    super();
+  }
+  connectedCallback() {
+    this.#name = this.getAttribute("name");
+    this.#src = this.getAttribute("src");
+    this.#import = this.getAttribute("import");
+    this.#force = this.getAttribute("force");
+    this.#noImport = this.getAttribute("no-import");
+    define(this.#src, this.#name, this.#import, this.#force, this.#noImport);
+  }
+}

package/src/polyfill-window.component/readme.md

@@ -0,0 +1,30 @@
+# Polyfill Window
+
+Dynamically imports a module and assigns its export to a key on
+`globalThis` -- for loading a global polyfill declaratively from HTML,
+rather than registering a custom element (compare
+[define-component.component](../define-component.component/readme.md),
+which this module's own `demo.html` uses to bootstrap itself and which
+solves the related "register a custom element from a URL" problem).
+
+## Attributes
+
+| Attribute | Description |
+|---|---|
+| `name` | Global key to assign the import to (required) |
+| `src` | URL of the module to import, resolved relative to the current document (required) |
+| `import` | Named export to assign. Defaults to the module's default export |
+| `force` | If present, re-imports and re-assigns even if `globalThis[name]` is already set |
+| `no-import` | If present, the module is imported (for its side effects) but nothing is assigned to `globalThis` |
+
+## Usage
+
+```html
+<script
+  type="module"
+  src="https://esm.sh/@johnhenry/definable/define-component.component/global.mjs"
+></script>
+<define-component name="polyfill-window" src="./index.mjs"></define-component>
+
+<polyfill-window name="shout" src="./shout-polyfill.mjs"></polyfill-window>
+```

package/src/polyfill-window.component/shout.mjs

@@ -0,0 +1 @@
+export default (text) => alert(text.toUpperCase());

package/src/until-window-load/global.mjs

@@ -0,0 +1,2 @@
+import removeLoadingClasses from "./index.mjs";
+removeLoadingClasses("until-window-load");

package/src/until-window-load/index.mjs

@@ -0,0 +1,9 @@
+export default (...classNames) => {
+  window.addEventListener("load", () => {
+    for (const className of classNames) {
+      window.document.querySelectorAll(`.${className}`).forEach((loading) => {
+        loading.classList.remove(className);
+      });
+    }
+  });
+};

package/src/until-window-load/readme.md

@@ -0,0 +1,49 @@
+# Until Window Load
+
+Declarative import to remove loading classes once the window has loaded.
+
+Useful to avoid content flash for custom components that arrange content
+after loading. Used by [polyfill-window.component](../polyfill-window.component/readme.md)'s
+own demo.
+
+## Usage
+
+### Manual
+
+Define the class to be removed:
+
+```js
+import removeLoadingClasses from "https://esm.sh/@johnhenry/definable/until-window-load/index.mjs";
+removeLoadingClasses("custom-loading-class");
+```
+
+```css
+.custom-loading-class {
+  visibility: hidden;
+}
+```
+
+```html
+<custom-component class="custom-loading-class"
+  >Hide me until window load</custom-component
+>
+```
+
+### Automatic
+
+Use the "global" import to automatically use the class name `until-window-load`:
+
+```html
+<script
+  type="module"
+  src="https://esm.sh/@johnhenry/definable/until-window-load/global.mjs"
+></script>
+<style>
+  .until-window-load {
+    visibility: hidden;
+  }
+</style>
+<custom-component class="until-window-load"
+  >Hide me until window load</custom-component
+>
+```