@dsai-io/tools 0.0.1

package/dist/icons/index.d.ts

@@ -0,0 +1,473 @@
+import { R as ResolvedConfig } from '../types-Idj08nad.js';
+
+/**
+ * Icon system type definitions
+ *
+ * @packageDocumentation
+ */
+/**
+ * Raw SVG data from file
+ */
+interface RawSVGData {
+    /** File path (absolute) */
+    filePath: string;
+    /** File name without extension */
+    fileName: string;
+    /** SVG content string */
+    content: string;
+    /** Original file size in bytes */
+    originalSize: number;
+}
+/**
+ * Parsed SVG data
+ */
+interface ParsedSVG {
+    /** Icon name (normalized) */
+    name: string;
+    /** Component name (PascalCase) */
+    componentName: string;
+    /** Original file name */
+    fileName: string;
+    /** SVG viewBox */
+    viewBox: string;
+    /** SVG width */
+    width?: string | number;
+    /** SVG height */
+    height?: string | number;
+    /** SVG inner content (without <svg> wrapper) */
+    innerContent: string;
+    /** Full SVG content */
+    fullContent: string;
+    /** SVG attributes */
+    attributes: Record<string, string>;
+    /** Title for accessibility */
+    title?: string;
+    /** Description for accessibility */
+    description?: string;
+}
+/**
+ * Optimized SVG data
+ */
+interface OptimizedSVG extends ParsedSVG {
+    /** Optimized file size in bytes */
+    optimizedSize: number;
+    /** Size reduction percentage */
+    sizeReduction: number;
+}
+/**
+ * Generated icon component
+ */
+interface GeneratedIcon {
+    /** Icon name */
+    name: string;
+    /** Component name */
+    componentName: string;
+    /** Generated code */
+    code: string;
+    /** Output file path */
+    outputPath: string;
+    /** Format (react, vue, svg) */
+    format: IconFormat;
+}
+/**
+ * Icon format
+ */
+type IconFormat = 'react' | 'vue' | 'svg' | 'svg-sprite';
+/**
+ * Icon build options
+ */
+interface IconBuildOptions {
+    /** Formats to generate */
+    formats?: IconFormat[];
+    /** Watch for changes */
+    watch?: boolean;
+    /** Specific icons to build (file names) */
+    icons?: string[];
+    /** Dry run - don't write files */
+    dryRun?: boolean;
+}
+/**
+ * Icon build result
+ */
+interface IconBuildResult {
+    /** Build successful */
+    success: boolean;
+    /** Generated icons */
+    icons: GeneratedIcon[];
+    /** Total icons processed */
+    totalIcons: number;
+    /** Files written */
+    filesWritten: number;
+    /** Total size reduction percentage */
+    totalSizeReduction: number;
+    /** Build errors */
+    errors: IconError[];
+    /** Build warnings */
+    warnings: IconWarning[];
+    /** Build duration in milliseconds */
+    duration: number;
+}
+/**
+ * Icon error
+ */
+interface IconError {
+    /** Icon name */
+    icon: string;
+    /** Error message */
+    message: string;
+    /** Error code */
+    code: IconErrorCode;
+}
+/**
+ * Icon error codes
+ */
+type IconErrorCode = 'SCAN_ERROR' | 'PARSE_ERROR' | 'OPTIMIZE_ERROR' | 'GENERATE_ERROR' | 'WRITE_ERROR' | 'BUILD_ERROR';
+/**
+ * Icon warning
+ */
+interface IconWarning {
+    /** Icon name */
+    icon: string;
+    /** Warning message */
+    message: string;
+}
+/**
+ * SVGO configuration
+ */
+interface SVGOConfig {
+    /** Enable multipass optimization */
+    multipass?: boolean;
+    /** Plugins to use */
+    plugins?: SVGOPlugin[];
+}
+/**
+ * SVGO plugin configuration
+ */
+interface SVGOPlugin {
+    /** Plugin name */
+    name: string;
+    /** Plugin parameters */
+    params?: Record<string, unknown>;
+}
+/**
+ * Icon template function
+ */
+type IconTemplate = (icon: OptimizedSVG) => string;
+/**
+ * Index template function
+ */
+type IndexTemplate = (icons: OptimizedSVG[]) => string;
+/**
+ * Types template function
+ */
+type TypesTemplate = (icons: OptimizedSVG[]) => string;
+/**
+ * Scanner options
+ */
+interface ScannerOptions {
+    /** Source directory */
+    sourceDir: string;
+    /** Glob patterns to include */
+    include?: string[];
+    /** Glob patterns to exclude */
+    exclude?: string[];
+}
+/**
+ * Generator options
+ */
+interface GeneratorOptions {
+    /** Custom icon template */
+    template?: IconTemplate;
+    /** Custom index template */
+    indexTemplate?: IndexTemplate;
+    /** Custom types template */
+    typesTemplate?: TypesTemplate;
+    /** Dry run - don't write files */
+    dryRun?: boolean;
+}
+
+/**
+ * SVG file scanner
+ *
+ * Scans directories for SVG files and reads their contents.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Scan directory for SVG files
+ *
+ * Uses fast-glob to find SVG files matching the specified patterns.
+ *
+ * @param options - Scanner options
+ * @returns Array of raw SVG data
+ *
+ * @example
+ * ```typescript
+ * const files = await scanSVGFiles({
+ *   sourceDir: './icons',
+ *   include: ['**\/*.svg'],
+ *   exclude: ['**\/node_modules\/**'],
+ * });
+ * ```
+ */
+declare function scanSVGFiles(options: ScannerOptions): Promise<RawSVGData[]>;
+/**
+ * Read a single SVG file
+ *
+ * @param filePath - Path to SVG file
+ * @returns Raw SVG data or null if failed
+ */
+declare function readSVGFile(filePath: string): RawSVGData | null;
+
+/**
+ * SVG parser
+ *
+ * Parses SVG content into structured data.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Parse raw SVG data into structured format
+ *
+ * Extracts viewBox, attributes, inner content, and accessibility info.
+ *
+ * @param raw - Raw SVG data
+ * @returns Parsed SVG data
+ */
+declare function parseSVG(raw: RawSVGData): ParsedSVG;
+/**
+ * Parse multiple SVG files
+ *
+ * @param rawFiles - Array of raw SVG data
+ * @returns Array of parsed SVG data
+ */
+declare function parseSVGFiles(rawFiles: RawSVGData[]): ParsedSVG[];
+/**
+ * Clean SVG content for React compatibility
+ *
+ * Converts kebab-case attributes to camelCase for JSX.
+ *
+ * @param svg - SVG content string
+ * @returns Cleaned SVG content
+ */
+declare function cleanSVGForReact(svg: string): string;
+/**
+ * Extract viewBox from SVG string
+ *
+ * @param svg - SVG content string
+ * @returns ViewBox string or default
+ */
+declare function extractViewBox(svg: string): string;
+
+/**
+ * SVG optimizer (SVGO integration)
+ *
+ * Optimizes SVG files using SVGO for smaller file sizes.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Default SVGO configuration
+ *
+ * Provides sensible defaults for icon optimization.
+ */
+declare const defaultSVGOConfig: SVGOConfig;
+/**
+ * Optimize a single SVG
+ *
+ * @param parsed - Parsed SVG data
+ * @param raw - Raw SVG data (for size comparison)
+ * @param config - SVGO configuration
+ * @returns Optimized SVG data
+ */
+declare function optimizeSVG(parsed: ParsedSVG, raw: RawSVGData, config?: SVGOConfig): Promise<OptimizedSVG>;
+/**
+ * Optimize multiple SVGs
+ *
+ * @param parsedFiles - Array of parsed SVG data
+ * @param rawFiles - Array of raw SVG data
+ * @param config - SVGO configuration
+ * @returns Array of optimized SVG data
+ */
+declare function optimizeSVGFiles(parsedFiles: ParsedSVG[], rawFiles: RawSVGData[], config?: SVGOConfig): Promise<OptimizedSVG[]>;
+/**
+ * Skip optimization and just add size metadata
+ *
+ * Useful when SVGO is not needed but the type structure is required.
+ *
+ * @param parsed - Parsed SVG data
+ * @param raw - Raw SVG data
+ * @returns Optimized SVG data (without actual optimization)
+ */
+declare function skipOptimization(parsed: ParsedSVG, raw: RawSVGData): OptimizedSVG;
+
+/**
+ * React component generator
+ *
+ * Generates React icon components from optimized SVG data.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Default React icon template
+ *
+ * Generates a forwardRef component with size, title, and aria support.
+ */
+declare const defaultReactTemplate: IconTemplate;
+/**
+ * Default React index template
+ *
+ * Exports all icon components from a single entry point.
+ */
+declare const defaultReactIndexTemplate: IndexTemplate;
+/**
+ * Default React types template
+ *
+ * Generates TypeScript types for all icons.
+ */
+declare const defaultReactTypesTemplate: TypesTemplate;
+/**
+ * Generate React icon components
+ *
+ * @param icons - Optimized SVG data
+ * @param outputDir - Output directory
+ * @param options - Generator options
+ * @returns Generated icons
+ *
+ * @example
+ * ```typescript
+ * const generated = await generateReactIcons(optimizedIcons, './dist/icons/react', {
+ *   dryRun: false,
+ * });
+ * console.log(\`Generated \${generated.length} files\`);
+ * ```
+ */
+declare function generateReactIcons(icons: OptimizedSVG[], outputDir: string, options?: GeneratorOptions): Promise<GeneratedIcon[]>;
+
+/**
+ * SVG sprite generator
+ *
+ * Generates SVG sprite files with symbol definitions.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * SVG sprite generator options
+ */
+interface SpriteOptions {
+    /** Sprite file name */
+    fileName?: string;
+    /** Generate preview HTML file */
+    generatePreview?: boolean;
+    /** Dry run - don't write files */
+    dryRun?: boolean;
+}
+/**
+ * Generate SVG sprite
+ *
+ * Creates an SVG sprite with symbol definitions for all icons.
+ *
+ * @param icons - Optimized SVG data
+ * @param outputDir - Output directory
+ * @param options - Generator options
+ * @returns Generated files
+ *
+ * @example
+ * ```typescript
+ * const generated = await generateSVGSprite(optimizedIcons, './dist/icons/sprite', {
+ *   fileName: 'icons.svg',
+ *   generatePreview: true,
+ * });
+ * ```
+ */
+declare function generateSVGSprite(icons: OptimizedSVG[], outputDir: string, options?: SpriteOptions): Promise<GeneratedIcon[]>;
+
+/**
+ * Icon naming utilities
+ *
+ * @packageDocumentation
+ */
+/**
+ * Convert string to PascalCase component name
+ *
+ * @param input - Input string (e.g., file name)
+ * @returns PascalCase component name
+ *
+ * @example
+ * ```typescript
+ * toComponentName('arrow-left') // 'ArrowLeft'
+ * toComponentName('24px-icon') // 'Icon24px'
+ * toComponentName('my_icon') // 'MyIcon'
+ * toComponentName('chevron-down-small') // 'ChevronDownSmall'
+ * ```
+ */
+declare function toComponentName(input: string): string;
+/**
+ * Convert string to kebab-case icon name
+ *
+ * @param input - Input string (e.g., component name)
+ * @returns kebab-case icon name
+ *
+ * @example
+ * ```typescript
+ * toIconName('ArrowLeft') // 'arrow-left'
+ * toIconName('ChevronDownSmall') // 'chevron-down-small'
+ * toIconName('Icon24px') // 'icon-24px'
+ * ```
+ */
+declare function toIconName(input: string): string;
+/**
+ * Validate icon name
+ *
+ * @param name - Icon name to validate
+ * @returns True if valid, false otherwise
+ */
+declare function isValidIconName(name: string): boolean;
+/**
+ * Normalize icon name from file name
+ *
+ * @param fileName - File name (without extension)
+ * @returns Normalized icon name
+ */
+declare function normalizeIconName(fileName: string): string;
+
+/**
+ * Icon tooling module for @dsai-io/tools
+ *
+ * Provides utilities for generating icon components from SVG source files.
+ * Supports React components, SVG sprites, with SVGO optimization.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Build icons from SVG source files
+ *
+ * Scans the source directory, parses and optimizes SVGs, then generates
+ * output in the specified formats (React, SVG sprite).
+ *
+ * @param config - Resolved DSAi configuration
+ * @param options - Build options
+ * @returns Build result with generated files
+ *
+ * @example
+ * ```typescript
+ * import { loadConfig } from '@dsai-io/tools/config';
+ * import { buildIcons } from '@dsai-io/tools/icons';
+ *
+ * const { config } = await loadConfig();
+ * const result = await buildIcons(config, {
+ *   formats: ['react', 'svg-sprite'],
+ * });
+ *
+ * console.log(\`Generated \${result.totalIcons} icons\`);
+ * ```
+ */
+declare function buildIcons(config: ResolvedConfig, options?: IconBuildOptions): Promise<IconBuildResult>;
+
+export { type GeneratedIcon, type GeneratorOptions, type IconBuildOptions, type IconBuildResult, type IconError, type IconErrorCode, type IconFormat, type IconTemplate, type IconWarning, type IndexTemplate, type OptimizedSVG, type ParsedSVG, type RawSVGData, type SVGOConfig, type SVGOPlugin, type ScannerOptions, type TypesTemplate, buildIcons, cleanSVGForReact, defaultReactIndexTemplate, defaultReactTemplate, defaultReactTypesTemplate, defaultSVGOConfig, extractViewBox, generateReactIcons, generateSVGSprite, isValidIconName, normalizeIconName, optimizeSVG, optimizeSVGFiles, parseSVG, parseSVGFiles, readSVGFile, scanSVGFiles, skipOptimization, toComponentName, toIconName };