@excom/include-content 0.1.0

package/.rush/temp/chunked-rush-logs/include-content.apply-exports.chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: cd \"$RUSH_PROJECT_FOLDER\" && node ../heft-rig/scripts/apply-exports.mjs \n"}

package/.rush/temp/chunked-rush-logs/include-content.build_docs.chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs \n"}

package/.rush/temp/chunked-rush-logs/include-content.build_package-metas.chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs \n"}

package/.rush/temp/operation/apply-exports/all.log

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

package/.rush/temp/operation/apply-exports/log-chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: cd \"$RUSH_PROJECT_FOLDER\" && node ../heft-rig/scripts/apply-exports.mjs \n"}

package/.rush/temp/operation/apply-exports/state.json

@@ -0,0 +1,3 @@
+{
+  "nonCachedDurationMs": 34.939984000000095
+}

package/.rush/temp/operation/build_docs/all.log

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

package/.rush/temp/operation/build_docs/log-chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-docs.mjs \n"}

package/.rush/temp/operation/build_docs/state.json

@@ -0,0 +1,3 @@
+{
+  "nonCachedDurationMs": 59.212716
+}

package/.rush/temp/operation/build_package-metas/all.log

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

package/.rush/temp/operation/build_package-metas/log-chunks.jsonl

@@ -0,0 +1 @@
+{"kind":"O","text":"Invoking: node node_modules/@excom/heft-rig/scripts/build-package-metas.mjs \n"}

package/.rush/temp/operation/build_package-metas/state.json

@@ -0,0 +1,3 @@
+{
+  "nonCachedDurationMs": 102.55112600000007
+}

package/.rush/temp/shrinkwrap-deps.json

@@ -0,0 +1,3 @@
+{
+  "../../packages/include-content": "../../packages/include-content:KH+u+L7h3dxOQYJV5Q4J+e9v8OEBWGr84HDgdzWGGFs=:"
+}

package/config/rig.json

@@ -0,0 +1,5 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
+  "rigPackageName": "@excom/heft-rig",
+  "rigProfile": "default"
+}

package/include-content.ts

@@ -0,0 +1,176 @@
+import { requestIdleCb } from "@excom/kit-shims";
+import { selectOne } from "@excom/kit-utils";
+import { Neutron } from "@excom/neutron";
+import { RenderableElement } from "@excom/renderable-element";
+
+/**
+ * Renders a `<template>` / remote HTML on demand — when visible, when idle,
+ * or immediately. Common cases need no app JavaScript.
+ *
+ * @summary Declarative view rendering — lazy (un)load, idle, conditional.
+ */
+export const IncludeContent = Neutron.compose([
+  RenderableElement,
+  Neutron({
+    tag: "include-content",
+    props: {
+      /**
+       * @option
+       * Activate after first paint, when the browser is idle. Useful for
+       * below-the-fold / secondary views that should not compete with
+       * critical content.
+       */
+      idleLoad: Boolean,
+      /**
+       * @option
+       * Activate when this element is on screen. Pair with
+       * `lazy-unload` for lazy load and lazy unload of views.
+       */
+      lazyLoad: Boolean,
+      /**
+       * @option
+       * Deactivate (unrender) when no longer on screen. Use with
+       * `lazy-load` to free DOM for off-screen views.
+       */
+      lazyUnload: Boolean,
+      /**
+       * @option
+       * Scroll container for lazy load / unload. Defaults to the
+       * viewport.
+       * @values <CSS Selector>
+       */
+      observerRoot: String,
+      /**
+       * @option
+       * How far outside the root counts as "visible". Expand (e.g.
+       * `500px`) to lazy-load a view *before* it enters the viewport so
+       * users never see an empty slot; shrink (default `-1px`) so
+       * edge-flush elements wait until they truly enter.
+       * @default -1px -1px -1px -1px
+       * @values <length> | <percentage>
+       */
+      observerRootMargin: {
+        type: String,
+        defaultValue: () => "-1px -1px -1px -1px",
+      },
+      /**
+       * @option
+       * Fraction of the element that must be visible (`0`–`1`) before
+       * activating.
+       */
+      observerThreshold: Number,
+      /**
+       * @option
+       * 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.
+       * @default 0
+       */
+      observerDelay: {
+        type: Number,
+        defaultValue: () => 0,
+      },
+      // private state
+      observer: IntersectionObserver,
+    },
+  }),
+])
+  .defineMethods({
+    determineActive: (element, entry: IntersectionObserverEntry) => {
+      const isVisible = element.checkVisibility
+        ? element.checkVisibility()
+        : true;
+      if (
+        isVisible &&
+        entry.isIntersecting &&
+        !element.isActive &&
+        element.lazyLoad
+      )
+        return { isActive: true };
+      else if (
+        (!isVisible || !entry.isIntersecting) &&
+        element.isActive &&
+        element.lazyUnload
+      )
+        return { isActive: false };
+    },
+    createObserver: (element) => {
+      if (!element.observer) {
+        return {
+          observer: watchElementWithIntersectionObserver(
+            element,
+            // @ts-ignore TODO defineMethods
+            element.determineActive,
+            {
+              root: element.observerRoot
+                ? selectOne(element.observerRoot, {
+                    scope: element,
+                  })
+                : null,
+              // Default `-1px` all around, so `top: 100vh` (etc.) isn't "visible"
+              rootMargin: element.observerRootMargin,
+              threshold: element.observerThreshold ?? undefined,
+              // IntersectionObserver spec v2; TypeScript typings lag behind
+              delay: element.observerDelay,
+            }
+          ),
+        };
+      }
+    },
+    destroyObserver: ({ observer }) => {
+      if (observer) {
+        observer.disconnect();
+        return {
+          observer: null,
+        };
+      }
+    },
+  })
+  .onPropSet("idleLoad", (el) => {
+    if (!el.isActive) {
+      const cb = () => {
+        // Re-check `idleLoad`; the captured value may be stale.
+        // `cancelIdleCallback` would be nicer, but Safari lacks it.
+        if (el.idleLoad) {
+          el.isActive = true;
+        }
+      };
+      // Fallback: wait until after the next paint (~16ms)
+      requestIdleCb(cb, 17);
+    }
+  })
+  .onPropChanged(["lazyLoad", "lazyUnload"], ({ lazyLoad, lazyUnload }) =>
+    lazyLoad || lazyUnload ? { createObserver: [] } : { destroyObserver: [] }
+  )
+  /* Drop the observer once it's no longer needed */
+  .onPropSet(
+    "isActive",
+    ({ lazyUnload }) =>
+      !lazyUnload && {
+        destroyObserver: [],
+      }
+  )
+  .onPropUnset(
+    "isActive",
+    ({ lazyLoad }) => !lazyLoad && { destroyObserver: [] }
+  )
+  .onDisconnected(() => ({ destroyObserver: [] }))
+  .onConnected(
+    ({ lazyLoad, lazyUnload, wasMounted }) =>
+      // Rebuilt after a real remove + reconnect (dev / framework remounts)
+      wasMounted && (lazyLoad || lazyUnload) && { createObserver: [] }
+  );
+
+function watchElementWithIntersectionObserver(
+  element: HTMLElement,
+  callback: (entry: IntersectionObserverEntry) => void,
+  // TODO: `IntersectionObserverInit` here causes a circular dependency?
+  options = {}
+) {
+  const observer = new IntersectionObserver((entries) => {
+    entries.forEach(callback);
+  }, options);
+  observer.observe(element);
+  return observer;
+}

package/index.css

@@ -0,0 +1,5 @@
+@import "./src/include-content.css";
+
+@layer {
+  @mixin module-include-content;
+}

package/index.ts

@@ -0,0 +1,17 @@
+import { IncludeContent } from "./include-content";
+
+IncludeContent.define();
+
+export { IncludeContent };
+
+type T_HTMLIncludeContentElement = typeof IncludeContent.CustomElement;
+declare global {
+  interface HTMLIncludeContentElement extends T_HTMLIncludeContentElement {}
+  interface Window {
+    HTMLIncludeContentElement: HTMLIncludeContentElement;
+  }
+  interface HTMLElementTagNameMap {
+    "include-content": HTMLIncludeContentElement;
+  }
+}
+export type { HTMLIncludeContentElement };

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@excom/include-content",
+  "version": "0.1.0",
+  "description": "<include-content> custom element",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24.13.0"
+  },
+  "type": "module",
+  "dependencies": {
+    "@excom/kit-shims": "^0.1.0",
+    "@excom/kit-utils": "^0.1.0",
+    "@excom/neutron": "^0.1.0",
+    "@excom/renderable-element": "^0.1.0"
+  },
+  "peerDependencies": {},
+  "devDependencies": {
+    "@excom/heft-rig": "^0.1.0"
+  },
+  "repository": {
+    "url": "excom-dev/nucleus",
+    "directory": "packages/include-content"
+  },
+  "homepage": "https://github.com/excom-dev/nucleus/tree/main/packages/include-content/support/docs/README.md",
+  "bugs": "https://github.com/excom-dev/nucleus/issues",
+  "keywords": [
+    "include-content",
+    "neutron",
+    "custom-elements"
+  ],
+  "excom": {
+    "packageType": "kit-element"
+  },
+  "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/include-content.apply-exports.cache.log

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

package/rush-logs/include-content.apply-exports.log

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

package/rush-logs/include-content.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/include-content.build_docs.log

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

package/rush-logs/include-content.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/include-content.build_package-metas.log

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

package/src/include-content.css

@@ -0,0 +1,66 @@
+@import "@excom/renderable-element/src/index.css";
+
+/**
+ * Styles for `<include-content>`.
+ * @element include-content
+ */
+
+/* Aliases */
+@custom-selector :--include-content include-content, .tag-include-content;
+@custom-selector :--include-content--lazy-load [lazy-load], [data-lazy-load];
+@custom-selector :--include-content--lazy-unload [lazy-unload], [data-lazy-unload];
+@custom-selector :--include-content--did-load [did-load], [data-did-load];
+@custom-selector :--include-content--is-active [is-active], [aria-current];
+@custom-selector :--include-content--host-shadow [host-ref="shadow"], [data-host-ref="shadow"];
+
+@define-mixin module-include-content {
+  :root {
+    /**
+     * Fade-in duration.
+     * @cssproperty
+     * @syntax <time>
+     * @default 0.15s
+     */
+    --include-content-transition-duration: var(
+      --v-transition-duration-fast,
+      0.15s
+    );
+    /**
+     * Fade-in easing.
+     * @cssproperty
+     * @syntax *
+     * @default ease-in
+     */
+    --include-content-transition-ease: var(--v-transition-ease-out, ease-in);
+  }
+
+  :--include-content {
+    display: block;
+
+    &:--include-content--lazy-load,
+    &:--include-content--lazy-unload {
+      min-height: 10px;
+      min-width: 10px;
+    }
+
+    /**
+     * Skip the built-in fade — bring your own animation / view transition.
+     * Also opts-out if the element is portalling content elsewhere ([host-ref])
+     * @cssclass instant
+     */
+    &:not(.instant):not([host-ref]) {
+      opacity: 0;
+      transition: opacity var(--include-content-transition-duration)
+        var(--include-content-transition-ease);
+
+      &:--include-content--did-load:--include-content--is-active {
+        &:--include-content--host-shadow,
+        &:has(> *:not(template)) {
+          opacity: 1;
+        }
+      }
+    }
+
+    @mixin renderable-element;
+  }
+}

package/support/custom-elements.json

@@ -0,0 +1,277 @@
+{
+  "schemaVersion": "1.0.0",
+  "modules": [
+    {
+      "kind": "javascript-module",
+      "path": "include-content.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "name": "IncludeContent",
+          "customElement": true,
+          "tagName": "include-content",
+          "mixins": [
+            {
+              "name": "RenderableElement",
+              "package": "@excom/renderable-element"
+            }
+          ],
+          "summary": "Declarative view rendering — lazy (un)load, idle, conditional.",
+          "description": "Renders a `<template>` / remote HTML on demand — when visible, when idle, or immediately. Common cases need no app JavaScript.",
+          "attributes": [
+            {
+              "name": "idle-load",
+              "type": {
+                "text": "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"
+            },
+            {
+              "name": "lazy-load",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Activate when this element is on screen. Pair with `lazy-unload` for lazy load and lazy unload of views.",
+              "fieldName": "lazyLoad"
+            },
+            {
+              "name": "lazy-unload",
+              "type": {
+                "text": "boolean"
+              },
+              "description": "Deactivate (unrender) when no longer on screen. Use with `lazy-load` to free DOM for off-screen views.",
+              "fieldName": "lazyUnload"
+            },
+            {
+              "name": "observer-root",
+              "type": {
+                "text": "string"
+              },
+              "description": "Scroll container for lazy load / unload. Defaults to the viewport.",
+              "fieldName": "observerRoot",
+              "values": [
+                "<CSS Selector>"
+              ]
+            },
+            {
+              "name": "observer-root-margin",
+              "type": {
+                "text": "string"
+              },
+              "description": "How far outside the root counts as \"visible\". Expand (e.g. `500px`) to lazy-load a view *before* it enters the viewport so users never see an empty slot; shrink (default `-1px`) so edge-flush elements wait until they truly enter.",
+              "fieldName": "observerRootMargin",
+              "default": "-1px -1px -1px -1px",
+              "values": [
+                "<length>",
+                "<percentage>"
+              ]
+            },
+            {
+              "name": "observer-threshold",
+              "type": {
+                "text": "number"
+              },
+              "description": "Fraction of the element that must be visible (`0`–`1`) before activating.",
+              "fieldName": "observerThreshold"
+            },
+            {
+              "name": "observer-delay",
+              "type": {
+                "text": "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",
+              "default": 0
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "idleLoad",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Activate after first paint, when the browser is idle. Useful for below-the-fold / secondary views that should not compete with critical content.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "lazyLoad",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Activate when this element is on screen. Pair with `lazy-unload` for lazy load and lazy unload of views.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "lazyUnload",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Deactivate (unrender) when no longer on screen. Use with `lazy-load` to free DOM for off-screen views.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "observerRoot",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Scroll container for lazy load / unload. Defaults to the viewport.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "observerRootMargin",
+              "type": {
+                "text": "string"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "How far outside the root counts as \"visible\". Expand (e.g. `500px`) to lazy-load a view *before* it enters the viewport so users never see an empty slot; shrink (default `-1px`) so edge-flush elements wait until they truly enter.",
+              "default": "-1px -1px -1px -1px",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "observerThreshold",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "description": "Fraction of the element that must be visible (`0`–`1`) before activating.",
+              "_neutron": {
+                "surface": "option"
+              }
+            },
+            {
+              "kind": "field",
+              "name": "observerDelay",
+              "type": {
+                "text": "number"
+              },
+              "privacy": "public",
+              "readonly": false,
+              "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.",
+              "default": 0,
+              "_neutron": {
+                "surface": "option"
+              }
+            }
+          ],
+          "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"
+            }
+          ],
+          "_neutron": {
+            "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"
+              },
+              {
+                "name": ":--include-content--lazy-load",
+                "selectors": [
+                  "[lazy-load]",
+                  "[data-lazy-load]"
+                ],
+                "kind": "state"
+              },
+              {
+                "name": ":--include-content--lazy-unload",
+                "selectors": [
+                  "[lazy-unload]",
+                  "[data-lazy-unload]"
+                ],
+                "kind": "state"
+              },
+              {
+                "name": ":--include-content--did-load",
+                "selectors": [
+                  "[did-load]",
+                  "[data-did-load]"
+                ],
+                "kind": "state"
+              },
+              {
+                "name": ":--include-content--is-active",
+                "selectors": [
+                  "[is-active]",
+                  "[aria-current]"
+                ],
+                "kind": "state"
+              },
+              {
+                "name": ":--include-content--host-shadow",
+                "selectors": [
+                  "[host-ref=\"shadow\"]",
+                  "[data-host-ref=\"shadow\"]"
+                ],
+                "kind": "state"
+              }
+            ]
+          }
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "IncludeContent",
+          "declaration": {
+            "name": "IncludeContent",
+            "module": "include-content.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "include-content",
+          "declaration": {
+            "name": "IncludeContent",
+            "module": "include-content.ts"
+          }
+        }
+      ]
+    }
+  ]
+}