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/dist/scan.d.ts ADDED Viewed

@@ -0,0 +1,24 @@
+/**
+ * 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';
+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 declare function scanAndRegister(root?: ParentNode, options?: ScanOptions): number;
+/**
+ * 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 declare function watchForTemplates(options?: ScanOptions): () => void;
+export {};

package/dist/scope-css.d.ts ADDED Viewed

@@ -0,0 +1,48 @@
+/**
+ * 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>`.
+ */
+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 declare function extractStyles(html: string): ExtractResult;
+/**
+ * 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 declare function injectScopedStyles(tagName: string, styles: string[]): boolean;
+/**
+ * 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 declare function _resetInjectedStylesForTest(): void;

package/dist/slots.d.ts ADDED Viewed

@@ -0,0 +1,15 @@
+/**
+ * Slot substitution — replace `<slot/>` and `<slot name="X"/>` placeholders
+ * in a template source string with content provided at instantiation.
+ *
+ * Port of upstream _hyperscript 0.9.91's `substituteSlots` (src/ext/component.js).
+ * Regex-based rather than DOM-based so the template source stays a plain string
+ * the render engine can consume.
+ */
+/**
+ * Replace `<slot name="X"/>` / `<slot name="X"></slot>` with named content,
+ * and `<slot/>` / `<slot></slot>` with default content.
+ *
+ * Returns the template source with all `<slot>` placeholders substituted.
+ */
+export declare function substituteSlots(templateSource: string, slotContent: string): string;

package/dist/template-ast.d.ts ADDED Viewed

@@ -0,0 +1,43 @@
+/**
+ * Template AST — parse + render with `#if`/`#else`/`#end`/`#for` directives.
+ *
+ * Mirrors upstream _hyperscript 0.9.91's component template syntax. Directives
+ * are line-oriented: each directive must occupy its own line (modulo
+ * surrounding whitespace). `${...}` interpolation can appear anywhere in
+ * static text; it's evaluated by the same path used outside directives.
+ *
+ * Supported:
+ *   #if <expr>          ... [#else] ... #end
+ *   #for <name> in <expr> ... [#else] ... #end       (#else fires on empty)
+ *
+ * Deferred (v2.1+):
+ *   #continue   — skip the current iteration of the enclosing `#for`
+ */
+export type TemplateNode = {
+    kind: 'text';
+    content: string;
+} | {
+    kind: 'if';
+    cond: string;
+    then: TemplateNode[];
+    else: TemplateNode[];
+} | {
+    kind: 'for';
+    varName: string;
+    iterableExpr: string;
+    body: TemplateNode[];
+    elseEmpty: TemplateNode[];
+};
+/**
+ * Parse a template body into a sequence of TemplateNodes.
+ * Directives are recognized only when they occupy their own line.
+ */
+export declare function parseTemplate(source: string): TemplateNode[];
+/**
+ * Render a parsed template AST against a scope. `interpText` handles `${...}`
+ * interpolation in static blocks; `evalExpr` evaluates the bare expression in
+ * `#if <expr>` and `#for <var> in <expr>`. Both are passed in so the renderer
+ * stays decoupled from the components plugin's host-element / caret-var
+ * specifics — each callsite supplies the appropriate evaluator closure.
+ */
+export declare function renderTemplate(nodes: TemplateNode[], scope: Record<string, unknown>, interpText: (text: string, scope: Record<string, unknown>) => string, evalExpr: (expr: string, scope: Record<string, unknown>) => unknown): string;

package/dist/types.d.ts ADDED Viewed

@@ -0,0 +1,25 @@
+/**
+ * Lightweight local type stubs — mirror the speech/reactivity pattern of
+ * avoiding tight coupling to `@hyperfixi/core` internals.
+ */
+export interface RuntimeLike {
+    execute(node: unknown, context: unknown): Promise<unknown>;
+    getCleanupRegistry(): {
+        registerCustom(element: Element, cleanup: () => void, description?: string): void;
+    };
+    process?: (root: Element) => void | Promise<void>;
+}
+export interface ASTNode {
+    type: string;
+    name?: string;
+    value?: unknown;
+    [k: string]: unknown;
+}
+export interface ExecutionContext {
+    me?: Element | null;
+    result?: unknown;
+    it?: unknown;
+    globals?: Map<string, unknown>;
+    locals?: Map<string, unknown>;
+    [k: string]: unknown;
+}

package/package.json ADDED Viewed

@@ -0,0 +1,64 @@
+{
+  "name": "@hyperfixi/components",
+  "version": "2.4.0",
+  "description": "Template-component plugin for hyperfixi — register custom elements from `<template component=\"tag-name\">` definitions (upstream _hyperscript 0.9.90).",
+  "type": "module",
+  "sideEffects": false,
+  "main": "dist/index.cjs",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "scripts": {
+    "build": "tsup && npm run build:types",
+    "build:types": "tsc --emitDeclarationOnly --outDir dist --noEmit false",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:check": "vitest run --reporter=dot 2>&1 | tail -5",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@hyperfixi/core": "*",
+    "@hyperfixi/reactivity": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "happy-dom": "^20.9.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.0.0",
+    "vitest": "^4.1.5"
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE"
+  ],
+  "keywords": [
+    "hyperfixi",
+    "hyperscript",
+    "components",
+    "custom-elements",
+    "template",
+    "plugin",
+    "_hyperscript",
+    "v0.9.90"
+  ],
+  "author": "LokaScript Contributors",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codetalcott/hyperfixi.git",
+    "directory": "packages/components"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/attrs.test.ts ADDED Viewed

@@ -0,0 +1,62 @@
+/**
+ * `attrs` proxy unit tests.
+ */
+import { describe, it, expect } from 'vitest';
+import { createAttrsProxy } from './attrs';
+describe('createAttrsProxy', () => {
+  it('reads a string attribute as-is', () => {
+    const el = document.createElement('my-comp');
+    el.setAttribute('label', 'Hello');
+    const attrs = createAttrsProxy(el);
+    expect(attrs.label).toBe('Hello');
+  });
+  it('coerces numeric-looking attributes to numbers', () => {
+    const el = document.createElement('my-comp');
+    el.setAttribute('count', '42');
+    el.setAttribute('rate', '1.5');
+    el.setAttribute('neg', '-7');
+    const attrs = createAttrsProxy(el);
+    expect(attrs.count).toBe(42);
+    expect(attrs.rate).toBe(1.5);
+    expect(attrs.neg).toBe(-7);
+  });
+  it('coerces "true" / "false" to booleans', () => {
+    const el = document.createElement('my-comp');
+    el.setAttribute('open', 'true');
+    el.setAttribute('closed', 'false');
+    const attrs = createAttrsProxy(el);
+    expect(attrs.open).toBe(true);
+    expect(attrs.closed).toBe(false);
+  });
+  it('maps camelCase prop reads to kebab-case attributes', () => {
+    const el = document.createElement('my-comp');
+    el.setAttribute('initial-count', '5');
+    const attrs = createAttrsProxy(el);
+    expect(attrs.initialCount).toBe(5);
+  });
+  it('returns undefined for missing attributes', () => {
+    const el = document.createElement('my-comp');
+    const attrs = createAttrsProxy(el);
+    expect(attrs.missing).toBeUndefined();
+  });
+  it('writes back as kebab-case when prop is camelCase', () => {
+    const el = document.createElement('my-comp');
+    const attrs = createAttrsProxy(el);
+    attrs.initialCount = 10;
+    expect(el.getAttribute('initial-count')).toBe('10');
+  });
+  it('does not coerce non-numeric strings that happen to start with digits', () => {
+    const el = document.createElement('my-comp');
+    el.setAttribute('id', '42px'); // common CSS-like value
+    const attrs = createAttrsProxy(el);
+    expect(attrs.id).toBe('42px'); // unchanged
+  });
+});

package/src/attrs.ts ADDED Viewed

@@ -0,0 +1,80 @@
+/**
+ * `attrs` proxy — read component attributes as values on the component scope.
+ *
+ * Simplified from upstream's hyperscript-expression-evaluating version: for v1
+ * we treat attributes as plain strings with a few type coercions (number, bool)
+ * and a kebab-case-to-camelCase accessor.
+ *
+ * `<my-counter initial-count="5">` exposes `attrs.initialCount` = 5 (number).
+ */
+/**
+ * Coerce attribute string to a typed value.
+ * Rules:
+ *  - "true"   → true
+ *  - "false"  → false
+ *  - number-like strings (e.g. "5", "-3.14") → number
+ *  - everything else → original string
+ */
+function coerceAttrValue(raw: string | null): unknown {
+  if (raw == null) return undefined;
+  if (raw === 'true') return true;
+  if (raw === 'false') return false;
+  // Number check: not empty, fully numeric after Number()
+  if (raw !== '' && !Number.isNaN(Number(raw)) && /^-?(\d+\.?\d*|\.\d+)$/.test(raw)) {
+    return Number(raw);
+  }
+  return raw;
+}
+/**
+ * Convert camelCase prop name to kebab-case attribute name. Used so that
+ * reading `attrs.initialCount` finds the `initial-count="..."` attribute.
+ */
+function camelToKebab(name: string): string {
+  return name.replace(/[A-Z]/g, m => '-' + m.toLowerCase());
+}
+/**
+ * Create a proxy over a component element's attributes. Getting a property
+ * reads and coerces the matching kebab-case attribute. Setting a property
+ * writes it back as a string (simple stringification for v1).
+ */
+export function createAttrsProxy(componentEl: Element): Record<string, unknown> {
+  return new Proxy({} as Record<string, unknown>, {
+    get(_target, prop) {
+      if (typeof prop !== 'string' || prop.startsWith('_')) return undefined;
+      // Try exact match first (e.g. "role", "data-x"), then kebab-cased form.
+      const exact = componentEl.getAttribute(prop);
+      if (exact != null) return coerceAttrValue(exact);
+      const kebab = componentEl.getAttribute(camelToKebab(prop));
+      if (kebab != null) return coerceAttrValue(kebab);
+      return undefined;
+    },
+    set(_target, prop, value) {
+      if (typeof prop !== 'string') return false;
+      const attrName = componentEl.hasAttribute(prop) ? prop : camelToKebab(prop);
+      componentEl.setAttribute(attrName, value == null ? '' : String(value));
+      return true;
+    },
+    has(_target, prop) {
+      if (typeof prop !== 'string') return false;
+      return componentEl.hasAttribute(prop) || componentEl.hasAttribute(camelToKebab(prop));
+    },
+    ownKeys(_target) {
+      return Array.from(componentEl.attributes).map(a => a.name);
+    },
+    getOwnPropertyDescriptor(_target, prop) {
+      if (typeof prop !== 'string') return undefined;
+      const kebab = camelToKebab(prop);
+      if (componentEl.hasAttribute(prop) || componentEl.hasAttribute(kebab)) {
+        return {
+          enumerable: true,
+          configurable: true,
+          value: coerceAttrValue(componentEl.getAttribute(prop) ?? componentEl.getAttribute(kebab)),
+        };
+      }
+      return undefined;
+    },
+  });
+}

package/src/index.ts ADDED Viewed

@@ -0,0 +1,110 @@
+/**
+ * @hyperfixi/components — template-component plugin for hyperfixi.
+ *
+ * Registers custom elements from `<template component="tag-name">` definitions
+ * (mirrors upstream _hyperscript 0.9.91's component extension). Users write:
+ *
+ * ```html
+ * <template component="my-counter">
+ *   <button>Count: ${attrs.initialCount ?? 0}</button>
+ * </template>
+ *
+ * <my-counter initial-count="5"></my-counter>
+ * ```
+ *
+ * Install at app startup:
+ *
+ * ```ts
+ * import { createRuntime, installPlugin } from '@hyperfixi/core';
+ * import { componentsPlugin } from '@hyperfixi/components';
+ *
+ * const runtime = createRuntime();
+ * installPlugin(runtime, componentsPlugin);
+ * // Then scan (typically after DOMContentLoaded):
+ * componentsPlugin.scan(document);
+ * ```
+ *
+ * v2.1 scope:
+ *   - `<template component="tag-name">` scan + customElements.define
+ *   - `${attrs.name}` and `${^var}` interpolation (kebab-case attribute →
+ *     camelCase prop, with Number/Boolean coercion)
+ *   - `^var` reads tracked via @hyperfixi/reactivity; the template re-stamps
+ *     when any tracked `^var` changes
+ *   - Per-instance init script — `<template _="set ^count to 0">` (or `_=`
+ *     on the upstream `<script type="text/hyperscript-template">` form) runs
+ *     once on each instance via the runtime's standard init mechanism
+ *   - `attrs` available as a hyperscript local inside the init script — so
+ *     `_="set ^user to attrs.data as JSON"` works (descendants don't see
+ *     attrs; copy via ^vars during init if needed)
+ *   - `<slot/>` + `<slot name="X"/>` substitution from instantiation children
+ *   - `#if` / `#for` / `#else` / `#end` template directives
+ *   - `dom-scope="isolated"` boundary auto-set on each instance — nested
+ *     components don't leak `^var` reads/writes through each other
+ *   - `<style>` blocks lifted into <head> wrapped in `@scope (tag-name)` so
+ *     styles only apply within instances of that tag
+ *   - disconnectedCallback fires CleanupRegistry teardown
+ *   - MutationObserver watches for dynamically-added templates
+ *
+ * v2.2+ deferred:
+ *   - `#continue` directive in `#for` loops
+ *   - Reactive array mutation auto-tracking (matches upstream's known limit)
+ *   - Full parent-scope hyperscript evaluation of attribute values (today
+ *     `attrs.X` returns the raw string; users `as JSON` to parse)
+ */
+import type { HyperfixiPlugin, HyperfixiPluginContext } from '@hyperfixi/core';
+import type { RuntimeLike } from './types';
+import { scanAndRegister, watchForTemplates } from './scan';
+import { registerTemplateComponent } from './register';
+export { registerTemplateComponent, scanAndRegister, watchForTemplates };
+/**
+ * Module-level handle to the runtime captured at install time. Used by `scan`
+ * and `watch` to thread the runtime into each registered component for
+ * cleanup-registry access and child-processing.
+ */
+let INSTALLED_RUNTIME: RuntimeLike | null = null;
+let STOP_WATCH: (() => void) | null = null;
+/**
+ * Plugin object. `install()` captures the runtime; `scan()` / `watch()` can
+ * be called any time after install.
+ */
+export const componentsPlugin: HyperfixiPlugin & {
+  scan(root?: ParentNode): number;
+  watch(): () => void;
+  unwatch(): void;
+} = {
+  name: '@hyperfixi/components',
+  install(ctx: HyperfixiPluginContext) {
+    INSTALLED_RUNTIME = ctx.runtime as unknown as RuntimeLike;
+  },
+  /**
+   * Scan `root` (defaults to `document`) for template components and register
+   * each. Safe to call before or after install (but install is needed for
+   * cleanup-registry hookup).
+   */
+  scan(root?: ParentNode): number {
+    return scanAndRegister(root, { runtime: INSTALLED_RUNTIME ?? undefined });
+  },
+  /**
+   * Start watching the document for dynamically-added template components.
+   * Idempotent — calling twice is a no-op on the second call.
+   * Returns a disposer that also clears the module-level handle.
+   */
+  watch(): () => void {
+    if (STOP_WATCH) return STOP_WATCH;
+    const stop = watchForTemplates({ runtime: INSTALLED_RUNTIME ?? undefined });
+    STOP_WATCH = () => {
+      stop();
+      STOP_WATCH = null;
+    };
+    return STOP_WATCH;
+  },
+  unwatch(): void {
+    if (STOP_WATCH) STOP_WATCH();
+  },
+};
+export default componentsPlugin;