@webjsdev/ui 0.3.7 → 0.3.8

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/ui",
-  "version": "0.3.7",
+  "version": "0.3.8",
   "type": "module",
   "description": "An AI-first component library - class-helper functions for visuals, custom elements only where state matters. Source-copied into your repo, you own it. Works with any Tailwind v4 project.",
   "bin": {

package/packages/registry/components/alert-dialog.ts

@@ -65,7 +65,8 @@
  */
 import { WebComponent, html, prop } from '@webjsdev/core';
 import { ref, createRef } from '@webjsdev/core/directives';
-import { ensureId, onBeforeCache } from '../lib/utils.ts';
+import { ensureId } from '../lib/utils.ts';
+import { onBeforeCache } from '../lib/dom.ts';
 import { buttonClass, type ButtonVariant, type ButtonSize } from './button.ts';
 
 export const alertDialogContentClass = (): string =>

package/packages/registry/components/dialog.ts

@@ -65,7 +65,8 @@
  */
 import { WebComponent, html, unsafeHTML, prop } from '@webjsdev/core';
 import { ref, createRef } from '@webjsdev/core/directives';
-import { ensureId, onBeforeCache } from '../lib/utils.ts';
+import { ensureId } from '../lib/utils.ts';
+import { onBeforeCache } from '../lib/dom.ts';
 import { buttonClass } from './button.ts';
 
 // Wires a dialog panel's accessible name + description to its title /

package/packages/registry/components/dropdown-menu.ts

@@ -78,7 +78,8 @@
  * --accent-foreground, --destructive, --muted-foreground, --border.
  */
 import { WebComponent, html, unsafeHTML, signal, prop } from '@webjsdev/core';
-import { ensureId, onBeforeCache } from '../lib/utils.ts';
+import { ensureId } from '../lib/utils.ts';
+import { onBeforeCache } from '../lib/dom.ts';
 import { positionFloating, type PopoverSide, type PopoverAlign } from './popover.ts';
 
 // --------------------------------------------------------------------------

package/packages/registry/components/hover-card.ts

@@ -39,7 +39,8 @@
  * Design tokens used: --popover, --popover-foreground, --border.
  */
 import { WebComponent, html, prop } from '@webjsdev/core';
-import { ensureId, onBeforeCache } from '../lib/utils.ts';
+import { ensureId } from '../lib/utils.ts';
+import { onBeforeCache } from '../lib/dom.ts';
 import { positionFloating, type PopoverSide, type PopoverAlign } from './popover.ts';
 
 // `fixed m-0` opts out of the UA `[popover]` auto-centering margin so

package/packages/registry/components/sonner.ts

@@ -44,7 +44,7 @@
  * Design tokens used: --popover, --popover-foreground, --border, --radius.
  */
 import { WebComponent, html, repeat, unsafeHTML, signal, prop } from '@webjsdev/core';
-import { onBeforeCache } from '../lib/utils.ts';
+import { onBeforeCache } from '../lib/dom.ts';
 
 type ToastType = 'default' | 'success' | 'error' | 'info' | 'warning' | 'loading';
 

package/packages/registry/components/tooltip.ts

@@ -41,7 +41,8 @@
  * Design tokens used: --foreground, --background.
  */
 import { WebComponent, html, prop } from '@webjsdev/core';
-import { ensureId, onBeforeCache } from '../lib/utils.ts';
+import { ensureId } from '../lib/utils.ts';
+import { onBeforeCache } from '../lib/dom.ts';
 import { positionFloating, type PopoverSide, type PopoverAlign } from './popover.ts';
 
 // UA `[popover]` defaults paint a bordered, padded panel centered with

package/packages/registry/lib/dom.ts

@@ -0,0 +1,18 @@
+// Client-only DOM helpers. Kept SEPARATE from lib/utils.ts because these
+// reference `document`: any module that references a client global is treated
+// as client-effecting by the elision analyzer, so bundling this with the pure
+// `cn()` would pin every page that imports `cn` to the browser (#819). Import
+// these ONLY from components (which ship anyway), never from a page/layout.
+
+/**
+ * Run `reset` just before the webjs client router snapshots the page into its
+ * back/forward cache (the `webjs:before-cache` event). Transient overlays use
+ * this to close themselves so a restored snapshot is clean. SSR-safe (a no-op
+ * when there is no `document`). Wire it in `connectedCallback` and call the
+ * returned disposer in `disconnectedCallback` so it never leaks across navs.
+ */
+export function onBeforeCache(reset: () => void): () => void {
+  if (typeof document === 'undefined') return () => {};
+  document.addEventListener('webjs:before-cache', reset);
+  return () => document.removeEventListener('webjs:before-cache', reset);
+}

package/packages/registry/lib/utils.ts

@@ -127,95 +127,12 @@ export function ensureId(el: { id: string }, prefix = 'ui'): string {
   return el.id;
 }
 
-// ---------------------------------------------------------------------------
-// Custom-element base: SSR-safe. In the browser `Base = HTMLElement`. On
-// the server (Node, during SSR) `HTMLElement` is undefined; we substitute
-// a stub class so that `class Foo extends Base { … }` doesn't throw at
-// module-load time. The stub's methods are never actually called server-side
-// because connectedCallback/lifecycle hooks only run when the element is
-// inserted into a live DOM, which doesn't happen during webjs SSR.
-// ---------------------------------------------------------------------------
-
-const HasHTMLElement = typeof HTMLElement !== 'undefined';
-
-class ServerHTMLElementStub {
-  // Minimal surface so attribute reads/writes inside synchronous code paths
-  // that DO execute during SSR (e.g. attribute reflection) don't throw.
-  _ssrAttrs: Record<string, string> = {};
-  getAttribute(name: string): string | null {
-    return this._ssrAttrs[name] ?? null;
-  }
-  setAttribute(name: string, value: string): void {
-    this._ssrAttrs[name] = String(value);
-  }
-  hasAttribute(name: string): boolean {
-    return name in this._ssrAttrs;
-  }
-  removeAttribute(name: string): void {
-    delete this._ssrAttrs[name];
-  }
-  toggleAttribute(name: string, force?: boolean): boolean {
-    const want = force === undefined ? !this.hasAttribute(name) : force;
-    if (want) this.setAttribute(name, '');
-    else this.removeAttribute(name);
-    return want;
-  }
-  addEventListener(): void {}
-  removeEventListener(): void {}
-  dispatchEvent(): boolean {
-    return true;
-  }
-  // Tree-walk APIs no-op into null: components that call them server-side
-  // simply see "no children / no siblings", which is acceptable for SSR.
-  closest(): null {
-    return null;
-  }
-  querySelector(): null {
-    return null;
-  }
-  querySelectorAll(): never[] {
-    return [];
-  }
-  focus(): void {}
-  blur(): void {}
-  contains(): boolean {
-    return false;
-  }
-  insertBefore<T>(node: T): T {
-    return node;
-  }
-  appendChild<T>(node: T): T {
-    return node;
-  }
-  replaceChildren(): void {}
-  get firstChild(): null {
-    return null;
-  }
-  get classList() {
-    return { add: () => {}, remove: () => {}, toggle: () => false, contains: () => false };
-  }
-  get className(): string {
-    return this._ssrAttrs.class ?? '';
-  }
-  set className(v: string) {
-    this._ssrAttrs.class = v;
-  }
-  get style(): Record<string, string> {
-    return {};
-  }
-}
-
-/** SSR-safe base class: `HTMLElement` in browser, a thin stub in Node. */
-export const Base: typeof HTMLElement = (HasHTMLElement
-  ? HTMLElement
-  : (ServerHTMLElementStub as unknown as typeof HTMLElement)) as typeof HTMLElement;
-
-/** Register a custom element. No-op on server (no `customElements` global). */
-export function defineElement(name: string, cls: CustomElementConstructor): void {
-  if (typeof customElements === 'undefined') return;
-  if (customElements.get(name)) return; // already defined (HMR / double-import)
-  customElements.define(name, cls);
-}
+// NOTE: the old `HTMLElement`-era `Base` / `defineElement` / SSR-stub helpers
+// were removed. The ui registry components extend `WebComponent` from
+// `@webjsdev/core` now, so those helpers were dead code, and referencing
+// `HTMLElement` / `customElements` at module scope marked this util (and any
+// page that imports `cn`) as client-effecting. Everything below is pure or
+// SSR-safe, so importing `cn` no longer pins a page to the browser (#819).
 
 // ---------------------------------------------------------------------------
 // Layout helpers: encode the design-system rhythm (spacing between label /
@@ -266,19 +183,3 @@ export const helpClass = () => 'text-xs text-muted-foreground';
 
 /** Validation error text: replaces hint when the field is invalid. */
 export const errorClass = () => 'text-sm font-medium text-destructive';
-
-/**
- * Run `reset` just before the webjs client router snapshots the page into its
- * back/forward cache (the `webjs:before-cache` event). Transient overlays use
- * this to close themselves so a restored snapshot is clean rather than, say, a
- * hover-card frozen open after Back then Forward (#766). Wire it in
- * `connectedCallback` and call the returned disposer in `disconnectedCallback`
- * so the listener never leaks across soft navigations.
- *
- * SSR-safe: a no-op when there is no `document` (server / no client router).
- */
-export function onBeforeCache(reset: () => void): () => void {
-  if (typeof document === 'undefined') return () => {};
-  document.addEventListener('webjs:before-cache', reset);
-  return () => document.removeEventListener('webjs:before-cache', reset);
-}

package/packages/registry/registry.json

@@ -15,6 +15,18 @@
         }
       ]
     },
+    {
+      "name": "lib-dom",
+      "type": "registry:lib",
+      "description": "onBeforeCache() client-router cache hook",
+      "files": [
+        {
+          "path": "lib/dom.ts",
+          "type": "registry:lib",
+          "target": "lib/dom.ts"
+        }
+      ]
+    },
     {
       "name": "theme-neutral",
       "type": "registry:theme",
@@ -59,7 +71,8 @@
       "type": "registry:ui",
       "registryDependencies": [
         "button",
-        "dialog"
+        "dialog",
+        "lib-dom"
       ],
       "dependencies": [
         "@webjsdev/core"
@@ -189,7 +202,8 @@
       "type": "registry:ui",
       "registryDependencies": [
         "lib-utils",
-        "button"
+        "button",
+        "lib-dom"
       ],
       "dependencies": [
         "@webjsdev/core"
@@ -205,7 +219,8 @@
       "name": "dropdown-menu",
       "type": "registry:ui",
       "registryDependencies": [
-        "popover"
+        "popover",
+        "lib-dom"
       ],
       "dependencies": [
         "@webjsdev/core"
@@ -221,7 +236,8 @@
       "name": "hover-card",
       "type": "registry:ui",
       "registryDependencies": [
-        "popover"
+        "popover",
+        "lib-dom"
       ],
       "dependencies": [
         "@webjsdev/core"
@@ -381,6 +397,9 @@
     {
       "name": "sonner",
       "type": "registry:ui",
+      "registryDependencies": [
+        "lib-dom"
+      ],
       "dependencies": [
         "@webjsdev/core"
       ],
@@ -476,7 +495,8 @@
       "name": "tooltip",
       "type": "registry:ui",
       "registryDependencies": [
-        "popover"
+        "popover",
+        "lib-dom"
       ],
       "dependencies": [
         "@webjsdev/core"

package/src/commands/add.js

@@ -76,31 +76,51 @@ async function writeRegistryFile(cwd, config, item, file, opts) {
 }
 
 /**
- * Rewrite the registry-relative `'../lib/utils.ts'` import to the path
- * that resolves correctly from the file's target location to the user's
- * cn() helper.
+ * Rewrite the registry-relative `'../lib/utils.ts'` and `'../lib/dom.ts'`
+ * imports to the paths that resolve correctly from the file's target
+ * location to the user's cn() helper and onBeforeCache() DOM helper.
  *
  * The registry source assumes its own layout (`<registry>/components/<x>.ts`
- * imports `'../lib/utils.ts'`). When that file lands in the user's
- * components/ui/<x>.ts, the literal `'../lib/utils.ts'` resolves to
- * `components/lib/utils.ts`, which doesn't exist. We compute the actual
- * relative path from the target directory to `config.resolvedPaths.utils`
- * (an absolute path the user has already configured via components.json's
- * aliases.utils) and substitute it in.
+ * imports `'../lib/utils.ts'` / `'../lib/dom.ts'`). When that file lands in
+ * the user's components/ui/<x>.ts, the literal `'../lib/utils.ts'` resolves
+ * to `components/lib/utils.ts`, which doesn't exist. We compute the actual
+ * relative path from the target directory to the user's configured helper
+ * (`config.resolvedPaths.utils`, from components.json's aliases.utils) and
+ * substitute it in. The DOM helper is written as a SIBLING of the utils
+ * file (the scaffold puts it at `lib/utils/dom.ts`, next to `cn.ts`), so its
+ * absolute target is `dom.ts` in the utils file's directory. sonner imports
+ * ONLY the DOM helper, so both specifiers are handled independently and
+ * neither presence gates the other.
  *
  * @param {string} content raw file content from the registry
  * @param {string} target absolute path where the file will be written
  * @param {{ resolvedPaths: { utils: string } }} config parsed components.json
  */
 export function rewriteUtilsImport(content, target, config) {
-  if (!content.includes('../lib/utils.ts')) return content;
   const utilsAbs = config?.resolvedPaths?.utils;
   if (!utilsAbs) return content;
-  let rel = relPath(dirname(target), utilsAbs).split(/[\\/]/).join('/');
+  let out = replaceImportSpecifier(content, '../lib/utils.ts', utilsAbs, target);
+  const domAbs = join(dirname(utilsAbs), 'dom.ts');
+  out = replaceImportSpecifier(out, '../lib/dom.ts', domAbs, target);
+  return out;
+}
+
+/**
+ * Replace a single registry-relative import specifier with the relative path
+ * from `target`'s directory to `destAbs`. No-op when `spec` is absent.
+ *
+ * @param {string} content
+ * @param {string} spec the registry-relative specifier to replace
+ * @param {string} destAbs absolute path of the destination file
+ * @param {string} target absolute path where the importing file is written
+ */
+function replaceImportSpecifier(content, spec, destAbs, target) {
+  if (!content.includes(spec)) return content;
+  let rel = relPath(dirname(target), destAbs).split(/[\\/]/).join('/');
   if (!rel.startsWith('.')) rel = './' + rel;
   return content
-    .replaceAll("'../lib/utils.ts'", `'${rel}'`)
-    .replaceAll('"../lib/utils.ts"', `"${rel}"`);
+    .replaceAll(`'${spec}'`, `'${rel}'`)
+    .replaceAll(`"${spec}"`, `"${rel}"`);
 }
 
 function resolveTarget(cwd, config, item, file) {

package/src/commands/init.js

@@ -75,21 +75,45 @@ export const init = new Command()
   });
 
 async function writeLibUtils(cwd, utilsAlias, registryUrl) {
+  // `utils` alias points at e.g. "lib/utils" so we write to lib/utils.ts
+  const utilsRel = utilsAlias.replace(/^@\//, '') + '.ts';
+  const utilsTarget = join(cwd, utilsRel);
   try {
     const item = await fetchRegistryItem('lib-utils', registryUrl);
+    if (item.files) {
+      for (const f of item.files) {
+        ensureDir(dirname(utilsTarget));
+        writeFileSync(utilsTarget, f.content || '', 'utf8');
+        logger.success(`Wrote ${utilsAlias}.ts`);
+      }
+    }
+  } catch (e) {
+    logger.warn(`Could not fetch lib-utils from registry (${e.message}). You may need to write lib/utils.ts manually.`);
+  }
+
+  // The onBeforeCache() DOM helper lives in a SEPARATE module (#819) because
+  // it references `document`, so keeping it out of cn()'s file prevents the
+  // elision analyzer pinning every page that imports cn to the browser.
+  // Overlay components import it from `../lib/dom.ts`, so write it as a
+  // sibling of the utils file (e.g. lib/utils/dom.ts next to cn.ts).
+  const domTarget = join(dirname(utilsTarget), 'dom.ts');
+  try {
+    const item = await fetchRegistryItem('lib-dom', registryUrl);
     if (!item.files) return;
     for (const f of item.files) {
-      // `utils` alias points at e.g. "lib/utils" → we write to lib/utils.ts
-      const target = join(cwd, utilsAlias.replace(/^@\//, '') + '.ts');
-      ensureDir(dirname(target));
-      writeFileSync(target, f.content || '', 'utf8');
-      logger.success(`Wrote ${utilsAlias}.ts`);
+      ensureDir(dirname(domTarget));
+      writeFileSync(domTarget, f.content || '', 'utf8');
+      logger.success(`Wrote ${relative(cwd, domTarget)}`);
     }
   } catch (e) {
-    logger.warn(`Could not fetch lib-utils from registry (${e.message}). You may need to write lib/utils.ts manually.`);
+    logger.warn(`Could not fetch lib-dom from registry (${e.message}). You may need to write lib/dom.ts manually.`);
   }
 }
 
+function relative(cwd, p) {
+  return p.startsWith(cwd) ? p.slice(cwd.length + 1) : p;
+}
+
 async function writeTheme(cwd, baseColor, cssPath, registryUrl) {
   try {
     const item = await fetchRegistryItem(`theme-${baseColor}`, registryUrl);

package/src/utils/detect-project.js

@@ -34,7 +34,9 @@ export function defaultsForProject(cwd = process.cwd()) {
   switch (type) {
     case 'webjs':
       return {
-        tailwindCss: 'app/globals.css',
+        // styles/globals.css, NOT app/globals.css: in webjs, app/ is routing-only,
+        // so a non-routing stylesheet lives outside it.
+        tailwindCss: 'styles/globals.css',
         aliases: { components: 'components', utils: 'lib/utils', ui: 'components/ui', lib: 'lib' },
       };
     case 'next':