@truenas/ui-components 0.1.46 → 0.1.47

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@truenas/ui-components",
-  "version": "0.1.46",
+  "version": "0.1.47",
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
     "access": "public"

package/scripts/icon-sprite/__fixtures__/consumer-templates/basic.component.html

@@ -0,0 +1,30 @@
+<!-- Static tn-icon -->
+<tn-icon name="folder" library="mdi"></tn-icon>
+
+<!-- Bound tn-icon with ternary -->
+<tn-icon [name]="expanded ? 'chevron-down' : 'chevron-right'" library="mdi"></tn-icon>
+
+<!-- Material icon -->
+<tn-icon name="check_circle" library="material"></tn-icon>
+
+<!-- Registry format (should be skipped) -->
+<tn-icon name="lucide:home"></tn-icon>
+
+<!-- tn-icon-button -->
+<tn-icon-button name="close" library="mdi"></tn-icon-button>
+
+<!-- Forwarding: tn-empty with static icon -->
+<tn-empty icon="inbox" iconLibrary="mdi" title="No messages"></tn-empty>
+
+<!-- Forwarding: tn-empty with bound icon ternary -->
+<tn-empty [icon]="hasData ? 'check' : 'alert'" title="Status"></tn-empty>
+
+<!-- Forwarding: tn-input with prefix/suffix icons -->
+<tn-input prefixIcon="search" prefixIconLibrary="mdi"></tn-input>
+<tn-input suffixIcon="eye" suffixIconLibrary="material"></tn-input>
+
+<!-- Forwarding: tn-chip (no library, no default) -->
+<tn-chip icon="star"></tn-chip>
+
+<!-- Dynamic binding (not extractable) -->
+<tn-empty [icon]="dynamicIcon()" title="Dynamic"></tn-empty>

package/scripts/icon-sprite/__fixtures__/custom-icons/brand.svg

@@ -0,0 +1 @@
+<svg viewBox="0 0 24 24"><circle cx="12" cy="12" r="10"/></svg>

package/scripts/icon-sprite/__fixtures__/custom-icons/logo.svg

@@ -0,0 +1 @@
+<svg viewBox="0 0 24 24"><path d="M12 2L2 7v10l10 5 10-5V7z"/></svg>

package/scripts/icon-sprite/__fixtures__/forwarding-components/multi-icon.component.html

@@ -0,0 +1,7 @@
+@if (prefixIcon()) {
+  <tn-icon [name]="prefixIcon()!" [library]="prefixIconLibrary()" />
+}
+<input class="tn-input" />
+@if (suffixIcon()) {
+  <tn-icon [name]="suffixIcon()!" [library]="suffixIconLibrary()" />
+}

package/scripts/icon-sprite/__fixtures__/forwarding-components/multi-icon.component.ts

@@ -0,0 +1,15 @@
+import { Component, input } from '@angular/core';
+import type { TnIconForwardingComponent } from '../icon/icon-forwarding';
+import type { IconLibraryType } from '../icon/icon.component';
+
+@Component({
+  selector: 'tn-input',
+  standalone: true,
+  templateUrl: './multi-icon.component.html',
+})
+export class TnInputComponent implements TnIconForwardingComponent, AfterViewInit {
+  prefixIcon = input<string | undefined>(undefined);
+  prefixIconLibrary = input<IconLibraryType | undefined>(undefined);
+  suffixIcon = input<string | undefined>(undefined);
+  suffixIconLibrary = input<IconLibraryType | undefined>(undefined);
+}

package/scripts/icon-sprite/__fixtures__/forwarding-components/no-library.component.html

@@ -0,0 +1,3 @@
+@if (icon()) {
+  <tn-icon [name]="icon()!" />
+}

package/scripts/icon-sprite/__fixtures__/forwarding-components/no-library.component.ts

@@ -0,0 +1,11 @@
+import { Component, input } from '@angular/core';
+import type { TnIconForwardingComponent } from '../icon/icon-forwarding';
+
+@Component({
+  selector: 'tn-chip',
+  standalone: true,
+  templateUrl: './no-library.component.html',
+})
+export class TnChipComponent implements TnIconForwardingComponent {
+  icon = input<string | undefined>(undefined);
+}

package/scripts/icon-sprite/__fixtures__/forwarding-components/not-forwarding.component.html

@@ -0,0 +1 @@
+<button class="tn-button">{{ label() }}</button>

package/scripts/icon-sprite/__fixtures__/forwarding-components/not-forwarding.component.ts

@@ -0,0 +1,10 @@
+import { Component, input } from '@angular/core';
+
+@Component({
+  selector: 'tn-button',
+  standalone: true,
+  templateUrl: './not-forwarding.component.html',
+})
+export class TnButtonComponent {
+  label = input<string>('');
+}

package/scripts/icon-sprite/__fixtures__/forwarding-components/single-icon.component.html

@@ -0,0 +1,3 @@
+@if (icon()) {
+  <tn-icon [name]="icon()!" [library]="iconLibrary()" />
+}

package/scripts/icon-sprite/__fixtures__/forwarding-components/single-icon.component.ts

@@ -0,0 +1,13 @@
+import { Component, input } from '@angular/core';
+import type { TnIconForwardingComponent } from '../icon/icon-forwarding';
+import type { IconLibraryType } from '../icon/icon.component';
+
+@Component({
+  selector: 'tn-empty',
+  standalone: true,
+  templateUrl: './single-icon.component.html',
+})
+export class TnEmptyComponent implements TnIconForwardingComponent {
+  icon = input<string>();
+  iconLibrary = input<IconLibraryType>('mdi');
+}

package/scripts/icon-sprite/__fixtures__/marker-sources/icons.ts

@@ -0,0 +1,24 @@
+import { tnIconMarker } from '../lib/icon/icon-marker';
+import { libIconMarker } from '../lib/icon/icon-marker';
+
+// MDI icons
+const saveIcon = tnIconMarker('content-save', 'mdi');
+const deleteIcon = tnIconMarker('delete', 'mdi');
+
+// Material icons
+const checkIcon = tnIconMarker('check_circle', 'material');
+
+// Custom icon
+const logoIcon = tnIconMarker('my-logo', 'custom');
+
+// No library
+const rawIcon = tnIconMarker('some-icon');
+
+// Library internal
+const datasetIcon = libIconMarker('tn-dataset');
+
+// Array of icons
+const actions = [
+  { name: 'Edit', icon: tnIconMarker('pencil', 'mdi') },
+  { name: 'Remove', icon: tnIconMarker('trash-can', 'mdi') },
+];

package/scripts/icon-sprite/cli-main.ts

@@ -5,6 +5,7 @@
  *
  * Usage:
  *   npx truenas-icons generate [options]
+ *   npx truenas-icons validate [options]
  *
  * Options:
  *   --src <dirs>        Comma-separated source directories to scan (default: ./src/lib,./src/app)
@@ -25,6 +26,8 @@
  */
 
 import { generateSprite } from './generate-sprite.js';
+import { validateIcons, printValidationReport } from './lib/validate-icons.js';
+import { resolveConfig } from './sprite-config-interface.js';
 import fs from 'fs';
 import path from 'path';
 
@@ -33,6 +36,11 @@ truenas-icons - Icon sprite generation for TrueNAS UI components
 
 Usage:
   npx truenas-icons generate [options]
+  npx truenas-icons validate [options]
+
+Commands:
+  generate            Scan source files and generate the icon sprite
+  validate            Check for missing or stale icons without rebuilding
 
 Options:
   --src <dirs>        Comma-separated source directories to scan
@@ -67,6 +75,9 @@ Examples:
   # Generate with defaults
   npx truenas-icons generate
 
+  # Validate current sprite against code
+  npx truenas-icons validate
+
   # Specify custom source directories
   npx truenas-icons generate --src ./src,./app
 
@@ -94,8 +105,8 @@ function parseArgs() {
 
     if (arg === '--help' || arg === '-h') {
       parsed.showHelp = true;
-    } else if (arg === 'generate') {
-      parsed.command = 'generate';
+    } else if (arg === 'generate' || arg === 'validate') {
+      parsed.command = arg;
     } else if (arg === '--src') {
       parsed.srcDirs = args[++i]?.split(',') || null;
     } else if (arg === '--output') {
@@ -143,8 +154,8 @@ async function main() {
     process.exit(0);
   }
 
-  if (!args.command || args.command !== 'generate') {
-    console.error('Error: No command specified. Use "generate" to create icon sprite.');
+  if (!args.command || !['generate', 'validate'].includes(args.command)) {
+    console.error('Error: No command specified. Use "generate" or "validate".');
     console.log('\nRun "truenas-icons --help" for usage information.');
     process.exit(1);
   }
@@ -162,11 +173,19 @@ async function main() {
       projectRoot: process.cwd(),
     };
 
-    console.log('Generating icon sprite...\n');
-    await generateSprite(config);
-    console.log('\nIcon sprite generated successfully!');
+    if (args.command === 'generate') {
+      console.log('Generating icon sprite...\n');
+      await generateSprite(config);
+      console.log('\nIcon sprite generated successfully!');
+    } else if (args.command === 'validate') {
+      console.log('Validating icon sprite...\n');
+      const resolved = resolveConfig(config);
+      const result = validateIcons(resolved);
+      const exitCode = printValidationReport(result);
+      process.exit(exitCode);
+    }
   } catch (error: any) {
-    console.error('\nError generating sprite:', error.message);
+    console.error('\nError:', error.message);
     process.exit(1);
   }
 }

package/scripts/icon-sprite/generate-sprite.ts

@@ -2,6 +2,7 @@ import crypto from 'crypto';
 import fs from 'fs';
 import { resolve } from 'path';
 import { buildSprite } from './lib/build-sprite';
+import { discoverForwardingMappings } from './lib/find-icons-in-forwarding-components';
 import { findIconsInTemplates } from './lib/find-icons-in-templates';
 import { findIconsWithMarker } from './lib/find-icons-with-marker';
 import { getIconPaths } from './lib/get-icon-paths';
@@ -35,17 +36,27 @@ export async function generateSprite(config: SpriteGeneratorConfig = {}): Promis
       console.info(`Loaded ${libraryIcons.size} icon(s) from truenas-ui library`);
     }
 
+    // Discover icon-forwarding components from source dirs AND from the library
+    const forwardingMappings = discoverForwardingMappings(srcDirs, resolved.projectRoot);
+    if (forwardingMappings.length > 0) {
+      console.info(`Discovered ${forwardingMappings.length} icon-forwarding component(s):`);
+      for (const mapping of forwardingMappings) {
+        const slots = mapping.iconSlots.map(s => s.iconAttribute).join(', ');
+        console.info(`  ${mapping.selector} → [${slots}]`);
+      }
+    }
+
     // Scan all source directories for icon usage, skipping icons already in library
     const templateIcons = new Set<string>();
     const markerIcons = new Set<string>();
 
     for (const srcDir of srcDirs) {
       if (fs.existsSync(srcDir)) {
-        const dirTemplateIcons = findIconsInTemplates(srcDir, libraryIcons);
-        const dirMarkerIcons = findIconsWithMarker(srcDir, libraryIcons);
+        const dirTemplateResult = findIconsInTemplates(srcDir, libraryIcons, forwardingMappings);
+        const dirMarkerResult = findIconsWithMarker(srcDir, libraryIcons);
 
-        dirTemplateIcons.forEach(icon => templateIcons.add(icon));
-        dirMarkerIcons.forEach(icon => markerIcons.add(icon));
+        dirTemplateResult.icons.forEach(icon => templateIcons.add(icon));
+        dirMarkerResult.icons.forEach(icon => markerIcons.add(icon));
       } else {
         console.warn(`Source directory not found, skipping: ${srcDir}`);
       }

package/scripts/icon-sprite/jest.config.ts

@@ -0,0 +1,14 @@
+import type { Config } from 'jest';
+
+const config: Config = {
+  testEnvironment: 'node',
+  transform: {
+    '^.+\\.tsx?$': ['ts-jest', {
+      tsconfig: '<rootDir>/tsconfig.json',
+    }],
+  },
+  testMatch: ['<rootDir>/**/*.spec.ts'],
+  moduleFileExtensions: ['ts', 'js', 'json'],
+};
+
+export default config;

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

@@ -0,0 +1,77 @@
+import path from 'path';
+import { findForwardingComponentMappings } from './find-icons-in-forwarding-components';
+
+const FIXTURES_DIR = path.resolve(__dirname, '../__fixtures__/forwarding-components');
+
+describe('findForwardingComponentMappings', () => {
+  it('should discover components implementing TnIconForwardingComponent', () => {
+    const mappings = findForwardingComponentMappings([FIXTURES_DIR]);
+    const selectors = mappings.map(m => m.selector).sort();
+    expect(selectors).toEqual(['tn-chip', 'tn-empty', 'tn-input']);
+  });
+
+  it('should not discover components that do not implement the interface', () => {
+    const mappings = findForwardingComponentMappings([FIXTURES_DIR]);
+    const selectors = mappings.map(m => m.selector);
+    expect(selectors).not.toContain('tn-button');
+  });
+
+  it('should extract single icon slot with library from tn-empty', () => {
+    const mappings = findForwardingComponentMappings([FIXTURES_DIR]);
+    const empty = mappings.find(m => m.selector === 'tn-empty');
+
+    expect(empty).toBeDefined();
+    expect(empty!.iconSlots).toHaveLength(1);
+    expect(empty!.iconSlots[0]).toEqual({
+      iconAttribute: 'icon',
+      libraryAttribute: 'iconLibrary',
+      defaultLibrary: 'mdi',
+    });
+  });
+
+  it('should extract multiple icon slots from tn-input', () => {
+    const mappings = findForwardingComponentMappings([FIXTURES_DIR]);
+    const input = mappings.find(m => m.selector === 'tn-input');
+
+    expect(input).toBeDefined();
+    expect(input!.iconSlots).toHaveLength(2);
+
+    const attrNames = input!.iconSlots.map(s => s.iconAttribute).sort();
+    expect(attrNames).toEqual(['prefixIcon', 'suffixIcon']);
+
+    const prefix = input!.iconSlots.find(s => s.iconAttribute === 'prefixIcon');
+    expect(prefix!.libraryAttribute).toBe('prefixIconLibrary');
+
+    const suffix = input!.iconSlots.find(s => s.iconAttribute === 'suffixIcon');
+    expect(suffix!.libraryAttribute).toBe('suffixIconLibrary');
+  });
+
+  it('should handle component with no library attribute (tn-chip)', () => {
+    const mappings = findForwardingComponentMappings([FIXTURES_DIR]);
+    const chip = mappings.find(m => m.selector === 'tn-chip');
+
+    expect(chip).toBeDefined();
+    expect(chip!.iconSlots).toHaveLength(1);
+    expect(chip!.iconSlots[0].iconAttribute).toBe('icon');
+    expect(chip!.iconSlots[0].libraryAttribute).toBeUndefined();
+    expect(chip!.iconSlots[0].defaultLibrary).toBeUndefined();
+  });
+
+  it('should return empty array for directory with no forwarding components', () => {
+    const mappings = findForwardingComponentMappings([path.resolve(__dirname, '../__fixtures__/custom-icons')]);
+    expect(mappings).toEqual([]);
+  });
+
+  it('should return empty array for non-existent directory', () => {
+    const mappings = findForwardingComponentMappings(['/non/existent/path']);
+    expect(mappings).toEqual([]);
+  });
+
+  it('should deduplicate results from overlapping search paths', () => {
+    // Pass the same path twice — duplicates should be removed by selector
+    const mappings = findForwardingComponentMappings([FIXTURES_DIR, FIXTURES_DIR]);
+    expect(mappings).toHaveLength(3);
+    const selectors = mappings.map(m => m.selector).sort();
+    expect(selectors).toEqual(['tn-chip', 'tn-empty', 'tn-input']);
+  });
+});

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

@@ -0,0 +1,209 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'fs';
+import path from 'path';
+import { resolve } from 'path';
+import * as cheerio from 'cheerio';
+
+export interface IconSlotMapping {
+  iconAttribute: string;
+  libraryAttribute?: string;
+  defaultLibrary?: string;
+}
+
+export interface ForwardingComponentMapping {
+  selector: string;
+  iconSlots: IconSlotMapping[];
+}
+
+/**
+ * Discovers components implementing TnIconForwardingComponent and derives
+ * their icon attribute mappings by reading their templates.
+ *
+ * Steps:
+ * 1. Grep for `implements TnIconForwardingComponent` (or `implements.*TnIconForwardingComponent`)
+ * 2. Extract the @Component selector and templateUrl from the same file
+ * 3. Read the component template and find <tn-icon> [name] / [library] bindings
+ * 4. Map binding expressions back to input names (strip signal call syntax)
+ * 5. Extract default library values from input declarations in the TS file
+ */
+export function findForwardingComponentMappings(searchPaths: string[]): ForwardingComponentMapping[] {
+  const bySelector = new Map<string, ForwardingComponentMapping>();
+  const componentFiles = findForwardingComponentFiles(searchPaths);
+
+  for (const filePath of componentFiles) {
+    const mapping = extractMappingFromComponent(filePath);
+    if (mapping && !bySelector.has(mapping.selector)) {
+      bySelector.set(mapping.selector, mapping);
+    }
+  }
+
+  return [...bySelector.values()];
+}
+
+/**
+ * Discover icon-forwarding component mappings from consumer source dirs
+ * and the installed library (if present in node_modules).
+ */
+export function discoverForwardingMappings(srcDirs: string[], projectRoot: string): ForwardingComponentMapping[] {
+  const searchPaths = [...srcDirs];
+
+  const libSrcPath = resolve(projectRoot, 'node_modules/@truenas/ui-components/src/lib');
+  if (fs.existsSync(libSrcPath)) {
+    searchPaths.push(libSrcPath);
+  }
+
+  return findForwardingComponentMappings(searchPaths);
+}
+
+/**
+ * Grep for .ts files containing `implements TnIconForwardingComponent`
+ * (handles multi-interface: `implements TnIconForwardingComponent, AfterViewInit`)
+ */
+function findForwardingComponentFiles(searchPaths: string[]): string[] {
+  const files: string[] = [];
+
+  for (const searchPath of searchPaths) {
+    if (!fs.existsSync(searchPath)) {
+      continue;
+    }
+
+    const result = spawnSync(
+      'grep',
+      ['-rl', 'implements.*TnIconForwardingComponent', '--include=*.ts', searchPath],
+      { encoding: 'utf-8' },
+    );
+
+    if (result.status === 1 && !result.stderr) {
+      // grep returns exit code 1 when no matches found
+      continue;
+    }
+    if (result.status !== 0 && result.status !== 1) {
+      throw new Error(`grep failed: ${result.stderr}`);
+    }
+
+    result.stdout
+      .split('\n')
+      .filter(Boolean)
+      .forEach((file) => files.push(file));
+  }
+
+  return files;
+}
+
+/**
+ * Extract the forwarding component mapping from a single component .ts file.
+ *
+ * Reads the TS file to get the selector and templateUrl, then reads the
+ * template to find <tn-icon> bindings and maps them back to input names.
+ */
+function extractMappingFromComponent(tsFilePath: string): ForwardingComponentMapping | null {
+  const tsContent = fs.readFileSync(tsFilePath, 'utf-8');
+
+  // Extract selector from @Component({ selector: '...' })
+  const selectorMatch = /selector:\s*['"]([^'"]+)['"]/.exec(tsContent);
+  if (!selectorMatch) {
+    return null;
+  }
+  const selector = selectorMatch[1];
+
+  // Extract templateUrl from @Component({ templateUrl: '...' })
+  const templateUrlMatch = /templateUrl:\s*['"]([^'"]+)['"]/.exec(tsContent);
+  if (!templateUrlMatch) {
+    return null;
+  }
+
+  // Resolve template path relative to the TS file
+  const templatePath = path.resolve(path.dirname(tsFilePath), templateUrlMatch[1]);
+  if (!fs.existsSync(templatePath)) {
+    return null;
+  }
+
+  const templateContent = fs.readFileSync(templatePath, 'utf-8');
+  const iconSlots = extractIconSlotsFromTemplate(templateContent, tsContent);
+
+  if (iconSlots.length === 0) {
+    return null;
+  }
+
+  return { selector, iconSlots };
+}
+
+/**
+ * Find <tn-icon> elements in the template and extract the input names
+ * from their [name] and [library] bindings.
+ *
+ * For example:
+ *   <tn-icon [name]="icon()!" [library]="iconLibrary()">
+ *   yields: { iconAttribute: 'icon', libraryAttribute: 'iconLibrary' }
+ *
+ *   <tn-icon [name]="prefixIcon()!">
+ *   yields: { iconAttribute: 'prefixIcon' }
+ */
+function extractIconSlotsFromTemplate(templateContent: string, tsContent: string): IconSlotMapping[] {
+  const $ = cheerio.load(templateContent);
+  const slots: IconSlotMapping[] = [];
+
+  $('tn-icon').each((_, el) => {
+    const boundName = $(el).attr('[name]');
+    if (!boundName) {
+      return;
+    }
+
+    // Extract the signal/input name from the binding expression
+    // Handles: "icon()", "icon()!", "prefixIcon()!", etc.
+    const inputName = extractInputName(boundName);
+    if (!inputName) {
+      return;
+    }
+
+    const slot: IconSlotMapping = { iconAttribute: inputName };
+
+    // Check for [library] binding on the same <tn-icon>
+    const boundLibrary = $(el).attr('[library]');
+    if (boundLibrary) {
+      const libraryInputName = extractInputName(boundLibrary);
+      if (libraryInputName) {
+        slot.libraryAttribute = libraryInputName;
+
+        // Try to extract the default value from the input declaration in the TS
+        const defaultLibrary = extractInputDefault(tsContent, libraryInputName);
+        if (defaultLibrary) {
+          slot.defaultLibrary = defaultLibrary;
+        }
+      }
+    }
+
+    slots.push(slot);
+  });
+
+  return slots;
+}
+
+/**
+ * Extract a simple input/signal name from a template binding expression.
+ *
+ * Matches patterns like:
+ *   "icon()"     -> "icon"
+ *   "icon()!"    -> "icon"
+ *   "prefixIcon()!" -> "prefixIcon"
+ *
+ * Returns null for complex expressions (ternaries, method calls with args, etc.)
+ * since those represent computed values, not direct input forwarding.
+ */
+function extractInputName(expression: string): string | null {
+  const match = /^\s*(\w+)\(\)!?\s*$/.exec(expression);
+  return match ? match[1] : null;
+}
+
+/**
+ * Extract the default value from an Angular input declaration.
+ *
+ * Matches patterns like:
+ *   iconLibrary = input<IconLibraryType>('mdi')  -> "mdi"
+ *   iconLibrary = input('mdi')                    -> "mdi"
+ */
+function extractInputDefault(tsContent: string, inputName: string): string | null {
+  const regex = new RegExp(`${inputName}\\s*=\\s*input[^(]*\\(\\s*['"]([^'"]+)['"]`);
+  const match = regex.exec(tsContent);
+  return match ? match[1] : null;
+}