@truenas/ui-components 0.1.46 → 0.1.47

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

@@ -0,0 +1,185 @@
+import fs from 'fs';
+import { resolve } from 'path';
+import { discoverForwardingMappings } from './find-icons-in-forwarding-components';
+import { findIconsInTemplates } from './find-icons-in-templates';
+import type { ScanResult } from './find-icons-in-templates';
+import { findIconsWithMarker } from './find-icons-with-marker';
+import type { ResolvedSpriteConfig } from '../sprite-config-interface';
+
+export interface ValidationResult {
+  scannedIcons: Set<string>;
+  spriteIcons: Set<string>;
+  missingFromSprite: Set<string>;
+  staleInSprite: Set<string>;
+  sources: Map<string, string[]>;
+  spriteConfigFound: boolean;
+}
+
+/**
+ * Validates icon usage against the current sprite manifest.
+ * Reports missing icons (in code but not in sprite) and stale icons (in sprite but not in code).
+ */
+export function validateIcons(resolved: ResolvedSpriteConfig): ValidationResult {
+  const srcDirs = resolved.srcDirs.map(dir => resolve(resolved.projectRoot, dir));
+  const configPath = resolve(resolved.projectRoot, resolved.outputDir, 'sprite-config.json');
+
+  // Load library icons
+  const libraryIcons = loadLibraryIconsForValidation(resolved.projectRoot);
+
+  // Discover forwarding component mappings
+  const forwardingMappings = discoverForwardingMappings(srcDirs, resolved.projectRoot);
+
+  // Scan all source directories
+  const allSources = new Map<string, string[]>();
+  const scannedIcons = new Set<string>();
+
+  for (const srcDir of srcDirs) {
+    if (!fs.existsSync(srcDir)) {
+      continue;
+    }
+
+    const templateResult = findIconsInTemplates(srcDir, libraryIcons, forwardingMappings);
+    const markerResult = findIconsWithMarker(srcDir, libraryIcons);
+
+    mergeScanResult(scannedIcons, allSources, templateResult);
+    mergeScanResult(scannedIcons, allSources, markerResult);
+  }
+
+  // Include library icons in the scanned set (they're expected in the sprite)
+  for (const icon of libraryIcons) {
+    scannedIcons.add(icon);
+  }
+
+  // Include custom icons (they're always added to the sprite by generate)
+  if (resolved.customIconsDir) {
+    const customDir = resolve(resolved.projectRoot, resolved.customIconsDir);
+    if (fs.existsSync(customDir)) {
+      for (const filename of fs.readdirSync(customDir)) {
+        if (filename.endsWith('.svg')) {
+          scannedIcons.add(`tn-${filename.replace('.svg', '')}`);
+        }
+      }
+    }
+  }
+
+  // Load existing sprite config
+  let spriteIcons = new Set<string>();
+  let spriteConfigFound = false;
+
+  if (fs.existsSync(configPath)) {
+    spriteConfigFound = true;
+    try {
+      const config = JSON.parse(fs.readFileSync(configPath, 'utf-8'));
+      spriteIcons = new Set<string>(config.icons || []);
+    } catch {
+      // Corrupt config — treat as empty
+    }
+  }
+
+  // Compute differences
+  const missingFromSprite = new Set<string>();
+  for (const icon of scannedIcons) {
+    if (!spriteIcons.has(icon)) {
+      missingFromSprite.add(icon);
+    }
+  }
+
+  const staleInSprite = new Set<string>();
+  for (const icon of spriteIcons) {
+    if (!scannedIcons.has(icon)) {
+      staleInSprite.add(icon);
+    }
+  }
+
+  return {
+    scannedIcons,
+    spriteIcons,
+    missingFromSprite,
+    staleInSprite,
+    sources: allSources,
+    spriteConfigFound,
+  };
+}
+
+/**
+ * Prints the validation report to stdout.
+ * Returns the appropriate exit code (0 = clean, 1 = missing icons).
+ */
+export function printValidationReport(result: ValidationResult): number {
+  console.log('Icon Sprite Validation Report');
+  console.log('==============================\n');
+
+  if (!result.spriteConfigFound) {
+    console.log('⚠ No sprite-config.json found. Run "npx truenas-icons generate" first.\n');
+    console.log(`Scanned: ${result.scannedIcons.size} icon(s) across templates and markers`);
+    return 1;
+  }
+
+  console.log(`Scanned: ${result.scannedIcons.size} icon(s) across templates and markers`);
+  console.log(`Sprite:  ${result.spriteIcons.size} icon(s) in current sprite\n`);
+
+  if (result.missingFromSprite.size > 0) {
+    console.log(`Missing from sprite (${result.missingFromSprite.size} new icon(s) found):`);
+    for (const icon of [...result.missingFromSprite].sort()) {
+      const sourceFiles = result.sources.get(icon);
+      const sourceHint = sourceFiles?.length
+        ? ` (from ${sourceFiles[0]})`
+        : '';
+      console.log(`  + ${icon}${sourceHint}`);
+    }
+    console.log('');
+  }
+
+  if (result.staleInSprite.size > 0) {
+    console.log(`Stale icons (${result.staleInSprite.size} in sprite but not referenced):`);
+    for (const icon of [...result.staleInSprite].sort()) {
+      console.log(`  - ${icon}`);
+    }
+    console.log('');
+  }
+
+  if (result.missingFromSprite.size === 0 && result.staleInSprite.size === 0) {
+    console.log('✓ Sprite is up to date — no missing or stale icons.\n');
+    return 0;
+  }
+
+  if (result.missingFromSprite.size > 0) {
+    console.log('Run "npx truenas-icons generate" to rebuild the sprite.\n');
+    return 1;
+  }
+
+  return 0;
+}
+
+function mergeScanResult(
+  icons: Set<string>,
+  sources: Map<string, string[]>,
+  result: ScanResult,
+): void {
+  for (const icon of result.icons) {
+    icons.add(icon);
+  }
+  for (const [icon, files] of result.sources) {
+    const existing = sources.get(icon) || [];
+    existing.push(...files);
+    sources.set(icon, existing);
+  }
+}
+
+function loadLibraryIconsForValidation(projectRoot: string): Set<string> {
+  const librarySpritePath = resolve(
+    projectRoot,
+    'node_modules/@truenas/ui-components/assets/tn-icons/sprite-config.json'
+  );
+
+  if (!fs.existsSync(librarySpritePath)) {
+    return new Set<string>();
+  }
+
+  try {
+    const config = JSON.parse(fs.readFileSync(librarySpritePath, 'utf-8'));
+    return new Set<string>(config.icons || []);
+  } catch {
+    return new Set<string>();
+  }
+}

package/scripts/icon-sprite/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "Node16",
+    "moduleResolution": "Node16",
+    "esModuleInterop": true,
+    "isolatedModules": true,
+    "strict": true,
+    "types": ["jest", "node"],
+    "rootDir": ".",
+    "outDir": "../../dist/out-tsc/scripts"
+  },
+  "include": ["**/*.ts"]
+}

package/types/truenas-ui-components.d.ts

@@ -628,6 +628,7 @@ interface IconResult {
     spriteUrl?: string;
 }
 declare class TnIconComponent {
+    private static warnedIcons;
     name: _angular_core.InputSignal<string>;
     size: _angular_core.InputSignal<IconSize>;
     color: _angular_core.InputSignal<string | undefined>;
@@ -658,6 +659,12 @@ declare class TnIconComponent {
     private tryCssIcon;
     private tryUnicodeIcon;
     private generateTextAbbreviation;
+    /**
+     * Warns once per icon name in dev mode when a sprite-prefixed icon is not
+     * found in the sprite. Only fires when the sprite is loaded and the icon
+     * name has a prefix indicating it should be a sprite icon.
+     */
+    private warnMissingSpriteIcon;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<TnIconComponent, never>;
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<TnIconComponent, "tn-icon", never, { "name": { "alias": "name"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "color": { "alias": "color"; "required": false; "isSignal": true; }; "tooltip": { "alias": "tooltip"; "required": false; "isSignal": true; }; "ariaLabel": { "alias": "ariaLabel"; "required": false; "isSignal": true; }; "library": { "alias": "library"; "required": false; "isSignal": true; }; "fullSize": { "alias": "fullSize"; "required": false; "isSignal": true; }; "customSize": { "alias": "customSize"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
@@ -832,7 +839,38 @@ declare enum InputType {
     PlainText = "text"
 }
 
-declare class TnInputComponent implements AfterViewInit, ControlValueAccessor {
+/**
+ * Marker interface for components that forward icon inputs to `<tn-icon>`.
+ *
+ * When a component implements this interface, the sprite generation scanner
+ * will read its template to discover which inputs map to `<tn-icon>` `[name]`
+ * and `[library]` bindings, then scan consumer templates for those attributes.
+ *
+ * This means icons passed as template attributes to these components are
+ * automatically included in the sprite — no `tnIconMarker()` needed.
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   selector: 'tn-empty',
+ *   templateUrl: './empty.component.html',
+ * })
+ * export class TnEmptyComponent implements TnIconForwardingComponent {
+ *   icon = input<string>();
+ *   iconLibrary = input<IconLibraryType>('mdi');
+ * }
+ * ```
+ *
+ * The scanner will detect that `tn-empty` forwards `icon` to `<tn-icon [name]>`,
+ * so `<tn-empty icon="inbox">` in consumer templates will automatically include
+ * `mdi-inbox` in the sprite.
+ *
+ * @public
+ */
+interface TnIconForwardingComponent {
+}
+
+declare class TnInputComponent implements TnIconForwardingComponent, AfterViewInit, ControlValueAccessor {
     inputEl: _angular_core.Signal<ElementRef<HTMLInputElement | HTMLTextAreaElement>>;
     inputType: _angular_core.InputSignal<InputType>;
     placeholder: _angular_core.InputSignal<string>;
@@ -1174,7 +1212,7 @@ declare class TnInputDirective {
 }
 
 type ChipColor = 'primary' | 'secondary' | 'accent';
-declare class TnChipComponent implements AfterViewInit, OnDestroy {
+declare class TnChipComponent implements TnIconForwardingComponent, AfterViewInit, OnDestroy {
     chipEl: _angular_core.Signal<ElementRef<HTMLElement>>;
     label: _angular_core.InputSignal<string>;
     icon: _angular_core.InputSignal<string | undefined>;
@@ -5514,7 +5552,7 @@ declare class TnFilePickerPopupComponent implements OnInit, AfterViewInit, After
 }
 
 type TnEmptySize = 'default' | 'compact';
-declare class TnEmptyComponent {
+declare class TnEmptyComponent implements TnIconForwardingComponent {
     title: _angular_core.InputSignal<string>;
     description: _angular_core.InputSignal<string | undefined>;
     icon: _angular_core.InputSignal<string | undefined>;
@@ -6062,4 +6100,4 @@ declare const TN_THEME_DEFINITIONS: readonly TnThemeDefinition[];
 declare const THEME_MAP: Map<TnTheme, TnThemeDefinition>;
 
 export { CommonShortcuts, DEFAULT_THEME, DiskIconComponent, DiskType, FileSizePipe, InputType, LIGHT_THEME, LinuxModifierKeys, LinuxShortcuts, ModifierKeys, QuickShortcuts, ShortcutBuilder, StripMntPrefixPipe, THEME_MAP, THEME_STORAGE_KEY, TN_THEME_DEFINITIONS, TnAutocompleteComponent, TnAutocompleteHarness, TnBannerActionDirective, TnBannerComponent, TnBannerHarness, TnBrandedSpinnerComponent, TnButtonComponent, TnButtonHarness, TnButtonToggleComponent, TnButtonToggleGroupComponent, TnButtonToggleGroupHarness, TnButtonToggleHarness, TnCalendarComponent, TnCalendarHeaderComponent, TnCardComponent, TnCellDefDirective, TnCheckboxComponent, TnCheckboxHarness, TnCheckboxLabelDirective, TnChipComponent, TnConfirmDialogComponent, TnDateInputComponent, TnDateInputHarness, TnDateRangeInputComponent, TnDateRangeInputHarness, TnDetailRowDefDirective, TnDialog, TnDialogHarness, TnDialogShellComponent, TnDialogTesting, TnDividerComponent, TnDividerDirective, TnDrawerComponent, TnDrawerContainerComponent, TnDrawerContainerHarness, TnDrawerContentComponent, TnDrawerHarness, TnEmptyComponent, TnEmptyHarness, TnExpansionPanelComponent, TnExpansionPanelHarness, TnFilePickerComponent, TnFilePickerPopupComponent, TnFormFieldComponent, TnFormFieldHarness, TnHeaderCellDefDirective, TnIconButtonComponent, TnIconButtonHarness, TnIconComponent, TnIconHarness, TnIconRegistryService, TnIconTesting, TnInputComponent, TnInputDirective, TnInputHarness, TnKeyboardShortcutComponent, TnKeyboardShortcutService, TnListAvatarDirective, TnListComponent, TnListIconDirective, TnListItemComponent, TnListItemLineDirective, TnListItemPrimaryDirective, TnListItemSecondaryDirective, TnListItemTitleDirective, TnListItemTrailingDirective, TnListOptionComponent, TnListSubheaderComponent, TnMenuActivateHoverDirective, TnMenuComponent, TnMenuHarness, TnMenuTesting, TnMenuTriggerDirective, TnMonthViewComponent, TnMultiYearViewComponent, TnNestedTreeNodeComponent, TnParticleProgressBarComponent, TnProgressBarComponent, TnRadioComponent, TnRadioHarness, TnSelectComponent, TnSelectHarness, TnSelectionListComponent, TnSidePanelActionDirective, TnSidePanelComponent, TnSidePanelHarness, TnSidePanelHeaderActionDirective, TnSlideToggleComponent, TnSlideToggleHarness, TnSliderComponent, TnSliderThumbDirective, TnSliderWithLabelDirective, TnSpinnerComponent, TnSpriteLoaderService, TnStepComponent, TnStepperComponent, TnTabComponent, TnTabHarness, TnTabPanelComponent, TnTabPanelHarness, TnTableColumnDirective, TnTableComponent, TnTableHarness, TnTabsComponent, TnTabsHarness, TnTheme, TnThemeService, TnTimeInputComponent, TnToastComponent, TnToastMock, TnToastPosition, TnToastRef, TnToastService, TnToastTesting, TnToastType, TnTooltipComponent, TnTooltipDirective, TnTreeComponent, TnTreeFlatDataSource, TnTreeFlattener, TnTreeNodeComponent, TnTreeNodeOutletDirective, TruncatePathPipe, WindowsModifierKeys, WindowsShortcuts, createLucideLibrary, createShortcut, defaultSpriteBasePath, defaultSpriteConfigPath, libIconMarker, registerLucideIcons, setupLucideIntegration, tnIconMarker };
-export type { AutocompleteHarnessFilters, BannerHarnessFilters, ButtonHarnessFilters, ButtonToggleHarnessFilters, CalendarCell, CheckboxHarnessFilters, ChipColor, CreateFolderEvent, DateInputHarnessFilters, DateRange, DateRangeInputHarnessFilters, DialogHarnessFilters, EmptyHarnessFilters, ExpansionPanelHarnessFilters, FilePickerCallbacks, FilePickerError, FilePickerMode, FileSystemItem, FormFieldHarnessFilters, IconButtonHarnessFilters, IconHarnessFilters, IconLibrary, IconLibraryType, IconResult, IconSize, IconSource, IconTestingMockOverrides, InputHarnessFilters, KeyCombination, LabelType, LucideIconOptions, MenuHarnessFilters, MockIconRegistry, MockSpriteLoader, PathSegment, PlatformType, ProgressBarMode, RadioHarnessFilters, ResolvedIcon, SelectHarnessFilters, ShortcutHandler, SidePanelHarnessFilters, SlideToggleColor, SlideToggleHarnessFilters, SpinnerMode, SpriteConfig, SubscriptSizing, TabChangeEvent, TabHarnessFilters, TabPanelHarnessFilters, TabsHarnessFilters, TnBannerType, TnButtonToggleType, TnCardAction, TnCardControl, TnCardFooterLink, TnCardHeaderStatus, TnConfirmDialogData, TnDialogDefaults, TnDialogOpenTarget, TnDrawerMode, TnDrawerPosition, TnEmptySize, TnFlatTreeNode, TnMenuItem, TnSelectOption, TnSelectOptionGroup, TnSelectionChange, TnSortEvent, TnTableDataSource, TnTableHarnessFilters, TnThemeDefinition, TnToastCall, TnToastConfig, TooltipPosition, YearCell };
+export type { AutocompleteHarnessFilters, BannerHarnessFilters, ButtonHarnessFilters, ButtonToggleHarnessFilters, CalendarCell, CheckboxHarnessFilters, ChipColor, CreateFolderEvent, DateInputHarnessFilters, DateRange, DateRangeInputHarnessFilters, DialogHarnessFilters, EmptyHarnessFilters, ExpansionPanelHarnessFilters, FilePickerCallbacks, FilePickerError, FilePickerMode, FileSystemItem, FormFieldHarnessFilters, IconButtonHarnessFilters, IconHarnessFilters, IconLibrary, IconLibraryType, IconResult, IconSize, IconSource, IconTestingMockOverrides, InputHarnessFilters, KeyCombination, LabelType, LucideIconOptions, MenuHarnessFilters, MockIconRegistry, MockSpriteLoader, PathSegment, PlatformType, ProgressBarMode, RadioHarnessFilters, ResolvedIcon, SelectHarnessFilters, ShortcutHandler, SidePanelHarnessFilters, SlideToggleColor, SlideToggleHarnessFilters, SpinnerMode, SpriteConfig, SubscriptSizing, TabChangeEvent, TabHarnessFilters, TabPanelHarnessFilters, TabsHarnessFilters, TnBannerType, TnButtonToggleType, TnCardAction, TnCardControl, TnCardFooterLink, TnCardHeaderStatus, TnConfirmDialogData, TnDialogDefaults, TnDialogOpenTarget, TnDrawerMode, TnDrawerPosition, TnEmptySize, TnFlatTreeNode, TnIconForwardingComponent, TnMenuItem, TnSelectOption, TnSelectOptionGroup, TnSelectionChange, TnSortEvent, TnTableDataSource, TnTableHarnessFilters, TnThemeDefinition, TnToastCall, TnToastConfig, TooltipPosition, YearCell };