@truenas/ui-components 0.1.46 → 0.1.48

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@truenas/ui-components",
-  "version": "0.1.46",
+  "version": "0.1.48",
   "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__/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,182 @@
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import { discoverForwardingMappings } from './find-icons-in-forwarding-components';
+import type { ForwardingComponentMapping } from './find-icons-in-forwarding-components';
+
+function writeManifest(dir: string, mappings: ForwardingComponentMapping[]): void {
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(
+    path.join(dir, 'forwarding-mappings.json'),
+    JSON.stringify(mappings),
+  );
+}
+
+describe('discoverForwardingMappings', () => {
+  let tempDir: string;
+
+  beforeEach(() => {
+    tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'fwd-mappings-'));
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempDir, { recursive: true, force: true });
+  });
+
+  describe('library manifest loading', () => {
+    it('should load mappings from the installed library manifest', () => {
+      const manifestDir = path.join(tempDir, 'node_modules/@truenas/ui-components/assets/tn-icons');
+      writeManifest(manifestDir, [
+        {
+          selector: 'tn-empty',
+          iconSlots: [{ iconAttribute: 'icon', libraryAttribute: 'iconLibrary', defaultLibrary: 'mdi' }],
+        },
+        {
+          selector: 'tn-chip',
+          iconSlots: [{ iconAttribute: 'icon' }],
+        },
+      ]);
+
+      const mappings = discoverForwardingMappings([], tempDir);
+      expect(mappings).toHaveLength(2);
+
+      const selectors = mappings.map(m => m.selector).sort();
+      expect(selectors).toEqual(['tn-chip', 'tn-empty']);
+    });
+
+    it('should extract icon slot details from manifest', () => {
+      const manifestDir = path.join(tempDir, 'node_modules/@truenas/ui-components/assets/tn-icons');
+      writeManifest(manifestDir, [
+        {
+          selector: 'tn-empty',
+          iconSlots: [{ iconAttribute: 'icon', libraryAttribute: 'iconLibrary', defaultLibrary: 'mdi' }],
+        },
+      ]);
+
+      const mappings = discoverForwardingMappings([], tempDir);
+      expect(mappings[0].iconSlots[0]).toEqual({
+        iconAttribute: 'icon',
+        libraryAttribute: 'iconLibrary',
+        defaultLibrary: 'mdi',
+      });
+    });
+
+    it('should return empty array when library is not installed', () => {
+      const mappings = discoverForwardingMappings([], tempDir);
+      expect(mappings).toEqual([]);
+    });
+
+    it('should handle corrupt library manifest gracefully', () => {
+      const manifestDir = path.join(tempDir, 'node_modules/@truenas/ui-components/assets/tn-icons');
+      fs.mkdirSync(manifestDir, { recursive: true });
+      fs.writeFileSync(path.join(manifestDir, 'forwarding-mappings.json'), 'not valid json');
+
+      const mappings = discoverForwardingMappings([], tempDir);
+      expect(mappings).toEqual([]);
+    });
+
+    it('should handle manifest with non-array content gracefully', () => {
+      const manifestDir = path.join(tempDir, 'node_modules/@truenas/ui-components/assets/tn-icons');
+      fs.mkdirSync(manifestDir, { recursive: true });
+      fs.writeFileSync(path.join(manifestDir, 'forwarding-mappings.json'), '{"not": "an array"}');
+
+      const mappings = discoverForwardingMappings([], tempDir);
+      expect(mappings).toEqual([]);
+    });
+  });
+
+  describe('consumer manifest loading', () => {
+    it('should load mappings from a consumer source directory', () => {
+      const consumerSrc = path.join(tempDir, 'src/app');
+      writeManifest(consumerSrc, [
+        {
+          selector: 'app-status',
+          iconSlots: [{ iconAttribute: 'statusIcon', libraryAttribute: 'statusIconLibrary' }],
+        },
+      ]);
+
+      const mappings = discoverForwardingMappings([consumerSrc], tempDir);
+      expect(mappings).toHaveLength(1);
+      expect(mappings[0].selector).toBe('app-status');
+    });
+
+    it('should ignore source dirs without a manifest', () => {
+      const emptySrc = path.join(tempDir, 'src/app');
+      fs.mkdirSync(emptySrc, { recursive: true });
+
+      const mappings = discoverForwardingMappings([emptySrc], tempDir);
+      expect(mappings).toEqual([]);
+    });
+
+    it('should handle non-existent source dirs', () => {
+      const mappings = discoverForwardingMappings(['/non/existent/path'], tempDir);
+      expect(mappings).toEqual([]);
+    });
+  });
+
+  describe('merging library and consumer manifests', () => {
+    it('should merge mappings from library and consumer', () => {
+      // Library provides tn-empty
+      const libraryDir = path.join(tempDir, 'node_modules/@truenas/ui-components/assets/tn-icons');
+      writeManifest(libraryDir, [
+        {
+          selector: 'tn-empty',
+          iconSlots: [{ iconAttribute: 'icon', libraryAttribute: 'iconLibrary', defaultLibrary: 'mdi' }],
+        },
+      ]);
+
+      // Consumer provides app-status
+      const consumerSrc = path.join(tempDir, 'src/app');
+      writeManifest(consumerSrc, [
+        {
+          selector: 'app-status',
+          iconSlots: [{ iconAttribute: 'statusIcon' }],
+        },
+      ]);
+
+      const mappings = discoverForwardingMappings([consumerSrc], tempDir);
+      const selectors = mappings.map(m => m.selector).sort();
+      expect(selectors).toEqual(['app-status', 'tn-empty']);
+    });
+
+    it('should allow consumer to override a library mapping by selector', () => {
+      // Library defines tn-empty with defaultLibrary: 'mdi'
+      const libraryDir = path.join(tempDir, 'node_modules/@truenas/ui-components/assets/tn-icons');
+      writeManifest(libraryDir, [
+        {
+          selector: 'tn-empty',
+          iconSlots: [{ iconAttribute: 'icon', libraryAttribute: 'iconLibrary', defaultLibrary: 'mdi' }],
+        },
+      ]);
+
+      // Consumer overrides tn-empty with a different default
+      const consumerSrc = path.join(tempDir, 'src/app');
+      writeManifest(consumerSrc, [
+        {
+          selector: 'tn-empty',
+          iconSlots: [{ iconAttribute: 'icon', libraryAttribute: 'iconLibrary', defaultLibrary: 'material' }],
+        },
+      ]);
+
+      const mappings = discoverForwardingMappings([consumerSrc], tempDir);
+      expect(mappings).toHaveLength(1);
+      expect(mappings[0].iconSlots[0].defaultLibrary).toBe('material');
+    });
+
+    it('should merge manifests from multiple consumer source dirs', () => {
+      const srcApp = path.join(tempDir, 'src/app');
+      writeManifest(srcApp, [
+        { selector: 'app-foo', iconSlots: [{ iconAttribute: 'icon' }] },
+      ]);
+
+      const srcLib = path.join(tempDir, 'src/lib');
+      writeManifest(srcLib, [
+        { selector: 'app-bar', iconSlots: [{ iconAttribute: 'barIcon' }] },
+      ]);
+
+      const mappings = discoverForwardingMappings([srcApp, srcLib], tempDir);
+      const selectors = mappings.map(m => m.selector).sort();
+      expect(selectors).toEqual(['app-bar', 'app-foo']);
+    });
+  });
+});

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

@@ -0,0 +1,68 @@
+import fs from 'fs';
+import { resolve } from 'path';
+
+export interface IconSlotMapping {
+  iconAttribute: string;
+  libraryAttribute?: string;
+  defaultLibrary?: string;
+}
+
+export interface ForwardingComponentMapping {
+  selector: string;
+  iconSlots: IconSlotMapping[];
+}
+
+/**
+ * Load forwarding component mappings from JSON manifest files.
+ *
+ * Mappings tell the sprite scanner which component attributes forward icon
+ * values to `<tn-icon>`. For example, `<tn-empty icon="inbox">` forwards
+ * its `icon` attribute to an internal `<tn-icon [name]>`.
+ *
+ * Sources (merged in order, later entries override by selector):
+ * 1. The library's published manifest at
+ *    `node_modules/@truenas/ui-components/assets/tn-icons/forwarding-mappings.json`
+ * 2. Any `forwarding-mappings.json` files found in the consumer's source dirs
+ */
+export function discoverForwardingMappings(srcDirs: string[], projectRoot: string): ForwardingComponentMapping[] {
+  const bySelector = new Map<string, ForwardingComponentMapping>();
+
+  // Load library manifest (published with the npm package)
+  const libraryMappings = loadManifest(resolve(
+    projectRoot,
+    'node_modules/@truenas/ui-components/assets/tn-icons/forwarding-mappings.json',
+  ));
+  for (const mapping of libraryMappings) {
+    bySelector.set(mapping.selector, mapping);
+  }
+
+  // Load consumer manifests from source dirs
+  for (const srcDir of srcDirs) {
+    const consumerManifest = resolve(srcDir, 'forwarding-mappings.json');
+    for (const mapping of loadManifest(consumerManifest)) {
+      bySelector.set(mapping.selector, mapping);
+    }
+  }
+
+  return [...bySelector.values()];
+}
+
+/**
+ * Read and parse a forwarding-mappings.json file.
+ * Returns an empty array if the file is missing or malformed.
+ */
+function loadManifest(filePath: string): ForwardingComponentMapping[] {
+  if (!fs.existsSync(filePath)) {
+    return [];
+  }
+
+  try {
+    const data = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    if (!Array.isArray(data)) {
+      return [];
+    }
+    return data;
+  } catch {
+    return [];
+  }
+}

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');
+    });
+  });
+});