@truenas/ui-components 0.1.2

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@truenas/ui-components",
+  "version": "0.1.2",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/iXsystems/truenas-ui-components.git"
+  },
+  "bin": {
+    "truenas-icons": "scripts/icon-sprite/cli.js"
+  },
+  "peerDependencies": {
+    "@angular/cdk": "^21.0.0",
+    "@angular/common": "^21.0.0",
+    "@angular/core": "^21.0.0",
+    "@mdi/angular-material": "^7.2.96",
+    "@mdi/js": "^7.4.47"
+  },
+  "dependencies": {
+    "@material-design-icons/svg": "~0.14.13",
+    "@mdi/svg": "~7.4.47",
+    "@types/svg-sprite": "~0.0.39",
+    "@types/vinyl": "~2.0.12",
+    "cheerio": "~1.0.0",
+    "svg-sprite": "~2.0.4",
+    "tslib": "^2.3.0",
+    "tsx": "~4.19.1",
+    "vinyl": "~3.0.0"
+  },
+  "sideEffects": false,
+  "module": "fesm2022/truenas-ui-components.mjs",
+  "typings": "types/truenas-ui-components.d.ts",
+  "exports": {
+    "./package.json": {
+      "default": "./package.json"
+    },
+    ".": {
+      "types": "./types/truenas-ui-components.d.ts",
+      "default": "./fesm2022/truenas-ui-components.mjs"
+    }
+  }
+}

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

@@ -0,0 +1,174 @@
+#!/usr/bin/env tsx
+
+/**
+ * CLI entry point for truenas-icons sprite generation
+ *
+ * Usage:
+ *   npx truenas-icons generate [options]
+ *
+ * Options:
+ *   --src <dirs>        Comma-separated source directories to scan (default: ./src/lib,./src/app)
+ *   --output <dir>      Output directory for sprite files (default: ./src/assets/icons)
+ *   --url <path>        Runtime URL path for sprite (defaults to output dir with './' stripped)
+ *   --custom <dir>      Custom icons directory (optional)
+ *   --config <file>     Configuration file path (default: truenas-icons.config.js)
+ *   --help              Show help
+ *
+ * Configuration File:
+ *   Create truenas-icons.config.js in your project root:
+ *
+ *   export default {
+ *     srcDirs: ['./src/lib', './src/app'],
+ *     outputDir: './src/assets/icons',
+ *     customIconsDir: './custom-icons'
+ *   };
+ */
+
+import { generateSprite } from './generate-sprite.js';
+import fs from 'fs';
+import path from 'path';
+
+const HELP_TEXT = `
+truenas-icons - Icon sprite generation for TrueNAS UI components
+
+Usage:
+  npx truenas-icons generate [options]
+
+Options:
+  --src <dirs>        Comma-separated source directories to scan
+                      Default: ./src/lib,./src/app
+
+  --output <dir>      Output directory for sprite files
+                      Default: ./src/assets/icons
+
+  --url <path>        Runtime URL path for sprite (in sprite-config.json)
+                      Default: output dir with './' stripped
+                      Use when build transforms paths (e.g., Angular strips 'src/')
+                      Example: --output ./src/assets/tn-icons --url assets/tn-icons
+
+  --custom <dir>      Custom icons directory (optional)
+                      Icons will be prefixed with 'tn-'
+
+  --config <file>     Configuration file path
+                      Default: truenas-icons.config.js
+
+  --help              Show this help message
+
+Configuration File:
+  Create truenas-icons.config.js in your project root:
+
+  export default {
+    srcDirs: ['./src/lib', './src/app'],
+    outputDir: './src/assets/icons',
+    customIconsDir: './custom-icons'
+  };
+
+Examples:
+  # Generate with defaults
+  npx truenas-icons generate
+
+  # Specify custom source directories
+  npx truenas-icons generate --src ./src,./app
+
+  # Specify output directory
+  npx truenas-icons generate --output ./public/icons
+
+  # Use custom icons
+  npx truenas-icons generate --custom ./my-icons
+`;
+
+function parseArgs() {
+  const args = process.argv.slice(2);
+  const parsed = {
+    command: null as string | null,
+    srcDirs: null as string[] | null,
+    outputDir: null as string | null,
+    spriteUrlPath: null as string | null,
+    customIconsDir: null as string | null,
+    configFile: 'truenas-icons.config.js',
+    showHelp: false,
+  };
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+
+    if (arg === '--help' || arg === '-h') {
+      parsed.showHelp = true;
+    } else if (arg === 'generate') {
+      parsed.command = 'generate';
+    } else if (arg === '--src') {
+      parsed.srcDirs = args[++i]?.split(',') || null;
+    } else if (arg === '--output') {
+      parsed.outputDir = args[++i] || null;
+    } else if (arg === '--url') {
+      parsed.spriteUrlPath = args[++i] || null;
+    } else if (arg === '--custom') {
+      parsed.customIconsDir = args[++i] || null;
+    } else if (arg === '--config') {
+      parsed.configFile = args[++i] || parsed.configFile;
+    }
+  }
+
+  return parsed;
+}
+
+async function loadConfig(configFile: string) {
+  const configPath = path.resolve(process.cwd(), configFile);
+
+  if (!fs.existsSync(configPath)) {
+    return {};
+  }
+
+  try {
+    // Try to load as ES module
+    const config = await import(configPath);
+    return config.default || config;
+  } catch (error) {
+    // Fallback to CommonJS
+    try {
+      const config = require(configPath);
+      return config.default || config;
+    } catch (err) {
+      console.warn(`Warning: Could not load config file: ${configPath}`);
+      return {};
+    }
+  }
+}
+
+async function main() {
+  const args = parseArgs();
+
+  if (args.showHelp) {
+    console.log(HELP_TEXT);
+    process.exit(0);
+  }
+
+  if (!args.command || args.command !== 'generate') {
+    console.error('Error: No command specified. Use "generate" to create icon sprite.');
+    console.log('\nRun "truenas-icons --help" for usage information.');
+    process.exit(1);
+  }
+
+  try {
+    // Load configuration file
+    const fileConfig = await loadConfig(args.configFile);
+
+    // Merge configurations (CLI args take precedence)
+    const config = {
+      srcDirs: args.srcDirs || fileConfig.srcDirs,
+      outputDir: args.outputDir || fileConfig.outputDir,
+      spriteUrlPath: args.spriteUrlPath || fileConfig.spriteUrlPath,
+      customIconsDir: args.customIconsDir || fileConfig.customIconsDir,
+      projectRoot: process.cwd(),
+    };
+
+    console.log('Generating icon sprite...\n');
+    await generateSprite(config);
+    console.log('\nIcon sprite generated successfully!');
+  } catch (error: any) {
+    console.error('\nError generating sprite:', error.message);
+    process.exit(1);
+  }
+}
+
+main();

package/scripts/icon-sprite/cli-wrapper.js

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+
+/**
+ * CLI wrapper that uses tsx to run the TypeScript CLI
+ * This allows us to distribute TypeScript files without needing to compile them
+ */
+
+const { spawn } = require('child_process');
+const path = require('path');
+
+// Get the directory where this script is located
+const scriptDir = __dirname;
+const tsxPath = path.join(scriptDir, '../../node_modules/.bin/tsx');
+const cliPath = path.join(scriptDir, 'cli-main.ts');
+
+// Check if tsx exists in the package
+const fs = require('fs');
+if (!fs.existsSync(path.join(scriptDir, '../../node_modules/tsx'))) {
+  console.error('Error: tsx is required but not found.');
+  console.error('This should have been installed as a dependency of truenas-ui.');
+  process.exit(1);
+}
+
+// Spawn tsx to run the TypeScript CLI
+const child = spawn('node', [tsxPath, cliPath, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+  cwd: process.cwd()
+});
+
+child.on('exit', (code) => {
+  process.exit(code || 0);
+});

package/scripts/icon-sprite/cli.js

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+
+/**
+ * CLI wrapper that uses tsx to run the TypeScript CLI
+ * This allows us to distribute TypeScript files without needing to compile them
+ */
+
+const { spawn } = require('child_process');
+const path = require('path');
+
+// Get the directory where this script is located
+const scriptDir = __dirname;
+const cliPath = path.join(scriptDir, 'cli-main.ts');
+
+// Use npx to run tsx, which will find it in node_modules
+const child = spawn('npx', ['tsx', cliPath, ...process.argv.slice(2)], {
+  stdio: 'inherit',
+  cwd: process.cwd(),
+  shell: process.platform === 'win32'
+});
+
+child.on('exit', (code) => {
+  process.exit(code || 0);
+});
+
+child.on('error', (err) => {
+  console.error('Failed to start tsx:', err.message);
+  console.error('Make sure tsx is installed as a dependency of truenas-ui.');
+  process.exit(1);
+});

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

@@ -0,0 +1,171 @@
+import crypto from 'crypto';
+import fs from 'fs';
+import { resolve } from 'path';
+import { buildSprite } from './lib/build-sprite';
+import { findIconsInTemplates } from './lib/find-icons-in-templates';
+import { findIconsWithMarker } from './lib/find-icons-with-marker';
+import { getIconPaths } from './lib/get-icon-paths';
+import { warnAboutDuplicates } from './lib/warn-about-duplicates';
+import { SpriteGeneratorConfig, resolveConfig } from './sprite-config-interface';
+
+/**
+ * Generates an icon sprite based on the provided configuration
+ *
+ * @param config - Configuration options for sprite generation
+ * @returns Promise that resolves when sprite generation is complete
+ */
+export async function generateSprite(config: SpriteGeneratorConfig = {}): Promise<void> {
+  try {
+    const resolved = resolveConfig(config);
+
+    // Resolve all paths relative to project root
+    const srcDirs = resolved.srcDirs.map(dir => resolve(resolved.projectRoot, dir));
+    const outputDir = resolve(resolved.projectRoot, resolved.outputDir);
+    const targetPath = resolve(outputDir, 'sprite.svg');
+    const configPath = resolve(outputDir, 'sprite-config.json');
+
+    // Ensure output directory exists
+    if (!fs.existsSync(outputDir)) {
+      fs.mkdirSync(outputDir, { recursive: true });
+    }
+
+    // Load library icons FIRST (if truenas-ui is installed as a dependency)
+    const libraryIcons = loadLibraryIcons(resolved.projectRoot);
+    if (libraryIcons.size > 0) {
+      console.info(`Loaded ${libraryIcons.size} icon(s) from truenas-ui library`);
+    }
+
+    // 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);
+
+        dirTemplateIcons.forEach(icon => templateIcons.add(icon));
+        dirMarkerIcons.forEach(icon => markerIcons.add(icon));
+      } else {
+        console.warn(`Source directory not found, skipping: ${srcDir}`);
+      }
+    }
+
+    // Combine library icons + consumer-specific icons
+    const consumerIconCount = templateIcons.size + markerIcons.size;
+    const usedIcons = new Set([...libraryIcons, ...templateIcons, ...markerIcons]);
+
+    if (consumerIconCount > 0) {
+      console.info(`Found ${consumerIconCount} additional icon(s) in consumer application`);
+    }
+
+    // Add custom icons if directory is specified
+    let allIcons: Set<string>;
+    if (resolved.customIconsDir) {
+      const customDir = resolve(resolved.projectRoot, resolved.customIconsDir);
+      if (fs.existsSync(customDir)) {
+        // Temporarily set __dirname context for addCustomIcons
+        // This is a workaround since addCustomIcons uses __dirname
+        allIcons = addCustomIconsFromPath(usedIcons, customDir);
+      } else {
+        console.warn(`Custom icons directory not found: ${customDir}`);
+        allIcons = usedIcons;
+      }
+    } else {
+      allIcons = usedIcons;
+    }
+
+    warnAboutDuplicates(allIcons);
+
+    if (!allIcons.size) {
+      throw new Error('No icons found in the project. Make sure your templates include <tn-icon> elements or use tnIconMarker() for dynamic icons.');
+    }
+
+    const icons = getIconPaths(allIcons, resolved.projectRoot);
+
+    const result = await buildSprite(icons);
+    const file = Object.values(result)[0].sprite;
+
+    const buffer = file.contents as Buffer;
+    const size = buffer.length / 1024;
+
+    fs.writeFileSync(targetPath, buffer);
+
+    // eslint-disable-next-line sonarjs/hashing
+    const hash = crypto.createHash('md5').update(buffer).digest('hex').slice(0, 10);
+
+    // Use configured sprite URL path (allows consumers to specify runtime URL separately from output dir)
+    const versionedUrl = `${resolved.spriteUrlPath}/sprite.svg?v=${hash}`;
+
+    fs.writeFileSync(configPath, JSON.stringify({
+      iconUrl: versionedUrl,
+      icons: Array.from(allIcons).sort()
+    }, null, 2));
+
+    console.info(`✓ Generated icon sprite with ${allIcons.size} icons (${size.toFixed(2)} KiB)`);
+    console.info(`✓ Versioned sprite URL: ${versionedUrl}`);
+    console.info(`✓ Output: ${targetPath}`);
+  } catch (error) {
+    console.error('Error when building the icon sprite:', error);
+    throw error;
+  }
+}
+
+/**
+ * Helper function to add custom icons from a specific path
+ */
+function addCustomIconsFromPath(usedIcons: Set<string>, customIconsPath: string): Set<string> {
+  const customIcons = new Set<string>();
+  const unusedCustomIcons = new Set<string>();
+
+  if (!fs.existsSync(customIconsPath)) {
+    return usedIcons;
+  }
+
+  fs.readdirSync(customIconsPath).forEach((filename) => {
+    if (!filename.endsWith('.svg')) {
+      return;
+    }
+
+    const icon = `tn-${filename.replace('.svg', '')}`;
+    if (!usedIcons.has(icon)) {
+      unusedCustomIcons.add(icon);
+    }
+
+    customIcons.add(icon);
+  });
+
+  if (unusedCustomIcons.size > 0) {
+    console.info(
+      `Including ${unusedCustomIcons.size} custom icon(s) not currently used (available for runtime)`,
+    );
+  }
+
+  return new Set([...customIcons, ...usedIcons]);
+}
+
+/**
+ * Load library icons from truenas-ui package if installed
+ * This ensures library-internal icons (chevrons, folder, etc.) are available in consumer apps
+ * Returns a Set of icon names from the library, or an empty Set if library is not installed
+ */
+function loadLibraryIcons(projectRoot: string): Set<string> {
+  const librarySpritePath = resolve(
+    projectRoot,
+    'node_modules/@truenas/ui-components/assets/tn-icons/sprite-config.json'
+  );
+
+  // Skip if truenas-ui is not installed (e.g., when building the library itself)
+  if (!fs.existsSync(librarySpritePath)) {
+    return new Set<string>();
+  }
+
+  try {
+    const libraryConfig = JSON.parse(fs.readFileSync(librarySpritePath, 'utf-8'));
+    const libraryIcons = libraryConfig.icons || [];
+    return new Set<string>(libraryIcons);
+  } catch (error) {
+    console.warn('Warning: Could not load library sprite config:', error);
+    return new Set<string>();
+  }
+}

package/scripts/icon-sprite/lib/add-custom-icons.ts

@@ -0,0 +1,33 @@
+import fs from 'fs';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+export function addCustomIcons(usedIcons: Set<string>): Set<string> {
+  // Library structure: custom icons are in assets/tn-icons/custom/ (not src/assets/)
+  const customIconsPath = resolve(__dirname, '../../../assets/tn-icons/custom');
+
+  const customIcons = new Set<string>();
+  const unusedCustomIcons = new Set<string>();
+
+  fs.readdirSync(customIconsPath).forEach((filename) => {
+    const icon = `tn-${filename.replace('.svg', '')}`;
+    if (!usedIcons.has(icon)) {
+      unusedCustomIcons.add(icon);
+    }
+
+    customIcons.add(icon);
+  });
+
+  // For a library, custom icons should always be included so consumers can use them
+  // Just log unused icons for informational purposes
+  if (unusedCustomIcons.size > 0) {
+    console.info(
+      `Including ${unusedCustomIcons.size} custom icon(s) not currently used in library components (available for consumers)`,
+    );
+  }
+
+  return new Set([...customIcons, ...usedIcons]);
+}

package/scripts/icon-sprite/lib/build-sprite.ts

@@ -0,0 +1,25 @@
+import fs from 'fs';
+import Spriter from 'svg-sprite';
+import File from 'vinyl';
+
+export type SpriteResult = Record<string, { sprite: File }>;
+
+export async function buildSprite(icons: Map<string, string>): Promise<SpriteResult> {
+  const spriter = new Spriter({
+    mode: {
+      stack: true,
+    },
+  });
+
+  icons.forEach((path, name) => {
+    try {
+      spriter.add(name, null, fs.readFileSync(path, 'utf-8'));
+    } catch (error) {
+      console.error(`Failed to add icon "${name}": `);
+      throw error;
+    }
+  });
+
+  const { result } = await spriter.compileAsync() as { result: SpriteResult };
+  return result;
+}

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

@@ -0,0 +1,108 @@
+import fs from 'fs';
+import fg from 'fast-glob';
+import * as cheerio from 'cheerio';
+
+export function findIconsInTemplates(path: string, skipIcons?: Set<string>): Set<string> {
+  const iconNames = new Set<string>();
+
+  const templates = fg.sync(`${path}/**/*.html`);
+
+  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');
+
+      const extractedNames: string[] = [];
+
+      // Handle static name attribute: name="folder"
+      if (staticName) {
+        extractedNames.push(staticName);
+      }
+
+      // Handle bound name attribute: [name]="expression"
+      // Extract string literals from the expression
+      if (boundName) {
+        // Match string literals that are values, not comparison operands
+        // This handles:
+        // - Ternary: isExpanded ? 'chevron-down' : 'chevron-right'
+        // - But skips comparisons: element.status === 'Active' ? 'check' : 'close'
+        //
+        // Strategy: Match quoted strings that come after ? or : (ternary results)
+        // or are standalone (not part of a comparison)
+        const ternaryResultRegex = /[?:]\s*['"]([^'"]+)['"]/g;
+        let match;
+        while ((match = ternaryResultRegex.exec(boundName)) !== null) {
+          const iconName = match[1];
+          // Valid icon names only contain alphanumeric, hyphens, and underscores
+          if (/^[a-z0-9\-_]+$/i.test(iconName)) {
+            extractedNames.push(iconName);
+          }
+        }
+
+        // Also handle simple string literals (no ternary, no comparison)
+        // e.g., [name]="'folder'" (though this is unusual)
+        if (!boundName.includes('?') && !boundName.includes('=')) {
+          const simpleStringRegex = /^['"]([^'"]+)['"]$/;
+          const simpleMatch = boundName.match(simpleStringRegex);
+          if (simpleMatch && /^[a-z0-9\-_]+$/i.test(simpleMatch[1])) {
+            extractedNames.push(simpleMatch[1]);
+          }
+        }
+      }
+
+      if (extractedNames.length === 0) {
+        return;
+      }
+
+      // Process each extracted name
+      extractedNames.forEach((iconName) => {
+        // Skip icons with registry format (e.g., "mdi:menu", "lucide:home")
+        // These are resolved at runtime via icon registry, not sprite
+        if (iconName.includes(':')) {
+          return;
+        }
+
+        // Determine the final icon name with appropriate prefix
+        let finalIconName: string;
+
+        // Handle library attribute - prefix the icon name with library prefix
+        if (library === 'mdi' && !iconName.startsWith('mdi-')) {
+          finalIconName = `mdi-${iconName}`;
+        } else if (library === '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-')) {
+          finalIconName = `mat-${iconName}`; // Material icons get mat- prefix
+        } else {
+          finalIconName = iconName;
+        }
+
+        // Skip if already provided by library
+        if (skipIcons?.has(finalIconName)) {
+          return;
+        }
+
+        iconNames.add(finalIconName);
+      });
+    };
+
+    // Scan tn-icon elements
+    parsedTemplate('tn-icon').each((_, iconTag) => {
+      processIconElement(iconTag);
+    });
+
+    // Scan tn-icon-button elements (they also have name and library attributes)
+    parsedTemplate('tn-icon-button').each((_, iconTag) => {
+      processIconElement(iconTag);
+    });
+  });
+
+  return iconNames;
+}

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

@@ -0,0 +1,63 @@
+import { execSync } from 'node:child_process';
+
+export function findIconsWithMarker(path: string, skipIcons?: Set<string>): Set<string> {
+  // 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 icons = new Set<string>();
+
+  try {
+    const output = execSync(command, { encoding: 'utf-8' });
+    output
+      .split('\n')
+      .filter(Boolean)
+      .forEach((line) => {
+        const [, match] = line.split(':');
+        if (!match) {
+          return;
+        }
+
+        // Extract icon name (first parameter)
+        const iconNameMatch = /'([^']+)'/.exec(match);
+        if (!iconNameMatch) {
+          return;
+        }
+
+        let iconName = iconNameMatch[1];
+
+        // Extract library parameter (second parameter) if present
+        // Look for pattern: , 'library' after the icon name
+        const libraryMatch = /,\s*'([^']+)'/.exec(match);
+        const library = libraryMatch?.[1];
+
+        // Apply prefix transformation (matching runtime tnIconMarker() logic)
+        if (library === 'mdi' && !iconName.startsWith('mdi-')) {
+          iconName = `mdi-${iconName}`;
+        } else if (library === 'custom' && !iconName.startsWith('app-')) {
+          iconName = `app-${iconName}`;
+        } else if (library === 'material' && !iconName.startsWith('mat-')) {
+          iconName = `mat-${iconName}`;
+        }
+        // Material icons get mat- prefix
+        // libIconMarker already has tn- prefix, no transformation needed
+
+        // Skip if already provided by library
+        if (skipIcons?.has(iconName)) {
+          return;
+        }
+
+        icons.add(iconName);
+      });
+  } 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;
+}