@ohos-ports/stacksjs-stx 0.2.287-beta.0

package/dist/component-registry.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Component Registry
+ *
+ * Handles resolution of both builtin and file-based STX components.
+ * Builtin components (e.g., StxLink, StxImage) are registered in-memory
+ * and render directly to HTML without requiring a .stx file on disk.
+ * File-based components are resolved through a multi-strategy search
+ * that mirrors the existing resolution logic in utils.ts.
+ *
+ * @module component-registry
+ */
+import type { StxOptions } from './types';
+/**
+ * Context passed to builtin component render functions.
+ */
+export interface RenderContext {
+    /** Template variable context */
+    context: Record<string, any>;
+    /** Path of the template invoking this component */
+    filePath: string;
+    /** Compiler options */
+    options: StxOptions;
+    /** Dependency set for cache invalidation tracking */
+    dependencies: Set<string>;
+}
+/**
+ * Props resolved from component attributes, categorized by binding type.
+ */
+export interface ResolvedProps {
+    /** Static attribute values — e.g. title="Hello", disabled */
+    static: Record<string, string | boolean>;
+    /**
+     * Original attribute spelling for any `static` key that was camelized,
+     * keyed by the camelized name — e.g. `{ activeClass: 'active-class' }`.
+     *
+     * A static attribute is two things at once, and they disagree about naming.
+     * To a `.stx` component it is a prop, and `active-class` has to arrive as
+     * `$props.activeClass` because a kebab key cannot be destructured. To a
+     * builtin that forwards unconsumed attributes onto real markup it is an HTML
+     * attribute, and must go out spelled the way the author wrote it. Keeping the
+     * original here lets both be true; without it, forwarding emitted
+     * `activeClass="…"` and the browser saw an unknown attribute.
+     *
+     * Only present for names that actually changed, so `key in staticNames` is a
+     * meaningful test.
+     */
+    staticNames: Record<string, string>;
+    /** Server-side dynamic bindings — e.g. :count="items.length" (evaluated at compile time) */
+    serverDynamic: Record<string, unknown>;
+    /**
+     * Original attribute spelling for any `serverDynamic` key that was camelized.
+     *
+     * Same reason as {@link ResolvedProps.staticNames}: a builtin forwarding an
+     * unconsumed binding onto real markup must spell it the way the author wrote
+     * it, or `:some-attr="x"` goes out as `someAttr` and the browser sees an
+     * attribute it does not know.
+     */
+    serverDynamicNames?: Record<string, string>;
+    /** Client-side reactive bindings — expression string preserved for signals */
+    clientReactive: Record<string, string>;
+    /** Event handler bindings — e.g. @click="handler()" */
+    events: Record<string, string>;
+}
+/**
+ * Definition for a builtin component that renders without a .stx file.
+ */
+export interface BuiltinComponentDef {
+    /** Canonical component name (e.g. "StxLink") */
+    name: string;
+    /** Alternative names that resolve to this component (e.g. ["stx-link"]) */
+    aliases: string[];
+    /** Render the component to an HTML string */
+    render(props: ResolvedProps, slotContent: string, ctx: RenderContext): string;
+}
+/**
+ * Convert a kebab-case string to PascalCase.
+ *
+ * @example kebabToPascal("stx-link") // "StxLink"
+ */
+export declare function kebabToPascal(str: string): string;
+/**
+ * Convert a PascalCase string to kebab-case.
+ *
+ * @example pascalToKebab("StxLink") // "stx-link"
+ */
+export declare function pascalToKebab(str: string): string;
+/**
+ * Central registry for STX components.
+ *
+ * Manages builtin components (registered in-memory) and provides
+ * file-based component resolution with multi-directory search.
+ */
+export declare class ComponentRegistry {
+    /** Map of lowercase name/alias → builtin definition */
+    builtins: Map<string, BuiltinComponentDef>;
+    /**
+     * Register a builtin component under its canonical name and all aliases.
+     */
+    registerBuiltin(def: BuiltinComponentDef): void;
+    /**
+     * Check whether a component name matches a registered builtin (case-insensitive).
+     */
+    isBuiltin(name: string): boolean;
+    /**
+     * Retrieve a builtin component definition by name (case-insensitive).
+     * Returns null if no matching builtin is found.
+     */
+    getBuiltin(name: string): BuiltinComponentDef | null;
+    /**
+     * Resolve a file-based component to an absolute file path.
+     *
+     * Resolution order:
+     * 1. Check `context.__importedComponents` Map (explicit @import directives)
+     * 2. Generate name variants: [baseName.stx, PascalCase.stx, kebab-case.stx]
+     * 3. Search directories in priority order:
+     *    - Page-relative components/
+     *    - Global componentsDir
+     *    - Parent-relative components/
+     *    - Project root src/components and components/
+     *    - Built-in STX components directory
+     * 4. Search subdirectories one level deep within each directory
+     * 5. Return null if not found
+     */
+    resolveFile(name: string, fromFile: string, options: StxOptions, parentContext?: Record<string, any>): Promise<string | null>;
+}
+/** Singleton registry instance shared across the framework */
+export declare const registry: ComponentRegistry;

package/dist/component-registry.js

@@ -0,0 +1,90 @@
+import path from "node:path";
+import fs from "node:fs";
+import { fileExists } from "./utils.js";
+export function kebabToPascal(str) {
+  return str.split("-").map((part) => part.charAt(0).toUpperCase() + part.slice(1)).join("");
+}
+export function pascalToKebab(str) {
+  return str.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+
+export class ComponentRegistry {
+  builtins = new Map;
+  registerBuiltin(def) {
+    this.builtins.set(def.name.toLowerCase(), def);
+    for (const alias of def.aliases)
+      this.builtins.set(alias.toLowerCase(), def);
+  }
+  isBuiltin(name) {
+    return this.builtins.has(name.toLowerCase());
+  }
+  getBuiltin(name) {
+    return this.builtins.get(name.toLowerCase()) ?? null;
+  }
+  async resolveFile(name, fromFile, options, parentContext) {
+    const baseName = name.endsWith(".stx") ? name.slice(0, -4) : name, importedComponents = parentContext?.__importedComponents;
+    if (importedComponents) {
+      const namesToTry = [
+        baseName,
+        baseName.toLowerCase(),
+        kebabToPascal(baseName),
+        pascalToKebab(baseName)
+      ];
+      for (const n of namesToTry)
+        if (importedComponents.has(n))
+          return importedComponents.get(n);
+    }
+    const fileVariants = [...new Set([
+      `${baseName}.stx`,
+      `${kebabToPascal(baseName)}.stx`,
+      `${pascalToKebab(baseName)}.stx`
+    ])];
+    if (baseName.startsWith("./") || baseName.startsWith("../")) {
+      const resolved = path.resolve(path.dirname(fromFile), `${baseName}.stx`);
+      if (await fileExists(resolved))
+        return resolved;
+      return null;
+    }
+    const searchDirs = [], componentsDir = options.componentsDir || "", originalFilePath = parentContext?.__originalFilePath;
+    if (originalFilePath)
+      searchDirs.push(path.join(path.dirname(originalFilePath), "components"));
+    if (componentsDir)
+      searchDirs.push(componentsDir);
+    const parentRelative = path.join(path.dirname(fromFile), "components");
+    if (!searchDirs.includes(parentRelative))
+      searchDirs.push(parentRelative);
+    const projectRoot = process.cwd(), fallbackDirs = [
+      path.resolve(projectRoot, "src/components"),
+      path.resolve(projectRoot, "components"),
+      path.resolve(import.meta.dir, "components")
+    ];
+    for (const fallback of fallbackDirs)
+      if (!searchDirs.includes(fallback))
+        searchDirs.push(fallback);
+    for (const dir of searchDirs) {
+      if (!dir)
+        continue;
+      for (const variant of fileVariants) {
+        const tryPath = path.join(dir, variant);
+        if (await fileExists(tryPath))
+          return tryPath;
+      }
+      try {
+        if (!fs.statSync(dir, { throwIfNoEntry: !1 })?.isDirectory())
+          continue;
+        const entries = fs.readdirSync(dir, { withFileTypes: !0 });
+        for (const entry of entries)
+          if (entry.isDirectory()) {
+            const subDir = path.join(dir, entry.name);
+            for (const variant of fileVariants) {
+              const tryPath = path.join(subDir, variant);
+              if (await fileExists(tryPath))
+                return tryPath;
+            }
+          }
+      } catch {}
+    }
+    return null;
+  }
+}
+export const registry = new ComponentRegistry;

package/dist/component-renderer.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Unified Component Renderer
+ *
+ * Replaces all existing component processing with a single `processComponents()`
+ * entry point. Handles:
+ *
+ * 1. Built-in components (StxLink, StxImage, StxLoadingIndicator) — resolved
+ *    via the component registry and rendered directly to HTML.
+ * 2. File-based user components — resolved from the filesystem and rendered
+ *    via `renderComponentWithSlot()`.
+ * 3. `@component` directives — `@component('name', { props })...@endcomponent`.
+ * 4. `@import` directives — `@import('ComponentName', './path/to/component')`.
+ *
+ * Props are categorized into static, serverDynamic, clientReactive, and events
+ * through `parseComponentProps()` before being passed to the appropriate renderer.
+ *
+ * @module component-renderer
+ */
+import type { StxOptions } from './types';
+import { freeIdentifiers } from './safe-evaluator';
+/**
+ * Process ES `import { A, B } from '<spec>'` statements inside `<script>` tags
+ * for component tag registration. Registers each named import as a tag pointing
+ * at the matching `.stx` file (resolved by component name within the package or
+ * relative directory) and strips the import line from the script body so it
+ * doesn't run as JS at template runtime.
+ *
+ * - `<spec>` may be a bare module specifier (resolved via node_modules walk) or
+ *   a relative path to a directory or a single `.stx` file.
+ * - Default imports (`import Foo from '...'`) are also supported when `<spec>`
+ *   resolves to a single `.stx` file.
+ * - Named imports referencing non-`.stx` exports are left untouched in the script.
+ */
+export { freeIdentifiers };
+export declare function processESImports(template: string, context: Record<string, any>, filePath: string, options: StxOptions, dependencies: Set<string>): Promise<string>;
+/**
+ * Unified component processing entry point.
+ *
+ * Processes all component-related syntax in the template in the correct order:
+ * 1. Register builtin components (once)
+ * 2. Process `@import` directives
+ * 3. Process `@component` directives
+ * 4. Process custom element tags (builtins and file-based)
+ *
+ * @param template - The template string to process
+ * @param context - Template variable context
+ * @param filePath - Absolute path of the template being processed
+ * @param options - Compiler options
+ * @param dependencies - Set to track file dependencies for cache invalidation
+ * @returns The processed template with all components rendered
+ */
+export declare function processComponents(template: string, context: Record<string, any>, filePath: string, options: StxOptions, dependencies: Set<string>): Promise<string>;