@coherent.js/web-components 1.0.0-beta.5 → 1.0.0-beta.7

package/dist/index.js

@@ -0,0 +1,110 @@
+// src/index.js
+import { render } from "@coherent.js/core";
+function defineComponent(name, component, options = {}) {
+  if (typeof window === "undefined") {
+    return { name, component, options };
+  }
+  if (!window.customElements) {
+    throw new Error("Custom Elements API not supported");
+  }
+  const observedAttrs = options.observedAttributes || [];
+  const defaults = options.defaults || {};
+  class CoherentElement extends HTMLElement {
+    static get observedAttributes() {
+      return observedAttrs;
+    }
+    constructor() {
+      super();
+      this._props = { ...defaults };
+      this._connected = false;
+      this.component = component;
+      this.options = options;
+    }
+    connectedCallback() {
+      this._connected = true;
+      for (const attr of observedAttrs) {
+        if (this.hasAttribute(attr)) {
+          this._props[attr] = this.getAttribute(attr);
+        }
+      }
+      this._render();
+    }
+    disconnectedCallback() {
+      this._connected = false;
+      if (options.shadow && this.shadowRoot) {
+        this.shadowRoot.innerHTML = "";
+      } else {
+        this.innerHTML = "";
+      }
+    }
+    attributeChangedCallback(attrName, oldValue, newValue) {
+      if (oldValue === newValue) return;
+      this._props[attrName] = newValue;
+      if (this._connected) {
+        this._render();
+      }
+    }
+    /**
+     * Set a property and re-render
+     */
+    setProperty(key, value) {
+      this._props[key] = value;
+      if (this._connected) {
+        this._render();
+      }
+    }
+    /**
+     * Get current props
+     */
+    getProperties() {
+      return { ...this._props };
+    }
+    _render() {
+      const componentDef = typeof this.component === "function" ? this.component(this._props) : this.component;
+      const html = render(componentDef);
+      if (this.options.shadow) {
+        if (!this.shadowRoot) {
+          this.attachShadow({ mode: "open" });
+        }
+        this.shadowRoot.innerHTML = html;
+        this._delegateEvents(this.shadowRoot);
+      } else {
+        this.innerHTML = html;
+        this._delegateEvents(this);
+      }
+    }
+    /**
+     * Delegate data-action events to component handlers
+     */
+    _delegateEvents(root) {
+      const actionElements = root.querySelectorAll("[data-action]");
+      for (const el of actionElements) {
+        const action = el.dataset.action;
+        const [eventType, handlerName] = action.includes(":") ? action.split(":") : ["click", action];
+        el.addEventListener(eventType, (event) => {
+          this.dispatchEvent(new CustomEvent("coherent-action", {
+            bubbles: true,
+            detail: { action: handlerName, event, element: el }
+          }));
+        });
+      }
+    }
+  }
+  window.customElements.define(name, CoherentElement);
+  return CoherentElement;
+}
+function integrateWithWebComponents(_runtime) {
+  return {
+    defineComponent: (name, component, options) => defineComponent(name, component, options)
+  };
+}
+function defineCoherentElement(name, component, options = {}) {
+  return defineComponent(name, component, options);
+}
+export {
+  defineComponent as default,
+  defineCoherentElement,
+  defineComponent,
+  integrateWithWebComponents
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../src/index.js"],
+  "sourcesContent": ["/**\n * Coherent.js Web Components Integration\n * Provides custom element and web component utilities\n */\n\nimport { render } from '@coherent.js/core';\n\n/**\n * Define a Coherent.js component as a custom element\n *\n * @param {string} name - Custom element tag name (must contain a hyphen)\n * @param {Function|Object} component - Coherent.js component (function or object)\n * @param {Object} [options] - Configuration options\n * @param {boolean} [options.shadow] - Use Shadow DOM for style encapsulation\n * @param {string[]} [options.observedAttributes] - Attributes to watch for changes\n * @param {Object} [options.defaults] - Default property values\n * @returns {Function|Object} The custom element class, or a server-side placeholder\n */\nexport function defineComponent(name, component, options = {}) {\n  if (typeof window === 'undefined') {\n    // Server-side: return a placeholder for SSR\n    return { name, component, options };\n  }\n\n  if (!window.customElements) {\n    throw new Error('Custom Elements API not supported');\n  }\n\n  const observedAttrs = options.observedAttributes || [];\n  const defaults = options.defaults || {};\n\n  class CoherentElement extends HTMLElement {\n    static get observedAttributes() {\n      return observedAttrs;\n    }\n\n    constructor() {\n      super();\n      this._props = { ...defaults };\n      this._connected = false;\n      this.component = component;\n      this.options = options;\n    }\n\n    connectedCallback() {\n      this._connected = true;\n      // Copy initial attributes to props\n      for (const attr of observedAttrs) {\n        if (this.hasAttribute(attr)) {\n          this._props[attr] = this.getAttribute(attr);\n        }\n      }\n      this._render();\n    }\n\n    disconnectedCallback() {\n      this._connected = false;\n      // Cleanup: remove event listeners and clear content\n      if (options.shadow && this.shadowRoot) {\n        this.shadowRoot.innerHTML = '';\n      } else {\n        this.innerHTML = '';\n      }\n    }\n\n    attributeChangedCallback(attrName, oldValue, newValue) {\n      if (oldValue === newValue) return;\n      this._props[attrName] = newValue;\n      if (this._connected) {\n        this._render();\n      }\n    }\n\n    /**\n     * Set a property and re-render\n     */\n    setProperty(key, value) {\n      this._props[key] = value;\n      if (this._connected) {\n        this._render();\n      }\n    }\n\n    /**\n     * Get current props\n     */\n    getProperties() {\n      return { ...this._props };\n    }\n\n    _render() {\n      const componentDef = typeof this.component === 'function'\n        ? this.component(this._props)\n        : this.component;\n\n      const html = render(componentDef);\n\n      if (this.options.shadow) {\n        if (!this.shadowRoot) {\n          this.attachShadow({ mode: 'open' });\n        }\n        this.shadowRoot.innerHTML = html;\n        this._delegateEvents(this.shadowRoot);\n      } else {\n        this.innerHTML = html;\n        this._delegateEvents(this);\n      }\n    }\n\n    /**\n     * Delegate data-action events to component handlers\n     */\n    _delegateEvents(root) {\n      const actionElements = root.querySelectorAll('[data-action]');\n      for (const el of actionElements) {\n        const action = el.dataset.action;\n        const [eventType, handlerName] = action.includes(':')\n          ? action.split(':')\n          : ['click', action];\n\n        el.addEventListener(eventType, (event) => {\n          this.dispatchEvent(new CustomEvent('coherent-action', {\n            bubbles: true,\n            detail: { action: handlerName, event, element: el }\n          }));\n        });\n      }\n    }\n  }\n\n  window.customElements.define(name, CoherentElement);\n  return CoherentElement;\n}\n\n/**\n * Integration utilities for runtime environments\n */\nexport function integrateWithWebComponents(_runtime) {\n  return {\n    defineComponent: (name, component, options) => defineComponent(name, component, options)\n  };\n}\n\n/**\n * Alias for defineComponent\n */\nexport function defineCoherentElement(name, component, options = {}) {\n  return defineComponent(name, component, options);\n}\n\nexport { defineComponent as default };\n"],
+  "mappings": ";AAKA,SAAS,cAAc;AAahB,SAAS,gBAAgB,MAAM,WAAW,UAAU,CAAC,GAAG;AAC7D,MAAI,OAAO,WAAW,aAAa;AAEjC,WAAO,EAAE,MAAM,WAAW,QAAQ;AAAA,EACpC;AAEA,MAAI,CAAC,OAAO,gBAAgB;AAC1B,UAAM,IAAI,MAAM,mCAAmC;AAAA,EACrD;AAEA,QAAM,gBAAgB,QAAQ,sBAAsB,CAAC;AACrD,QAAM,WAAW,QAAQ,YAAY,CAAC;AAAA,EAEtC,MAAM,wBAAwB,YAAY;AAAA,IACxC,WAAW,qBAAqB;AAC9B,aAAO;AAAA,IACT;AAAA,IAEA,cAAc;AACZ,YAAM;AACN,WAAK,SAAS,EAAE,GAAG,SAAS;AAC5B,WAAK,aAAa;AAClB,WAAK,YAAY;AACjB,WAAK,UAAU;AAAA,IACjB;AAAA,IAEA,oBAAoB;AAClB,WAAK,aAAa;AAElB,iBAAW,QAAQ,eAAe;AAChC,YAAI,KAAK,aAAa,IAAI,GAAG;AAC3B,eAAK,OAAO,IAAI,IAAI,KAAK,aAAa,IAAI;AAAA,QAC5C;AAAA,MACF;AACA,WAAK,QAAQ;AAAA,IACf;AAAA,IAEA,uBAAuB;AACrB,WAAK,aAAa;AAElB,UAAI,QAAQ,UAAU,KAAK,YAAY;AACrC,aAAK,WAAW,YAAY;AAAA,MAC9B,OAAO;AACL,aAAK,YAAY;AAAA,MACnB;AAAA,IACF;AAAA,IAEA,yBAAyB,UAAU,UAAU,UAAU;AACrD,UAAI,aAAa,SAAU;AAC3B,WAAK,OAAO,QAAQ,IAAI;AACxB,UAAI,KAAK,YAAY;AACnB,aAAK,QAAQ;AAAA,MACf;AAAA,IACF;AAAA;AAAA;AAAA;AAAA,IAKA,YAAY,KAAK,OAAO;AACtB,WAAK,OAAO,GAAG,IAAI;AACnB,UAAI,KAAK,YAAY;AACnB,aAAK,QAAQ;AAAA,MACf;AAAA,IACF;AAAA;AAAA;AAAA;AAAA,IAKA,gBAAgB;AACd,aAAO,EAAE,GAAG,KAAK,OAAO;AAAA,IAC1B;AAAA,IAEA,UAAU;AACR,YAAM,eAAe,OAAO,KAAK,cAAc,aAC3C,KAAK,UAAU,KAAK,MAAM,IAC1B,KAAK;AAET,YAAM,OAAO,OAAO,YAAY;AAEhC,UAAI,KAAK,QAAQ,QAAQ;AACvB,YAAI,CAAC,KAAK,YAAY;AACpB,eAAK,aAAa,EAAE,MAAM,OAAO,CAAC;AAAA,QACpC;AACA,aAAK,WAAW,YAAY;AAC5B,aAAK,gBAAgB,KAAK,UAAU;AAAA,MACtC,OAAO;AACL,aAAK,YAAY;AACjB,aAAK,gBAAgB,IAAI;AAAA,MAC3B;AAAA,IACF;AAAA;AAAA;AAAA;AAAA,IAKA,gBAAgB,MAAM;AACpB,YAAM,iBAAiB,KAAK,iBAAiB,eAAe;AAC5D,iBAAW,MAAM,gBAAgB;AAC/B,cAAM,SAAS,GAAG,QAAQ;AAC1B,cAAM,CAAC,WAAW,WAAW,IAAI,OAAO,SAAS,GAAG,IAChD,OAAO,MAAM,GAAG,IAChB,CAAC,SAAS,MAAM;AAEpB,WAAG,iBAAiB,WAAW,CAAC,UAAU;AACxC,eAAK,cAAc,IAAI,YAAY,mBAAmB;AAAA,YACpD,SAAS;AAAA,YACT,QAAQ,EAAE,QAAQ,aAAa,OAAO,SAAS,GAAG;AAAA,UACpD,CAAC,CAAC;AAAA,QACJ,CAAC;AAAA,MACH;AAAA,IACF;AAAA,EACF;AAEA,SAAO,eAAe,OAAO,MAAM,eAAe;AAClD,SAAO;AACT;AAKO,SAAS,2BAA2B,UAAU;AACnD,SAAO;AAAA,IACL,iBAAiB,CAAC,MAAM,WAAW,YAAY,gBAAgB,MAAM,WAAW,OAAO;AAAA,EACzF;AACF;AAKO,SAAS,sBAAsB,MAAM,WAAW,UAAU,CAAC,GAAG;AACnE,SAAO,gBAAgB,MAAM,WAAW,OAAO;AACjD;",
+  "names": []
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@coherent.js/web-components",
-  "version": "1.0.0-beta.5",
+  "version": "1.0.0-beta.7",
   "description": "Web Components integration for Coherent.js",
   "type": "module",
   "main": "src/index.js",
@@ -15,8 +15,8 @@
   ],
   "author": "Coherent.js Team",
   "license": "MIT",
-  "dependencies": {
-    "@coherent.js/core": "1.0.0-beta.5"
+  "peerDependencies": {
+    "@coherent.js/core": "1.0.0-beta.7"
   },
   "devDependencies": {
     "vitest": "^3.2.4"
@@ -25,11 +25,20 @@
     "type": "git",
     "url": "git+https://github.com/Tomdrouv1/coherent.js.git"
   },
+  "homepage": "https://github.com/Tomdrouv1/coherent.js",
+  "bugs": {
+    "url": "https://github.com/Tomdrouv1/coherent.js/issues"
+  },
   "publishConfig": {
     "access": "public"
   },
+  "engines": {
+    "node": ">=20.0.0"
+  },
   "types": "./types/index.d.ts",
   "files": [
+    "dist/",
+    "src/",
     "LICENSE",
     "README.md",
     "types/"

package/src/index.js

@@ -7,10 +7,18 @@ import { render } from '@coherent.js/core';
 
 /**
  * Define a Coherent.js component as a custom element
+ *
+ * @param {string} name - Custom element tag name (must contain a hyphen)
+ * @param {Function|Object} component - Coherent.js component (function or object)
+ * @param {Object} [options] - Configuration options
+ * @param {boolean} [options.shadow] - Use Shadow DOM for style encapsulation
+ * @param {string[]} [options.observedAttributes] - Attributes to watch for changes
+ * @param {Object} [options.defaults] - Default property values
+ * @returns {Function|Object} The custom element class, or a server-side placeholder
  */
 export function defineComponent(name, component, options = {}) {
   if (typeof window === 'undefined') {
-    // Server-side: just return a placeholder
+    // Server-side: return a placeholder for SSR
     return { name, component, options };
   }
 
@@ -18,24 +26,104 @@ export function defineComponent(name, component, options = {}) {
     throw new Error('Custom Elements API not supported');
   }
 
+  const observedAttrs = options.observedAttributes || [];
+  const defaults = options.defaults || {};
+
   class CoherentElement extends HTMLElement {
+    static get observedAttributes() {
+      return observedAttrs;
+    }
+
     constructor() {
       super();
+      this._props = { ...defaults };
+      this._connected = false;
       this.component = component;
       this.options = options;
     }
 
     connectedCallback() {
-      this.render();
+      this._connected = true;
+      // Copy initial attributes to props
+      for (const attr of observedAttrs) {
+        if (this.hasAttribute(attr)) {
+          this._props[attr] = this.getAttribute(attr);
+        }
+      }
+      this._render();
+    }
+
+    disconnectedCallback() {
+      this._connected = false;
+      // Cleanup: remove event listeners and clear content
+      if (options.shadow && this.shadowRoot) {
+        this.shadowRoot.innerHTML = '';
+      } else {
+        this.innerHTML = '';
+      }
+    }
+
+    attributeChangedCallback(attrName, oldValue, newValue) {
+      if (oldValue === newValue) return;
+      this._props[attrName] = newValue;
+      if (this._connected) {
+        this._render();
+      }
+    }
+
+    /**
+     * Set a property and re-render
+     */
+    setProperty(key, value) {
+      this._props[key] = value;
+      if (this._connected) {
+        this._render();
+      }
+    }
+
+    /**
+     * Get current props
+     */
+    getProperties() {
+      return { ...this._props };
     }
 
-    render() {
-      const html = render(this.component);
+    _render() {
+      const componentDef = typeof this.component === 'function'
+        ? this.component(this._props)
+        : this.component;
+
+      const html = render(componentDef);
+
       if (this.options.shadow) {
-        const shadow = this.attachShadow({ mode: 'open' });
-        shadow.innerHTML = html;
+        if (!this.shadowRoot) {
+          this.attachShadow({ mode: 'open' });
+        }
+        this.shadowRoot.innerHTML = html;
+        this._delegateEvents(this.shadowRoot);
       } else {
         this.innerHTML = html;
+        this._delegateEvents(this);
+      }
+    }
+
+    /**
+     * Delegate data-action events to component handlers
+     */
+    _delegateEvents(root) {
+      const actionElements = root.querySelectorAll('[data-action]');
+      for (const el of actionElements) {
+        const action = el.dataset.action;
+        const [eventType, handlerName] = action.includes(':')
+          ? action.split(':')
+          : ['click', action];
+
+        el.addEventListener(eventType, (event) => {
+          this.dispatchEvent(new CustomEvent('coherent-action', {
+            bubbles: true,
+            detail: { action: handlerName, event, element: el }
+          }));
+        });
       }
     }
   }
@@ -45,7 +133,7 @@ export function defineComponent(name, component, options = {}) {
 }
 
 /**
- * Integration utilities
+ * Integration utilities for runtime environments
  */
 export function integrateWithWebComponents(_runtime) {
   return {
@@ -53,6 +141,9 @@ export function integrateWithWebComponents(_runtime) {
   };
 }
 
+/**
+ * Alias for defineComponent
+ */
 export function defineCoherentElement(name, component, options = {}) {
   return defineComponent(name, component, options);
 }

package/types/index.d.ts

@@ -3,19 +3,51 @@
  * @module @coherent.js/web-components
  */
 
-// ===== Web Component Integration Types =====
+import type { CoherentNode, CoherentComponent, ComponentState, ComponentProps } from '@coherent.js/core';
 
+// ============================================================================
+// Web Component Configuration
+// ============================================================================
+
+/**
+ * Property type constructors
+ */
+export type PropertyType =
+  | StringConstructor
+  | NumberConstructor
+  | BooleanConstructor
+  | ObjectConstructor
+  | ArrayConstructor;
+
+/**
+ * Property definition for web components
+ */
+export interface PropertyDefinition {
+  /** Property type */
+  type?: PropertyType;
+  /** Default value */
+  default?: unknown;
+  /** Whether property is required */
+  required?: boolean;
+  /** Custom validator */
+  validator?: (value: unknown) => boolean;
+}
+
+/**
+ * Component options for web component registration
+ */
 export interface ComponentOptions {
+  /** Use shadow DOM */
   shadow?: boolean;
+  /** Shadow root mode */
   mode?: 'open' | 'closed';
+  /** Delegates focus to shadow root */
   delegatesFocus?: boolean;
+  /** Attributes to observe */
   observedAttributes?: string[];
-  props?: Record<string, {
-    type?: StringConstructor | NumberConstructor | BooleanConstructor | ObjectConstructor | ArrayConstructor;
-    default?: any;
-    required?: boolean;
-    validator?: (value: any) => boolean;
-  }>;
+  /** Property definitions */
+  props?: Record<string, PropertyDefinition>;
+  /** Lifecycle hooks */
   lifecycle?: {
     connected?: () => void;
     disconnected?: () => void;
@@ -24,19 +56,85 @@ export interface ComponentOptions {
   };
 }
 
+/**
+ * Web component configuration
+ */
+export interface WebComponentConfig {
+  /** Custom element tag name (must contain hyphen) */
+  tagName: string;
+  /** Coherent.js component */
+  component: CoherentComponent;
+  /** Attributes to observe */
+  observedAttributes?: string[];
+  /** Use shadow DOM */
+  shadow?: boolean | ShadowRootInit;
+  /** Styles to apply */
+  styles?: string | string[];
+  /** Adopted style sheets */
+  adoptedStyleSheets?: CSSStyleSheet[];
+}
+
+// ============================================================================
+// Coherent Web Component
+// ============================================================================
+
+/**
+ * Coherent element constructor
+ */
 export interface CoherentElementConstructor {
   new (): CoherentElement;
   prototype: CoherentElement;
 }
 
+/**
+ * Coherent web component element interface
+ */
 export interface CoherentElement extends HTMLElement {
-  component: any;
+  /** The wrapped component */
+  component: CoherentComponent;
+  /** Component options */
   options: ComponentOptions;
+
+  /** Render the component */
   render(): void;
-  update(props?: Record<string, any>): void;
-  hydrate(data?: any): void;
+
+  /** Update with new props */
+  update(props?: Record<string, unknown>): void;
+
+  /** Hydrate with server data */
+  hydrate(data?: unknown): void;
 }
 
+/**
+ * Extended coherent web component interface
+ */
+export interface CoherentWebComponent extends HTMLElement {
+  /** Component instance reference */
+  readonly componentInstance: unknown;
+  /** Current props */
+  props: Record<string, unknown>;
+  /** Current state */
+  state: ComponentState;
+
+  /** Called when element is added to DOM */
+  connectedCallback(): void;
+  /** Called when element is removed from DOM */
+  disconnectedCallback(): void;
+  /** Called when an observed attribute changes */
+  attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+  /** Called when element is moved to a new document */
+  adoptedCallback(): void;
+
+  /** Update component state */
+  setState(updates: Partial<ComponentState>): void;
+  /** Force a re-render */
+  forceUpdate(): void;
+}
+
+// ============================================================================
+// Registration Functions
+// ============================================================================
+
 /**
  * Define a Coherent.js component as a custom element
  *
@@ -53,14 +151,14 @@ export interface CoherentElement extends HTMLElement {
  */
 export function defineComponent(
   name: string,
-  component: any | ((props: any) => any),
+  component: CoherentComponent | CoherentNode,
   options?: ComponentOptions
 ): CoherentElementConstructor;
 
 /**
- * Integration utilities for web components runtime
+ * Define a web component with full configuration
  */
-export function integrateWithWebComponents(runtime: any): void;
+export function defineWebComponent(config: WebComponentConfig): typeof CoherentWebComponent;
 
 /**
  * Register multiple components at once
@@ -73,7 +171,30 @@ export function integrateWithWebComponents(runtime: any): void;
  * });
  * ```
  */
-export function registerComponents(components: Record<string, any>, options?: ComponentOptions): void;
+export function registerComponents(
+  components: Record<string, CoherentComponent | CoherentNode>,
+  options?: ComponentOptions
+): void;
+
+/**
+ * Register web components with full configuration
+ */
+export function registerWebComponents(
+  components: Record<string, WebComponentConfig>
+): void;
+
+/**
+ * Create a custom element class from a component
+ */
+export function createCustomElement(
+  component: CoherentComponent,
+  options?: Partial<WebComponentConfig>
+): typeof CoherentWebComponent;
+
+/**
+ * Integration utilities for web components runtime
+ */
+export function integrateWithWebComponents(runtime: unknown): void;
 
 /**
  * Check if a custom element is defined
@@ -93,19 +214,31 @@ export function upgradeElement(element: Element): void;
 /**
  * Create a Coherent.js component from a custom element
  */
-export function fromCustomElement(element: HTMLElement): any;
+export function fromCustomElement(element: HTMLElement): CoherentNode;
+
+// ============================================================================
+// Property Decorators
+// ============================================================================
 
 /**
- * Helper for creating reactive properties on custom elements
+ * Property declaration for decorators
  */
 export interface PropertyDeclaration {
-  type?: StringConstructor | NumberConstructor | BooleanConstructor | ObjectConstructor | ArrayConstructor;
+  /** Property type */
+  type?: PropertyType;
+  /** Sync with attribute */
   attribute?: boolean | string;
+  /** Reflect to attribute */
   reflect?: boolean;
-  converter?: (value: string) => any;
-  default?: any;
+  /** Custom converter from attribute string */
+  converter?: (value: string) => unknown;
+  /** Default value */
+  default?: unknown;
 }
 
+/**
+ * Create a property definition
+ */
 export function createProperty(declaration: PropertyDeclaration): PropertyDecorator;
 
 /**
@@ -120,56 +253,141 @@ export function property(declaration?: PropertyDeclaration): PropertyDecorator;
  */
 export function customElement(tagName: string): ClassDecorator;
 
-// ===== Event System Types =====
+// ============================================================================
+// Event System
+// ============================================================================
 
+/**
+ * Custom event options
+ */
 export interface EventOptions {
+  /** Whether event bubbles */
   bubbles?: boolean;
+  /** Whether event is composed (crosses shadow boundary) */
   composed?: boolean;
+  /** Whether event is cancelable */
   cancelable?: boolean;
-  detail?: any;
+  /** Event detail data */
+  detail?: unknown;
 }
 
+/**
+ * Create a custom event
+ */
 export function createEvent(type: string, options?: EventOptions): CustomEvent;
-export function dispatchCustomEvent(element: Element, type: string, options?: EventOptions): boolean;
 
-// ===== Slot Utilities Types =====
+/**
+ * Dispatch a custom event on an element
+ */
+export function dispatchCustomEvent(
+  element: Element,
+  type: string,
+  options?: EventOptions
+): boolean;
 
+// ============================================================================
+// Slot Utilities
+// ============================================================================
+
+/**
+ * Slot change event interface
+ */
 export interface SlotChangeEvent extends Event {
   target: HTMLSlotElement;
 }
 
+/**
+ * Get slotted content
+ */
 export function getSlotContent(element: Element, slotName?: string): Node[];
+
+/**
+ * Check if slot has content
+ */
 export function hasSlotContent(element: Element, slotName?: string): boolean;
-export function onSlotChange(element: Element, callback: (event: SlotChangeEvent) => void, slotName?: string): () => void;
 
-// ===== Shadow DOM Utilities Types =====
+/**
+ * Listen for slot changes
+ */
+export function onSlotChange(
+  element: Element,
+  callback: (event: SlotChangeEvent) => void,
+  slotName?: string
+): () => void;
 
+// ============================================================================
+// Shadow DOM Utilities
+// ============================================================================
+
+/**
+ * Shadow root initialization options
+ */
 export interface ShadowRootInit {
+  /** Shadow mode */
   mode: 'open' | 'closed';
+  /** Delegates focus */
   delegatesFocus?: boolean;
+  /** Slot assignment mode */
   slotAssignment?: 'manual' | 'named';
 }
 
+/**
+ * Create a shadow root
+ */
 export function createShadowRoot(element: Element, init: ShadowRootInit): ShadowRoot;
+
+/**
+ * Adopt styles into a shadow root
+ */
 export function adoptStyles(shadowRoot: ShadowRoot, styles: string | CSSStyleSheet[]): void;
+
+/**
+ * Get an element's shadow root
+ */
 export function getShadowRoot(element: Element): ShadowRoot | null;
 
-// ===== Template Utilities Types =====
+// ============================================================================
+// Template Utilities
+// ============================================================================
 
+/**
+ * Create a template element from HTML
+ */
 export function createTemplate(html: string): HTMLTemplateElement;
+
+/**
+ * Clone a template's content
+ */
 export function cloneTemplate(template: HTMLTemplateElement): DocumentFragment;
-export function renderToTemplate(component: any): HTMLTemplateElement;
 
-// ===== Lifecycle Hooks =====
+/**
+ * Render a component to a template
+ */
+export function renderToTemplate(component: CoherentNode): HTMLTemplateElement;
+
+// ============================================================================
+// Lifecycle Hooks
+// ============================================================================
 
+/**
+ * Lifecycle hook definitions
+ */
 export interface LifecycleHooks {
+  /** Called when element is added to DOM */
   onConnected?: () => void;
+  /** Called when element is removed from DOM */
   onDisconnected?: () => void;
+  /** Called when element is moved to new document */
   onAdopted?: () => void;
+  /** Called when observed attribute changes */
   onAttributeChanged?: (name: string, oldValue: string | null, newValue: string | null) => void;
-  onPropertyChanged?: (name: string, oldValue: any, newValue: any) => void;
+  /** Called when a property changes */
+  onPropertyChanged?: (name: string, oldValue: unknown, newValue: unknown) => void;
 }
 
+/**
+ * Create a lifecycle manager
+ */
 export function createLifecycleManager(hooks: LifecycleHooks): {
   connected(): void;
   disconnected(): void;