@ozsarman/clarityjs 0.6.0

package/src/head.js

@@ -0,0 +1,393 @@
+/**
+ * Clarity.js — Head / Meta Management
+ *
+ * Reactive <title>, <meta>, <link>, <script> injection — works in both
+ * client-side and SSR contexts.
+ *
+ * ── Client API ──────────────────────────────────────────────────────────────
+ *
+ *   import { useHead } from '@ozsarman/clarityjs/head';
+ *
+ *   component ProductPage(product: Object) {
+ *     useHead({
+ *       title:       () => `${product.name} — MyShop`,
+ *       description: () => product.description,
+ *       og: {
+ *         title: () => product.name,
+ *         image: () => product.imageUrl,
+ *         type:  'website',
+ *       },
+ *       link: [
+ *         { rel: 'canonical', href: () => `https://myshop.com/products/${product.slug}` },
+ *       ],
+ *     });
+ *   }
+ *
+ * ── SSR API ─────────────────────────────────────────────────────────────────
+ *
+ *   import { createHead, renderHead } from '@ozsarman/clarityjs/head';
+ *
+ *   const head = createHead();
+ *   // ... render component tree (components call useHead internally) ...
+ *   const { title, metas, links, scripts } = renderHead(head);
+ *
+ * Author: Claude (Anthropic) + Özdemir Sarman
+ */
+
+import { signal, effect, batch } from './runtime.js';
+
+// ─── Global head instance ────────────────────────────────────────────────────
+
+let _globalHead = null;
+
+/**
+ * Create and activate a new head manager.
+ * Call this once per app (or once per SSR request).
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.titleTemplate]   – e.g. '%s | MyApp'  (%s = page title)
+ * @param {string} [opts.defaultTitle]    – fallback when no component sets a title
+ * @returns {HeadManager}
+ */
+export function createHead(opts = {}) {
+  const head = new HeadManager(opts);
+  _globalHead = head;
+  return head;
+}
+
+/**
+ * Get the active global head manager (created by createHead).
+ * @returns {HeadManager|null}
+ */
+export function getHead() {
+  return _globalHead;
+}
+
+// ─── HeadManager ─────────────────────────────────────────────────────────────
+
+class HeadManager {
+  constructor({ titleTemplate = null, defaultTitle = '' } = {}) {
+    this._titleTemplate = titleTemplate;   // '%s | MyApp'
+    this._defaultTitle  = defaultTitle;
+
+    // Each entry is an object from useHead() — stored in render order.
+    // Later entries win (deeper component wins over parent).
+    this._entries  = [];
+    this._disposes = [];                   // cleanup functions from effect()
+
+    // Reactive resolved values (signals) — DOM patches subscribe to these
+    this._resolvedTitle   = signal(defaultTitle);
+    this._resolvedMetas   = signal([]);
+    this._resolvedLinks   = signal([]);
+    this._resolvedScripts = signal([]);
+
+    // DOM patching (client only)
+    if (typeof document !== 'undefined') {
+      this._initDOMPatcher();
+    }
+  }
+
+  /**
+   * Register a head entry (called by useHead()).
+   * Returns a dispose function that removes the entry.
+   */
+  _register(entry) {
+    this._entries.push(entry);
+    this._recompute();
+
+    return () => {
+      const idx = this._entries.indexOf(entry);
+      if (idx !== -1) this._entries.splice(idx, 1);
+      this._recompute();
+    };
+  }
+
+  /** Merge all entries and update resolved signals */
+  _recompute() {
+    // Title: last entry with a title wins
+    let rawTitle = this._defaultTitle;
+    let metaMap  = new Map();   // key → { attrs }
+    let linkMap  = new Map();   // key → { attrs }
+    let scripts  = [];
+
+    for (const entry of this._entries) {
+      // ── title ──────────────────────────────────────────────────────────────
+      const t = _resolve(entry.title);
+      if (t != null && t !== '') rawTitle = String(t);
+
+      // ── description meta ───────────────────────────────────────────────────
+      const desc = _resolve(entry.description);
+      if (desc != null) {
+        metaMap.set('name:description', { name: 'description', content: desc });
+      }
+
+      // ── keywords ───────────────────────────────────────────────────────────
+      const kw = _resolve(entry.keywords);
+      if (kw != null) {
+        const kwStr = Array.isArray(kw) ? kw.join(', ') : String(kw);
+        metaMap.set('name:keywords', { name: 'keywords', content: kwStr });
+      }
+
+      // ── robots ─────────────────────────────────────────────────────────────
+      const robots = _resolve(entry.robots);
+      if (robots != null) {
+        metaMap.set('name:robots', { name: 'robots', content: robots });
+      }
+
+      // ── og: ────────────────────────────────────────────────────────────────
+      const og = entry.og ?? {};
+      for (const [k, v] of Object.entries(og)) {
+        const val = _resolve(v);
+        if (val != null) {
+          metaMap.set(`property:og:${k}`, { property: `og:${k}`, content: val });
+        }
+      }
+
+      // ── twitter: ───────────────────────────────────────────────────────────
+      const twitter = entry.twitter ?? {};
+      for (const [k, v] of Object.entries(twitter)) {
+        const val = _resolve(v);
+        if (val != null) {
+          metaMap.set(`name:twitter:${k}`, { name: `twitter:${k}`, content: val });
+        }
+      }
+
+      // ── arbitrary meta array ───────────────────────────────────────────────
+      for (const m of (entry.meta ?? [])) {
+        const key = m.name
+          ? `name:${m.name}`
+          : m.property
+            ? `property:${m.property}`
+            : m['http-equiv']
+              ? `http-equiv:${m['http-equiv']}`
+              : JSON.stringify(m);
+        const resolved = {};
+        for (const [mk, mv] of Object.entries(m)) resolved[mk] = _resolve(mv);
+        metaMap.set(key, resolved);
+      }
+
+      // ── link array ─────────────────────────────────────────────────────────
+      for (const l of (entry.link ?? [])) {
+        const resolved = {};
+        for (const [lk, lv] of Object.entries(l)) resolved[lk] = _resolve(lv);
+        const key = `${resolved.rel ?? ''}:${resolved.href ?? ''}`;
+        linkMap.set(key, resolved);
+      }
+
+      // ── script array ───────────────────────────────────────────────────────
+      for (const s of (entry.script ?? [])) {
+        const resolved = {};
+        for (const [sk, sv] of Object.entries(s)) resolved[sk] = _resolve(sv);
+        scripts.push(resolved);
+      }
+    }
+
+    // Apply title template
+    let finalTitle = rawTitle;
+    if (this._titleTemplate && rawTitle !== this._defaultTitle) {
+      finalTitle = this._titleTemplate.replace('%s', rawTitle);
+    }
+
+    batch(() => {
+      this._resolvedTitle.set(finalTitle);
+      this._resolvedMetas.set([...metaMap.values()]);
+      this._resolvedLinks.set([...linkMap.values()]);
+      this._resolvedScripts.set(scripts);
+    });
+  }
+
+  // ─── DOM patcher (client only) ──────────────────────────────────────────────
+
+  _initDOMPatcher() {
+    // Title
+    const disposeTitle = effect(() => {
+      const t = this._resolvedTitle.get();
+      if (document.title !== t) document.title = t;
+    });
+
+    // Meta
+    const disposeMeta = effect(() => {
+      const metas = this._resolvedMetas.get();
+      _patchMeta(metas);
+    });
+
+    // Link (canonical etc.)
+    const disposeLink = effect(() => {
+      const links = this._resolvedLinks.get();
+      _patchLinks(links);
+    });
+
+    this._disposes.push(disposeTitle, disposeMeta, disposeLink);
+  }
+
+  dispose() {
+    this._disposes.forEach(d => d());
+    this._disposes = [];
+    this._entries  = [];
+    if (_globalHead === this) _globalHead = null;
+  }
+}
+
+// ─── useHead ─────────────────────────────────────────────────────────────────
+
+/**
+ * Declare head tags from a component.
+ * Merges with any parent/sibling useHead() calls; later/deeper entries win.
+ *
+ * @param {object} entry
+ * @param {string|Function} [entry.title]
+ * @param {string|Function} [entry.description]
+ * @param {string|Function} [entry.keywords]     – string or string[]
+ * @param {string|Function} [entry.robots]
+ * @param {object}          [entry.og]           – Open Graph { title, description, image, type, url }
+ * @param {object}          [entry.twitter]      – Twitter Card { card, site, creator, ... }
+ * @param {Array}           [entry.meta]         – arbitrary <meta> objects
+ * @param {Array}           [entry.link]         – arbitrary <link> objects
+ * @param {Array}           [entry.script]       – arbitrary <script> objects
+ */
+export function useHead(entry = {}) {
+  const head = _globalHead;
+  if (!head) {
+    if (typeof console !== 'undefined') {
+      console.warn('[clarity/head] useHead() called before createHead(). Call createHead() in your app entry.');
+    }
+    return;
+  }
+
+  // Register the entry — recompute immediately so effects run synchronously
+  const dispose = head._register(entry);
+
+  // Hook into component lifecycle if available
+  if (typeof _onCleanup === 'function') {
+    _onCleanup(dispose);
+  }
+
+  return dispose;
+}
+
+// ─── SSR helpers ─────────────────────────────────────────────────────────────
+
+/**
+ * Serialize the current head state to HTML strings suitable for injection
+ * into the <head> of a server-rendered document.
+ *
+ * Returns:
+ *   {
+ *     title:   '<title>My Page | MyApp</title>',
+ *     metas:   '<meta name="description" content="…">\n...',
+ *     links:   '<link rel="canonical" href="…">\n...',
+ *     scripts: '<script type="application/ld+json">…</script>\n...',
+ *   }
+ *
+ * @param {HeadManager} [head]  – defaults to the global head
+ */
+export function renderHead(head = _globalHead) {
+  if (!head) return { title: '', metas: '', links: '', scripts: '' };
+
+  const title   = head._resolvedTitle.get();
+  const metas   = head._resolvedMetas.get();
+  const links   = head._resolvedLinks.get();
+  const scripts = head._resolvedScripts.get();
+
+  return {
+    title:   title   ? `<title>${_esc(title)}</title>`                          : '',
+    metas:   metas   .map(_renderMeta)  .filter(Boolean).join('\n'),
+    links:   links   .map(_renderLink)  .filter(Boolean).join('\n'),
+    scripts: scripts .map(_renderScript).filter(Boolean).join('\n'),
+  };
+}
+
+// ─── DOM helpers (client) ─────────────────────────────────────────────────────
+
+const _CLARITY_META_KEY  = 'data-clarity-head';
+
+function _patchMeta(metas) {
+  // Remove old managed metas
+  document.querySelectorAll(`meta[${_CLARITY_META_KEY}]`).forEach(el => el.remove());
+
+  for (const attrs of metas) {
+    const el = document.createElement('meta');
+    el.setAttribute(_CLARITY_META_KEY, '');
+    for (const [k, v] of Object.entries(attrs)) {
+      if (v != null) el.setAttribute(k, String(v));
+    }
+    document.head.appendChild(el);
+  }
+}
+
+function _patchLinks(links) {
+  // Only manage links we created; don't touch stylesheet links etc.
+  document.querySelectorAll(`link[${_CLARITY_META_KEY}]`).forEach(el => el.remove());
+
+  for (const attrs of links) {
+    const el = document.createElement('link');
+    el.setAttribute(_CLARITY_META_KEY, '');
+    for (const [k, v] of Object.entries(attrs)) {
+      if (v != null) el.setAttribute(k, String(v));
+    }
+    document.head.appendChild(el);
+  }
+}
+
+// ─── SSR serializers ─────────────────────────────────────────────────────────
+
+function _renderMeta(attrs) {
+  const parts = Object.entries(attrs)
+    .filter(([, v]) => v != null)
+    .map(([k, v]) => `${k}="${_esc(String(v))}"`)
+    .join(' ');
+  return parts ? `<meta ${parts}>` : '';
+}
+
+function _renderLink(attrs) {
+  const parts = Object.entries(attrs)
+    .filter(([, v]) => v != null)
+    .map(([k, v]) => `${k}="${_esc(String(v))}"`)
+    .join(' ');
+  return parts ? `<link ${parts}>` : '';
+}
+
+function _renderScript(attrs) {
+  const { children, ...rest } = attrs;
+  const parts = Object.entries(rest)
+    .filter(([, v]) => v != null)
+    .map(([k, v]) => `${k}="${_esc(String(v))}"`)
+    .join(' ');
+  const inner = children != null ? String(children) : '';
+  return `<script ${parts}>${inner}</script>`;
+}
+
+// ─── Utilities ────────────────────────────────────────────────────────────────
+
+/** Resolve a value or a getter function */
+function _resolve(v) {
+  return typeof v === 'function' ? v() : v;
+}
+
+/** HTML-escape for attribute values and title */
+function _esc(str) {
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/"/g, '&quot;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;');
+}
+
+// ─── Lifecycle hook ───────────────────────────────────────────────────────────
+// Injected by runtime.js to avoid circular dependencies.
+// runtime.js calls head._setLifecycleHook(onCleanup) during init.
+
+let _onCleanup = null;
+
+/**
+ * Called by the runtime to inject the onCleanup hook.
+ * This avoids a circular import between head.js and runtime.js.
+ * @internal
+ */
+export function _setHeadLifecycleHook(fn) {
+  _onCleanup = fn;
+}
+
+// ─── Named export alias ───────────────────────────────────────────────────────
+
+export { HeadManager };

package/src/hydrate.js

@@ -0,0 +1,292 @@
+/**
+ * Clarity.js — Client-Side Hydration
+ *
+ * hydrateRoot() attaches reactivity to server-rendered HTML without a
+ * visible content shift. The server serialises signal state into
+ * window.__CLARITY_DATA__; the client reads it back and re-mounts the
+ * component with the same initial values — so the rendered DOM is
+ * byte-for-byte identical to what the server produced.
+ *
+ * Usage (client entry point):
+ *
+ *   import { hydrateRoot }  from '@ozsarman/clarityjs/hydrate';
+ *   import { MyComponent }  from './MyComponent.js';
+ *
+ *   hydrateRoot(
+ *     document.getElementById('app'),
+ *     MyComponent,
+ *     { /* optional props *\/ }
+ *   );
+ *
+ * Server side (Node.js / Express):
+ *
+ *   import { renderToDocument } from '@ozsarman/clarityjs/ssr';
+ *   const html = renderToDocument(MyComponent, { props: { ... }, clientScript: '/app.js' });
+ *   res.send(html);
+ *
+ * Author: Claude (Anthropic) + Özdemir Sarman
+ */
+
+// ─── Hydration walker ─────────────────────────────────────────────────────────
+//
+// The walker traverses the server-rendered DOM in document order, matching
+// each createElement() call to the corresponding existing node.  When there
+// is a structural mismatch (e.g. server rendered a <div> but the component
+// now wants a <span>), the walker falls back to creating a fresh node and
+// logs a warning.
+//
+// Why this works with Clarity's h() function:
+//   h(tag, props, children) calls:
+//     1. document.createElement(tag)      ← we intercept → return existing node
+//     2. el.setAttribute / addEventListener ← applied to the EXISTING node ✓
+//     3. appendChild(el, child)            ← child is already in el; DOM spec
+//                                            moves it only if it isn't ✓
+// The existing node's children are cleared once claimed so that h() can
+// re-append them in the correct reactive order without duplication.
+
+class _HydrationWalker {
+  /**
+   * @param {Element} root  - The container element (e.g. #app)
+   */
+  constructor(root) {
+    // Each frame: { el: Element, kids: Element[], i: number }
+    this._stack = [this._frame(root)];
+    this._mismatches = 0;
+  }
+
+  _frame(el) {
+    // Element children only — skip text, comment, processing-instruction nodes
+    const kids = Array.from(el.childNodes).filter(n => n.nodeType === 1);
+    return { el, kids, i: 0 };
+  }
+
+  /**
+   * Attempt to claim the next element child with the given tag.
+   * Returns the existing DOM node on success, null on mismatch.
+   */
+  claimElement(tag) {
+    const frame = this._stack[this._stack.length - 1];
+    if (!frame) return null;
+
+    const existing = frame.kids[frame.i];
+    if (!existing) return null;
+
+    if (existing.tagName.toLowerCase() !== tag.toLowerCase()) {
+      this._mismatches++;
+      if (this._mismatches <= 5) {
+        console.warn(
+          `[Clarity hydrateRoot] DOM mismatch: expected <${tag}> ` +
+          `but found <${existing.tagName.toLowerCase()}>. ` +
+          `Falling back to fresh element.`
+        );
+      }
+      return null;
+    }
+
+    frame.i++;
+    // Save existing children, then clear the node so h() can re-append them
+    // via the reactive effects without duplication.
+    const savedChildren = Array.from(existing.childNodes);
+    existing.__clarity_saved_children__ = savedChildren;
+    existing.innerHTML = '';
+
+    // Push frame so nested createElement() calls target this element's children
+    this._stack.push(this._frame({ childNodes: savedChildren }));
+    return existing;
+  }
+
+  /**
+   * Pop the current frame — called after h() finishes populating an element.
+   * We hook this via a patched appendChild: when the element's last child is
+   * appended, we know h() is done with it.
+   */
+  popFrame() {
+    if (this._stack.length > 1) this._stack.pop();
+  }
+
+  get depth() { return this._stack.length; }
+  get mismatches() { return this._mismatches; }
+}
+
+// ─── hydrateRoot ─────────────────────────────────────────────────────────────
+
+/**
+ * Attach client-side reactivity to server-rendered HTML.
+ *
+ * This is the primary public API for SSR + hydration workflows.
+ *
+ * @param {Element}  container   - DOM element that wraps the server HTML (e.g. #app)
+ * @param {Function} ComponentFn - Compiled Clarity component function
+ * @param {object}   [props={}]  - Props to pass to the component
+ * @returns {{ unmount: () => void }} - Call unmount() to remove the component
+ */
+export function hydrateRoot(container, ComponentFn, props = {}) {
+  if (!container) {
+    throw new Error('[Clarity] hydrateRoot: container element not found');
+  }
+
+  // ── 1. Read server state ─────────────────────────────────────────────────────
+  const ssrData =
+    (typeof window !== 'undefined' && window.__CLARITY_DATA__)
+      ? window.__CLARITY_DATA__
+      : {};
+
+  // ── 2. Attempt DOM adoption ──────────────────────────────────────────────────
+  // We try to walk the existing server-rendered DOM and reuse nodes, only
+  // creating fresh ones on mismatch.  If the server HTML is absent (e.g.
+  // in a test environment), this gracefully degrades to a normal mount.
+
+  let unmount;
+
+  const hasServerHTML =
+    container.childNodes.length > 0 &&
+    container.innerHTML.trim() !== '';
+
+  if (hasServerHTML) {
+    unmount = _hydrateWithAdoption(container, ComponentFn, { ...props, __ssr: ssrData });
+  } else {
+    // No server HTML — fall through to a plain mount (dev server, test env)
+    unmount = _plainMount(container, ComponentFn, { ...props, __ssr: ssrData });
+  }
+
+  // ── 3. Mark as hydrated ──────────────────────────────────────────────────────
+  container.setAttribute('data-clarity-hydrated', 'true');
+
+  return { unmount };
+}
+
+// ─── DOM Adoption ─────────────────────────────────────────────────────────────
+
+function _hydrateWithAdoption(container, ComponentFn, props) {
+  const walker = new _HydrationWalker(container);
+
+  // Patch document.createElement to return existing nodes when possible
+  const _origCreateElement  = document.createElement.bind(document);
+  const _origCreateTextNode = document.createTextNode.bind(document);
+  const _origCreateComment  = document.createComment.bind(document);
+
+  // Track depth changes via element creation to know when to pop frames
+  let _depth = 0;
+
+  document.createElement = function _hydratingCreateElement(tag) {
+    const existing = walker.claimElement(tag);
+    if (existing) {
+      existing.__clarity_adopted__ = true;
+      return existing;
+    }
+    // Mismatch or exhausted — create fresh
+    return _origCreateElement(tag);
+  };
+
+  // Text nodes and comments are recreated fresh (they carry reactive content)
+  // but we avoid console noise for them.
+  document.createTextNode = _origCreateTextNode;
+  document.createComment  = _origCreateComment;
+
+  let rootEl;
+  try {
+    // Run the component — h() calls will use the patched createElement
+    rootEl = ComponentFn(props);
+  } catch (err) {
+    _restoreDocumentAPIs(document, _origCreateElement, _origCreateTextNode, _origCreateComment);
+    console.error('[Clarity] hydrateRoot: component threw during hydration', err);
+    // Fall back to plain mount
+    return _plainMount(container, ComponentFn, props);
+  }
+
+  _restoreDocumentAPIs(document, _origCreateElement, _origCreateTextNode, _origCreateComment);
+
+  if (walker.mismatches > 0) {
+    console.warn(
+      `[Clarity] hydrateRoot: ${walker.mismatches} DOM mismatch(es) detected. ` +
+      `Check that server and client render the same component with the same props.`
+    );
+  }
+
+  // Wire up the root node
+  if (_isNodeLike(rootEl)) {
+    // If adoption succeeded, the root node may already be in the container.
+    // If not (fresh element on root mismatch), append it.
+    if (!container.contains?.(rootEl)) {
+      container.innerHTML = '';
+      container.appendChild(rootEl);
+    }
+
+    if (typeof rootEl.__clarity_mount__ === 'function') {
+      rootEl.__clarity_mount__();
+    }
+
+    // Register in AI discovery registry (same pattern as runtime mount())
+    if (rootEl.__clarity_ai__) {
+      try {
+        // Dynamic import avoids circular dependency; aiRegistry lives in runtime
+        import('./runtime.js').then(rt => {
+          if (typeof rt._aiRegistryAdd === 'function') rt._aiRegistryAdd(rootEl);
+        }).catch(() => {});
+      } catch {}
+    }
+  }
+
+  return function unmount() {
+    if (rootEl && typeof rootEl.__clarity_cleanup__ === 'function') {
+      rootEl.__clarity_cleanup__();
+    }
+    if (rootEl && rootEl.parentNode) {
+      rootEl.parentNode.removeChild(rootEl);
+    }
+    container.removeAttribute('data-clarity-hydrated');
+  };
+}
+
+function _restoreDocumentAPIs(doc, createElement, createTextNode, createComment) {
+  doc.createElement  = createElement;
+  doc.createTextNode = createTextNode;
+  doc.createComment  = createComment;
+}
+
+// ─── Plain mount (fallback) ───────────────────────────────────────────────────
+
+function _plainMount(container, ComponentFn, props) {
+  container.innerHTML = '';
+  const el = ComponentFn(props);
+
+  if (_isNodeLike(el)) {
+    container.appendChild(el);
+    if (typeof el.__clarity_mount__ === 'function') el.__clarity_mount__();
+  }
+
+  return function unmount() {
+    if (el && typeof el.__clarity_cleanup__ === 'function') el.__clarity_cleanup__();
+    if (el && el.parentNode) el.parentNode.removeChild(el);
+    container.removeAttribute('data-clarity-hydrated');
+  };
+}
+
+// ─── Duck-typing helper (avoids `instanceof Node` which is browser-only) ─────
+function _isNodeLike(val) {
+  return val !== null && typeof val === 'object' && typeof val.nodeType === 'number';
+}
+
+// ─── Helpers ──────────────────────────────────────────────────────────────────
+
+/**
+ * isHydrated — check if a container has been hydrated by Clarity.
+ *
+ * @param {Element} container
+ * @returns {boolean}
+ */
+export function isHydrated(container) {
+  return container?.getAttribute('data-clarity-hydrated') === 'true';
+}
+
+/**
+ * getSSRData — read the server-serialised state object.
+ * Returns an empty object if not available (e.g. no SSR).
+ *
+ * @returns {Record<string, unknown>}
+ */
+export function getSSRData() {
+  return (typeof window !== 'undefined' && window.__CLARITY_DATA__)
+    ? window.__CLARITY_DATA__
+    : {};
+}