@hyperfixi/components 2.4.0

package/src/slots.ts

@@ -0,0 +1,70 @@
+/**
+ * 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.
+ */
+
+/**
+ * Partition raw slot content into named and default parts.
+ * Named = elements with a `slot="name"` attribute.
+ * Default = all other children (elements or text).
+ */
+function partitionSlotContent(slotContent: string): {
+  named: Record<string, string>;
+  defaultContent: string;
+} {
+  const named: Record<string, string> = {};
+  const defaultParts: string[] = [];
+
+  if (typeof document === 'undefined') {
+    // Non-browser fallback: treat everything as default content.
+    return { named, defaultContent: slotContent };
+  }
+
+  const tmp = document.createElement('div');
+  tmp.innerHTML = slotContent;
+
+  for (const child of Array.from(tmp.childNodes)) {
+    if (child.nodeType === Node.ELEMENT_NODE) {
+      const el = child as Element;
+      const slotName = el.getAttribute('slot');
+      if (slotName) {
+        el.removeAttribute('slot');
+        if (!named[slotName]) named[slotName] = '';
+        named[slotName] += (el as Element & { outerHTML: string }).outerHTML;
+        continue;
+      }
+      defaultParts.push((el as Element & { outerHTML: string }).outerHTML);
+    } else if (child.nodeType === Node.TEXT_NODE) {
+      defaultParts.push(child.textContent ?? '');
+    }
+  }
+
+  return { named, defaultContent: defaultParts.join('') };
+}
+
+/**
+ * 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 function substituteSlots(templateSource: string, slotContent: string): string {
+  if (!slotContent) return templateSource;
+  const { named, defaultContent } = partitionSlotContent(slotContent);
+
+  // Named slots first: <slot name="X"/> or <slot name="X"></slot>.
+  let source = templateSource.replace(
+    /<slot\s+name\s*=\s*["']([^"']+)["']\s*\/?\s*>(\s*<\/slot>)?/g,
+    (_match, name) => named[name as string] ?? ''
+  );
+
+  // Default slots: <slot/> or <slot></slot> (after named, so named-with-no-name
+  // attribute doesn't accidentally swallow default slot content).
+  source = source.replace(/<slot\s*\/?\s*>(\s*<\/slot>)?/g, defaultContent);
+
+  return source;
+}

package/src/template-ast.test.ts

@@ -0,0 +1,82 @@
+import { describe, it, expect } from 'vitest';
+import { parseTemplate, renderTemplate } from './template-ast';
+
+const noopInterp = (t: string): string => t;
+
+describe('parseTemplate', () => {
+  it('parses plain text as a single text node', () => {
+    const ast = parseTemplate('hello world');
+    expect(ast).toEqual([{ kind: 'text', content: 'hello world' }]);
+  });
+
+  it('parses a simple #if/#end', () => {
+    const ast = parseTemplate('before\n#if cond\ninner\n#end\nafter');
+    expect(ast.length).toBe(3);
+    expect(ast[0]).toEqual({ kind: 'text', content: 'before' });
+    expect(ast[1].kind).toBe('if');
+    if (ast[1].kind === 'if') {
+      expect(ast[1].cond).toBe('cond');
+      expect(ast[1].then).toEqual([{ kind: 'text', content: 'inner' }]);
+      expect(ast[1].else).toEqual([]);
+    }
+    expect(ast[2]).toEqual({ kind: 'text', content: 'after' });
+  });
+
+  it('parses #if/#else/#end', () => {
+    const ast = parseTemplate('#if cond\nT\n#else\nF\n#end');
+    expect(ast.length).toBe(1);
+    expect(ast[0].kind).toBe('if');
+    if (ast[0].kind === 'if') {
+      expect(ast[0].then).toEqual([{ kind: 'text', content: 'T' }]);
+      expect(ast[0].else).toEqual([{ kind: 'text', content: 'F' }]);
+    }
+  });
+
+  it('parses #for/#end', () => {
+    const ast = parseTemplate('#for item in items\nbody\n#end');
+    expect(ast.length).toBe(1);
+    expect(ast[0].kind).toBe('for');
+    if (ast[0].kind === 'for') {
+      expect(ast[0].varName).toBe('item');
+      expect(ast[0].iterableExpr).toBe('items');
+      expect(ast[0].body).toEqual([{ kind: 'text', content: 'body' }]);
+    }
+  });
+});
+
+describe('renderTemplate', () => {
+  it('renders text with interpolation passthrough', () => {
+    const ast = parseTemplate('hello world');
+    const out = renderTemplate(ast, {}, noopInterp, () => undefined);
+    expect(out).toBe('hello world');
+  });
+
+  it('renders the then-branch when condition is truthy', () => {
+    const ast = parseTemplate('#if cond\nyes\n#else\nno\n#end');
+    const out = renderTemplate(ast, {}, noopInterp, expr => expr === 'cond');
+    expect(out).toBe('yes');
+  });
+
+  it('renders the else-branch when condition is falsy', () => {
+    const ast = parseTemplate('#if cond\nyes\n#else\nno\n#end');
+    const out = renderTemplate(ast, {}, noopInterp, () => false);
+    expect(out).toBe('no');
+  });
+
+  it('renders #for body once per item', () => {
+    const ast = parseTemplate('#for item in items\n${item}\n#end');
+    const out = renderTemplate(
+      ast,
+      {},
+      (t, s) => t.replace('${item}', String(s.item ?? '')),
+      expr => (expr === 'items' ? ['a', 'b', 'c'] : undefined)
+    );
+    expect(out).toBe('a\nb\nc');
+  });
+
+  it('renders #for #else when iterable is empty', () => {
+    const ast = parseTemplate('#for item in items\n${item}\n#else\nempty\n#end');
+    const out = renderTemplate(ast, {}, noopInterp, expr => (expr === 'items' ? [] : undefined));
+    expect(out).toBe('empty');
+  });
+});

package/src/template-ast.ts

@@ -0,0 +1,147 @@
+/**
+ * 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[];
+    };
+
+const IF_RE = /^#if\s+(.+)$/;
+const ELSE_RE = /^#else\s*$/;
+const END_RE = /^#end\s*$/;
+const FOR_RE = /^#for\s+([A-Za-z_$][\w$]*)\s+in\s+(.+)$/;
+
+/**
+ * Parse a template body into a sequence of TemplateNodes.
+ * Directives are recognized only when they occupy their own line.
+ */
+export function parseTemplate(source: string): TemplateNode[] {
+  const lines = source.split('\n');
+  const cursor = { i: 0 };
+
+  function parseBlock(stop: (line: string) => boolean): TemplateNode[] {
+    const nodes: TemplateNode[] = [];
+    let textBuffer: string[] = [];
+
+    const flushText = (): void => {
+      if (textBuffer.length > 0) {
+        nodes.push({ kind: 'text', content: textBuffer.join('\n') });
+        textBuffer = [];
+      }
+    };
+
+    while (cursor.i < lines.length) {
+      const line = lines[cursor.i];
+      const trimmed = line.trim();
+
+      if (stop(trimmed)) {
+        flushText();
+        return nodes;
+      }
+
+      const ifMatch = IF_RE.exec(trimmed);
+      const forMatch = FOR_RE.exec(trimmed);
+
+      if (ifMatch) {
+        flushText();
+        const cond = ifMatch[1].trim();
+        cursor.i++;
+        const thenBlock = parseBlock(l => ELSE_RE.test(l) || END_RE.test(l));
+        let elseBlock: TemplateNode[] = [];
+        if (cursor.i < lines.length && ELSE_RE.test(lines[cursor.i].trim())) {
+          cursor.i++;
+          elseBlock = parseBlock(l => END_RE.test(l));
+        }
+        if (cursor.i < lines.length && END_RE.test(lines[cursor.i].trim())) cursor.i++;
+        nodes.push({ kind: 'if', cond, then: thenBlock, else: elseBlock });
+      } else if (forMatch) {
+        flushText();
+        const varName = forMatch[1];
+        const iterableExpr = forMatch[2].trim();
+        cursor.i++;
+        const bodyBlock = parseBlock(l => ELSE_RE.test(l) || END_RE.test(l));
+        let elseEmptyBlock: TemplateNode[] = [];
+        if (cursor.i < lines.length && ELSE_RE.test(lines[cursor.i].trim())) {
+          cursor.i++;
+          elseEmptyBlock = parseBlock(l => END_RE.test(l));
+        }
+        if (cursor.i < lines.length && END_RE.test(lines[cursor.i].trim())) cursor.i++;
+        nodes.push({
+          kind: 'for',
+          varName,
+          iterableExpr,
+          body: bodyBlock,
+          elseEmpty: elseEmptyBlock,
+        });
+      } else {
+        textBuffer.push(line);
+        cursor.i++;
+      }
+    }
+    flushText();
+    return nodes;
+  }
+
+  return parseBlock(() => false);
+}
+
+/**
+ * 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 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 {
+  return nodes
+    .map(node => {
+      if (node.kind === 'text') {
+        return interpText(node.content, scope);
+      }
+      if (node.kind === 'if') {
+        const value = evalExpr(node.cond, scope);
+        const branch = value ? node.then : node.else;
+        return renderTemplate(branch, scope, interpText, evalExpr);
+      }
+      // for
+      const iterable = evalExpr(node.iterableExpr, scope) as Iterable<unknown> | null | undefined;
+      const items =
+        iterable != null &&
+        typeof (iterable as { [Symbol.iterator]?: unknown })[Symbol.iterator] === 'function'
+          ? Array.from(iterable as Iterable<unknown>)
+          : [];
+      if (items.length === 0) {
+        return renderTemplate(node.elseEmpty, scope, interpText, evalExpr);
+      }
+      return items
+        .map(item =>
+          renderTemplate(node.body, { ...scope, [node.varName]: item }, interpText, evalExpr)
+        )
+        .join('\n');
+    })
+    .join('\n');
+}

package/src/types.ts

@@ -0,0 +1,29 @@
+/**
+ * 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;
+  };
+  // Optional — core's Runtime has this for re-processing a subtree.
+  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;
+}