solid-tag-runtime 0.0.1 → 0.0.3

package/html.d.ts

@@ -0,0 +1,201 @@
+import { SolidTagRuntimeError } from "./index.js";
+import type { ModuleFormat, ModuleNamespaceLike, SolidTagRuntime } from "./index.js";
+
+export interface HTMLModuleScriptElement {
+  textContent?: string | null;
+  baseURI?: string;
+  ownerDocument?: HTMLDocumentLike;
+  getAttribute(name: string): string | null;
+  hasAttribute?(name: string): boolean;
+  setAttribute?(name: string, value: string): void;
+}
+
+export interface HTMLAppendTarget {
+  append?(element: HTMLModuleScriptElement): void;
+  appendChild?(element: HTMLModuleScriptElement): unknown;
+}
+
+export interface HTMLDocumentLike extends HTMLModuleRoot, HTMLAppendTarget {
+  body?: HTMLAppendTarget;
+  documentElement?: HTMLAppendTarget;
+  createElement?(tagName: string): HTMLModuleScriptElement;
+}
+
+export interface HTMLModuleRoot {
+  baseURI?: string;
+  ownerDocument?: HTMLDocumentLike;
+  body?: HTMLAppendTarget;
+  documentElement?: HTMLAppendTarget;
+  querySelectorAll(selector: string): Iterable<HTMLModuleScriptElement> | ArrayLike<HTMLModuleScriptElement>;
+}
+
+export interface HTMLFetchResponse {
+  ok?: boolean;
+  status?: number;
+  statusText?: string;
+  text(): Promise<string>;
+}
+
+export type HTMLFetch = (url: string) => Promise<HTMLFetchResponse>;
+
+export interface HTMLMutationObserverLike {
+  observe(
+    target: unknown,
+    options: {
+      childList: boolean;
+      subtree: boolean;
+    },
+  ): void;
+  disconnect(): void;
+}
+
+export interface HTMLMutationObserverConstructor {
+  new (
+    callback: (...args: unknown[]) => void,
+  ): HTMLMutationObserverLike;
+}
+
+export interface DefineScriptOptions {
+  root?: HTMLModuleRoot;
+  baseUrl?: string;
+  format?: ModuleFormat | "javascript";
+  fetch?: HTMLFetch;
+  /** Declarative ownership scope stored in data-solid-runtime. */
+  scope?: string;
+  /** Whether an HTML runtime may claim scripts without data-solid-runtime. Default: true. */
+  acceptUnscoped?: boolean;
+}
+
+export interface HTMLModuleDefinition {
+  id: string;
+  format: ModuleFormat;
+  entry: boolean;
+  sourceUrl?: string;
+  inline: boolean;
+  element: HTMLModuleScriptElement;
+}
+
+export interface RegisterHTMLOptions extends DefineScriptOptions {
+  selector?: string;
+  executeEntries?: boolean;
+}
+
+export interface RegisterHTMLResult {
+  modules: HTMLModuleDefinition[];
+  entries: string[];
+  executed: Array<{
+    id: string;
+    namespace: ModuleNamespaceLike;
+  }>;
+}
+
+export interface ObserveHTMLOptions extends RegisterHTMLOptions {
+  /** Register scripts already present when observation starts. Default: true. */
+  registerExisting?: boolean;
+  /** Observe descendant additions as well as direct children. Default: true. */
+  subtree?: boolean;
+  /** Override the platform MutationObserver constructor, useful for DOM-like hosts/tests. */
+  MutationObserver?: HTMLMutationObserverConstructor;
+  /** Called for asynchronous observer registration/import failures. */
+  onError?: (error: unknown) => void;
+}
+
+export interface AddHTMLModuleOptions extends DefineScriptOptions {
+  id?: string;
+  module?: string;
+  source?: string;
+  src?: string;
+  entry?: boolean;
+  type?: string;
+  language?: string;
+  executeEntries?: boolean;
+  appendTo?: HTMLAppendTarget;
+  document?: HTMLDocumentLike;
+  createElement?: (tagName: string) => HTMLModuleScriptElement;
+}
+
+export interface HTMLRuntimeOptions extends ObserveHTMLOptions {
+  appendTo?: HTMLAppendTarget;
+  createElement?: (tagName: string) => HTMLModuleScriptElement;
+}
+
+export interface HTMLRuntimeController {
+  readonly runtime: SolidTagRuntime;
+  readonly scope?: string;
+  readonly connected: boolean;
+  /** Result of the observer's initial scan. */
+  readonly initial: RegisterHTMLResult;
+
+  /** 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;
+
+  /** 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>;
+
+  /** 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. */
+  addModule(options: AddHTMLModuleOptions): Promise<HTMLModuleDefinition>;
+
+  owns(element: HTMLModuleScriptElement): boolean;
+  getModuleId(element: HTMLModuleScriptElement): string | undefined;
+  getElement(id: string): HTMLModuleScriptElement | undefined;
+}
+
+/** Legacy observer shape is now the full HTML runtime controller. */
+export type HTMLObserverController = HTMLRuntimeController;
+
+export declare class HTMLModuleError extends SolidTagRuntimeError {
+  element?: HTMLModuleScriptElement;
+  moduleId?: string;
+  sourceUrl?: string;
+}
+
+export declare class HTMLModuleOwnershipError extends HTMLModuleError {
+  ownerScope?: string;
+  requestedScope?: string;
+}
+
+export declare const htmlModuleSelector: string;
+export declare const htmlRuntimeScopeAttribute: "data-solid-runtime";
+
+export declare function createHTMLRuntime(
+  runtime: SolidTagRuntime,
+  options?: HTMLRuntimeOptions,
+): HTMLRuntimeController;
+
+export declare function defineScript(
+  runtime: SolidTagRuntime,
+  element: HTMLModuleScriptElement,
+  options?: DefineScriptOptions,
+): Promise<HTMLModuleDefinition>;
+
+export declare function registerHTML(
+  runtime: SolidTagRuntime,
+  options?: RegisterHTMLOptions,
+): Promise<RegisterHTMLResult>;
+
+export declare function observeHTML(
+  runtime: SolidTagRuntime,
+  options?: ObserveHTMLOptions,
+): Promise<HTMLObserverController>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "solid-tag-runtime",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Runtime module system for JSX modules compiled with solid-tag and executed through @solidjs/html",
   "type": "module",
   "exports": {
@@ -18,6 +18,11 @@
       "types": "./index.d.ts",
       "import": "./src/runtime.js",
       "default": "./src/runtime.js"
+    },
+    "./html": {
+      "types": "./html.d.ts",
+      "import": "./src/html.js",
+      "default": "./src/html.js"
     }
   },
   "main": "./src/index.js",
@@ -26,6 +31,7 @@
   "files": [
     "src",
     "index.d.ts",
+    "html.d.ts",
     "README.md",
     "ARCHITECTURE.md"
   ],