@adia-ai/web-components 0.8.3 → 0.8.5

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.