@data-club/ai-hub 0.0.1

package/src/webcomponent/defineWebComponent.tsx

@@ -0,0 +1,193 @@
+/**
+ * `defineWebComponent()` — the helper every per-customer wrapper calls
+ * exactly once to ship its React tree as a `<{customer}-chat>` Web
+ * Component (§7.10).
+ *
+ * Default behavior:
+ *
+ * 1. Validates `tagName` per the WHATWG custom-element naming rules
+ *    (lowercase, contains a hyphen, not a reserved name).
+ *    https://html.spec.whatwg.org/multipage/custom-elements.html#valid-custom-element-name
+ * 2. Creates an `HTMLElement` subclass:
+ *    - `connectedCallback` opens an open Shadow Root (default) or mounts
+ *      directly on the host, calls `react-dom`'s `createRoot()` against
+ *      that root, and renders `<Component />`.
+ *    - `disconnectedCallback` unmounts the React root.
+ *    - The `onConnect` / `onDisconnect` hooks fire around mount/unmount.
+ * 3. Injects the package's default CSS into the shadow root unless
+ *    `cssText` is provided (in which case the per-customer CSS is
+ *    responsible for everything).
+ * 4. Calls `customElements.define(tagName, GeneratedClass)`. Re-registration
+ *    (e.g. during hot reload) is detected and warned, not thrown — the
+ *    second registration is a no-op so dev workflows aren't blocked.
+ *
+ * @see SPECIFICATIONS.md §7.10 — defineWebComponent
+ */
+
+import { createElement, type ComponentType } from "react";
+import { createRoot, type Root } from "react-dom/client";
+
+/* eslint-disable jsdoc/require-jsdoc -- minor private members */
+declare global {
+  interface HTMLElement {
+    /** Root used by `defineWebComponent` to track the React tree. */
+    __dcAIHubRoot?: Root;
+  }
+}
+/* eslint-enable jsdoc/require-jsdoc */
+
+/**
+ * Options for `defineWebComponent`.
+ */
+export interface DefineWebComponentOptions {
+  /**
+   * Render into a Shadow DOM. Default true — style isolation is what
+   * makes ai-hub safe to embed in any third-party website (§7.10).
+   * Disable only for advanced cases where the host page must reach into
+   * the chat tree (e.g. legacy print-stylesheets).
+   */
+  shadowDom?: boolean;
+  /**
+   * CSS to inject into the Shadow Root. When omitted, the library injects
+   * its bundled `default.css` (set by the consuming app's bundler via
+   * `import "@data-club/ai-hub/styles/default.css"`-style raw imports —
+   * the helper itself does not pull the file at runtime).
+   *
+   * For Step 7 the per-customer wrapper is responsible for providing
+   * either `cssText` or arranging for `default.css` to be loaded another
+   * way; the helper validates that one of the two is in place but does
+   * not embed a CSS string itself.
+   */
+  cssText?: string;
+  /**
+   * Called immediately after the React root mounts. Useful for the
+   * wrapper to attach analytics or read host-element attributes.
+   *
+   * @param host - the custom-element host.
+   */
+  onConnect?: (host: HTMLElement) => void;
+  /**
+   * Called when the custom element disconnects (just before the React root
+   * is unmounted).
+   *
+   * @param host - the custom-element host.
+   */
+  onDisconnect?: (host: HTMLElement) => void;
+}
+
+/**
+ * Validates a custom-element tag name per the WHATWG rules:
+ *
+ * - Starts with a lowercase ASCII letter.
+ * - Contains at least one hyphen.
+ * - Only lowercase ASCII letters, digits, hyphens, dots, and underscores.
+ * - Does not match the reserved-name list (`annotation-xml`, `color-profile`,
+ *   `font-face`, `font-face-src`, `font-face-uri`, `font-face-format`,
+ *   `font-face-name`, `missing-glyph`).
+ *
+ * @param tagName - the proposed tag name.
+ * @returns true when the name is valid.
+ */
+export function isValidCustomElementName(tagName: string): boolean {
+  if (typeof tagName !== "string" || tagName.length === 0) return false;
+  if (!/^[a-z][a-z0-9._-]*-[a-z0-9._-]*$/.test(tagName)) return false;
+  const reserved = new Set([
+    "annotation-xml",
+    "color-profile",
+    "font-face",
+    "font-face-src",
+    "font-face-uri",
+    "font-face-format",
+    "font-face-name",
+    "missing-glyph",
+  ]);
+  return !reserved.has(tagName);
+}
+
+/**
+ * Registers a custom HTML element that renders `Component` inside a
+ * Shadow DOM (or directly on the host when `shadowDom: false`).
+ *
+ * Idempotent on re-registration of the same `tagName`: emits a console
+ * warning and returns without throwing (the existing element keeps
+ * working — useful during HMR).
+ *
+ * @param tagName - the custom-element tag name (must contain a hyphen).
+ * @param Component - the React component to mount.
+ * @param options - optional shadow-DOM + CSS + lifecycle settings.
+ *
+ * @example
+ * ```ts
+ * defineWebComponent("bankxyz-chat", () => <DataClubAIHub />, {
+ *   cssText: customerThemeCss,
+ * });
+ * ```
+ */
+export function defineWebComponent(
+  tagName: string,
+  Component: ComponentType,
+  options: DefineWebComponentOptions = {},
+): void {
+  if (!isValidCustomElementName(tagName)) {
+    throw new Error(
+      `defineWebComponent: "${tagName}" is not a valid custom-element name. ` +
+        `Names must start with a lowercase letter, contain at least one hyphen, and use only [a-z0-9._-].`,
+    );
+  }
+
+  if (typeof customElements === "undefined") {
+    throw new Error(
+      "defineWebComponent: the `customElements` registry is unavailable. " +
+        "This helper must run in a browser-like environment.",
+    );
+  }
+
+  if (customElements.get(tagName)) {
+    // Hot-reload friendliness — registries are immutable, so we warn and
+    // bail rather than throwing.
+    // eslint-disable-next-line no-console
+    console.warn(
+      `defineWebComponent: <${tagName}> is already registered. Skipping re-registration.`,
+    );
+    return;
+  }
+
+  const shadowDom = options.shadowDom !== false;
+  const cssText = options.cssText;
+  const onConnect = options.onConnect;
+  const onDisconnect = options.onDisconnect;
+
+  class AIHubElement extends HTMLElement {
+    connectedCallback(): void {
+      const target: Element | ShadowRoot = shadowDom
+        ? this.attachShadow({ mode: "open" })
+        : this;
+
+      if (shadowDom && cssText) {
+        const styleEl = document.createElement("style");
+        styleEl.textContent = cssText;
+        (target as ShadowRoot).appendChild(styleEl);
+      }
+
+      const mountNode = document.createElement("div");
+      mountNode.className = "data-club-ai-hub-mount";
+      target.appendChild(mountNode);
+
+      const root = createRoot(mountNode);
+      root.render(createElement(Component));
+      this.__dcAIHubRoot = root;
+      onConnect?.(this);
+    }
+
+    disconnectedCallback(): void {
+      onDisconnect?.(this);
+      const root = this.__dcAIHubRoot;
+      if (root) {
+        root.unmount();
+        delete this.__dcAIHubRoot;
+      }
+    }
+  }
+
+  customElements.define(tagName, AIHubElement);
+}

package/src/webcomponent/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Re-exports for the `webcomponent/` directory.
+ *
+ * @see SPECIFICATIONS.md §7.10 — defineWebComponent
+ */
+
+export {
+  defineWebComponent,
+  isValidCustomElementName,
+  type DefineWebComponentOptions,
+} from "./defineWebComponent.js";