@truenas/ui-components 0.1.46 → 0.1.47

package/scripts/icon-sprite/lib/find-icons-in-templates.spec.ts

@@ -0,0 +1,119 @@
+import path from 'path';
+import { findIconsInTemplates } from './find-icons-in-templates';
+import type { ForwardingComponentMapping } from './find-icons-in-forwarding-components';
+
+const CONSUMER_FIXTURES = path.resolve(__dirname, '../__fixtures__/consumer-templates');
+
+const FORWARDING_MAPPINGS: ForwardingComponentMapping[] = [
+  {
+    selector: 'tn-empty',
+    iconSlots: [{ iconAttribute: 'icon', libraryAttribute: 'iconLibrary', defaultLibrary: 'mdi' }],
+  },
+  {
+    selector: 'tn-input',
+    iconSlots: [
+      { iconAttribute: 'prefixIcon', libraryAttribute: 'prefixIconLibrary' },
+      { iconAttribute: 'suffixIcon', libraryAttribute: 'suffixIconLibrary' },
+    ],
+  },
+  {
+    selector: 'tn-chip',
+    iconSlots: [{ iconAttribute: 'icon' }],
+  },
+];
+
+describe('findIconsInTemplates', () => {
+  describe('tn-icon scanning (existing behavior)', () => {
+    it('should find static tn-icon names with library prefix', () => {
+      const { icons } = findIconsInTemplates(CONSUMER_FIXTURES);
+      expect(icons.has('mdi-folder')).toBe(true);
+    });
+
+    it('should find tn-icon ternary expressions', () => {
+      const { icons } = findIconsInTemplates(CONSUMER_FIXTURES);
+      expect(icons.has('mdi-chevron-down')).toBe(true);
+      expect(icons.has('mdi-chevron-right')).toBe(true);
+    });
+
+    it('should find material library icons', () => {
+      const { icons } = findIconsInTemplates(CONSUMER_FIXTURES);
+      expect(icons.has('mat-check_circle')).toBe(true);
+    });
+
+    it('should skip registry format icons (with colon)', () => {
+      const { icons } = findIconsInTemplates(CONSUMER_FIXTURES);
+      const registryIcons = [...icons].filter(i => i.includes(':'));
+      expect(registryIcons).toEqual([]);
+    });
+
+    it('should find tn-icon-button names', () => {
+      const { icons } = findIconsInTemplates(CONSUMER_FIXTURES);
+      expect(icons.has('mdi-close')).toBe(true);
+    });
+  });
+
+  describe('forwarding component scanning', () => {
+    it('should find icons from tn-empty static attributes', () => {
+      const { icons } = findIconsInTemplates(CONSUMER_FIXTURES, undefined, FORWARDING_MAPPINGS);
+      expect(icons.has('mdi-inbox')).toBe(true);
+    });
+
+    it('should find icons from tn-empty ternary with default library', () => {
+      const { icons } = findIconsInTemplates(CONSUMER_FIXTURES, undefined, FORWARDING_MAPPINGS);
+      // tn-empty has defaultLibrary: 'mdi', ternary values get prefixed
+      expect(icons.has('mdi-check')).toBe(true);
+      expect(icons.has('mdi-alert')).toBe(true);
+    });
+
+    it('should find icons from tn-input prefixIcon with explicit library', () => {
+      const { icons } = findIconsInTemplates(CONSUMER_FIXTURES, undefined, FORWARDING_MAPPINGS);
+      expect(icons.has('mdi-search')).toBe(true);
+    });
+
+    it('should find icons from tn-input suffixIcon with material library', () => {
+      const { icons } = findIconsInTemplates(CONSUMER_FIXTURES, undefined, FORWARDING_MAPPINGS);
+      expect(icons.has('mat-eye')).toBe(true);
+    });
+
+    it('should find icons from tn-chip (no library, no default)', () => {
+      const { icons } = findIconsInTemplates(CONSUMER_FIXTURES, undefined, FORWARDING_MAPPINGS);
+      expect(icons.has('star')).toBe(true);
+    });
+
+    it('should not extract dynamic signal bindings', () => {
+      const { icons } = findIconsInTemplates(CONSUMER_FIXTURES, undefined, FORWARDING_MAPPINGS);
+      // [icon]="dynamicIcon()" should NOT produce any icon
+      const dynamicArtifacts = [...icons].filter(i => i.includes('dynamic') || i.includes('Icon'));
+      expect(dynamicArtifacts).toEqual([]);
+    });
+
+    it('should not find forwarding icons when mappings are not provided', () => {
+      const withMappings = findIconsInTemplates(CONSUMER_FIXTURES, undefined, FORWARDING_MAPPINGS);
+      const withoutMappings = findIconsInTemplates(CONSUMER_FIXTURES);
+
+      // Without mappings, tn-empty/tn-input/tn-chip icons should be missing
+      expect(withMappings.icons.size).toBeGreaterThan(withoutMappings.icons.size);
+      expect(withoutMappings.icons.has('mdi-inbox')).toBe(false);
+      expect(withoutMappings.icons.has('mdi-search')).toBe(false);
+    });
+  });
+
+  describe('skipIcons filtering', () => {
+    it('should exclude icons in the skip set', () => {
+      const skipIcons = new Set(['mdi-folder', 'mat-check_circle']);
+      const { icons } = findIconsInTemplates(CONSUMER_FIXTURES, skipIcons);
+      expect(icons.has('mdi-folder')).toBe(false);
+      expect(icons.has('mat-check_circle')).toBe(false);
+    });
+  });
+
+  describe('source tracking', () => {
+    it('should return source file paths for each icon', () => {
+      const { sources } = findIconsInTemplates(CONSUMER_FIXTURES);
+      expect(sources.has('mdi-folder')).toBe(true);
+      const folderSources = sources.get('mdi-folder')!;
+      expect(folderSources.length).toBeGreaterThan(0);
+      expect(folderSources[0]).toContain('basic.component.html');
+    });
+  });
+});

package/scripts/icon-sprite/lib/find-icons-in-templates.ts

@@ -1,31 +1,69 @@
 import fs from 'fs';
 import fg from 'fast-glob';
 import * as cheerio from 'cheerio';
+import type { ForwardingComponentMapping } from './find-icons-in-forwarding-components';
 
-export function findIconsInTemplates(path: string, skipIcons?: Set<string>): Set<string> {
+export interface ScanResult {
+  icons: Set<string>;
+  sources: Map<string, string[]>;
+}
+
+export function findIconsInTemplates(
+  path: string,
+  skipIcons?: Set<string>,
+  forwardingMappings?: ForwardingComponentMapping[],
+): ScanResult {
   const iconNames = new Set<string>();
+  const sources = new Map<string, string[]>();
 
   const templates = fg.sync(`${path}/**/*.html`);
 
+  const addIcon = (iconName: string, templateFile: string) => {
+    iconNames.add(iconName);
+    const existing = sources.get(iconName) || [];
+    existing.push(templateFile);
+    sources.set(iconName, existing);
+  };
+
   templates.forEach((template) => {
     const content = fs.readFileSync(template, 'utf-8');
     const parsedTemplate = cheerio.load(content);
 
-    // Helper function to extract icon names from elements (used for both tn-icon and tn-icon-button)
-    const processIconElement = (iconTag: cheerio.Element) => {
-      // Check both 'name' and '[name]' attributes (Angular binding syntax)
-      const staticName = parsedTemplate(iconTag).attr('name');
-      const boundName = parsedTemplate(iconTag).attr('[name]');
-      const library = parsedTemplate(iconTag).attr('library');
+    // Generic function to extract icon names from an element's attributes
+    const processElement = (
+      el: cheerio.Element,
+      iconAttr: string,
+      libraryAttr: string | undefined,
+      defaultLibrary: string | undefined,
+    ) => {
+      // Check both static and [bound] attributes (Angular binding syntax)
+      // Cheerio lowercases HTML attribute names, so look up the lowercase form
+      const iconAttrLower = iconAttr.toLowerCase();
+      const staticName = parsedTemplate(el).attr(iconAttrLower);
+      const boundName = parsedTemplate(el).attr(`[${iconAttrLower}]`);
+      const libraryAttrLower = libraryAttr?.toLowerCase();
+      const library = libraryAttrLower
+        ? parsedTemplate(el).attr(libraryAttrLower) || parsedTemplate(el).attr(`[${libraryAttrLower}]`)
+        : undefined;
+
+      // Resolve library: use explicit value, fall back to default
+      let resolvedLibrary = defaultLibrary;
+      if (library) {
+        // Handle both static library="mdi" and bound [library]="'mdi'"
+        const staticLib = library.replace(/^['"]|['"]$/g, '');
+        if (/^[a-z]+$/.test(staticLib)) {
+          resolvedLibrary = staticLib;
+        }
+      }
 
       const extractedNames: string[] = [];
 
-      // Handle static name attribute: name="folder"
+      // Handle static name attribute: icon="folder"
       if (staticName) {
         extractedNames.push(staticName);
       }
 
-      // Handle bound name attribute: [name]="expression"
+      // Handle bound name attribute: [icon]="expression"
       // Extract string literals from the expression
       if (boundName) {
         // Match string literals that are values, not comparison operands
@@ -46,7 +84,7 @@ export function findIconsInTemplates(path: string, skipIcons?: Set<string>): Set
         }
 
         // Also handle simple string literals (no ternary, no comparison)
-        // e.g., [name]="'folder'" (though this is unusual)
+        // e.g., [icon]="'folder'" (though this is unusual)
         if (!boundName.includes('?') && !boundName.includes('=')) {
           const simpleStringRegex = /^['"]([^'"]+)['"]$/;
           const simpleMatch = boundName.match(simpleStringRegex);
@@ -72,13 +110,13 @@ export function findIconsInTemplates(path: string, skipIcons?: Set<string>): Set
         let finalIconName: string;
 
         // Handle library attribute - prefix the icon name with library prefix
-        if (library === 'mdi' && !iconName.startsWith('mdi-')) {
+        if (resolvedLibrary === 'mdi' && !iconName.startsWith('mdi-')) {
           finalIconName = `mdi-${iconName}`;
-        } else if (library === 'custom' && !iconName.startsWith('app-') && !iconName.startsWith('tn-')) {
+        } else if (resolvedLibrary === 'custom' && !iconName.startsWith('app-') && !iconName.startsWith('tn-')) {
           // Consumer custom icons get app- prefix
           // (Library templates should never use library="custom", they use libIconMarker() instead)
           finalIconName = `app-${iconName}`;
-        } else if (library === 'material' && !iconName.startsWith('mat-')) {
+        } else if (resolvedLibrary === 'material' && !iconName.startsWith('mat-')) {
           finalIconName = `mat-${iconName}`; // Material icons get mat- prefix
         } else {
           finalIconName = iconName;
@@ -89,20 +127,31 @@ export function findIconsInTemplates(path: string, skipIcons?: Set<string>): Set
           return;
         }
 
-        iconNames.add(finalIconName);
+        addIcon(finalIconName, template);
       });
     };
 
     // Scan tn-icon elements
     parsedTemplate('tn-icon').each((_, iconTag) => {
-      processIconElement(iconTag);
+      processElement(iconTag, 'name', 'library', undefined);
     });
 
     // Scan tn-icon-button elements (they also have name and library attributes)
     parsedTemplate('tn-icon-button').each((_, iconTag) => {
-      processIconElement(iconTag);
+      processElement(iconTag, 'name', 'library', undefined);
     });
+
+    // Scan icon-forwarding components
+    if (forwardingMappings) {
+      for (const mapping of forwardingMappings) {
+        parsedTemplate(mapping.selector).each((_, el) => {
+          for (const slot of mapping.iconSlots) {
+            processElement(el, slot.iconAttribute, slot.libraryAttribute, slot.defaultLibrary);
+          }
+        });
+      }
+    }
   });
 
-  return iconNames;
+  return { icons: iconNames, sources };
 }

package/scripts/icon-sprite/lib/find-icons-with-marker.spec.ts

@@ -0,0 +1,58 @@
+import path from 'path';
+import { findIconsWithMarker } from './find-icons-with-marker';
+
+const MARKER_FIXTURES = path.resolve(__dirname, '../__fixtures__/marker-sources');
+
+describe('findIconsWithMarker', () => {
+  it('should find tnIconMarker calls with mdi library', () => {
+    const { icons } = findIconsWithMarker(MARKER_FIXTURES);
+    expect(icons.has('mdi-content-save')).toBe(true);
+    expect(icons.has('mdi-delete')).toBe(true);
+    expect(icons.has('mdi-pencil')).toBe(true);
+    expect(icons.has('mdi-trash-can')).toBe(true);
+  });
+
+  it('should find tnIconMarker calls with material library', () => {
+    const { icons } = findIconsWithMarker(MARKER_FIXTURES);
+    expect(icons.has('mat-check_circle')).toBe(true);
+  });
+
+  it('should find tnIconMarker calls with custom library', () => {
+    const { icons } = findIconsWithMarker(MARKER_FIXTURES);
+    expect(icons.has('app-my-logo')).toBe(true);
+  });
+
+  it('should find tnIconMarker calls without library', () => {
+    const { icons } = findIconsWithMarker(MARKER_FIXTURES);
+    expect(icons.has('some-icon')).toBe(true);
+  });
+
+  it('should find libIconMarker calls with tn- prefix', () => {
+    const { icons } = findIconsWithMarker(MARKER_FIXTURES);
+    expect(icons.has('tn-dataset')).toBe(true);
+  });
+
+  it('should skip icons in the skip set', () => {
+    const skipIcons = new Set(['mdi-content-save', 'tn-dataset']);
+    const { icons } = findIconsWithMarker(MARKER_FIXTURES, skipIcons);
+    expect(icons.has('mdi-content-save')).toBe(false);
+    expect(icons.has('tn-dataset')).toBe(false);
+    // Others should still be found
+    expect(icons.has('mdi-delete')).toBe(true);
+  });
+
+  describe('source tracking', () => {
+    it('should return source file paths for each icon', () => {
+      const { sources } = findIconsWithMarker(MARKER_FIXTURES);
+      expect(sources.has('mdi-content-save')).toBe(true);
+      const saveSources = sources.get('mdi-content-save')!;
+      expect(saveSources.length).toBeGreaterThan(0);
+      expect(saveSources[0]).toContain('icons.ts');
+    });
+  });
+
+  it('should return empty set for directory with no markers', () => {
+    const { icons } = findIconsWithMarker(path.resolve(__dirname, '../__fixtures__/custom-icons'));
+    expect(icons.size).toBe(0);
+  });
+});

package/scripts/icon-sprite/lib/find-icons-with-marker.ts

@@ -1,22 +1,46 @@
-import { execSync } from 'node:child_process';
+import { spawnSync } from 'node:child_process';
+import type { ScanResult } from './find-icons-in-templates';
 
-export function findIconsWithMarker(path: string, skipIcons?: Set<string>): Set<string> {
+export function findIconsWithMarker(path: string, skipIcons?: Set<string>): ScanResult {
   // Updated regex to capture tnIconMarker() and libIconMarker() calls with optional second parameter
   // Matches: tnIconMarker('name') or tnIconMarker('name', 'library') or libIconMarker('tn-name')
-  const command = `grep -rEo "(tn|lib)IconMarker\\\\('[^']+',?\\s*'?[^'\\)]*'?\\)" --include="*.ts" --include="*.html" ${path}`;
+  const pattern = "(tn|lib)IconMarker\\('[^']+',?\\s*'?[^'\\)]*'?\\)";
 
   const icons = new Set<string>();
+  const sources = new Map<string, string[]>();
 
-  try {
-    const output = execSync(command, { encoding: 'utf-8' });
-    output
-      .split('\n')
-      .filter(Boolean)
-      .forEach((line) => {
-        const [, match] = line.split(':');
-        if (!match) {
+  const addIcon = (iconName: string, sourceFile: string) => {
+    icons.add(iconName);
+    const existing = sources.get(iconName) || [];
+    existing.push(sourceFile);
+    sources.set(iconName, existing);
+  };
+
+  const result = spawnSync(
+    'grep',
+    ['-rEo', pattern, '--include=*.ts', '--include=*.html', path],
+    { encoding: 'utf-8' },
+  );
+
+  if (result.status === 1 && !result.stderr) {
+    // grep returns exit code 1 when no matches found
+    return { icons, sources };
+  }
+  if (result.status !== 0 && result.status !== 1) {
+    throw new Error(`grep failed: ${result.stderr}`);
+  }
+
+  result.stdout
+    .split('\n')
+    .filter(Boolean)
+    .forEach((line) => {
+        // grep output format: "filepath:match"
+        const colonIdx = line.indexOf(':');
+        if (colonIdx === -1) {
           return;
         }
+        const sourceFile = line.substring(0, colonIdx);
+        const match = line.substring(colonIdx + 1);
 
         // Extract icon name (first parameter)
         const iconNameMatch = /'([^']+)'/.exec(match);
@@ -47,17 +71,8 @@ export function findIconsWithMarker(path: string, skipIcons?: Set<string>): Set<
           return;
         }
 
-        icons.add(iconName);
+        addIcon(iconName, sourceFile);
       });
-  } catch (error: any) {
-    // grep returns exit code 1 when no matches are found, which is not an error
-    if (error.status === 1 && !error.stderr) {
-      // No matches found, return empty set
-      return icons;
-    }
-    // Re-throw actual errors
-    throw error;
-  }
 
-  return icons;
+  return { icons, sources };
 }

package/scripts/icon-sprite/lib/validate-icons.spec.ts

@@ -0,0 +1,170 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { validateIcons, printValidationReport } from './validate-icons';
+import type { ResolvedSpriteConfig } from '../sprite-config-interface';
+
+const FIXTURES_BASE = path.resolve(__dirname, '../__fixtures__');
+
+function createTempConfig(overrides: Partial<ResolvedSpriteConfig> = {}): ResolvedSpriteConfig {
+  return {
+    projectRoot: FIXTURES_BASE,
+    srcDirs: ['./consumer-templates', './marker-sources'],
+    outputDir: './output',
+    spriteUrlPath: 'assets/tn-icons',
+    customIconsDir: overrides.customIconsDir ?? null,
+    ...overrides,
+  };
+}
+
+function writeSpriteConfig(dir: string, icons: string[]): void {
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(
+    path.join(dir, 'sprite-config.json'),
+    JSON.stringify({ iconUrl: 'sprite.svg?v=abc', icons }),
+  );
+}
+
+describe('validateIcons', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'icon-validate-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  it('should report missing sprite config', () => {
+    const config = createTempConfig({ outputDir: path.join(tempDir, 'nonexistent') });
+    const result = validateIcons(config);
+
+    expect(result.spriteConfigFound).toBe(false);
+    expect(result.spriteIcons.size).toBe(0);
+  });
+
+  it('should detect icons missing from sprite', () => {
+    const outputDir = path.join(tempDir, 'output');
+    // Write a sprite config with only some icons
+    writeSpriteConfig(outputDir, ['mdi-folder']);
+
+    const config = createTempConfig({ outputDir });
+    const result = validateIcons(config);
+
+    expect(result.spriteConfigFound).toBe(true);
+    expect(result.missingFromSprite.size).toBeGreaterThan(0);
+    // mdi-folder is in the sprite, so it should NOT be missing
+    expect(result.missingFromSprite.has('mdi-folder')).toBe(false);
+  });
+
+  it('should detect stale icons in sprite', () => {
+    const outputDir = path.join(tempDir, 'output');
+    writeSpriteConfig(outputDir, ['mdi-folder', 'mdi-nonexistent-icon']);
+
+    const config = createTempConfig({ outputDir });
+    const result = validateIcons(config);
+
+    expect(result.staleInSprite.has('mdi-nonexistent-icon')).toBe(true);
+  });
+
+  it('should report clean when sprite matches scanned icons', () => {
+    const outputDir = path.join(tempDir, 'output');
+    // First, scan to get the full set
+    const config = createTempConfig({ outputDir });
+    const scan = validateIcons(config);
+    // Now write a sprite config with exactly those icons
+    writeSpriteConfig(outputDir, [...scan.scannedIcons]);
+
+    const result = validateIcons(config);
+    expect(result.missingFromSprite.size).toBe(0);
+    expect(result.staleInSprite.size).toBe(0);
+  });
+
+  it('should include custom icons in scanned set', () => {
+    const outputDir = path.join(tempDir, 'output');
+    writeSpriteConfig(outputDir, ['tn-logo', 'tn-brand']);
+
+    const config = createTempConfig({
+      outputDir,
+      customIconsDir: './custom-icons',
+    });
+    const result = validateIcons(config);
+
+    expect(result.scannedIcons.has('tn-logo')).toBe(true);
+    expect(result.scannedIcons.has('tn-brand')).toBe(true);
+  });
+});
+
+describe('printValidationReport', () => {
+  let consoleOutput: string[];
+  const originalLog = console.log;
+
+  beforeEach(() => {
+    consoleOutput = [];
+    console.log = (...args: unknown[]) => {
+      consoleOutput.push(args.map(String).join(' '));
+    };
+  });
+
+  afterEach(() => {
+    console.log = originalLog;
+  });
+
+  it('should return 0 when sprite is clean', () => {
+    const exitCode = printValidationReport({
+      scannedIcons: new Set(['mdi-folder']),
+      spriteIcons: new Set(['mdi-folder']),
+      missingFromSprite: new Set(),
+      staleInSprite: new Set(),
+      sources: new Map(),
+      spriteConfigFound: true,
+    });
+
+    expect(exitCode).toBe(0);
+    expect(consoleOutput.some(line => line.includes('up to date'))).toBe(true);
+  });
+
+  it('should return 1 when icons are missing', () => {
+    const exitCode = printValidationReport({
+      scannedIcons: new Set(['mdi-folder', 'mdi-new']),
+      spriteIcons: new Set(['mdi-folder']),
+      missingFromSprite: new Set(['mdi-new']),
+      staleInSprite: new Set(),
+      sources: new Map([['mdi-new', ['src/app/test.html']]]),
+      spriteConfigFound: true,
+    });
+
+    expect(exitCode).toBe(1);
+    expect(consoleOutput.some(line => line.includes('mdi-new'))).toBe(true);
+    expect(consoleOutput.some(line => line.includes('test.html'))).toBe(true);
+  });
+
+  it('should return 1 when no sprite config found', () => {
+    const exitCode = printValidationReport({
+      scannedIcons: new Set(['mdi-folder']),
+      spriteIcons: new Set(),
+      missingFromSprite: new Set(),
+      staleInSprite: new Set(),
+      sources: new Map(),
+      spriteConfigFound: false,
+    });
+
+    expect(exitCode).toBe(1);
+    expect(consoleOutput.some(line => line.includes('No sprite-config.json'))).toBe(true);
+  });
+
+  it('should return 0 when only stale icons exist', () => {
+    const exitCode = printValidationReport({
+      scannedIcons: new Set(['mdi-folder']),
+      spriteIcons: new Set(['mdi-folder', 'mdi-old']),
+      missingFromSprite: new Set(),
+      staleInSprite: new Set(['mdi-old']),
+      sources: new Map(),
+      spriteConfigFound: true,
+    });
+
+    expect(exitCode).toBe(0);
+    expect(consoleOutput.some(line => line.includes('mdi-old'))).toBe(true);
+  });
+});