@adia-ai/web-components 0.8.4 → 0.8.5

package/core/element.js

@@ -64,6 +64,26 @@ function installProps(el, props) {
   }
 }
 
+// A minimal no-op ElementInternals shim for environments with no real
+// implementation (linkedom and other DOM-shim SSR passes — gh#285). Real
+// form-participation/validation behavior is meaningless server-side (no
+// live user interaction to validate); the shim exists so the ~12
+// call sites across the framework that read `this.internals.setValidity(…)`
+// / `.setFormValue(…)` / `.validity` etc. keep working as inert no-ops
+// instead of throwing on a missing method. Surface matches exactly what
+// the framework's own consumers call (grepped, not guessed).
+const NOOP_INTERNALS = Object.freeze({
+  setFormValue() {},
+  setValidity() {},
+  checkValidity() { return true; },
+  reportValidity() { return true; },
+  get form() { return null; },
+  get labels() { return []; },
+  get validity() { return {}; },
+  get validationMessage() { return ''; },
+  get willValidate() { return false; },
+});
+
 function reflect(el, a, v, t) {
   t === Boolean
     ? v ? el.setAttribute(a, '') : el.removeAttribute(a)
@@ -78,6 +98,11 @@ function adoptStyles(ctor) {
   ctor._sa = true;
   const sheets = ctor.styles;
   if (!sheets) return;
+  // gh#285 — linkedom's document has no adoptedStyleSheets at all; SSR
+  // has no rendered stylesheet to adopt into anyway (styles matter for
+  // paint, which doesn't happen server-side), so skipping is a correct
+  // no-op, not a degraded feature.
+  if (!('adoptedStyleSheets' in document)) return;
   const list = Array.isArray(sheets) ? sheets : [sheets];
   document.adoptedStyleSheets = [...document.adoptedStyleSheets, ...list.filter(s => !document.adoptedStyleSheets.includes(s))];
 }
@@ -114,7 +139,17 @@ export class UIElement extends HTMLElement {
 
   constructor() {
     super();
-    this.internals = this.attachInternals();
+    // gh#285 — linkedom (and other DOM-shim SSR passes) implement no
+    // ElementInternals; an unconditional attachInternals() call threw
+    // HERE, before ANY subclass code ran — the single highest-leverage
+    // crash site in the whole framework under SSR. Feature-detect and
+    // fall back to a no-op shim (form participation is meaningless
+    // server-side) rather than leaving `this.internals` undefined,
+    // which would just move the crash to every consumer's first
+    // `.setValidity(…)` call instead of fixing it.
+    this.internals = typeof this.attachInternals === 'function'
+      ? this.attachInternals()
+      : NOOP_INTERNALS;
     installProps(this, this.constructor.properties);
   }
 

package/core/element.test.js

@@ -249,3 +249,70 @@ describe('UIElement — addTrait', () => {
     expect(disconnects).toBe(1);
   });
 });
+
+// gh#285 — SSR DOM shims (linkedom et al.) implement no ElementInternals
+// and no document.adoptedStyleSheets. These tests simulate that absence
+// directly (deleting the real APIs) rather than trusting a mock — the
+// bug was an unconditional call crashing the CONSTRUCTOR, before any
+// subclass code ran, so the only real proof is exercising construction
+// with the API genuinely gone.
+describe('UIElement — SSR browser-API absence (gh#285)', () => {
+  beforeEach(() => { document.body.innerHTML = ''; });
+
+  it('constructs without throwing when attachInternals does not exist', () => {
+    const original = HTMLElement.prototype.attachInternals;
+    delete HTMLElement.prototype.attachInternals;
+    try {
+      class El extends UIElement {}
+      const tag = registerTestElement(El);
+      expect(() => mount(tag)).not.toThrow();
+    } finally {
+      HTMLElement.prototype.attachInternals = original;
+    }
+  });
+
+  it('the no-op internals shim answers every call site the framework actually makes', () => {
+    const original = HTMLElement.prototype.attachInternals;
+    delete HTMLElement.prototype.attachInternals;
+    let el;
+    try {
+      class El extends UIElement {}
+      const tag = registerTestElement(El);
+      el = mount(tag);
+    } finally {
+      HTMLElement.prototype.attachInternals = original;
+    }
+    expect(() => el.internals.setFormValue('x')).not.toThrow();
+    expect(() => el.internals.setValidity({})).not.toThrow();
+    expect(el.internals.checkValidity()).toBe(true);
+    expect(el.internals.reportValidity()).toBe(true);
+    expect(el.internals.form).toBeNull();
+    expect(el.internals.labels).toEqual([]);
+    expect(el.internals.validity).toEqual({});
+    expect(el.internals.validationMessage).toBe('');
+    expect(el.internals.willValidate).toBe(false);
+  });
+
+  it('a real attachInternals is still used when the browser provides one (no regression)', () => {
+    class El extends UIElement {}
+    const tag = registerTestElement(El);
+    const el = mount(tag);
+    // happy-dom's real attachInternals — not the shim.
+    expect(el.internals).not.toBe(null);
+    expect(typeof el.internals.setFormValue).toBe('function');
+  });
+
+  it('adoptStyles no-ops instead of throwing when adoptedStyleSheets does not exist', () => {
+    const desc = Object.getOwnPropertyDescriptor(Document.prototype, 'adoptedStyleSheets');
+    delete Document.prototype.adoptedStyleSheets;
+    try {
+      class El extends UIElement {
+        static styles = ['/* fake sheet */'];
+      }
+      const tag = registerTestElement(El);
+      expect(() => mount(tag)).not.toThrow();
+    } finally {
+      if (desc) Object.defineProperty(Document.prototype, 'adoptedStyleSheets', desc);
+    }
+  });
+});

package/core/icons-phosphor.js

@@ -31,13 +31,66 @@
  *   import { installIconLoaders } from '@adia-ai/web-components/core/icons';
  *   installIconLoaders({
  *     regular: import.meta.glob(
- *       '/node_modules/@phosphor-icons/core/assets/regular/{caret-right,moon,sun,x}.svg',
+ *       '../node_modules/@phosphor-icons/core/assets/regular/{caret-right,moon,sun,x}.svg',
  *       { query: '?raw', import: 'default', eager: true }
  *     ),
  *   });
  *
  * Brace-list globs are statically analyzed; only the named files are
- * emitted as chunks (or inlined when `eager: true`).
+ * emitted as chunks (or inlined when `eager: true`). Use the `../node_modules/...`
+ * form shown here, not `/node_modules/...` — see "Why the glob is entry-relative,
+ * not root-relative" below; the same reasoning applies to a hand-written
+ * scoped glob as to the auto-discovery globs this file installs by default.
+ *
+ * ## Why the glob is entry-relative, not root-relative
+ *
+ * `import.meta.glob` only accepts a small set of static forms (`/`-rooted,
+ * `./`, `../`, `**\/`, or a `#`-subpath with a literal `*`), and each resolves
+ * via a literal path join, not module resolution (confirmed against Vite 8's
+ * `toAbsoluteGlob`, gh#287). A `/`-rooted glob joins to Vite's CONFIGURED
+ * PROJECT ROOT — for a consumer app, that only reaches `@phosphor-icons/core`
+ * when it's ALSO hoisted to that exact root. Under pnpm's default
+ * (non-hoisted, symlinked) linking, a package you depend on only
+ * TRANSITIVELY — `@phosphor-icons/core` is a dependency of THIS package, not
+ * necessarily your app's — is linked only inside that package's own
+ * resolution scope, never flattened into your app's top-level `node_modules`.
+ * A root-rooted glob then silently matches zero files.
+ *
+ * A `../`-prefixed glob instead joins to THIS FILE'S OWN directory
+ * (`core/`), one level inside `@adia-ai/web-components` — so `../node_modules`
+ * reaches `@adia-ai/web-components`'s own local `node_modules`, which pnpm
+ * always populates with a package's own direct dependencies (a symlink into
+ * the pnpm store) regardless of whether your app also hoists them. This
+ * holds for the published package too — `core/icons-phosphor.js` ships at
+ * the same one-level depth (see `package.json`'s `files` field). Verified
+ * empirically against a real hoisting-gap install (a pnpm workspace where
+ * `@phosphor-icons/core` is declared only by a nested package, not the
+ * workspace root): the root-rooted form matches zero files; the
+ * entry-relative form matches the full set with real content.
+ *
+ * ## Vite dep-optimizer pre-bundling (gh#287, second independent failure mode)
+ *
+ * In DEV, Vite pre-bundles bare-specifier dependencies with esbuild
+ * (`optimizeDeps`) for faster cold starts, BEFORE its own plugin pipeline
+ * (which includes the glob transform) ever sees them. Confirmed empirically:
+ * when this package gets swept into that pre-bundling step, esbuild's scan
+ * transforms each `import.meta.glob(...)` call into a literal `Object.assign({})`
+ * — no exception, `hasViteGlob` stays `true`, but every weight's map is empty.
+ * This is indistinguishable from a genuine zero-match glob to the code below,
+ * so the same `totalIcons === 0` diagnostic fires — the fix differs, though:
+ * add this package to your Vite config's `optimizeDeps.exclude` so it's
+ * requested directly instead of pre-bundled (confirmed empirically to restore
+ * full auto-discovery with no code change):
+ *
+ *   // vite.config.js
+ *   export default defineConfig({
+ *     optimizeDeps: { exclude: ['@adia-ai/web-components', '@adia-ai/web-modules'] },
+ *   });
+ *
+ * If you can't control the Vite config (e.g. Astro, or another framework
+ * that manages it), fall back to the scoped, explicit-import recipe above —
+ * plain bare-specifier imports in your OWN first-party source are never
+ * swept into `optimizeDeps` in the first place.
  *
  * ## Vite glob detection
  *
@@ -57,12 +110,12 @@ let weightModules;
 let hasViteGlob = false;
 try {
   weightModules = {
-    regular: import.meta.glob('/node_modules/@phosphor-icons/core/assets/regular/*.svg', { query: '?raw', import: 'default' }),
-    thin:    import.meta.glob('/node_modules/@phosphor-icons/core/assets/thin/*.svg',    { query: '?raw', import: 'default' }),
-    light:   import.meta.glob('/node_modules/@phosphor-icons/core/assets/light/*.svg',   { query: '?raw', import: 'default' }),
-    bold:    import.meta.glob('/node_modules/@phosphor-icons/core/assets/bold/*.svg',    { query: '?raw', import: 'default' }),
-    fill:    import.meta.glob('/node_modules/@phosphor-icons/core/assets/fill/*.svg',    { query: '?raw', import: 'default' }),
-    duotone: import.meta.glob('/node_modules/@phosphor-icons/core/assets/duotone/*.svg', { query: '?raw', import: 'default' }),
+    regular: import.meta.glob('../node_modules/@phosphor-icons/core/assets/regular/*.svg', { query: '?raw', import: 'default' }),
+    thin:    import.meta.glob('../node_modules/@phosphor-icons/core/assets/thin/*.svg',    { query: '?raw', import: 'default' }),
+    light:   import.meta.glob('../node_modules/@phosphor-icons/core/assets/light/*.svg',   { query: '?raw', import: 'default' }),
+    bold:    import.meta.glob('../node_modules/@phosphor-icons/core/assets/bold/*.svg',    { query: '?raw', import: 'default' }),
+    fill:    import.meta.glob('../node_modules/@phosphor-icons/core/assets/fill/*.svg',    { query: '?raw', import: 'default' }),
+    duotone: import.meta.glob('../node_modules/@phosphor-icons/core/assets/duotone/*.svg', { query: '?raw', import: 'default' }),
   };
   hasViteGlob = true;
 } catch (err) {
@@ -85,28 +138,39 @@ if (hasViteGlob) {
   // FB-08: detect the silent-empty-glob case — `import.meta.glob` returns
   // `{}` when zero files match (it does NOT throw). The previous behavior
   // installed empty per-weight maps and the consumer saw an empty icon
-  // registry with no diagnostic. This happens when the consumer's Vite
-  // root sits below `node_modules`, or with pnpm/yarn-berry virtual paths,
-  // or when this file runs from inside a published package directory
-  // (its absolute-style glob is resolved relative to the Vite root, not
-  // this file's directory).
+  // registry with no diagnostic. gh#287 names two independent causes, both
+  // producing this same empty-map symptom:
+  //   1. A packaging/bundler step re-nested this file at a different depth
+  //      than it ships at (breaks the `../`-relative glob's one-level-inside
+  //      assumption — see "Why the glob is entry-relative" above), a Yarn
+  //      Berry PnP install (virtual/zip filesystem), or @phosphor-icons/core
+  //      missing entirely.
+  //   2. Vite's dev-server `optimizeDeps` pre-bundled this package (see
+  //      "Vite dep-optimizer pre-bundling" above) — confirmed empirically to
+  //      transform the glob into a literal empty object, no exception.
   const totalIcons = Object.values(weightModules).reduce(
     (sum, weight) => sum + Object.keys(weight).length, 0
   );
   if (totalIcons === 0) {
     console.warn(
       `[icons-phosphor] No Phosphor icons matched the auto-install glob ` +
-      `\`/node_modules/@phosphor-icons/core/assets/<weight>/*.svg\`. ` +
-      `This usually means your Vite root sits below node_modules, you use ` +
-      `pnpm/yarn-berry virtual paths, or this module is loaded from a ` +
-      `published package directory. Install loaders manually from your app entry:\n` +
+      `\`../node_modules/@phosphor-icons/core/assets/<weight>/*.svg\` (resolved ` +
+      `relative to this file's own directory — hoisting-safe under pnpm, gh#287). ` +
+      `Two known causes: (1) this package got pre-bundled by Vite's dev-server ` +
+      `optimizeDeps, which empties the glob — add it to optimizeDeps.exclude in ` +
+      `your Vite config:\n` +
+      `  optimizeDeps: { exclude: ['@adia-ai/web-components', '@adia-ai/web-modules'] }\n` +
+      `(2) @phosphor-icons/core is missing, or this file was re-nested to a ` +
+      `different depth by a packaging step (Yarn PnP, a custom bundler). If ` +
+      `neither fix applies, install loaders manually instead:\n` +
       `  import { installIconLoaders } from '@adia-ai/web-components/core/icons';\n` +
+      `  import caretRight from '@phosphor-icons/core/assets/regular/caret-right.svg?raw';\n` +
       `  installIconLoaders({\n` +
-      `    regular: import.meta.glob(\n` +
-      `      '../node_modules/@phosphor-icons/core/assets/regular/*.svg',\n` +
-      `      { query: '?raw', import: 'default', eager: true }\n` +
-      `    ),\n` +
-      `  });`
+      `    regular: {\n` +
+      `      '/node_modules/@phosphor-icons/core/assets/regular/caret-right.svg': caretRight,\n` +
+      `    },\n` +
+      `  });\n` +
+      `See the JSDoc header of icons-phosphor.js for the full recipe.`
     );
   }
   installIconLoaders(weightModules);

package/core/icons.js

@@ -33,17 +33,25 @@
  *          import '@adia-ai/web-components/core/icons-phosphor';
  *
  *   3. **Scoped registration (recommended for production bundle-size
- *      SLOs).** Skip `icons-phosphor.js` entirely and register only the
- *      icons you actually use. `import.meta.glob` with a brace-list emits
- *      one chunk per matched file — for a 4-icon app, that's ~4 chunks
- *      instead of the ~9000 the full set would produce:
+ *      SLOs, and for Vite dev-servers that pre-bundle this package via
+ *      `optimizeDeps` — see `icons-phosphor.js`'s JSDoc header, "Vite
+ *      dep-optimizer pre-bundling", gh#287).** Skip `icons-phosphor.js`
+ *      entirely and register only the icons you actually use, via plain
+ *      bare-specifier imports in your OWN first-party source — never swept
+ *      into `optimizeDeps`, unlike a glob written inside this package:
  *
  *          import { installIconLoaders } from '@adia-ai/web-components/core/icons';
+ *          import caretRight from '@phosphor-icons/core/assets/regular/caret-right.svg?raw';
+ *          import caretUpDown from '@phosphor-icons/core/assets/regular/caret-up-down.svg?raw';
+ *          import moon from '@phosphor-icons/core/assets/regular/moon.svg?raw';
+ *          import sun from '@phosphor-icons/core/assets/regular/sun.svg?raw';
  *          installIconLoaders({
- *            regular: import.meta.glob(
- *              '/node_modules/@phosphor-icons/core/assets/regular/{caret-right,caret-up-down,moon,sun}.svg',
- *              { query: '?raw', import: 'default', eager: true }
- *            ),
+ *            regular: {
+ *              '/node_modules/@phosphor-icons/core/assets/regular/caret-right.svg': caretRight,
+ *              '/node_modules/@phosphor-icons/core/assets/regular/caret-up-down.svg': caretUpDown,
+ *              '/node_modules/@phosphor-icons/core/assets/regular/moon.svg': moon,
+ *              '/node_modules/@phosphor-icons/core/assets/regular/sun.svg': sun,
+ *            },
  *          });
  *
  *      Or register single SVGs directly:
@@ -236,6 +244,12 @@ export function installIconLoaders(modules) {
  *   import { installIconLoadersForRegistered } from '@adia-ai/web-components/core/icons';
  *
  *   // Build the Phosphor loader map from your bundler (Vite, Webpack, etc.).
+ *   // NOTE: this glob only matches under a hoisted install (npm/yarn classic,
+ *   // or pnpm with @phosphor-icons/core hoisted to your project root). Plain
+ *   // pnpm links a transitive dependency like this one inside its own
+ *   // resolution scope only — the glob silently matches zero files there.
+ *   // Use the plain bare-specifier import recipe in this file's own JSDoc
+ *   // header (path 3, above) instead if that's your install. See gh#287.
  *   const modules = import.meta.glob('/node_modules/@phosphor-icons/core/assets/regular/*.svg', { query: '?raw' });
  *
  *   // Aggregate requiredIcons across all defined primitives + install.