@excom/include-content 0.1.0

package/support/package-meta.json

@@ -0,0 +1,360 @@
+{
+  "shortName": "include-content",
+  "package": {
+    "name": "@excom/include-content",
+    "version": "0.1.0",
+    "description": "<include-content> custom element",
+    "peerDependencies": {},
+    "excom": {
+      "packageType": "kit-element"
+    }
+  },
+  "demos": {
+    "lazy": "<section>\n  <p>Scroll down…</p>\n  <include-content lazy-load lazy-unload observer-root=\"section:has(> :scope)\"\n    observer-root-margin=\"0px\" observer-threshold=\"0.5\">\n    <template>\n      <p>Rendered at 50% visibility. Scroll away to remove\n        (<code>lazy-unload</code>).</p>\n    </template>\n  </include-content>\n  <p>Keep scrolling…</p>\n  <style>\n    #demo-include-content-lazy > :first-child {\n      include-content {\n        /* Prevent size collapse → render/unrender loop */\n        min-height: 108px;\n      }\n    }\n  </style>\n</section>\n",
+    "persist-content": "<div>\n  <quark-sheet>\n    :scope {\n      @on change {\n        include-content { is-active: if(event.target.checked: \"\"; else: none); }\n      }\n    }\n  </quark-sheet>\n  <form>\n    <label>\n      <input type=\"checkbox\" name=\"is-active\" checked />\n      Active\n    </label>\n  </form>\n  <include-content is-active persist-content>\n    <template>\n      <label>\n        Type, then toggle Active —\n        <input type=\"text\" placeholder=\"value is kept\" />\n      </label>\n    </template>\n  </include-content>\n</div>\n",
+    "portal": "<div>\n  <include-content is-active host-ref=\"#ic-portal-mount\">\n    <template>\n      <p>Portaled into the aside.</p>\n    </template>\n  </include-content>\n  <aside id=\"ic-portal-mount\"></aside>\n</div>\n",
+    "simple": "<div>\n  <a>Hover me</a>\n  <include-content lazy-load>\n    <template>\n      <p>HTML inserted</p>\n    </template>\n  </include-content>\n  <small role=\"note\">See Live document tab for DOM changes.</small>\n  <style>\n    #demo-include-content-simple > :first-child {\n      a:not(:hover) + include-content:not([is-active]) {\n        display: none;\n      }\n    }\n  </style>\n</div>\n",
+    "template-include": "<div>\n  <template id=\"ic-include-piece\">\n    <p>A reusable view piece.</p>\n  </template>\n  <include-content is-active template-ref=\"#ic-include-piece\"></include-content>\n  <include-content is-active template-ref=\"/fragments/remote-include.html\"></include-content>\n</div>\n",
+    "template-ref": "<div>\n  <template id=\"ic-shared-template\">\n    <p>Shared template — both hosts render this node.</p>\n  </template>\n  <include-content is-active template-ref=\"#ic-shared-template\"></include-content>\n  <include-content idle-load template-ref=\"#ic-shared-template\"></include-content>\n</div>\n"
+  },
+  "readme": "<h1 id=\"md-include-content\">include-content</h1>\n<p>One-stop shop for rendering a view when &amp; where you need it — lazy-loading/unloading, conditional rendering, portalling… no app JS required.</p>\n<p><include-content data-demo=\"simple\"></include-content></p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Zero JS</strong> Sophisticated UX from a simple HTML-only API, as with all Nucleus Kit elements.</li>\n<li><strong>Lazy (un)load</strong> Lazy load and lazy unload your views</li>\n<li><strong>Eager / idle</strong> Prioritize critical content; defer the rest</li>\n<li><strong>Prefetch</strong> Warm templates so they&#39;re ready on activate</li>\n<li><strong>Shared / remote templates</strong> Point at a DOM <code>&lt;template&gt;</code> or URL</li>\n<li><strong>Choose the host</strong> Portal into light DOM, shadow, author iframe, or any selector</li>\n<li><strong>Keep state</strong> Reuse the same tree across toggles</li>\n<li><strong>Animatable</strong> Built-in fade, or bring your own with <code>.instant</code></li>\n</ul>\n<h2 id=\"md-installation\">Installation</h2>\n<p><include-content is-active template-ref=\"/views/install-section/install-section.html\"></include-content></p>\n<h2 id=\"md-usage\">Usage</h2>\n<p>Put a <code>&lt;template&gt;</code> inside (or set <code>template-ref</code>) and pick when it should appear. For conditional rendering, use Quark or JS to toggle <code>is-active</code>.</p>\n<include-content data-language=\"html\"><template>&lt;include-content lazy-load template-ref=\"/path/to/view.html\"&gt;&lt;/include-content&gt;</template></include-content>\n<h3 id=\"md-api-reference\">API Reference</h3>\n<p><include-content is-active template-ref=\"/views/api-reference/api-reference.html\"></include-content></p>\n<h3 id=\"md-examples\">Examples</h3>\n<h4 id=\"md-template-include\">Template include</h4>\n<p>Break your app into smaller views. Point <code>template-ref</code> at a <code>&lt;template&gt;</code> or a URL with <code>is-active</code> to render it immediately. This demo does both.</p>\n<p><include-content data-demo=\"template-include\"></include-content></p>\n<h4 id=\"md-lazy-load-amp-unload\">Lazy Load &amp; Unload</h4>\n<p><code>lazy-load</code> waits until on screen; <code>lazy-unload</code> removes it when it leaves. Give the host a real <code>min-height</code> so the trigger isn&#39;t ambiguous. Tune with <code>observer-root</code>, <code>observer-root-margin</code>, <code>observer-threshold</code>, and <code>observer-delay</code> — e.g. expand the margin to pre-render before the user scrolls to it. If remote template, pair with <code>pre-fetch=&quot;idle&quot;</code> to warm the cache early.</p>\n<p><include-content data-demo=\"lazy\"></include-content></p>\n<h4 id=\"md-portal-elsewhere\">Portal elsewhere</h4>\n<p>By default content lands in the element&#39;s light DOM. Set <code>host-ref</code> to\n<code>shadow</code>, <code>iframe</code> (with a child <code>&lt;iframe data-render-host&gt;</code>), or any CSS\nselector to render somewhere else. The iframe host only moves nodes: custom\nelements inside it upgrade only if that document loads their definitions.</p>\n<p><include-content data-demo=\"portal\"></include-content></p>\n<h4 id=\"md-keep-tree-state\">Keep tree state</h4>\n<p>Toggling <code>is-active</code> off leaves <code>did-load</code> set (warm re-resolve; URL\nrefs hit the shared fetch cache). <code>persist-content</code> goes further and\nreuses the same live nodes so implicit state (form values, open details,\netc.) survives toggles.</p>\n<p><include-content data-demo=\"persist-content\"></include-content></p>\n",
+  "docs": {
+    "readme": "<h1 id=\"md-include-content\">include-content</h1>\n<p>One-stop shop for rendering a view when &amp; where you need it — lazy-loading/unloading, conditional rendering, portalling… no app JS required.</p>\n<p><include-content data-demo=\"simple\"></include-content></p>\n<h2 id=\"md-features\">Features</h2>\n<ul>\n<li><strong>Zero JS</strong> Sophisticated UX from a simple HTML-only API, as with all Nucleus Kit elements.</li>\n<li><strong>Lazy (un)load</strong> Lazy load and lazy unload your views</li>\n<li><strong>Eager / idle</strong> Prioritize critical content; defer the rest</li>\n<li><strong>Prefetch</strong> Warm templates so they&#39;re ready on activate</li>\n<li><strong>Shared / remote templates</strong> Point at a DOM <code>&lt;template&gt;</code> or URL</li>\n<li><strong>Choose the host</strong> Portal into light DOM, shadow, author iframe, or any selector</li>\n<li><strong>Keep state</strong> Reuse the same tree across toggles</li>\n<li><strong>Animatable</strong> Built-in fade, or bring your own with <code>.instant</code></li>\n</ul>\n<h2 id=\"md-installation\">Installation</h2>\n<p><include-content is-active template-ref=\"/views/install-section/install-section.html\"></include-content></p>\n<h2 id=\"md-usage\">Usage</h2>\n<p>Put a <code>&lt;template&gt;</code> inside (or set <code>template-ref</code>) and pick when it should appear. For conditional rendering, use Quark or JS to toggle <code>is-active</code>.</p>\n<include-content data-language=\"html\"><template>&lt;include-content lazy-load template-ref=\"/path/to/view.html\"&gt;&lt;/include-content&gt;</template></include-content>\n<h3 id=\"md-api-reference\">API Reference</h3>\n<p><include-content is-active template-ref=\"/views/api-reference/api-reference.html\"></include-content></p>\n<h3 id=\"md-examples\">Examples</h3>\n<h4 id=\"md-template-include\">Template include</h4>\n<p>Break your app into smaller views. Point <code>template-ref</code> at a <code>&lt;template&gt;</code> or a URL with <code>is-active</code> to render it immediately. This demo does both.</p>\n<p><include-content data-demo=\"template-include\"></include-content></p>\n<h4 id=\"md-lazy-load-amp-unload\">Lazy Load &amp; Unload</h4>\n<p><code>lazy-load</code> waits until on screen; <code>lazy-unload</code> removes it when it leaves. Give the host a real <code>min-height</code> so the trigger isn&#39;t ambiguous. Tune with <code>observer-root</code>, <code>observer-root-margin</code>, <code>observer-threshold</code>, and <code>observer-delay</code> — e.g. expand the margin to pre-render before the user scrolls to it. If remote template, pair with <code>pre-fetch=&quot;idle&quot;</code> to warm the cache early.</p>\n<p><include-content data-demo=\"lazy\"></include-content></p>\n<h4 id=\"md-portal-elsewhere\">Portal elsewhere</h4>\n<p>By default content lands in the element&#39;s light DOM. Set <code>host-ref</code> to\n<code>shadow</code>, <code>iframe</code> (with a child <code>&lt;iframe data-render-host&gt;</code>), or any CSS\nselector to render somewhere else. The iframe host only moves nodes: custom\nelements inside it upgrade only if that document loads their definitions.</p>\n<p><include-content data-demo=\"portal\"></include-content></p>\n<h4 id=\"md-keep-tree-state\">Keep tree state</h4>\n<p>Toggling <code>is-active</code> off leaves <code>did-load</code> set (warm re-resolve; URL\nrefs hit the shared fetch cache). <code>persist-content</code> goes further and\nreuses the same live nodes so implicit state (form values, open details,\netc.) survives toggles.</p>\n<p><include-content data-demo=\"persist-content\"></include-content></p>\n"
+  },
+  "installation": {
+    "name": "@excom/include-content",
+    "shortName": "include-content",
+    "version": "0.1.0",
+    "description": "<include-content> custom element",
+    "packageType": "kit-element",
+    "cdn": "<script src=\"https://unpkg.com/@excom/kit-utils/dist/index.umd.min.js\"></script>\n<script src=\"https://unpkg.com/@excom/neutron/dist/index.umd.min.js\"></script>\n<script src=\"https://unpkg.com/@excom/include-content@0.1.0/dist/index.umd.min.js\"></script>\n<link rel=\"stylesheet\" href=\"https://unpkg.com/@excom/include-content@0.1.0/dist/index.css\">",
+    "install": {
+      "npm": "npm install @excom/include-content"
+    },
+    "imports": {
+      "js": "import \"@excom/include-content\";",
+      "css": "@import \"@excom/include-content\";",
+      "html": "<!-- import path to `node_modules` will depend on your build setup -->\n<script type=\"module\" src=\"/node_modules/@excom/include-content\"></script>\n<link rel=\"stylesheet\" href=\"/node_modules/@excom/include-content\">"
+    },
+    "peerDependencies": []
+  },
+  "elementApis": [
+    {
+      "tag": "include-content",
+      "summary": "Declarative view rendering — lazy (un)load, idle, conditional.",
+      "kind": "class",
+      "attributes": [
+        {
+          "name": "bypass-cache",
+          "type": "boolean",
+          "description": "Skip the in-memory response cache (URL <code>template-ref</code> only).",
+          "fieldName": "bypassCache",
+          "surface": "option",
+          "inheritedFrom": "@excom/renderable-element"
+        },
+        {
+          "name": "host-ref",
+          "type": "string",
+          "description": "Where rendered children land. Unset = this element&#39;s light DOM. <code>shadow</code> attaches an open shadow root. <code>iframe</code> paints into a child <code>&lt;iframe data-render-host&gt;</code> body (you supply the iframe — useful for sandboxed / third-party document isolation). Any other value is a portal selector.",
+          "fieldName": "hostRef",
+          "surface": "option",
+          "values": "\"shadow\" | \"iframe\" | <CSS Selector>",
+          "inheritedFrom": "@excom/renderable-element"
+        },
+        {
+          "name": "idle-load",
+          "type": "boolean",
+          "description": "Activate after first paint, when the browser is idle. Useful for below-the-fold / secondary views that should not compete with critical content.",
+          "fieldName": "idleLoad",
+          "surface": "option"
+        },
+        {
+          "name": "lazy-load",
+          "type": "boolean",
+          "description": "Activate when this element is on screen. Pair with <code>lazy-unload</code> for lazy load and lazy unload of views.",
+          "fieldName": "lazyLoad",
+          "surface": "option"
+        },
+        {
+          "name": "lazy-unload",
+          "type": "boolean",
+          "description": "Deactivate (unrender) when no longer on screen. Use with <code>lazy-load</code> to free DOM for off-screen views.",
+          "fieldName": "lazyUnload",
+          "surface": "option"
+        },
+        {
+          "name": "observer-delay",
+          "type": "number",
+          "description": "Minimum time visible before activating (ms). Ignored where unsupported. Useful for ensuring lazy load is not triggered when a programmatic smooth scroll zips the user right past the element.",
+          "fieldName": "observerDelay",
+          "surface": "option",
+          "default": "0"
+        },
+        {
+          "name": "observer-root",
+          "type": "string",
+          "description": "Scroll container for lazy load / unload. Defaults to the viewport.",
+          "fieldName": "observerRoot",
+          "surface": "option",
+          "values": "<CSS Selector>"
+        },
+        {
+          "name": "observer-root-margin",
+          "type": "string",
+          "description": "How far outside the root counts as &quot;visible&quot;. Expand (e.g. <code>500px</code>) to lazy-load a view <em>before</em> it enters the viewport so users never see an empty slot; shrink (default <code>-1px</code>) so edge-flush elements wait until they truly enter.",
+          "fieldName": "observerRootMargin",
+          "surface": "option",
+          "default": "\"-1px -1px -1px -1px\"",
+          "values": "<length> | <percentage>"
+        },
+        {
+          "name": "observer-threshold",
+          "type": "number",
+          "description": "Fraction of the element that must be visible (<code>0</code>–<code>1</code>) before activating.",
+          "fieldName": "observerThreshold",
+          "surface": "option"
+        },
+        {
+          "name": "persist-content",
+          "type": "boolean",
+          "description": "Reuse the same live nodes across unrender / render (held on <code>_persistedTree</code>) so form values, scroll position, and subtree state survive toggles.",
+          "fieldName": "persistContent",
+          "surface": "option",
+          "inheritedFrom": "@excom/renderable-element"
+        },
+        {
+          "name": "pre-fetch",
+          "type": "string",
+          "description": "When to fetch the template, independent of when it renders. <code>&quot;&quot;</code> aliases <code>eager</code>.",
+          "fieldName": "preFetch",
+          "surface": "option",
+          "default": "\"lazy\"",
+          "values": "\"\" | \"eager\" | \"idle\" | \"lazy\"",
+          "inheritedFrom": "@excom/renderable-element"
+        },
+        {
+          "name": "ready-on",
+          "type": "string",
+          "description": "Event name that marks rendered children &quot;ready&quot;. Until it fires, <code>delaying-ready</code> is set so CSS can hide the host for a coordinated paint / view transition.",
+          "fieldName": "readyOn",
+          "surface": "option",
+          "values": "<Event Name>",
+          "inheritedFrom": "@excom/renderable-element"
+        },
+        {
+          "name": "template-ref",
+          "type": "string",
+          "description": "Source <code>&lt;template&gt;</code> — in-document selector or remote URL. Changing mid-flight aborts and reloads. Can use <code>:scope</code> to relatively select elements: e.g. <code>main:has(:scope) &gt; template</code>",
+          "fieldName": "templateRef",
+          "surface": "option",
+          "default": "\":scope > template\"",
+          "values": "<CSS Selector> | <URL>",
+          "inheritedFrom": "@excom/renderable-element"
+        },
+        {
+          "name": "is-active",
+          "type": "boolean",
+          "description": "Master switch. Set to load (if needed) and render; unset to unrender. Drive from visibility, route match, hover, etc.",
+          "fieldName": "isActive",
+          "surface": "hybrid",
+          "inheritedFrom": "@excom/renderable-element"
+        },
+        {
+          "name": "delaying-ready",
+          "type": "boolean",
+          "description": "Between <code>render</code> and the matching <code>ready-on</code> event. Hook with CSS for coordinated paints / view transitions.",
+          "fieldName": "delayingReady",
+          "surface": "state",
+          "inheritedFrom": "@excom/renderable-element"
+        },
+        {
+          "name": "did-load",
+          "type": "boolean",
+          "description": "Template resolved at least once. Stays set across <code>is-active</code> toggles so consumers know later paints are warm (URL refs reuse the shared fetch cache in kit-utils). Cleared when <code>template-ref</code> changes or <code>--reload</code> forces a fresh resolve.",
+          "fieldName": "didLoad",
+          "surface": "state",
+          "inheritedFrom": "@excom/renderable-element"
+        },
+        {
+          "name": "is-error",
+          "type": "boolean",
+          "description": "Latest template fetch rejected (excluding abort). Fires with the <code>error</code> event.",
+          "fieldName": "isError",
+          "surface": "state",
+          "inheritedFrom": "@excom/renderable-element"
+        },
+        {
+          "name": "is-loading",
+          "type": "boolean",
+          "description": "Template fetch in flight.",
+          "fieldName": "isLoading",
+          "surface": "state",
+          "inheritedFrom": "@excom/renderable-element"
+        }
+      ],
+      "events": [
+        {
+          "name": "include-content-aborted",
+          "description": "Dispatched when an in-flight load / ready wait is canceled because <code>is-active</code> was unset (via <code>startTeardown</code>).",
+          "type": "RenderableAbortedEvent",
+          "typeExpanded": "CustomEvent & { type: \"{tag}-aborted\"; detail: void; bubbles: true; cancelable: true; composed: true }",
+          "inheritedFrom": "@excom/renderable-element"
+        },
+        {
+          "name": "include-content-did-render",
+          "description": "Dispatched after the template content has actually been placed into the host.",
+          "type": "RenderableDidRenderEvent",
+          "typeExpanded": "CustomEvent & { type: \"{tag}-did-render\"; detail: void; bubbles: true; cancelable: true; composed: true }",
+          "inheritedFrom": "@excom/renderable-element"
+        },
+        {
+          "name": "include-content-did-unrender",
+          "description": "Dispatched after rendered children have been removed from the host.",
+          "type": "RenderableDidUnrenderEvent",
+          "typeExpanded": "CustomEvent & { type: \"{tag}-did-unrender\"; detail: void; bubbles: true; cancelable: true; composed: true }",
+          "inheritedFrom": "@excom/renderable-element"
+        },
+        {
+          "name": "include-content-error",
+          "description": "Dispatched when the template promise rejects with anything other than an <code>AbortError</code>.",
+          "type": "RenderableErrorEvent",
+          "typeExpanded": "CustomEvent & { type: \"{tag}-error\"; detail: void; bubbles: true; cancelable: true; composed: true }",
+          "inheritedFrom": "@excom/renderable-element"
+        },
+        {
+          "name": "include-content-render",
+          "description": "Cancelable. Dispatched when the element becomes active and is about to place template content into the host. <code>event.detail</code> is a thunk that performs the load (if not already loaded) and renders the children, returning a Promise that resolves once the corresponding <code>ready-on</code> event fires (or immediately if <code>ready-on</code> is unset). The promise rejects if the element is torn down mid-flight (<code>startTeardown</code> while loading / <code>delaying-ready</code>). Call <code>preventDefault()</code> to defer rendering and invoke <code>event.detail()</code> later.",
+          "type": "RenderableRenderEvent",
+          "typeExpanded": "CustomEvent & { type: \"{tag}-render\"; detail: () => Promise<void>; bubbles: true; cancelable: true; composed: true }",
+          "inheritedFrom": "@excom/renderable-element",
+          "defaultAction": "Invokes <code>event.detail()</code> to load (if needed) and render the template into the host."
+        },
+        {
+          "name": "include-content-unrender",
+          "description": "Cancelable. Dispatched when the element becomes inactive and content is already painted. <code>event.detail</code> is a thunk that removes the rendered children. Call <code>preventDefault()</code> to defer the removal. Not fired when teardown cancels an in-flight load — that path emits <code>aborted</code> instead.",
+          "type": "RenderableUnrenderEvent",
+          "typeExpanded": "CustomEvent & { type: \"{tag}-unrender\"; detail: () => void; bubbles: true; cancelable: true; composed: true }",
+          "inheritedFrom": "@excom/renderable-element",
+          "defaultAction": "Invokes <code>event.detail()</code> to remove rendered children from the host."
+        }
+      ],
+      "slots": [],
+      "cssProperties": [
+        {
+          "name": "--include-content-transition-duration",
+          "description": "Fade-in duration.",
+          "syntax": "<time>",
+          "default": "0.15s"
+        },
+        {
+          "name": "--include-content-transition-ease",
+          "description": "Fade-in easing.",
+          "syntax": "*",
+          "default": "ease-in"
+        }
+      ],
+      "cssClasses": [
+        {
+          "name": "instant",
+          "description": "Skip the built-in fade — bring your own animation / view transition. Also opts-out if the element is portalling content elsewhere ([host-ref])"
+        }
+      ],
+      "cssAliases": [
+        {
+          "name": ":--include-content",
+          "selectors": [
+            "include-content",
+            ".tag-include-content"
+          ],
+          "kind": "element",
+          "description": ""
+        },
+        {
+          "name": ":--include-content--did-load",
+          "selectors": [
+            "[did-load]",
+            "[data-did-load]"
+          ],
+          "kind": "state",
+          "description": ""
+        },
+        {
+          "name": ":--include-content--host-shadow",
+          "selectors": [
+            "[host-ref=\"shadow\"]",
+            "[data-host-ref=\"shadow\"]"
+          ],
+          "kind": "state",
+          "description": ""
+        },
+        {
+          "name": ":--include-content--is-active",
+          "selectors": [
+            "[is-active]",
+            "[aria-current]"
+          ],
+          "kind": "state",
+          "description": ""
+        },
+        {
+          "name": ":--include-content--lazy-load",
+          "selectors": [
+            "[lazy-load]",
+            "[data-lazy-load]"
+          ],
+          "kind": "state",
+          "description": ""
+        },
+        {
+          "name": ":--include-content--lazy-unload",
+          "selectors": [
+            "[lazy-unload]",
+            "[data-lazy-unload]"
+          ],
+          "kind": "state",
+          "description": ""
+        }
+      ],
+      "listens": [],
+      "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).",
+          "inheritedFrom": "@excom/renderable-element"
+        }
+      ],
+      "defaultActions": [
+        {
+          "name": "include-content-render",
+          "description": "Invokes <code>event.detail()</code> to load (if needed) and render the template into the host.",
+          "inheritedFrom": "@excom/renderable-element"
+        },
+        {
+          "name": "include-content-unrender",
+          "description": "Invokes <code>event.detail()</code> to remove rendered children from the host.",
+          "inheritedFrom": "@excom/renderable-element"
+        }
+      ],
+      "expectedChildren": [
+        {
+          "name": "child:iframe[data-render-host]",
+          "relationship": "child",
+          "selector": "iframe[data-render-host]",
+          "required": false,
+          "description": "Required when <code>host-ref=&quot;iframe&quot;</code>. Content paints into <code>iframe.contentDocument.body</code>. Provide your own iframe (e.g. with <code>srcdoc</code>); the element will not create one.",
+          "inheritedFrom": "@excom/renderable-element"
+        },
+        {
+          "name": "child:template",
+          "relationship": "child",
+          "selector": "template",
+          "required": false,
+          "description": "Optional immediate <code>&lt;template&gt;</code> child used when <code>template-ref</code> is the default <code>&quot;:scope &gt; template&quot;</code>. Not required when <code>template-ref</code> points at a selector or URL elsewhere.",
+          "inheritedFrom": "@excom/renderable-element"
+        }
+      ],
+      "provisions": []
+    }
+  ],
+  "exportedFiles": {}
+}