solid-tag-runtime 0.0.8 → 0.0.11

package/html.d.ts

@@ -1,17 +1,31 @@
 import { SolidTagRuntimeError } from "./index.js";
 import type { ModuleFormat, ModuleNamespaceLike, SolidTagRuntime } from "./index.js";
 
-export interface HTMLModuleScriptElement {
+export interface HTMLAttributeElementLike {
   textContent?: string | null;
   baseURI?: string;
   ownerDocument?: HTMLDocumentLike | null;
-  parentNode?: { removeChild?(element: any): unknown } | null;
+  parentNode?: {
+    removeChild?(element: any): unknown;
+    insertBefore?(element: any, reference: any): unknown;
+  } | null;
   remove?(): void;
+  replaceWith?(...nodes: any[]): void;
   getAttribute(name: string): string | null;
   hasAttribute?(name: string): boolean;
   setAttribute?(name: string, value: string): void;
 }
 
+export interface HTMLModuleScriptElement extends HTMLAttributeElementLike {}
+
+export interface SolidRenderElement extends HTMLAttributeElementLike, HTMLAppendTarget {
+  props: Record<string, unknown>;
+  childNodes?: ArrayLike<any> | Iterable<any>;
+  attributes?: ArrayLike<{ name: string; value: string }> | Iterable<{ name: string; value: string }>;
+  replaceChildren?(...nodes: any[]): void;
+  dispatchEvent?(event: unknown): boolean;
+}
+
 export interface HTMLAppendTarget {
   append?(...nodes: any[]): void;
   appendChild?(element: any): unknown;
@@ -21,6 +35,8 @@ export interface HTMLDocumentLike extends HTMLModuleRoot, HTMLAppendTarget {
   body?: HTMLAppendTarget;
   documentElement?: HTMLAppendTarget;
   createElement?(tagName: string): any;
+  createComment?(data: string): any;
+  createDocumentFragment?(): any;
 }
 
 export interface HTMLModuleRoot {
@@ -28,7 +44,9 @@ export interface HTMLModuleRoot {
   ownerDocument?: HTMLDocumentLike | null;
   body?: HTMLAppendTarget;
   documentElement?: HTMLAppendTarget;
-  querySelectorAll(selector: string): Iterable<HTMLModuleScriptElement> | ArrayLike<HTMLModuleScriptElement>;
+  querySelectorAll(selector: string): Iterable<any> | ArrayLike<any>;
+  querySelector?(selector: string): any;
+  contains?(node: any): boolean;
 }
 
 export interface HTMLFetchResponse {
@@ -44,8 +62,9 @@ export interface HTMLMutationObserverLike {
   observe(
     target: unknown,
     options: {
-      childList: boolean;
-      subtree: boolean;
+      childList?: boolean;
+      subtree?: boolean;
+      attributes?: boolean;
     },
   ): void;
   disconnect(): void;
@@ -53,12 +72,44 @@ export interface HTMLMutationObserverLike {
 
 export interface HTMLMutationObserverConstructor {
   new (
-    callback: (...args: unknown[]) => void,
+    callback: (...args: any[]) => void,
   ): HTMLMutationObserverLike;
 }
 
+export interface HTMLMountRecord {
+  kind?: "container" | "range" | string;
+  target?: unknown;
+  updateProps?(props: Record<string, unknown>): void;
+  dispose?(): void | Promise<void>;
+}
+
+export interface HTMLRenderAdapter {
+  mountContainer(options: {
+    runtime: SolidTagRuntime;
+    target: any;
+    Component: Function;
+    props: Record<string, unknown>;
+    element?: HTMLAttributeElementLike | SolidRenderElement;
+    moduleId?: string;
+  }): HTMLMountRecord | Promise<HTMLMountRecord>;
+
+  mountRange(options: {
+    runtime: SolidTagRuntime;
+    parent: any;
+    before: any;
+    startMarker: any;
+    endMarker: any;
+    Component: Function;
+    props: Record<string, unknown>;
+    element?: HTMLModuleScriptElement;
+    moduleId?: string;
+  }): HTMLMountRecord | Promise<HTMLMountRecord>;
+}
+
 export interface DefineScriptOptions {
   root?: HTMLModuleRoot;
+  /** Optional selector-resolution root for declarative render="...". */
+  renderRoot?: HTMLModuleRoot;
   baseUrl?: string;
   format?: ModuleFormat | "javascript";
   fetch?: HTMLFetch;
@@ -72,15 +123,28 @@ export interface HTMLModuleDefinition {
   id: string;
   format: ModuleFormat;
   entry: boolean;
+  /** undefined = no render, true = in-place, string = selector target. */
+  render?: true | string;
+  /** Named component export. Missing means default export. */
+  component?: string;
   sourceUrl?: string;
   inline: boolean;
   element: HTMLModuleScriptElement;
 }
 
+export interface HTMLRenderedModule {
+  id: string;
+  namespace: ModuleNamespaceLike;
+  component: string;
+  mode: "selector" | "in-place";
+  target?: unknown;
+  element: HTMLModuleScriptElement;
+}
+
 export interface RemoveHTMLElementOptions {
   /** Remove the runtime module as well as releasing HTML ownership. Default: true. */
   removeModule?: boolean;
-  /** Remove the script element from the DOM. Default: true. */
+  /** Remove the script declaration/range from the DOM. Default: true. */
   removeFromDOM?: boolean;
   /** Invalidate runtime dependents when removing the module. Default: true. */
   invalidateDependents?: boolean;
@@ -96,6 +160,8 @@ export interface RemoveHTMLElementResult {
 export interface RegisterHTMLOptions extends DefineScriptOptions {
   selector?: string;
   executeEntries?: boolean;
+  /** Execute declarative render actions. Default: true. */
+  executeRenders?: boolean;
 }
 
 export interface RegisterHTMLResult {
@@ -105,6 +171,8 @@ export interface RegisterHTMLResult {
     id: string;
     namespace: ModuleNamespaceLike;
   }>;
+  renders: string[];
+  rendered: HTMLRenderedModule[];
 }
 
 export type HTMLRegistrationOrigin =
@@ -119,11 +187,15 @@ export type HTMLRegistrationOrigin =
   | "add-module"
   | "update-element"
   | "remove-element"
+  | "solid-render"
   | string;
 
+export type HTMLRenderSource = "script-render" | "solid-render";
+export type HTMLRenderMode = "selector" | "in-place" | "container";
+
 export type HTMLRuntimeEvent =
   | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "element-discovered"; element: HTMLModuleScriptElement; moduleId?: string; origin: HTMLRegistrationOrigin; accepted: boolean }
-  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "element-claimed"; element: HTMLModuleScriptElement; moduleId: string; format: ModuleFormat; entry: boolean; sourceUrl?: string; origin: HTMLRegistrationOrigin }
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "element-claimed"; element: HTMLModuleScriptElement; moduleId: string; format: ModuleFormat; entry: boolean; render?: true | string; component?: string; sourceUrl?: string; origin: HTMLRegistrationOrigin }
   | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "element-loading"; element: HTMLModuleScriptElement; moduleId: string; sourceUrl: string; origin: HTMLRegistrationOrigin }
   | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "element-loaded"; element: HTMLModuleScriptElement; moduleId: string; sourceUrl: string; origin: HTMLRegistrationOrigin; bytes: number; durationMs: number }
   | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "element-registered"; element: HTMLModuleScriptElement; moduleId: string; definition: HTMLModuleDefinition; origin: HTMLRegistrationOrigin }
@@ -140,7 +212,12 @@ export type HTMLRuntimeEvent =
   | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "append-target-changed"; previousTarget?: HTMLAppendTarget; target: HTMLAppendTarget }
   | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "entry-executing"; element: HTMLModuleScriptElement; moduleId: string; origin: HTMLRegistrationOrigin }
   | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "entry-executed"; element: HTMLModuleScriptElement; moduleId: string; namespace: ModuleNamespaceLike; origin: HTMLRegistrationOrigin }
-  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "html-error"; operation: "discover" | "claim" | "fetch" | "register" | "update" | "remove" | "entry" | "root-change" | "observer" | string; error: unknown; element?: HTMLModuleScriptElement; moduleId?: string; origin?: HTMLRegistrationOrigin };
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "render-mounting"; element: HTMLModuleScriptElement | SolidRenderElement; moduleId?: string; component: string; mode: HTMLRenderMode; origin: HTMLRegistrationOrigin; source: HTMLRenderSource }
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "render-mounted"; element: HTMLModuleScriptElement | SolidRenderElement; moduleId?: string; component: string; mode: HTMLRenderMode; target?: unknown; origin: HTMLRegistrationOrigin; source: HTMLRenderSource }
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "render-disposing"; element: HTMLModuleScriptElement | SolidRenderElement; moduleId?: string; component: string; mode: HTMLRenderMode; reason: string; origin: HTMLRegistrationOrigin; source: HTMLRenderSource }
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "render-disposed"; element: HTMLModuleScriptElement | SolidRenderElement; moduleId?: string; component: string; mode: HTMLRenderMode; reason: string; origin: HTMLRegistrationOrigin; source: HTMLRenderSource }
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "html-warning"; code: "unresolved-runtime-scope"; operation: "render"; message: string; element: HTMLModuleScriptElement; moduleId?: string; requestedScope: string; registeredScopes: string[]; matchingScopeRegistered: boolean; origin: HTMLRegistrationOrigin }
+  | { htmlRuntimeId: string; scope?: string; timestamp: number; type: "html-error"; operation: "discover" | "claim" | "fetch" | "register" | "update" | "remove" | "entry" | "render" | "solid-render" | "root-change" | "observer" | string; error: unknown; element?: HTMLModuleScriptElement | SolidRenderElement; moduleId?: string; origin?: HTMLRegistrationOrigin };
 
 export type HTMLRuntimeEventType = HTMLRuntimeEvent["type"];
 export type HTMLRuntimeEventOfType<T extends HTMLRuntimeEventType> =
@@ -163,9 +240,12 @@ export interface AddHTMLModuleOptions extends DefineScriptOptions {
   source?: string;
   src?: string;
   entry?: boolean;
+  render?: true | string;
+  component?: string;
   type?: string;
   language?: string;
   executeEntries?: boolean;
+  executeRenders?: boolean;
   appendTo?: HTMLAppendTarget;
   document?: HTMLDocumentLike;
   createElement?: (tagName: string) => HTMLModuleScriptElement;
@@ -174,6 +254,8 @@ export interface AddHTMLModuleOptions extends DefineScriptOptions {
 export interface HTMLRuntimeOptions extends ObserveHTMLOptions {
   appendTo?: HTMLAppendTarget;
   createElement?: (tagName: string) => HTMLModuleScriptElement;
+  /** Override Solid mounting for tests/special hosts. */
+  renderAdapter?: HTMLRenderAdapter;
 }
 
 export interface SetHTMLRootOptions extends RegisterHTMLOptions {
@@ -190,11 +272,8 @@ export interface HTMLRuntimeController {
   readonly runtime: SolidTagRuntime;
   readonly scope?: string;
   readonly connected: boolean;
-  /** Current configured/effective discovery root when available. */
   readonly root?: HTMLModuleRoot;
-  /** Current effective target used by append()/addModule() when available. */
   readonly appendTarget?: HTMLAppendTarget;
-  /** Result of the observer's initial scan. */
   readonly initial: RegisterHTMLResult;
 
   subscribe(listener: (event: HTMLRuntimeEvent) => void): () => boolean;
@@ -207,65 +286,22 @@ export interface HTMLRuntimeController {
     listener: (event: HTMLRuntimeEventOfType<T[number]>) => void,
   ): () => boolean;
 
-  /** One-shot scan of matching scripts under the configured/root override. */
   register(options?: RegisterHTMLOptions): Promise<RegisterHTMLResult>;
-
-  /** Start live addition observation. Returns this controller. */
   observe(options?: ObserveHTMLOptions): Promise<HTMLRuntimeController>;
-
-  /** Wait for queued observer work and scan for newly discoverable scripts. */
   flush(options?: RegisterHTMLOptions): Promise<RegisterHTMLResult>;
   disconnect(): void;
+  /** Dispose HTML-owned mounts/registry state without disposing the core runtime. */
+  dispose(): Promise<void>;
 
-  /**
-   * Change the discovery/observation root. A connected observer is rebound to
-   * the new node automatically.
-   */
-  setRoot(
-    root: HTMLModuleRoot,
-    options?: SetHTMLRootOptions,
-  ): Promise<RegisterHTMLResult>;
-
-  /** Change both the discovery root and append target to the selected root. */
-  moveTo(
-    root: HTMLModuleRoot,
-    options?: SetHTMLRootOptions,
-  ): Promise<RegisterHTMLResult>;
-
-  /** Change only where append()/addModule() insert future elements. */
+  setRoot(root: HTMLModuleRoot, options?: SetHTMLRootOptions): Promise<RegisterHTMLResult>;
+  moveTo(root: HTMLModuleRoot, options?: SetHTMLRootOptions): Promise<RegisterHTMLResult>;
   setAppendTarget(target: HTMLAppendTarget): HTMLRuntimeController;
 
-  /** Define one element without auto-running an entry. */
-  defineElement(
-    element: HTMLModuleScriptElement,
-    options?: DefineScriptOptions,
-  ): Promise<HTMLModuleDefinition>;
-
-  /** Explicitly claim/register an existing element for this runtime. */
-  registerElement(
-    element: HTMLModuleScriptElement,
-    options?: RegisterHTMLOptions,
-  ): Promise<HTMLModuleDefinition>;
-
-  /** Re-read and replace source for an element already owned by this controller. */
-  updateElement(
-    element: HTMLModuleScriptElement,
-    options?: RegisterHTMLOptions,
-  ): Promise<HTMLModuleDefinition>;
-
-  /** Release an owned element and optionally remove its module and DOM node. */
-  removeElement(
-    element: HTMLModuleScriptElement,
-    options?: RemoveHTMLElementOptions,
-  ): Promise<RemoveHTMLElementResult>;
-
-  /** Claim first, append a user-created element, then register it directly. */
-  append(
-    element: HTMLModuleScriptElement,
-    options?: RegisterHTMLOptions & { appendTo?: HTMLAppendTarget },
-  ): Promise<HTMLModuleDefinition>;
-
-  /** Create a runtime script element and add it through the controller. */
+  defineElement(element: HTMLModuleScriptElement, options?: DefineScriptOptions): Promise<HTMLModuleDefinition>;
+  registerElement(element: HTMLModuleScriptElement, options?: RegisterHTMLOptions): Promise<HTMLModuleDefinition>;
+  updateElement(element: HTMLModuleScriptElement, options?: RegisterHTMLOptions): Promise<HTMLModuleDefinition>;
+  removeElement(element: HTMLModuleScriptElement, options?: RemoveHTMLElementOptions): Promise<RemoveHTMLElementResult>;
+  append(element: HTMLModuleScriptElement, options?: RegisterHTMLOptions & { appendTo?: HTMLAppendTarget }): Promise<HTMLModuleDefinition>;
   addModule(options: AddHTMLModuleOptions): Promise<HTMLModuleDefinition>;
 
   owns(element: HTMLModuleScriptElement): boolean;
@@ -273,7 +309,16 @@ export interface HTMLRuntimeController {
   getElement(id: string): HTMLModuleScriptElement | undefined;
 }
 
-/** Legacy observer shape is now the full HTML runtime controller. */
+export interface CustomElementRegistryLike {
+  define(name: string, constructor: any): void;
+  get(name: string): any;
+}
+
+export interface RegisterSolidRenderElementOptions {
+  customElements?: CustomElementRegistryLike;
+  HTMLElement?: new (...args: any[]) => any;
+}
+
 export type HTMLObserverController = HTMLRuntimeController;
 
 export declare class HTMLModuleError extends SolidTagRuntimeError {
@@ -287,6 +332,12 @@ export declare class HTMLModuleOwnershipError extends HTMLModuleError {
   requestedScope?: string;
 }
 
+export declare class HTMLRenderError extends SolidTagRuntimeError {
+  element?: HTMLModuleScriptElement | SolidRenderElement;
+  moduleId?: string;
+  component?: string;
+}
+
 export declare const htmlModuleSelector: string;
 export declare const htmlRuntimeScopeAttribute: "data-solid-runtime";
 
@@ -295,6 +346,10 @@ export declare function createHTMLRuntime(
   options?: HTMLRuntimeOptions,
 ): HTMLRuntimeController;
 
+export declare function registerSolidRenderElement(
+  options?: RegisterSolidRenderElementOptions,
+): any | undefined;
+
 export declare function defineScript(
   runtime: SolidTagRuntime,
   element: HTMLModuleScriptElement,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid-tag-runtime",
-  "version": "0.0.8",
+  "version": "0.0.11",
   "description": "Runtime module system for JSX modules compiled with solid-tag and executed through @solidjs/html",
   "type": "module",
   "exports": {