@excom/renderable-element 0.1.0

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@excom/renderable-element",
+  "version": "0.1.0",
+  "description": "RenderableElement base for Neutron elements",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.13.0"
+  },
+  "type": "module",
+  "dependencies": {
+    "@excom/kit-logger": "^0.1.0",
+    "@excom/abortable-element": "^0.1.0",
+    "@excom/kit-shims": "^0.1.0",
+    "@excom/kit-utils": "^0.1.0",
+    "@excom/neutron": "^0.1.0"
+  },
+  "peerDependencies": {},
+  "devDependencies": {
+    "@excom/heft-rig": "^0.1.0"
+  },
+  "repository": {
+    "url": "excom-dev/nucleus",
+    "directory": "packages/renderable-element"
+  },
+  "homepage": "https://github.com/excom-dev/nucleus/tree/main/packages/renderable-element/support/docs/README.md",
+  "bugs": "https://github.com/excom-dev/nucleus/issues",
+  "keywords": [
+    "RenderableElement",
+    "renderable-element",
+    "neutron",
+    "kit-element-base",
+    "custom-elements"
+  ],
+  "excom": {
+    "packageType": "element-base"
+  },
+  "scripts": {
+    "build": "node node_modules/@excom/heft-rig/scripts/vite-build.mjs",
+    "build:watch": "node node_modules/@excom/heft-rig/scripts/vite-build-watch.mjs",
+    "format": "node node_modules/@excom/heft-rig/scripts/format.mjs",
+    "test": "node node_modules/@excom/heft-rig/scripts/vitest.mjs",
+    "coverage": "node node_modules/@excom/heft-rig/scripts/coverage.mjs",
+    "dev": "node node_modules/@excom/heft-rig/scripts/vite-dev.mjs",
+    "preview": "node node_modules/@excom/heft-rig/scripts/vite-preview.mjs",
+    "build:package-metas": "node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs",
+    "build:docs": "node node_modules/@excom/heft-rig/scripts/build-docs.mjs"
+  }
+}

package/rush-logs/renderable-element.apply-exports.cache.log

@@ -0,0 +1 @@
+Caching has been disabled for this project's "apply-exports" command.

package/rush-logs/renderable-element.apply-exports.log

@@ -0,0 +1 @@
+Invoking: cd "$RUSH_PROJECT_FOLDER" && node ../heft-rig/scripts/apply-exports.mjs 

package/rush-logs/renderable-element.build_docs.cache.log

@@ -0,0 +1 @@
+This project does not define the caching behavior of the "build:docs" command, so caching has been disabled.

package/rush-logs/renderable-element.build_docs.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs 

package/rush-logs/renderable-element.build_package-metas.cache.log

@@ -0,0 +1 @@
+This project does not define the caching behavior of the "build:package-metas" command, so caching has been disabled.

package/rush-logs/renderable-element.build_package-metas.log

@@ -0,0 +1 @@
+Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs 

package/src/index.css

@@ -0,0 +1,11 @@
+/**
+ * Shared styles for `RenderableElement` hosts. Hide while
+ * `delaying-ready` (waiting on `ready-on`).
+ */
+
+@define-mixin renderable-element {
+  &[delaying-ready] {
+    /* Always hide, even against later display rules */
+    display: none !important;
+  }
+}

package/support/custom-elements.json

@@ -0,0 +1,371 @@
+{
+  "schemaVersion": "1.0.0",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "index.ts",
+      "declarations": [
+        {
+          "kind": "mixin",
+          "name": "RenderableElement",
+          "mixins": [
+            {
+              "name": "AbortableElement",
+              "package": "@excom/abortable-element"
+            }
+          ],
+          "description": "Iframes waiting on `load` so their body can be `renderHost`.",
+          "attributes": [
+            {
+              "name": "template-ref",
+              "type": {
+                "text": "string"
+              },
+              "description": "Source `<template>` — in-document selector or remote URL. Changing mid-flight aborts and reloads. Can use `:scope` to relatively select elements: e.g. `main:has(:scope) > template`",
+              "fieldName": "templateRef",
+              "default": ":scope > template",
+              "values": [
+                "<CSS Selector>",
+                "<URL>"
+              ]
+            },
+            {
+              "name": "bypass-cache",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Skip the in-memory response cache (URL `template-ref` only).",
+              "fieldName": "bypassCache"
+            },
+            {
+              "name": "pre-fetch",
+              "type": {
+                "text": "string"
+              },
+              "description": "When to fetch the template, independent of when it renders. `\"\"` aliases `eager`.",
+              "fieldName": "preFetch",
+              "default": "lazy",
+              "values": [
+                "",
+                "eager",
+                "idle",
+                "lazy"
+              ]
+            },
+            {
+              "name": "persist-content",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Reuse the same live nodes across unrender / render (held on `_persistedTree`) so form values, scroll position, and subtree state survive toggles.",
+              "fieldName": "persistContent"
+            },
+            {
+              "name": "host-ref",
+              "type": {
+                "text": "string"
+              },
+              "description": "Where rendered children land. Unset = this element's light DOM. `shadow` attaches an open shadow root. `iframe` paints into a child `<iframe data-render-host>` body (you supply the iframe — useful for sandboxed / third-party document isolation). Any other value is a portal selector.",
+              "fieldName": "hostRef",
+              "values": [
+                "shadow",
+                "iframe",
+                "<CSS Selector>"
+              ]
+            },
+            {
+              "name": "ready-on",
+              "type": {
+                "text": "string"
+              },
+              "description": "Event name that marks rendered children \"ready\". Until it fires, `delaying-ready` is set so CSS can hide the host for a coordinated paint / view transition.",
+              "fieldName": "readyOn",
+              "values": [
+                "<Event Name>"
+              ]
+            },
+            {
+              "name": "is-active",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Master switch. Set to load (if needed) and render; unset to unrender. Drive from visibility, route match, hover, etc.",
+              "fieldName": "isActive"
+            },
+            {
+              "name": "is-loading",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Template fetch in flight.",
+              "fieldName": "isLoading"
+            },
+            {
+              "name": "did-load",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Template resolved at least once. Stays set across `is-active` toggles so consumers know later paints are warm (URL refs reuse the shared fetch cache in kit-utils). Cleared when `template-ref` changes or `--reload` forces a fresh resolve.",
+              "fieldName": "didLoad"
+            },
+            {
+              "name": "is-error",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Latest template fetch rejected (excluding abort). Fires with the `error` event.",
+              "fieldName": "isError"
+            },
+            {
+              "name": "delaying-ready",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Between `render` and the matching `ready-on` event. Hook with CSS for coordinated paints / view transitions.",
+              "fieldName": "delayingReady"
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "templateRef",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Source `<template>` — in-document selector or remote URL. Changing mid-flight aborts and reloads. Can use `:scope` to relatively select elements: e.g. `main:has(:scope) > template`",
+              "default": ":scope > template",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "bypassCache",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Skip the in-memory response cache (URL `template-ref` only).",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "preFetch",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "When to fetch the template, independent of when it renders. `\"\"` aliases `eager`.",
+              "default": "lazy",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "persistContent",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Reuse the same live nodes across unrender / render (held on `_persistedTree`) so form values, scroll position, and subtree state survive toggles.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "hostRef",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Where rendered children land. Unset = this element's light DOM. `shadow` attaches an open shadow root. `iframe` paints into a child `<iframe data-render-host>` body (you supply the iframe — useful for sandboxed / third-party document isolation). Any other value is a portal selector.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "readyOn",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Event name that marks rendered children \"ready\". Until it fires, `delaying-ready` is set so CSS can hide the host for a coordinated paint / view transition.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "isActive",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Master switch. Set to load (if needed) and render; unset to unrender. Drive from visibility, route match, hover, etc.",
+              "_neutron": {
+                "surface": "hybrid"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "isLoading",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": true,
+              "description": "Template fetch in flight.",
+              "_neutron": {
+                "surface": "state"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "didLoad",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": true,
+              "description": "Template resolved at least once. Stays set across `is-active` toggles so consumers know later paints are warm (URL refs reuse the shared fetch cache in kit-utils). Cleared when `template-ref` changes or `--reload` forces a fresh resolve.",
+              "_neutron": {
+                "surface": "state"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "isError",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": true,
+              "description": "Latest template fetch rejected (excluding abort). Fires with the `error` event.",
+              "_neutron": {
+                "surface": "state"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "delayingReady",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": true,
+              "description": "Between `render` and the matching `ready-on` event. Hook with CSS for coordinated paints / view transitions.",
+              "_neutron": {
+                "surface": "state"
+              }
+            }
+          ],
+          "events": [
+            {
+              "name": "{tag}-render",
+              "description": "Cancelable. Dispatched when the element becomes active and is about to place template content into the host. `event.detail` is a thunk that performs the load (if not already loaded) and renders the children, returning a Promise that resolves once the corresponding `ready-on` event fires (or immediately if `ready-on` is unset). The promise rejects if the element is torn down mid-flight (`startTeardown` while loading / `delaying-ready`). Call `preventDefault()` to defer rendering and invoke `event.detail()` later.",
+              "type": {
+                "text": "RenderableRenderEvent",
+                "expanded": "CustomEvent & { type: \"{tag}-render\"; detail: () => Promise<void>; bubbles: true; cancelable: true; composed: true }"
+              }
+            },
+            {
+              "name": "{tag}-unrender",
+              "description": "Cancelable. Dispatched when the element becomes inactive and content is already painted. `event.detail` is a thunk that removes the rendered children. Call `preventDefault()` to defer the removal. Not fired when teardown cancels an in-flight load — that path emits `aborted` instead.",
+              "type": {
+                "text": "RenderableUnrenderEvent",
+                "expanded": "CustomEvent & { type: \"{tag}-unrender\"; detail: () => void; bubbles: true; cancelable: true; composed: true }"
+              }
+            },
+            {
+              "name": "{tag}-did-render",
+              "description": "Dispatched after the template content has actually been placed into the host.",
+              "type": {
+                "text": "RenderableDidRenderEvent",
+                "expanded": "CustomEvent & { type: \"{tag}-did-render\"; detail: void; bubbles: true; cancelable: true; composed: true }"
+              }
+            },
+            {
+              "name": "{tag}-did-unrender",
+              "description": "Dispatched after rendered children have been removed from the host.",
+              "type": {
+                "text": "RenderableDidUnrenderEvent",
+                "expanded": "CustomEvent & { type: \"{tag}-did-unrender\"; detail: void; bubbles: true; cancelable: true; composed: true }"
+              }
+            },
+            {
+              "name": "{tag}-error",
+              "description": "Dispatched when the template promise rejects with anything other than an `AbortError`.",
+              "type": {
+                "text": "RenderableErrorEvent",
+                "expanded": "CustomEvent & { type: \"{tag}-error\"; detail: void; bubbles: true; cancelable: true; composed: true }"
+              }
+            },
+            {
+              "name": "{tag}-aborted",
+              "description": "Dispatched when an in-flight load / ready wait is canceled because `is-active` was unset (via `startTeardown`).",
+              "type": {
+                "text": "RenderableAbortedEvent",
+                "expanded": "CustomEvent & { type: \"{tag}-aborted\"; detail: void; bubbles: true; cancelable: true; composed: true }"
+              }
+            }
+          ],
+          "_neutron": {
+            "commands": [
+              {
+                "name": "--reload",
+                "description": "Aborts any in-flight fetch and re-resolves the template, bypassing the cache for URL refs (useful after remote content changes)."
+              }
+            ],
+            "defaultActions": [
+              {
+                "name": "{tag}-render",
+                "description": "Invokes `event.detail()` to load (if needed) and render the template into the host."
+              },
+              {
+                "name": "{tag}-unrender",
+                "description": "Invokes `event.detail()` to remove rendered children from the host."
+              }
+            ],
+            "expectedChildren": [
+              {
+                "relationship": "child",
+                "selector": "template",
+                "required": false,
+                "description": "Optional immediate `<template>` child used when `template-ref` is the default `\":scope > template\"`. Not required when `template-ref` points at a selector or URL elsewhere."
+              },
+              {
+                "relationship": "child",
+                "selector": "iframe[data-render-host]",
+                "required": false,
+                "description": "Required when `host-ref=\"iframe\"`. Content paints into `iframe.contentDocument.body`. Provide your own iframe (e.g. with `srcdoc`); the element will not create one."
+              }
+            ]
+          }
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "RenderableElement",
+          "declaration": {
+            "name": "RenderableElement",
+            "module": "index.ts"
+          }
+        }
+      ]
+    }
+  ]
+}

package/support/demos/host-iframe.html

@@ -0,0 +1,26 @@
+<include-content is-active host-ref="iframe">
+  <template>
+    <style>
+      body { font-family: system-ui; padding: 12px; color: #333; }
+      h4 { color: navy; margin: 0 0 4px; }
+    </style>
+    <h4>Hello from inside the iframe</h4>
+    <p>Rendered into <code>iframe.contentDocument.body</code>.</p>
+  </template>
+  <iframe data-render-host
+    srcdoc="<!doctype html><html><body></body></html>"></iframe>
+  <style>
+    #demo-renderable-element-host-iframe > :first-child {
+      display: block;
+      border: 1px dashed currentColor;
+      padding: 8px;
+
+      > iframe {
+        width: 100%;
+        height: 140px;
+        border: none;
+        background: white;
+      }
+    }
+  </style>
+</include-content>

package/support/demos/host-selector.html

@@ -0,0 +1,29 @@
+<p>Any other <code>host-ref</code> value is treated as a CSS selector. The element renders its template into whatever the selector resolves to.</p>
+
+<style>
+  .selector-demo {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 12px;
+  }
+  .selector-demo .mount-point {
+    border: 1px dashed currentColor;
+    padding: 8px;
+    min-height: 80px;
+  }
+</style>
+
+<div class="selector-demo">
+  <div>
+    <strong>Source element:</strong>
+    <include-content is-active host-ref=".sidebar-mount">
+      <template>
+        <p>I render into <code>.sidebar-mount</code> →</p>
+      </template>
+    </include-content>
+  </div>
+  <div>
+    <strong>Mount target:</strong>
+    <div class="mount-point sidebar-mount"></div>
+  </div>
+</div>

package/support/demos/host-shadow.html

@@ -0,0 +1,31 @@
+<p>Two <code>&lt;include-content&gt;</code> elements rendering the same template into different hosts. The shadow-root version is style-isolated.</p>
+
+<style>
+  .host-demo include-content {
+    display: block;
+    border: 1px dashed currentColor;
+    padding: 8px;
+    margin: 8px 0;
+  }
+  /* this rule cannot reach into a shadow root */
+  .host-demo h4 { color: rebeccapurple; }
+</style>
+
+<div class="host-demo">
+  <strong>Light DOM (default):</strong>
+  <include-content is-active>
+    <template>
+      <h4>I'm rebeccapurple</h4>
+      <p>Light-DOM children inherit the host page's CSS.</p>
+    </template>
+  </include-content>
+
+  <strong>Shadow DOM (<code>host-ref="shadow"</code>):</strong>
+  <include-content is-active host-ref="shadow">
+    <template>
+      <style>h4 { color: tomato; }</style>
+      <h4>I'm tomato — outer styles can't touch me</h4>
+      <p>Encapsulated inside an attached shadow root.</p>
+    </template>
+  </include-content>
+</div>

package/support/demos/persist-content.html

@@ -0,0 +1,57 @@
+<p>Type into both inputs, then toggle them off and on. The right side
+keeps its value because <code>persist-content</code> reuses the same
+template node instead of cloning a fresh copy each render.</p>
+
+<style>
+  .persist-demo {
+    display: grid;
+    grid-template-columns: 1fr 1fr;
+    gap: 12px;
+  }
+  .persist-demo include-content {
+    display: block;
+    border: 1px dashed currentColor;
+    padding: 8px;
+    margin-top: 4px;
+  }
+</style>
+
+<div class="persist-demo" id="persist-host">
+  <div>
+    <strong>Default (cloned each render):</strong>
+    <label>
+      <input type="checkbox" data-target="#cloned" checked />
+      Active
+    </label>
+    <include-content id="cloned" is-active>
+      <template>
+        <input type="text" placeholder="Type, then toggle off + on" />
+      </template>
+    </include-content>
+  </div>
+
+  <div>
+    <strong><code>persist-content</code>:</strong>
+    <label>
+      <input type="checkbox" data-target="#persisted" checked />
+      Active
+    </label>
+    <include-content id="persisted" is-active persist-content>
+      <template>
+        <input type="text" placeholder="Type, then toggle off + on" />
+      </template>
+    </include-content>
+  </div>
+</div>
+
+<script>
+  (() => {
+    document.querySelectorAll("#persist-host input[type=checkbox]").forEach((cb) => {
+      cb.addEventListener("change", () => {
+        document
+          .querySelector(cb.dataset.target)
+          .toggleAttribute("is-active", cb.checked);
+      });
+    });
+  })();
+</script>

package/support/demos/render-event.html

@@ -0,0 +1,66 @@
+<p>Toggle the checkbox to activate the element. The cancelable
+<code>include-content-render</code> event is intercepted, the actual
+DOM mutation is wrapped in <code>document.startViewTransition()</code>,
+and a parent listener can defer or skip the render entirely.</p>
+
+<style>
+  .render-event-demo {
+    border: 1px solid var(--border, #444);
+    padding: 12px;
+    border-radius: 4px;
+  }
+  .render-event-demo include-content {
+    display: block;
+    margin-top: 8px;
+    padding: 8px;
+    border: 1px dashed currentColor;
+  }
+  .render-event-demo include-content > article {
+    background: rgba(255, 200, 80, 0.15);
+    padding: 12px;
+    view-transition-name: render-demo-card;
+  }
+  ::view-transition-old(render-demo-card),
+  ::view-transition-new(render-demo-card) {
+    animation-duration: 350ms;
+  }
+</style>
+
+<div class="render-event-demo" id="render-event-host">
+  <label>
+    <input type="checkbox" id="toggle-active" />
+    Active
+  </label>
+
+  <include-content id="render-target">
+    <template>
+      <article>
+        <h4>Just rendered (with a view transition)</h4>
+        <p>The host swallowed the default render and ran it through <code>startViewTransition</code>.</p>
+      </article>
+    </template>
+  </include-content>
+</div>
+
+<script>
+  (() => {
+    const host = document.querySelector("#render-event-host");
+    const target = host.querySelector("#render-target");
+    const toggle = host.querySelector("#toggle-active");
+
+    target.addEventListener("include-content-render", (e) => {
+      if (!document.startViewTransition) return;
+      e.preventDefault();
+      document.startViewTransition(() => e.detail());
+    });
+    target.addEventListener("include-content-unrender", (e) => {
+      if (!document.startViewTransition) return;
+      e.preventDefault();
+      document.startViewTransition(() => e.detail());
+    });
+
+    toggle.addEventListener("change", () => {
+      target.toggleAttribute("is-active", toggle.checked);
+    });
+  })();
+</script>