npm - @hyperfixi/components - Versions diffs - 2.4.0 - Mend

@hyperfixi/components 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (27) hide show

package/src/register.ts ADDED Viewed

@@ -0,0 +1,308 @@
+/**
+ * Template-component registry — builds a Custom Element class for each
+ * `<template component="tag-name">` element and registers it via
+ * `customElements.define`.
+ *
+ * v2 render model:
+ *   - `${expr}` interpolation against `attrs`, with `^var` references rewritten
+ *     to call `reactive.readCaret(host, name)` so reads are tracked
+ *   - The render is wrapped in `reactive.createEffect(...)` so when any
+ *     tracked dep (e.g. `^count`) changes, the template re-stamps and the
+ *     runtime re-processes the new subtree
+ *   - Per-instance `_=` init script (from `<template _="...">` or
+ *     `<script type="text/hyperscript-template" _="...">`) is transferred
+ *     to the host element so the runtime processes it once via its standard
+ *     init mechanism
+ *
+ * v2.1 additions:
+ *   - `attrs` injected as a hyperscript local inside the init script
+ *   - `dom-scope="isolated"` set on each instance host
+ *   - `<style>` blocks lifted into <head> as `@scope (tag-name) { ... }`
+ *
+ * Deferred (v2.2+):
+ *   - Reactive re-render of attrs (today attrs values are read at first
+ *     render; mutating an attribute on the host doesn't re-render)
+ */
+import type { RuntimeLike } from './types';
+import { substituteSlots } from './slots';
+import { createAttrsProxy } from './attrs';
+import { reactive } from '@hyperfixi/reactivity';
+import { hyperscript, createContext } from '@hyperfixi/core';
+import { parseTemplate, renderTemplate, type TemplateNode } from './template-ast';
+import { extractStyles, injectScopedStyles } from './scope-css';
+/**
+ * Module-level registry of tag names already defined. `customElements.define`
+ * throws on duplicate registration, so we dedupe here.
+ */
+const REGISTERED = new Set<string>();
+interface RegistryOptions {
+  runtime?: RuntimeLike;
+}
+/**
+ * Rewrite `^name` references in an expression so they become calls to a
+ * tracked-read helper. Property access continues naturally:
+ *
+ *   ^count        → __c('count')
+ *   ^user.name    → __c('user').name
+ *   ^items.length → __c('items').length
+ *
+ * Only matches `^` followed by an identifier — bitwise XOR (`a ^ b`) where
+ * `b` starts with a digit/punctuation is unaffected. Bitwise XOR with a
+ * named operand inside an interpolation is rare enough not to worry about.
+ */
+function rewriteCaretRefs(expr: string): string {
+  return expr.replace(/\^([a-zA-Z_][a-zA-Z0-9_]*)/g, "__c('$1')");
+}
+/**
+ * Evaluate a `${...}` expression. Supports:
+ *   - `attrs.X` — read from the component's attrs proxy
+ *   - `^name` and `^name.path` — read DOM-scoped vars via the reactivity graph
+ *
+ * Errors silently return empty string (matches upstream tolerance).
+ */
+function evalInterpolation(
+  expr: string,
+  scope: Record<string, unknown>,
+  hostElement: Element
+): unknown {
+  const rewritten = rewriteCaretRefs(expr);
+  const fn = new Function(
+    ...Object.keys(scope),
+    '__c',
+    `"use strict"; try { return (${rewritten}); } catch (e) { return undefined; }`
+  );
+  return fn(...Object.values(scope), (name: string) => reactive.readCaret(hostElement, name));
+}
+/**
+ * Stamp a static text block by replacing each `${...}` with the stringified
+ * result of `evalInterpolation`.
+ */
+function interpolate(source: string, scope: Record<string, unknown>, hostElement: Element): string {
+  return source.replace(/\$\{([^}]+)\}/g, (_, expr) => {
+    try {
+      const result = evalInterpolation(expr.trim(), scope, hostElement);
+      return result == null ? '' : String(result);
+    } catch {
+      return '';
+    }
+  });
+}
+/**
+ * Render a parsed template AST (with `#if`/`#for` directives) against a scope.
+ * Routes both `${...}` interpolation and bare-expression evaluation through
+ * the same caret-aware path so `^var` works uniformly.
+ */
+function renderAst(
+  nodes: TemplateNode[],
+  scope: Record<string, unknown>,
+  hostElement: Element
+): string {
+  return renderTemplate(
+    nodes,
+    scope,
+    (text, s) => interpolate(text, s, hostElement),
+    (expr, s) => evalInterpolation(expr.trim(), s, hostElement)
+  );
+}
+/**
+ * Register a single `<template component="tag-name">` element.
+ * Idempotent: returns false (without error) if the tag is already registered.
+ */
+export function registerTemplateComponent(
+  templateEl: HTMLTemplateElement,
+  options: RegistryOptions = {}
+): boolean {
+  const tagName = templateEl.getAttribute('component');
+  if (!tagName || !tagName.includes('-')) {
+    if (typeof console !== 'undefined') {
+      console.error(
+        `[@hyperfixi/components] <template component="${tagName}"> must contain a dash`
+      );
+    }
+    return false;
+  }
+  if (REGISTERED.has(tagName) || customElements.get(tagName)) {
+    return false;
+  }
+  REGISTERED.add(tagName);
+  const { html: rawTemplateSource, init: initSource } = readTemplate(templateEl);
+  const runtime = options.runtime;
+  // Lift `<style>` blocks out of the template, scope them to this tag, and
+  // inject into <head>. The cleaned HTML (without the `<style>` blocks) is
+  // what each instance stamps. Idempotent — calling registerTemplateComponent
+  // a second time for the same tag is a no-op above; the style injection has
+  // its own data-component dedup so re-extraction is harmless either way.
+  const { html: templateSource, styles } = extractStyles(rawTemplateSource);
+  injectScopedStyles(tagName, styles);
+  // Parse the template AST once at registration time. Each instance reuses
+  // this AST and re-renders against its own scope.
+  const templateAst = parseTemplate(templateSource);
+  class TemplateComponent extends HTMLElement {
+    private _initialized = false;
+    private _cleanupFns: Array<() => void> = [];
+    connectedCallback() {
+      if (this._initialized) return;
+      this._initialized = true;
+      // Mark this instance as a `^var` isolation boundary so descendant
+      // caret-var reads/writes don't walk past it into the parent scope.
+      // Set BEFORE init runs so the init's own `set ^X to Y` writes land
+      // here (findCaretOwner stops at the boundary if no owner is found).
+      if (!this.hasAttribute('dom-scope')) {
+        this.setAttribute('dom-scope', 'isolated');
+      }
+      // Capture slot content (innerHTML) BEFORE we stamp the template, so
+      // children written in the page get inserted into `<slot/>` placeholders.
+      const slotContent = this.innerHTML;
+      this.innerHTML = '';
+      const attrs = createAttrsProxy(this);
+      // Slot substitution happens on the source HTML before AST rendering, so
+      // <slot/> placeholders are replaced once per instance against the AST's
+      // serialized output. (Slots aren't reactive — content is stamped at
+      // first render and stays stable across `^var` re-renders.)
+      const renderBody = (): string => {
+        const rendered = renderAst(templateAst, { attrs }, this);
+        return substituteSlots(rendered, slotContent);
+      };
+      // Run init `_=` once via hyperscript.eval. We do NOT put it on the host
+      // as an attribute — that would cause every subsequent reactive re-render
+      // (which calls hyperscript.process(this)) to re-run init and reset state.
+      //
+      // We build the context manually so we can pre-populate `attrs` as a
+      // local. That makes the upstream pattern `set ^user to attrs.data`
+      // work — `attrs` is then resolvable as a hyperscript identifier inside
+      // the init script. (Descendants' `_=` attributes go through the
+      // standard process path and don't see `attrs` — by design; if you need
+      // attrs values in descendants, copy them into `^vars` during init.)
+      if (initSource) {
+        try {
+          const initCtx = createContext(this);
+          initCtx.locals.set('attrs', attrs);
+          void hyperscript.eval(initSource, initCtx);
+        } catch (err) {
+          if (typeof console !== 'undefined') {
+            console.error('[@hyperfixi/components] init script failed:', err);
+          }
+        }
+      }
+      // Synchronous first render so callers see content immediately on
+      // appendChild — matches v1 semantics. Tracking-aware re-renders happen
+      // through the reactive effect below.
+      // Note: `hyperscript.process` is the singleton API entry point that
+      // compiles + binds `_=` attributes (the per-runtime `Runtime` class
+      // does not expose process directly).
+      const renderOnce = (): void => {
+        this.innerHTML = renderBody();
+        try {
+          hyperscript.process(this);
+        } catch (err) {
+          if (typeof console !== 'undefined') {
+            console.error('[@hyperfixi/components] hyperscript.process failed:', err);
+          }
+        }
+      };
+      renderOnce();
+      // Reactive effect: any `^var` read during render is tracked, and
+      // writes to those vars trigger a re-stamp + re-process. Effect
+      // initializes via microtask; first run sees same content (Object.is
+      // skips handler) but records dependencies for subsequent writes.
+      const stopEffect = reactive.createEffect(() => renderBody(), renderOnce, this);
+      this._cleanupFns.push(stopEffect);
+      // Register cleanup so disconnect fires teardown of any hyperscript
+      // observers bound to children. Uses core's CleanupRegistry via the
+      // runtime passed at install time.
+      if (runtime) {
+        try {
+          runtime.getCleanupRegistry().registerCustom(
+            this,
+            () => {
+              for (const fn of this._cleanupFns) {
+                try {
+                  fn();
+                } catch {
+                  /* ignore */
+                }
+              }
+              this._cleanupFns = [];
+            },
+            'template-component'
+          );
+        } catch {
+          /* getCleanupRegistry missing — skip */
+        }
+      }
+    }
+    disconnectedCallback() {
+      this._initialized = false;
+      for (const fn of this._cleanupFns) {
+        try {
+          fn();
+        } catch {
+          /* ignore */
+        }
+      }
+      this._cleanupFns = [];
+    }
+  }
+  try {
+    customElements.define(tagName, TemplateComponent);
+    return true;
+  } catch (err) {
+    REGISTERED.delete(tagName);
+    if (typeof console !== 'undefined') {
+      console.error(`[@hyperfixi/components] customElements.define("${tagName}") failed:`, err);
+    }
+    return false;
+  }
+}
+/**
+ * Read a template definition: extract the body HTML and (if present) the
+ * per-instance init script. Init source is read from `_=` (preferred) or
+ * `data-init` (the `<script>`-form converter sets this in scan.ts).
+ */
+function readTemplate(templateEl: HTMLTemplateElement): { html: string; init: string | null } {
+  const init = templateEl.getAttribute('_') ?? templateEl.getAttribute('data-init');
+  let html: string;
+  if (templateEl.content && typeof templateEl.content.childNodes !== 'undefined') {
+    const container = document.createElement('div');
+    for (const child of Array.from(templateEl.content.childNodes)) {
+      container.appendChild(child.cloneNode(true));
+    }
+    html = container.innerHTML;
+  } else {
+    html = templateEl.innerHTML;
+  }
+  return { html, init };
+}
+/**
+ * Clear the registered-tags set. Intended for test isolation only — custom
+ * element registrations cannot be un-defined, so this only affects our
+ * idempotency check, not the real registry.
+ */
+export function _resetRegisteredForTest(): void {
+  REGISTERED.clear();
+}

package/src/scan.ts ADDED Viewed

@@ -0,0 +1,96 @@
+/**
+ * DOM scanner — finds `<template component="tag-name">` elements and
+ * registers them. Also supports `<script type="text/hyperscript-template"
+ * component="tag-name">` for upstream compatibility.
+ */
+import type { RuntimeLike } from './types';
+import { registerTemplateComponent } from './register';
+interface ScanOptions {
+  runtime?: RuntimeLike;
+}
+/**
+ * Scan the given root (defaults to `document`) for template definitions and
+ * register each as a custom element.
+ *
+ * Returns the number of new registrations performed.
+ */
+export function scanAndRegister(
+  root: ParentNode = typeof document !== 'undefined' ? document : (null as never),
+  options: ScanOptions = {}
+): number {
+  if (!root) return 0;
+  let count = 0;
+  // <template component="tag-name">
+  const templates = root.querySelectorAll('template[component]');
+  templates.forEach(t => {
+    if (registerTemplateComponent(t as HTMLTemplateElement, options)) count++;
+  });
+  // <script type="text/hyperscript-template" component="tag-name" _="init script">
+  // Upstream uses this form; we support it for compat. Convert to a
+  // synthetic HTMLTemplateElement so register code is shared. Init scripts
+  // (`_=`) are preserved so they run once per instance.
+  const scripts = root.querySelectorAll('script[type="text/hyperscript-template"][component]');
+  scripts.forEach(s => {
+    const fake = document.createElement('template');
+    const componentAttr = s.getAttribute('component');
+    if (componentAttr) fake.setAttribute('component', componentAttr);
+    const initScript = s.getAttribute('_');
+    if (initScript) fake.setAttribute('data-init', initScript);
+    fake.innerHTML = s.textContent ?? '';
+    if (registerTemplateComponent(fake, options)) count++;
+  });
+  return count;
+}
+/**
+ * Start watching the document for dynamically-added template definitions.
+ * Returns a disposer that stops the observer.
+ *
+ * Safe to call in non-DOM environments (returns a no-op disposer).
+ */
+export function watchForTemplates(options: ScanOptions = {}): () => void {
+  if (typeof document === 'undefined' || typeof MutationObserver === 'undefined') {
+    return () => {};
+  }
+  const observer = new MutationObserver(mutations => {
+    for (const mut of mutations) {
+      for (const node of Array.from(mut.addedNodes)) {
+        if (node.nodeType !== Node.ELEMENT_NODE) continue;
+        const el = node as Element;
+        // Added node itself
+        if (el.tagName === 'TEMPLATE' && el.hasAttribute('component')) {
+          registerTemplateComponent(el as HTMLTemplateElement, options);
+        }
+        if (
+          el.tagName === 'SCRIPT' &&
+          el.getAttribute('type') === 'text/hyperscript-template' &&
+          el.hasAttribute('component')
+        ) {
+          const fake = document.createElement('template');
+          const componentAttr = el.getAttribute('component');
+          if (componentAttr) fake.setAttribute('component', componentAttr);
+          const initScript = el.getAttribute('_');
+          if (initScript) fake.setAttribute('data-init', initScript);
+          fake.innerHTML = el.textContent ?? '';
+          registerTemplateComponent(fake, options);
+        }
+        // Descendants
+        scanAndRegister(el, options);
+      }
+    }
+  });
+  observer.observe(document.documentElement || document.body, {
+    childList: true,
+    subtree: true,
+  });
+  return () => observer.disconnect();
+}

package/src/scope-css.test.ts ADDED Viewed

@@ -0,0 +1,80 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { extractStyles, injectScopedStyles, _resetInjectedStylesForTest } from './scope-css';
+describe('extractStyles', () => {
+  it('returns the input unchanged when there are no <style> blocks', () => {
+    const r = extractStyles('<div>hello</div>');
+    expect(r.html).toBe('<div>hello</div>');
+    expect(r.styles).toEqual([]);
+  });
+  it('strips a single <style> block and returns its body', () => {
+    const r = extractStyles('<div>hi</div><style>.x { color: red; }</style><p>p</p>');
+    expect(r.html).toBe('<div>hi</div><p>p</p>');
+    expect(r.styles).toEqual(['.x { color: red; }']);
+  });
+  it('strips multiple <style> blocks and returns them in order', () => {
+    const r = extractStyles('<style>a{}</style>mid<style>b{}</style>');
+    expect(r.html).toBe('mid');
+    expect(r.styles).toEqual(['a{}', 'b{}']);
+  });
+  it('handles attributes on the <style> tag', () => {
+    const r = extractStyles('<style type="text/css">.x{}</style>');
+    expect(r.styles).toEqual(['.x{}']);
+    expect(r.html).toBe('');
+  });
+  it('preserves the inner whitespace of style content', () => {
+    const css = '\n  .btn { padding: 4px; }\n';
+    const r = extractStyles(`before<style>${css}</style>after`);
+    expect(r.styles).toEqual([css]);
+    expect(r.html).toBe('beforeafter');
+  });
+});
+describe('injectScopedStyles', () => {
+  beforeEach(() => {
+    _resetInjectedStylesForTest();
+  });
+  it('does nothing when given no styles', () => {
+    const before = document.head.querySelectorAll('style[data-component]').length;
+    expect(injectScopedStyles('my-tag', [])).toBe(false);
+    expect(document.head.querySelectorAll('style[data-component]').length).toBe(before);
+  });
+  it('appends a single <style data-component> wrapped in @scope', () => {
+    expect(injectScopedStyles('my-tag', ['.btn { color: red; }'])).toBe(true);
+    const el = document.head.querySelector('style[data-component="my-tag"]');
+    expect(el).toBeTruthy();
+    expect(el!.textContent).toContain('@scope (my-tag)');
+    expect(el!.textContent).toContain('.btn { color: red; }');
+  });
+  it('joins multiple style blocks into one element with separate @scope rules', () => {
+    expect(injectScopedStyles('my-card', ['.a {}', '.b {}'])).toBe(true);
+    const el = document.head.querySelector('style[data-component="my-card"]');
+    expect(el).toBeTruthy();
+    const text = el!.textContent ?? '';
+    expect(text.match(/@scope \(my-card\)/g)?.length).toBe(2);
+    expect(text).toContain('.a {}');
+    expect(text).toContain('.b {}');
+  });
+  it('is idempotent for the same tag name', () => {
+    expect(injectScopedStyles('dedup-tag', ['.x {}'])).toBe(true);
+    expect(injectScopedStyles('dedup-tag', ['.x {}'])).toBe(false);
+    expect(injectScopedStyles('dedup-tag', ['.y {}'])).toBe(false);
+    const matches = document.head.querySelectorAll('style[data-component="dedup-tag"]');
+    expect(matches.length).toBe(1);
+  });
+  it('keeps distinct components in distinct <style> elements', () => {
+    expect(injectScopedStyles('comp-a', ['.a {}'])).toBe(true);
+    expect(injectScopedStyles('comp-b', ['.b {}'])).toBe(true);
+    expect(document.head.querySelector('style[data-component="comp-a"]')).toBeTruthy();
+    expect(document.head.querySelector('style[data-component="comp-b"]')).toBeTruthy();
+  });
+});

package/src/scope-css.ts ADDED Viewed

@@ -0,0 +1,87 @@
+/**
+ * Scoped CSS — lift `<style>` blocks out of component templates and inject
+ * them into `<head>` wrapped in `@scope (tag-name) { ... }`.
+ *
+ * Mirrors upstream _hyperscript 0.9.91's component style-scoping behavior.
+ * Two reasons we do this:
+ *   1. Without lifting, every instance's innerHTML would contain a copy of
+ *      the `<style>` block. The browser parses each one — wasteful and a
+ *      footgun if the user uses non-`@scope` selectors.
+ *   2. Wrapping the contents in `@scope (tag-name) { ... }` confines them
+ *      to that custom-element tree, so styles authored against a generic
+ *      `.btn` class don't leak globally.
+ *
+ * Browser support: `@scope` is in Chrome 118+, Safari 17.4+, Firefox 128+.
+ * In older browsers, the `@scope` rule is ignored and styles leak globally
+ * — graceful degradation; nothing actively breaks.
+ *
+ * Idempotency: the same component may be (re)scanned multiple times via
+ * `componentsPlugin.scan()` followed by `watchForTemplates()`. We dedupe by
+ * a `data-component="${tagName}"` attribute on the injected `<style>`.
+ */
+const STYLE_BLOCK_RE = /<style(?:\s[^>]*)?>([\s\S]*?)<\/style\s*>/gi;
+export interface ExtractResult {
+  /** The HTML with all `<style>` blocks removed. */
+  html: string;
+  /** The raw text content of each removed `<style>` block, in document order. */
+  styles: string[];
+}
+/**
+ * Strip `<style>...</style>` blocks from `html` and return their text content.
+ * Preserves the surrounding HTML otherwise. Tag-attributes on `<style>` are
+ * dropped (we re-build the injected element's attributes ourselves).
+ */
+export function extractStyles(html: string): ExtractResult {
+  const styles: string[] = [];
+  const cleaned = html.replace(STYLE_BLOCK_RE, (_match, body: string) => {
+    styles.push(body);
+    return '';
+  });
+  return { html: cleaned, styles };
+}
+/**
+ * Inject the given style blocks into `document.head` as a single
+ * `<style data-component="${tagName}">` element wrapped in `@scope`. No-op if
+ * `styles` is empty or if the injection has already been done for this tag.
+ *
+ * Returns `true` if injection happened, `false` if it was skipped (already
+ * present, no styles, or no document/head available).
+ */
+export function injectScopedStyles(tagName: string, styles: string[]): boolean {
+  if (styles.length === 0) return false;
+  if (typeof document === 'undefined' || !document.head) return false;
+  const selector = `style[data-component="${cssAttrEscape(tagName)}"]`;
+  if (document.head.querySelector(selector)) return false;
+  const wrapped = styles.map(body => `@scope (${tagName}) {\n${body}\n}`).join('\n\n');
+  const styleEl = document.createElement('style');
+  styleEl.setAttribute('data-component', tagName);
+  styleEl.textContent = wrapped;
+  document.head.appendChild(styleEl);
+  return true;
+}
+/**
+ * Test-only helper: remove any styles previously injected by
+ * `injectScopedStyles`. Real usage doesn't need this — once a component is
+ * registered, its scoped styles persist for the page's lifetime.
+ */
+export function _resetInjectedStylesForTest(): void {
+  if (typeof document === 'undefined' || !document.head) return;
+  const injected = document.head.querySelectorAll('style[data-component]');
+  injected.forEach(el => el.parentNode?.removeChild(el));
+}
+/**
+ * Escape `tagName` for safe use inside a CSS attribute-selector string.
+ * Custom-element tag names are restricted by the spec (lowercase ASCII +
+ * digit + hyphen + colon + dot + underscore), so this is mostly defensive.
+ */
+function cssAttrEscape(s: string): string {
+  return s.replace(/["\\]/g, '\\$&');
+}

package/src/slots.test.ts ADDED Viewed

@@ -0,0 +1,55 @@
+/**
+ * Slot substitution unit tests.
+ */
+import { describe, it, expect } from 'vitest';
+import { substituteSlots } from './slots';
+describe('substituteSlots', () => {
+  it('returns the template unchanged when slot content is empty', () => {
+    const tmpl = '<div><slot/></div>';
+    expect(substituteSlots(tmpl, '')).toBe(tmpl);
+  });
+  it('replaces <slot/> with default content', () => {
+    const result = substituteSlots('<div><slot/></div>', '<span>hi</span>');
+    expect(result).toContain('<span>hi</span>');
+    expect(result).not.toContain('<slot');
+  });
+  it('replaces <slot></slot> (explicit close) with default content', () => {
+    const result = substituteSlots('<div><slot></slot></div>', 'plain text');
+    expect(result).toContain('plain text');
+    expect(result).not.toContain('<slot');
+  });
+  it('replaces named slots with matching content', () => {
+    const tmpl = '<header><slot name="title"/></header><main><slot/></main>';
+    const content = '<h1 slot="title">Hello</h1><p>Body</p>';
+    const result = substituteSlots(tmpl, content);
+    expect(result).toContain('<h1>Hello</h1>'); // slot="title" stripped
+    expect(result).toContain('<p>Body</p>');
+  });
+  it('omits named-slot output when no matching content provided', () => {
+    const tmpl = '<header><slot name="title"/></header><slot/>';
+    const content = '<p>Body</p>'; // no slot="title" child
+    const result = substituteSlots(tmpl, content);
+    expect(result).not.toContain('slot'); // both placeholders removed
+    expect(result).toContain('<p>Body</p>');
+  });
+  it('handles multiple named slots', () => {
+    const tmpl = '<div><slot name="a"/></div><div><slot name="b"/></div>';
+    const content = '<x slot="a">A</x><y slot="b">B</y>';
+    const result = substituteSlots(tmpl, content);
+    expect(result).toContain('<x>A</x>');
+    expect(result).toContain('<y>B</y>');
+  });
+  it('preserves text nodes in default content', () => {
+    const tmpl = '<div><slot/></div>';
+    const result = substituteSlots(tmpl, 'plain words');
+    expect(result).toContain('plain words');
+  });
+});