native-sfc 0.0.1

package/dist/index.cdn.js

@@ -0,0 +1,272 @@
+// dependencies loaded from esm.sh
+
+// src/components.ts
+import * as stackTraceParser2 from "https://esm.sh/stacktrace-parser";
+
+// src/rewriter.ts
+import { parse } from "https://esm.sh/es-module-lexer/js";
+import * as stackTraceParser from "https://esm.sh/stacktrace-parser";
+function rewriteModule(code, sourceUrl) {
+  const [imports] = parse(code);
+  const rewritableImports = imports.filter((i) => {
+    const specifier = code.slice(i.s, i.e);
+    return !isBrowserUrl(specifier) && !specifier.startsWith("data:");
+  });
+  for (const importEntry of rewritableImports.reverse()) {
+    const specifier = code.slice(importEntry.s, importEntry.e);
+    let rewritten = specifier;
+    if (specifier.startsWith(".") || specifier.startsWith("/")) {
+      rewritten = new URL(specifier, sourceUrl).href;
+    } else {
+      rewritten = `https://esm.sh/${specifier}`;
+    }
+    code = code.slice(0, importEntry.s) + rewritten + code.slice(importEntry.e);
+  }
+  return `import.meta.url=${JSON.stringify(sourceUrl)};
+${code}`;
+}
+function isBrowserUrl(url) {
+  return url.startsWith("http://") || url.startsWith("https://") || url.startsWith("blob:http://") || url.startsWith("blob:https://") || url.startsWith("data:");
+}
+var blobMap = /* @__PURE__ */ new Map();
+async function esm(code, sourceUrl) {
+  code = rewriteModule(code, sourceUrl);
+  const blob = new Blob([code], { type: "text/javascript" });
+  const blobUrl = URL.createObjectURL(blob);
+  blobMap.set(blobUrl, sourceUrl);
+  try {
+    const module = await import(blobUrl);
+    return module;
+  } finally {
+    URL.revokeObjectURL(blobUrl);
+  }
+}
+function getImporterUrl() {
+  const stack = stackTraceParser.parse(new Error().stack);
+  for (const { file } of stack) {
+    if (file && file !== import.meta.url) {
+      if (file.startsWith("blob:")) {
+        if (blobMap.has(file)) {
+          return blobMap.get(file);
+        }
+        continue;
+      }
+      return file;
+    }
+  }
+  return null;
+}
+
+// src/error.ts
+var NativeSFCError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "NativeSFCError";
+  }
+};
+function warn(...args) {
+  console.warn("NativeSFC Warning:", ...args);
+}
+
+// src/network.ts
+var fetch = globalThis.fetch;
+function defineFetch(customFetch) {
+  fetch = customFetch;
+}
+async function requestText(url, userFriendlySource) {
+  return request(url, userFriendlySource).then((res) => res.text());
+}
+async function request(url, userFriendlySource) {
+  let response;
+  try {
+    response = await fetch(url);
+  } catch (error) {
+    throw new NativeSFCError(`Failed to fetch ${url} at ${userFriendlySource}`, {
+      cause: error
+    });
+  }
+  if (!response.ok) {
+    throw new NativeSFCError(`Failed to fetch ${url} at ${userFriendlySource}`, {
+      cause: new Error(`HTTP status ${response.status}`)
+    });
+  }
+  return response;
+}
+
+// src/events.ts
+var eventTarget = new EventTarget();
+function emit(eventName, detail) {
+  const event = new CustomEvent(eventName, { detail });
+  eventTarget.dispatchEvent(event);
+}
+function on(eventName, listener) {
+  eventTarget.addEventListener(eventName, listener);
+  return () => {
+    eventTarget.removeEventListener(eventName, listener);
+  };
+}
+
+// src/components.ts
+var loadedComponentsRecord = /* @__PURE__ */ new Map();
+async function loadComponent(name, url, afterConstructor) {
+  const importerUrl = getImporterUrl() || location.href;
+  url = new URL(url, importerUrl).href;
+  emit("component-loading", { name, url });
+  if (customElements.get(name)) {
+    if (!loadedComponentsRecord.has(name)) {
+      throw new NativeSFCError(`Component name ${JSON.stringify(name)} is already being used`);
+    }
+    const loadedComponentRecord = loadedComponentsRecord.get(name);
+    if (loadedComponentRecord.url === url) {
+      return loadedComponentRecord.cec;
+    }
+  }
+  const html = await requestText(
+    url,
+    `loadComponent(${JSON.stringify(name)}, ${JSON.stringify(url)})`
+  );
+  const doc = new DOMParser().parseFromString(html, "text/html");
+  filterGlobalStyle(doc);
+  rewriteStyleAndScript(doc, url);
+  const adoptedStyleSheets = await collectAdoptedStyleSheets(doc);
+  const result = await evaluateModules(doc, url);
+  for (const el of doc.querySelectorAll("script")) {
+    doc.body.prepend(el);
+  }
+  const component = result.default;
+  const defaultExportIsComponent = component?.prototype instanceof HTMLElement;
+  if (component && !defaultExportIsComponent) {
+    warn(
+      `The default export of component ${JSON.stringify(name)} loaded from ${url} is not a web component class`,
+      component
+    );
+  }
+  const define = (component2) => {
+    const cec = extendsElement(component2, doc.body.innerHTML, adoptedStyleSheets, afterConstructor);
+    customElements.define(name, cec);
+    emit("component-defined", { name, url });
+    loadedComponentsRecord.set(name, { cec, url });
+    return cec;
+  };
+  if (!component || !defaultExportIsComponent) {
+    return define(HTMLElement);
+  } else {
+    return define(component);
+  }
+}
+function extendsElement(BaseClass = HTMLElement, innerHTML, adoptedStyleSheets, afterConstructor) {
+  return class extends BaseClass {
+    constructor(...args) {
+      super(innerHTML, adoptedStyleSheets);
+      if (!this.shadowRoot) {
+        const shadowRoot = this.attachShadow({ mode: "open" });
+        shadowRoot.innerHTML = innerHTML;
+        if (adoptedStyleSheets && adoptedStyleSheets.length > 0) {
+          shadowRoot.adoptedStyleSheets = adoptedStyleSheets;
+        }
+      }
+      if (afterConstructor) {
+        afterConstructor.call(this);
+      }
+    }
+  };
+}
+function defineComponent(fc) {
+  const whoDefineMe = stackTraceParser2.parse(new Error().stack).at(-1).file;
+  if (blobMap.has(whoDefineMe)) {
+    return class extends HTMLElement {
+      connectedCallback() {
+        fc.call(this, this.shadowRoot || this.attachShadow({ mode: "open" }));
+      }
+    };
+  }
+  return fc.call(globalThis, document);
+}
+function filterGlobalStyle(doc) {
+  for (const styleElement of doc.querySelectorAll("style")) {
+    if (styleElement.hasAttribute("global")) {
+      document.head.append(styleElement);
+    }
+  }
+  for (const linkElement of doc.querySelectorAll('link[rel="stylesheet"]')) {
+    if (linkElement.hasAttribute("global")) {
+      document.head.append(linkElement);
+    }
+  }
+}
+function cssStyleSheetFromText(styleText, userFriendlySource) {
+  const sheet = new CSSStyleSheet();
+  try {
+    sheet.replaceSync(styleText);
+  } catch (error) {
+    warn(`Failed to create CSSStyleSheet at ${userFriendlySource}`, error);
+  }
+  return sheet;
+}
+async function collectAdoptedStyleSheets(doc) {
+  const adoptedStyleSheets = [];
+  for (const link of doc.querySelectorAll(`link[rel="stylesheet"]`)) {
+    const styleText = await requestText(link.href, link.outerHTML).catch(
+      (error) => {
+        warn(`Failed to load ${link.outerHTML}`, error);
+        return "";
+      }
+    );
+    if (!styleText) continue;
+    const sheet = cssStyleSheetFromText(styleText, link.outerHTML);
+    adoptedStyleSheets.push(sheet);
+    link.remove();
+  }
+  for (const style of doc.querySelectorAll("style")) {
+    const styleText = style.innerHTML;
+    if (!styleText) continue;
+    const sheet = cssStyleSheetFromText(styleText, style.outerHTML);
+    adoptedStyleSheets.push(sheet);
+    style.remove();
+  }
+  return adoptedStyleSheets;
+}
+function rewriteStyleAndScript(doc, url) {
+  for (const script of doc.querySelectorAll("script[src]")) {
+    const src = new URL(
+      script.getAttribute("src") || "",
+      // getAttribute to avoid getting absolute URL directly, do not use script.src
+      url
+    ).href;
+    script.src = src;
+  }
+  for (const link of doc.querySelectorAll("link[href]")) {
+    const href = new URL(
+      link.getAttribute("href") || "",
+      // getAttribute to avoid getting absolute URL directly, do not use link.href
+      url
+    ).href;
+    link.href = href;
+  }
+}
+async function evaluateModules(doc, url) {
+  const result = {};
+  for (const script of doc.querySelectorAll('script[type="module"]')) {
+    const src = script.src;
+    if (src) {
+      const res = await request(src, script.outerHTML);
+      const code = await res.text();
+      const module = await esm(code, res.url);
+      Object.assign(result, module);
+    } else {
+      const module = await esm(script.textContent, url);
+      Object.assign(result, module);
+    }
+    script.remove();
+  }
+  return result;
+}
+export {
+  NativeSFCError,
+  defineComponent,
+  defineFetch,
+  loadComponent,
+  on
+};
+//! we provide an extra argument to user's component constructor
+//! if the user's constructor does not create a shadow root, we will create one here

package/dist/index.d.ts

@@ -0,0 +1,71 @@
+// Generated by dts-bundle-generator v9.5.1
+
+/**
+ * @fileoverview Component loading and registration system for Native SFC (Single File Components).
+ *
+ * This module provides the core functionality to:
+ * - Load HTML-based web components from external files
+ * - Parse and process component templates, styles, and scripts
+ * - Register custom elements with the browser's CustomElementRegistry
+ * - Handle style encapsulation via Shadow DOM and adoptedStyleSheets
+ *
+ * The component loading process:
+ * 1. Fetch the component HTML file
+ * 2. Extract and process global styles (move to document head)
+ * 3. Rewrite relative URLs in scripts and stylesheets to absolute URLs
+ * 4. Convert styles to CSSStyleSheet objects for adoptedStyleSheets (prevents FOUC)
+ * 5. Evaluate ES modules and extract the default export (component class)
+ * 6. Create an extended component class that injects shadow root with template
+ * 7. Register the component with customElements.define()
+ */
+/**
+ * Load and register a web component from an HTML file.
+ *
+ * This is the primary entry point for loading Native SFC components.
+ * The HTML file can contain:
+ * - Template markup (the component's shadow DOM content)
+ * - `<style>` tags (scoped to the component's shadow DOM)
+ * - `<style global>` tags (injected into the main document)
+ * - `<script type="module">` (ES modules, default export should be the component class)
+ * - `<script>` (classic scripts, executed when component is instantiated)
+ * - `<link rel="stylesheet">` (external stylesheets, also supports `global` attribute)
+ *
+ * @param name - The custom element tag name (must contain a hyphen, e.g., "my-component")
+ * @param url - URL to the component HTML file (relative to the importer or absolute)
+ * @param afterConstructor - Optional callback invoked after component constructor completes
+ * @returns The CustomElementConstructor for the registered component
+ * @throws {NativeSFCError} If the component name is already registered by external code
+ *
+ * @example
+ * // Load and use a component
+ * await loadComponent('my-button', './components/my-button.html');
+ * document.body.innerHTML = '<my-button>Click me</my-button>';
+ */
+export declare function loadComponent(name: string, url: string, afterConstructor?: VoidFunction): Promise<CustomElementConstructor>;
+/**
+ * a dual component definition helper function
+ * - when used inside loadComponent-imported module, it defines a web component class
+ * - when used in normal document context, it just runs the function with document as root
+ */
+export declare function defineComponent(fc: (root: Document | ShadowRoot) => void): any;
+export declare class NativeSFCError extends Error {
+	constructor(message: string, options?: ErrorOptions);
+}
+declare let fetch$1: typeof globalThis.fetch;
+export declare function defineFetch(customFetch: typeof fetch$1): void;
+export interface NativeSFCEvents {
+	"component-loading": {
+		name: string;
+		url: string;
+	};
+	"component-defined": {
+		name: string;
+		url: string;
+	};
+}
+export type NativeSFCEventsMap = {
+	[K in keyof NativeSFCEvents]: CustomEvent<NativeSFCEvents[K]>;
+};
+export declare function on<K extends keyof NativeSFCEvents>(eventName: K, listener: (ev: NativeSFCEventsMap[K]) => any): () => void;
+
+export {};

package/dist/index.js

@@ -0,0 +1,272 @@
+// entrypoint for bundler
+
+// src/components.ts
+import * as stackTraceParser2 from "stacktrace-parser";
+
+// src/rewriter.ts
+import { parse } from "es-module-lexer/js";
+import * as stackTraceParser from "stacktrace-parser";
+function rewriteModule(code, sourceUrl) {
+  const [imports] = parse(code);
+  const rewritableImports = imports.filter((i) => {
+    const specifier = code.slice(i.s, i.e);
+    return !isBrowserUrl(specifier) && !specifier.startsWith("data:");
+  });
+  for (const importEntry of rewritableImports.reverse()) {
+    const specifier = code.slice(importEntry.s, importEntry.e);
+    let rewritten = specifier;
+    if (specifier.startsWith(".") || specifier.startsWith("/")) {
+      rewritten = new URL(specifier, sourceUrl).href;
+    } else {
+      rewritten = `https://esm.sh/${specifier}`;
+    }
+    code = code.slice(0, importEntry.s) + rewritten + code.slice(importEntry.e);
+  }
+  return `import.meta.url=${JSON.stringify(sourceUrl)};
+${code}`;
+}
+function isBrowserUrl(url) {
+  return url.startsWith("http://") || url.startsWith("https://") || url.startsWith("blob:http://") || url.startsWith("blob:https://") || url.startsWith("data:");
+}
+var blobMap = /* @__PURE__ */ new Map();
+async function esm(code, sourceUrl) {
+  code = rewriteModule(code, sourceUrl);
+  const blob = new Blob([code], { type: "text/javascript" });
+  const blobUrl = URL.createObjectURL(blob);
+  blobMap.set(blobUrl, sourceUrl);
+  try {
+    const module = await import(blobUrl);
+    return module;
+  } finally {
+    URL.revokeObjectURL(blobUrl);
+  }
+}
+function getImporterUrl() {
+  const stack = stackTraceParser.parse(new Error().stack);
+  for (const { file } of stack) {
+    if (file && file !== import.meta.url) {
+      if (file.startsWith("blob:")) {
+        if (blobMap.has(file)) {
+          return blobMap.get(file);
+        }
+        continue;
+      }
+      return file;
+    }
+  }
+  return null;
+}
+
+// src/error.ts
+var NativeSFCError = class extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "NativeSFCError";
+  }
+};
+function warn(...args) {
+  console.warn("NativeSFC Warning:", ...args);
+}
+
+// src/network.ts
+var fetch = globalThis.fetch;
+function defineFetch(customFetch) {
+  fetch = customFetch;
+}
+async function requestText(url, userFriendlySource) {
+  return request(url, userFriendlySource).then((res) => res.text());
+}
+async function request(url, userFriendlySource) {
+  let response;
+  try {
+    response = await fetch(url);
+  } catch (error) {
+    throw new NativeSFCError(`Failed to fetch ${url} at ${userFriendlySource}`, {
+      cause: error
+    });
+  }
+  if (!response.ok) {
+    throw new NativeSFCError(`Failed to fetch ${url} at ${userFriendlySource}`, {
+      cause: new Error(`HTTP status ${response.status}`)
+    });
+  }
+  return response;
+}
+
+// src/events.ts
+var eventTarget = new EventTarget();
+function emit(eventName, detail) {
+  const event = new CustomEvent(eventName, { detail });
+  eventTarget.dispatchEvent(event);
+}
+function on(eventName, listener) {
+  eventTarget.addEventListener(eventName, listener);
+  return () => {
+    eventTarget.removeEventListener(eventName, listener);
+  };
+}
+
+// src/components.ts
+var loadedComponentsRecord = /* @__PURE__ */ new Map();
+async function loadComponent(name, url, afterConstructor) {
+  const importerUrl = getImporterUrl() || location.href;
+  url = new URL(url, importerUrl).href;
+  emit("component-loading", { name, url });
+  if (customElements.get(name)) {
+    if (!loadedComponentsRecord.has(name)) {
+      throw new NativeSFCError(`Component name ${JSON.stringify(name)} is already being used`);
+    }
+    const loadedComponentRecord = loadedComponentsRecord.get(name);
+    if (loadedComponentRecord.url === url) {
+      return loadedComponentRecord.cec;
+    }
+  }
+  const html = await requestText(
+    url,
+    `loadComponent(${JSON.stringify(name)}, ${JSON.stringify(url)})`
+  );
+  const doc = new DOMParser().parseFromString(html, "text/html");
+  filterGlobalStyle(doc);
+  rewriteStyleAndScript(doc, url);
+  const adoptedStyleSheets = await collectAdoptedStyleSheets(doc);
+  const result = await evaluateModules(doc, url);
+  for (const el of doc.querySelectorAll("script")) {
+    doc.body.prepend(el);
+  }
+  const component = result.default;
+  const defaultExportIsComponent = component?.prototype instanceof HTMLElement;
+  if (component && !defaultExportIsComponent) {
+    warn(
+      `The default export of component ${JSON.stringify(name)} loaded from ${url} is not a web component class`,
+      component
+    );
+  }
+  const define = (component2) => {
+    const cec = extendsElement(component2, doc.body.innerHTML, adoptedStyleSheets, afterConstructor);
+    customElements.define(name, cec);
+    emit("component-defined", { name, url });
+    loadedComponentsRecord.set(name, { cec, url });
+    return cec;
+  };
+  if (!component || !defaultExportIsComponent) {
+    return define(HTMLElement);
+  } else {
+    return define(component);
+  }
+}
+function extendsElement(BaseClass = HTMLElement, innerHTML, adoptedStyleSheets, afterConstructor) {
+  return class extends BaseClass {
+    constructor(...args) {
+      super(innerHTML, adoptedStyleSheets);
+      if (!this.shadowRoot) {
+        const shadowRoot = this.attachShadow({ mode: "open" });
+        shadowRoot.innerHTML = innerHTML;
+        if (adoptedStyleSheets && adoptedStyleSheets.length > 0) {
+          shadowRoot.adoptedStyleSheets = adoptedStyleSheets;
+        }
+      }
+      if (afterConstructor) {
+        afterConstructor.call(this);
+      }
+    }
+  };
+}
+function defineComponent(fc) {
+  const whoDefineMe = stackTraceParser2.parse(new Error().stack).at(-1).file;
+  if (blobMap.has(whoDefineMe)) {
+    return class extends HTMLElement {
+      connectedCallback() {
+        fc.call(this, this.shadowRoot || this.attachShadow({ mode: "open" }));
+      }
+    };
+  }
+  return fc.call(globalThis, document);
+}
+function filterGlobalStyle(doc) {
+  for (const styleElement of doc.querySelectorAll("style")) {
+    if (styleElement.hasAttribute("global")) {
+      document.head.append(styleElement);
+    }
+  }
+  for (const linkElement of doc.querySelectorAll('link[rel="stylesheet"]')) {
+    if (linkElement.hasAttribute("global")) {
+      document.head.append(linkElement);
+    }
+  }
+}
+function cssStyleSheetFromText(styleText, userFriendlySource) {
+  const sheet = new CSSStyleSheet();
+  try {
+    sheet.replaceSync(styleText);
+  } catch (error) {
+    warn(`Failed to create CSSStyleSheet at ${userFriendlySource}`, error);
+  }
+  return sheet;
+}
+async function collectAdoptedStyleSheets(doc) {
+  const adoptedStyleSheets = [];
+  for (const link of doc.querySelectorAll(`link[rel="stylesheet"]`)) {
+    const styleText = await requestText(link.href, link.outerHTML).catch(
+      (error) => {
+        warn(`Failed to load ${link.outerHTML}`, error);
+        return "";
+      }
+    );
+    if (!styleText) continue;
+    const sheet = cssStyleSheetFromText(styleText, link.outerHTML);
+    adoptedStyleSheets.push(sheet);
+    link.remove();
+  }
+  for (const style of doc.querySelectorAll("style")) {
+    const styleText = style.innerHTML;
+    if (!styleText) continue;
+    const sheet = cssStyleSheetFromText(styleText, style.outerHTML);
+    adoptedStyleSheets.push(sheet);
+    style.remove();
+  }
+  return adoptedStyleSheets;
+}
+function rewriteStyleAndScript(doc, url) {
+  for (const script of doc.querySelectorAll("script[src]")) {
+    const src = new URL(
+      script.getAttribute("src") || "",
+      // getAttribute to avoid getting absolute URL directly, do not use script.src
+      url
+    ).href;
+    script.src = src;
+  }
+  for (const link of doc.querySelectorAll("link[href]")) {
+    const href = new URL(
+      link.getAttribute("href") || "",
+      // getAttribute to avoid getting absolute URL directly, do not use link.href
+      url
+    ).href;
+    link.href = href;
+  }
+}
+async function evaluateModules(doc, url) {
+  const result = {};
+  for (const script of doc.querySelectorAll('script[type="module"]')) {
+    const src = script.src;
+    if (src) {
+      const res = await request(src, script.outerHTML);
+      const code = await res.text();
+      const module = await esm(code, res.url);
+      Object.assign(result, module);
+    } else {
+      const module = await esm(script.textContent, url);
+      Object.assign(result, module);
+    }
+    script.remove();
+  }
+  return result;
+}
+export {
+  NativeSFCError,
+  defineComponent,
+  defineFetch,
+  loadComponent,
+  on
+};
+//! we provide an extra argument to user's component constructor
+//! if the user's constructor does not create a shadow root, we will create one here

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "native-sfc",
+  "version": "0.0.1",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "scripts": {
+    "build": "node esbuild.ts && dts-bundle-generator -o dist/index.d.ts src/index.ts",
+    "dev": "node esbuild.ts --dev"
+  },
+  "dependencies": {
+    "es-module-lexer": "^2.0.0",
+    "stacktrace-parser": "^0.1.11"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.6",
+    "dts-bundle-generator": "^9.5.1",
+    "esbuild": "^0.27.2"
+  },
+  "author": "YieldRay",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YieldRay/native-sfc.git"
+  },
+  "bugs": {
+    "url": "https://github.com/YieldRay/native-sfc/issues"
+  },
+  "homepage": "https://github.com/YieldRay/native-sfc#readme",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org"
+  }
+}