@nubisco/ui 4.1.0 → 4.1.1

package/dist/plugins/vite/glyphs.d.ts

@@ -20,6 +20,15 @@ export interface IGlyphOptions {
     packageName?: string;
     /** Log every rewrite. Useful when auditing what a page actually links. */
     verbose?: boolean;
+    /**
+     * Warn when a glyph forwarded through another component (`<NbButton
+     * :icon="…">`) is a value this plugin cannot see through, so no artwork was
+     * linked for it. On by default, once per file, because the alternative is
+     * the silence that lets an icon reach `NbIcon` with nothing to resolve it
+     * against. Turn it off in a codebase where those bindings are deliberate
+     * pass-through props, resolved by whoever passes them in.
+     */
+    warnUnresolved?: boolean;
 }
 export declare function nubiscoGlyphs(options?: IGlyphOptions): {
     name: string;

package/dist/plugins/vite/glyphs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"glyphs.d.ts","sourceRoot":"","sources":["../../../src/plugins/vite/glyphs.ts"],"names":[],"mappings":"AA0CA,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,KAAK,CAAA;AAE9C,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,iBAAiB,CAAA;IAC3B,4CAA4C;IAC5C,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,4CAA4C;IAC5C,KAAK,CAAC,EAAE,OAAO,CAAA;IACf;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAuFD,wBAAgB,aAAa,CAAC,OAAO,GAAE,aAAkB;;;;oBAwB/B,MAAM,MAAM,MAAM;;;;EA8I3C"}
+{"version":3,"file":"glyphs.d.ts","sourceRoot":"","sources":["../../../src/plugins/vite/glyphs.ts"],"names":[],"mappings":"AA0CA,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,KAAK,CAAA;AAE9C,MAAM,WAAW,aAAa;IAC5B;;;;;OAKG;IACH,OAAO,CAAC,EAAE,iBAAiB,CAAA;IAC3B,4CAA4C;IAC5C,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,4CAA4C;IAC5C,KAAK,CAAC,EAAE,OAAO,CAAA;IACf;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,4EAA4E;IAC5E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;;;;;OAOG;IACH,cAAc,CAAC,EAAE,OAAO,CAAA;CACzB;AAoLD,wBAAgB,aAAa,CAAC,OAAO,GAAE,aAAkB;;;;oBAyB/B,MAAM,MAAM,MAAM;;;;EA6L3C"}

package/dist/plugins/vite/glyphs.js

@@ -3,7 +3,7 @@ import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import MagicString from 'magic-string';
-import { parse } from 'vue/compiler-sfc';
+import { parse, babelParse } from 'vue/compiler-sfc';
 /**
  * Resolves icon and flag artwork at compile time.
  *
@@ -83,6 +83,95 @@ function staticWeight(element) {
     }
     return 'regular';
 }
+/**
+ * Parse one template expression on its own. `babelParse` wants a program, so
+ * the expression is wrapped; a binding Vue accepts but Babel cannot read is
+ * simply unknown, which the caller treats as unresolved.
+ */
+function parseExpression(expression) {
+    try {
+        const { program } = babelParse(`(${expression})`, {
+            sourceType: 'module',
+            plugins: ['typescript'],
+        });
+        const statement = program.body[0];
+        return statement?.type === 'ExpressionStatement'
+            ? statement.expression
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Whether every value this expression can hand to the component is artwork the
+ * bundle already links: a literal this plugin just rewrote, or a glyph module
+ * the file imported itself.
+ *
+ * The point is what it refuses. `open ? 'caret-up' : 'caret-down'` produces one
+ * of two rewritten literals and nothing else, so it is resolved. `block?.icon
+ * || 'cube'` also contains a rewritten literal, but it can just as easily
+ * produce `block.icon`, which is a runtime value and needs the catalogue.
+ * Judging by "a rewritten literal appears and no quoted string survives" called
+ * that second one resolved, which meant adding a literal fallback silently
+ * removed the coverage the same expression had without one.
+ */
+function producesOnlyLinkedGlyphs(node, isLinked) {
+    if (!node)
+        return false;
+    const recurse = (child) => producesOnlyLinkedGlyphs(child, isLinked);
+    switch (node.type) {
+        case 'Identifier':
+            return isLinked(node.name);
+        // The test is not a value the prop receives; the two arms are.
+        case 'ConditionalExpression':
+            return recurse(node.consequent) && recurse(node.alternate);
+        // `a || b`, `a ?? b` and `a && b` can all produce either side.
+        case 'LogicalExpression':
+            return recurse(node.left) && recurse(node.right);
+        case 'SequenceExpression':
+            return recurse(node.expressions[node.expressions.length - 1]);
+        case 'TSAsExpression':
+        case 'TSNonNullExpression':
+        case 'TSSatisfiesExpression':
+        case 'ParenthesizedExpression':
+            return recurse(node.expression);
+        default:
+            return false;
+    }
+}
+/**
+ * Local names bound to glyph modules by the file's own imports, so that
+ * `<NbIcon :name="GithubLogo" />` is understood as already-linked artwork
+ * rather than as a runtime name needing the whole catalogue.
+ */
+function glyphImportLocals(script, packageName) {
+    const locals = new Set();
+    const from = packageName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const pattern = new RegExp(`import\\s+([^;'"\n]+?)\\s+from\\s*['"]${from}/(?:icons|flags)/[^'"]+['"]`, 'g');
+    for (const match of script.matchAll(pattern)) {
+        const clause = match[1];
+        const namespace = clause.match(/\*\s+as\s+(\w+)/);
+        if (namespace)
+            locals.add(namespace[1]);
+        const defaultImport = clause.match(/^\s*(\w+)/);
+        if (defaultImport)
+            locals.add(defaultImport[1]);
+        const named = clause.match(/\{([^}]*)\}/);
+        if (named) {
+            for (const part of named[1].split(',')) {
+                const local = part
+                    .trim()
+                    .split(/\s+as\s+/)
+                    .pop()
+                    ?.trim();
+                if (local)
+                    locals.add(local);
+            }
+        }
+    }
+    return locals;
+}
 function staticPropKind(name, isIcon, isFlag) {
     if (isIcon)
         return name === 'name' || name === 'icon' ? 'icon' : undefined;
@@ -97,7 +186,7 @@ function staticPropKind(name, isIcon, isFlag) {
     return undefined;
 }
 export function nubiscoGlyphs(options = {}) {
-    const { catalog = 'auto', icons = true, flags = true, packageName = '@nubisco/ui', verbose = false, } = options;
+    const { catalog = 'auto', icons = true, flags = true, packageName = '@nubisco/ui', verbose = false, warnUnresolved = true, } = options;
     const glyphRoot = options.glyphRoot ?? defaultGlyphRoot();
     let names;
     const enabled = (kind) => (kind === 'icon' ? icons : flags);
@@ -121,6 +210,11 @@ export function nubiscoGlyphs(options = {}) {
             const edits = [];
             const used = new Map();
             const catalogsNeeded = new Set();
+            const unresolvedForwards = [];
+            // Artwork the file already imports by hand counts as linked: binding an
+            // imported module is the documented no-plugin path, and pulling a
+            // catalogue in on top of it would be pure waste.
+            const glyphLocals = glyphImportLocals(`${descriptor.scriptSetup?.content ?? ''}\n${descriptor.script?.content ?? ''}`, packageName);
             const use = (glyph) => {
                 const variable = identifierFor(glyph);
                 used.set(variable, glyph);
@@ -160,16 +254,16 @@ export function nubiscoGlyphs(options = {}) {
                         });
                         continue;
                     }
-                    /* ---- bound: :name="…" on NbIcon / NbFlag --------------------- */
+                    /* ---- bound: :name="…", :icon="…", :flag="…" ------------------ */
                     if (prop.type === NODE_DIRECTIVE &&
                         prop.name === 'bind' &&
                         prop.arg?.type === EXPR_SIMPLE &&
-                        prop.exp?.type === EXPR_SIMPLE &&
-                        (isIcon || isFlag)) {
-                        const kind = isIcon ? 'icon' : 'flag';
-                        if (!enabled(kind))
-                            continue;
-                        if (!['name', 'icon', 'flag'].includes(prop.arg.content))
+                        prop.exp?.type === EXPR_SIMPLE) {
+                        // Same rule as the static branch, so `:icon="a ? 'check' : 'copy'"`
+                        // links the two icons whether it is written on NbIcon or forwarded
+                        // through NbButton. Only the tag decides the kind.
+                        const kind = staticPropKind(prop.arg.content, isIcon, isFlag);
+                        if (!kind || !enabled(kind))
                             continue;
                         const expression = prop.exp.content;
                         const rewritten = expression.replace(/(['"])([a-z0-9][a-z0-9-]*)\1/g, (match, _quote, literal) => known(kind, literal)
@@ -186,15 +280,45 @@ export function nubiscoGlyphs(options = {}) {
                                 replacement: rewritten,
                             });
                         }
-                        // Considered resolved when every value the expression can produce
-                        // is one of the modules just imported: at least one appears, and
-                        // no string literal survived that could not be accounted for.
-                        const resolved = rewritten.includes('__nb_') && !/['"]/.test(rewritten);
-                        if (!resolved)
+                        const resolved = producesOnlyLinkedGlyphs(parseExpression(rewritten), (identifier) => used.has(identifier) || glyphLocals.has(identifier));
+                        if (resolved)
+                            continue;
+                        // On NbIcon or NbFlag an unresolvable name is fatal at first
+                        // render, so the catalogue is the only thing that can save it. On
+                        // a forwarding component the same expression may just as well be
+                        // a module arriving as a prop, and linking 1,500 icons on that
+                        // guess would make the common wrapper the most expensive file in
+                        // the bundle. So that case is reported rather than paid for.
+                        if (isIcon || isFlag)
                             catalogsNeeded.add(kind);
+                        else
+                            unresolvedForwards.push({
+                                tag,
+                                prop: prop.arg.content,
+                                exp: expression,
+                            });
                     }
                 }
             });
+            // One line per file, however many bindings it has: this is a note about
+            // the file, and repeating the same advice per expression would train
+            // people to skip it.
+            if (warnUnresolved && unresolvedForwards.length) {
+                const kinds = new Set(unresolvedForwards.map((f) => f.prop));
+                const register = kinds.has('flag')
+                    ? 'registerFlags()'
+                    : 'registerIcons()';
+                const catalogue = `${packageName}/${kinds.has('flag') ? 'flags' : 'icons'}/all`;
+                console.warn(`[nubisco-ui] ${path.relative(process.cwd(), file)}: no artwork ` +
+                    `linked for ` +
+                    unresolvedForwards
+                        .map((f) => `<${f.tag} :${f.prop}="${f.exp}">`)
+                        .join(', ') +
+                    `. The value is only known at runtime, so it will throw on first ` +
+                    `render unless something resolves it: ${register} for a known ` +
+                    `set, or import '${catalogue}' in this file. Nothing to do if ` +
+                    `these are pass-through props (set warnUnresolved: false).`);
+            }
             if (!used.size && !catalogsNeeded.size)
                 return;
             const imports = [];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nubisco/ui",
-  "version": "4.1.0",
+  "version": "4.1.1",
   "description": "Vue 3 UI component library",
   "packageManager": "pnpm@11.0.8",
   "repository": {

package/src/plugins/vite/glyphs.ts

@@ -3,7 +3,7 @@ import { existsSync } from 'node:fs'
 import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 import MagicString from 'magic-string'
-import { parse } from 'vue/compiler-sfc'
+import { parse, babelParse } from 'vue/compiler-sfc'
 
 /**
  * Resolves icon and flag artwork at compile time.
@@ -63,6 +63,15 @@ export interface IGlyphOptions {
   packageName?: string
   /** Log every rewrite. Useful when auditing what a page actually links. */
   verbose?: boolean
+  /**
+   * Warn when a glyph forwarded through another component (`<NbButton
+   * :icon="…">`) is a value this plugin cannot see through, so no artwork was
+   * linked for it. On by default, once per file, because the alternative is
+   * the silence that lets an icon reach `NbIcon` with nothing to resolve it
+   * against. Turn it off in a codebase where those bindings are deliberate
+   * pass-through props, resolved by whoever passes them in.
+   */
+  warnUnresolved?: boolean
 }
 
 type TKind = 'icon' | 'flag'
@@ -136,6 +145,99 @@ function staticWeight(element: any): string | undefined {
   return 'regular'
 }
 
+/**
+ * Parse one template expression on its own. `babelParse` wants a program, so
+ * the expression is wrapped; a binding Vue accepts but Babel cannot read is
+ * simply unknown, which the caller treats as unresolved.
+ */
+function parseExpression(expression: string): any {
+  try {
+    const { program } = babelParse(`(${expression})`, {
+      sourceType: 'module',
+      plugins: ['typescript'],
+    })
+    const statement: any = program.body[0]
+    return statement?.type === 'ExpressionStatement'
+      ? statement.expression
+      : undefined
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Whether every value this expression can hand to the component is artwork the
+ * bundle already links: a literal this plugin just rewrote, or a glyph module
+ * the file imported itself.
+ *
+ * The point is what it refuses. `open ? 'caret-up' : 'caret-down'` produces one
+ * of two rewritten literals and nothing else, so it is resolved. `block?.icon
+ * || 'cube'` also contains a rewritten literal, but it can just as easily
+ * produce `block.icon`, which is a runtime value and needs the catalogue.
+ * Judging by "a rewritten literal appears and no quoted string survives" called
+ * that second one resolved, which meant adding a literal fallback silently
+ * removed the coverage the same expression had without one.
+ */
+function producesOnlyLinkedGlyphs(
+  node: any,
+  isLinked: (name: string) => boolean,
+): boolean {
+  if (!node) return false
+  const recurse = (child: any) => producesOnlyLinkedGlyphs(child, isLinked)
+  switch (node.type) {
+    case 'Identifier':
+      return isLinked(node.name)
+    // The test is not a value the prop receives; the two arms are.
+    case 'ConditionalExpression':
+      return recurse(node.consequent) && recurse(node.alternate)
+    // `a || b`, `a ?? b` and `a && b` can all produce either side.
+    case 'LogicalExpression':
+      return recurse(node.left) && recurse(node.right)
+    case 'SequenceExpression':
+      return recurse(node.expressions[node.expressions.length - 1])
+    case 'TSAsExpression':
+    case 'TSNonNullExpression':
+    case 'TSSatisfiesExpression':
+    case 'ParenthesizedExpression':
+      return recurse(node.expression)
+    default:
+      return false
+  }
+}
+
+/**
+ * Local names bound to glyph modules by the file's own imports, so that
+ * `<NbIcon :name="GithubLogo" />` is understood as already-linked artwork
+ * rather than as a runtime name needing the whole catalogue.
+ */
+function glyphImportLocals(script: string, packageName: string): Set<string> {
+  const locals = new Set<string>()
+  const from = packageName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  const pattern = new RegExp(
+    `import\\s+([^;'"\n]+?)\\s+from\\s*['"]${from}/(?:icons|flags)/[^'"]+['"]`,
+    'g',
+  )
+  for (const match of script.matchAll(pattern)) {
+    const clause = match[1]
+    const namespace = clause.match(/\*\s+as\s+(\w+)/)
+    if (namespace) locals.add(namespace[1])
+    const defaultImport = clause.match(/^\s*(\w+)/)
+    if (defaultImport) locals.add(defaultImport[1])
+    const named = clause.match(/\{([^}]*)\}/)
+    if (named) {
+      for (const part of named[1].split(',')) {
+        const local = part
+          .trim()
+          .split(/\s+as\s+/)
+          .pop()
+          ?.trim()
+        if (local) locals.add(local)
+      }
+    }
+  }
+  return locals
+}
+
 function staticPropKind(
   name: string,
   isIcon: boolean,
@@ -157,6 +259,7 @@ export function nubiscoGlyphs(options: IGlyphOptions = {}) {
     flags = true,
     packageName = '@nubisco/ui',
     verbose = false,
+    warnUnresolved = true,
   } = options
 
   const glyphRoot = options.glyphRoot ?? defaultGlyphRoot()
@@ -186,6 +289,16 @@ export function nubiscoGlyphs(options: IGlyphOptions = {}) {
       const edits: IEdit[] = []
       const used = new Map<string, IGlyphImport>()
       const catalogsNeeded = new Set<TKind>()
+      const unresolvedForwards: { tag: string; prop: string; exp: string }[] =
+        []
+
+      // Artwork the file already imports by hand counts as linked: binding an
+      // imported module is the documented no-plugin path, and pulling a
+      // catalogue in on top of it would be pure waste.
+      const glyphLocals = glyphImportLocals(
+        `${descriptor.scriptSetup?.content ?? ''}\n${descriptor.script?.content ?? ''}`,
+        packageName,
+      )
 
       const use = (glyph: IGlyphImport) => {
         const variable = identifierFor(glyph)
@@ -229,17 +342,18 @@ export function nubiscoGlyphs(options: IGlyphOptions = {}) {
             continue
           }
 
-          /* ---- bound: :name="…" on NbIcon / NbFlag --------------------- */
+          /* ---- bound: :name="…", :icon="…", :flag="…" ------------------ */
           if (
             prop.type === NODE_DIRECTIVE &&
             prop.name === 'bind' &&
             prop.arg?.type === EXPR_SIMPLE &&
-            prop.exp?.type === EXPR_SIMPLE &&
-            (isIcon || isFlag)
+            prop.exp?.type === EXPR_SIMPLE
           ) {
-            const kind: TKind = isIcon ? 'icon' : 'flag'
-            if (!enabled(kind)) continue
-            if (!['name', 'icon', 'flag'].includes(prop.arg.content)) continue
+            // Same rule as the static branch, so `:icon="a ? 'check' : 'copy'"`
+            // links the two icons whether it is written on NbIcon or forwarded
+            // through NbButton. Only the tag decides the kind.
+            const kind = staticPropKind(prop.arg.content, isIcon, isFlag)
+            if (!kind || !enabled(kind)) continue
 
             const expression: string = prop.exp.content
             const rewritten = expression.replace(
@@ -262,16 +376,52 @@ export function nubiscoGlyphs(options: IGlyphOptions = {}) {
               })
             }
 
-            // Considered resolved when every value the expression can produce
-            // is one of the modules just imported: at least one appears, and
-            // no string literal survived that could not be accounted for.
-            const resolved =
-              rewritten.includes('__nb_') && !/['"]/.test(rewritten)
-            if (!resolved) catalogsNeeded.add(kind)
+            const resolved = producesOnlyLinkedGlyphs(
+              parseExpression(rewritten),
+              (identifier) =>
+                used.has(identifier) || glyphLocals.has(identifier),
+            )
+            if (resolved) continue
+
+            // On NbIcon or NbFlag an unresolvable name is fatal at first
+            // render, so the catalogue is the only thing that can save it. On
+            // a forwarding component the same expression may just as well be
+            // a module arriving as a prop, and linking 1,500 icons on that
+            // guess would make the common wrapper the most expensive file in
+            // the bundle. So that case is reported rather than paid for.
+            if (isIcon || isFlag) catalogsNeeded.add(kind)
+            else
+              unresolvedForwards.push({
+                tag,
+                prop: prop.arg.content,
+                exp: expression,
+              })
           }
         }
       })
 
+      // One line per file, however many bindings it has: this is a note about
+      // the file, and repeating the same advice per expression would train
+      // people to skip it.
+      if (warnUnresolved && unresolvedForwards.length) {
+        const kinds = new Set(unresolvedForwards.map((f) => f.prop))
+        const register = kinds.has('flag')
+          ? 'registerFlags()'
+          : 'registerIcons()'
+        const catalogue = `${packageName}/${kinds.has('flag') ? 'flags' : 'icons'}/all`
+        console.warn(
+          `[nubisco-ui] ${path.relative(process.cwd(), file)}: no artwork ` +
+            `linked for ` +
+            unresolvedForwards
+              .map((f) => `<${f.tag} :${f.prop}="${f.exp}">`)
+              .join(', ') +
+            `. The value is only known at runtime, so it will throw on first ` +
+            `render unless something resolves it: ${register} for a known ` +
+            `set, or import '${catalogue}' in this file. Nothing to do if ` +
+            `these are pass-through props (set warnUnresolved: false).`,
+        )
+      }
+
       if (!used.size && !catalogsNeeded.size) return
 
       const imports: string[] = []