@shohojdhara/atomix 0.3.14 → 0.4.0

package/build-tools/rollup-plugin.js

@@ -0,0 +1,236 @@
+/**
+ * @fileoverview Rollup Plugin for Atomix Design System
+ * Provides integration of Atomix components and styles into Rollup projects
+ */
+
+import fs from 'fs';
+import path from 'path';
+import {
+  resolveAtomixRoot,
+  filterComponents,
+  removeAtomImports,
+  generateThemeCss,
+  applyThemeToCSS,
+  getAvailableThemes,
+  generateThemeModule,
+  createLogger,
+} from './utils.js';
+import { Validator } from './error-handler.js';
+
+/**
+ * @typedef {Object} AtomixRollupPluginOptions
+ * @property {string} [theme='default'] - Theme to use
+ * @property {string[]} [components=[]] - Specific components to include
+ * @property {boolean} [optimize=true] - Whether to optimize imports
+ * @property {boolean} [includeAtoms=false] - Whether to include atoms
+ * @property {boolean} [verbose=false] - Enable verbose logging
+ */
+
+/**
+ * Atomix Rollup Plugin
+ * @param {AtomixRollupPluginOptions} options - Plugin options
+ * @returns {import('rollup').Plugin}
+ */
+export default function atomixRollupPlugin(options = {}) {
+  const {
+    theme = 'default',
+    components = [],
+    optimize = true,
+    includeAtoms = false,
+    verbose = false,
+  } = options;
+
+  const log = createLogger('[Atomix Rollup Plugin]', verbose);
+  let atomixRoot = null;
+
+  // Validate options — throws AtomixBuildError on failure
+  Validator.validateOptions({ theme, components }, [], []);
+
+  log.log(`Initializing with theme: ${theme}`);
+  if (components.length > 0) {
+    log.log(`Selected components: ${components.join(', ')}`);
+  }
+
+  return {
+    name: 'atomix',
+
+    /**
+     * Plugin initialization
+     */
+    buildStart() {
+      if (verbose) {
+        this.warn(`Starting build with Atomix plugin (theme: ${theme})`);
+      }
+
+      // Resolve Atomix package location
+      atomixRoot = resolveAtomixRoot();
+      if (atomixRoot) {
+        log.log(`Found Atomix at: ${atomixRoot}`);
+      } else if (verbose) {
+        this.warn('[Atomix Rollup Plugin] Could not resolve Atomix package location');
+      }
+
+      // Validate that requested components exist
+      if (components.length > 0 && atomixRoot) {
+        validateComponentsExist(components, atomixRoot, this);
+      }
+
+      // Validate theme exists
+      if (theme !== 'default' && atomixRoot) {
+        const themePath = path.join(atomixRoot, 'themes', theme);
+        if (!fs.existsSync(themePath)) {
+          const available = getAvailableThemes(atomixRoot);
+          this.warn(`[Atomix Rollup Plugin] Theme '${theme}' not found. Available themes: ${available.join(', ') || 'none detected'}`);
+        }
+      }
+    },
+
+    /**
+     * Transform Atomix imports to optimize for production
+     */
+    transform(code, id) {
+      const isAtomixFile =
+        id.includes('@shohojdhara/atomix') ||
+        (atomixRoot && id.includes(atomixRoot)) ||
+        code.includes('@shohojdhara/atomix');
+
+      if (!isAtomixFile) {
+        return null;
+      }
+
+      log.log(`Processing: ${id}`);
+
+      let transformedCode = code;
+
+      if (optimize) {
+        if (components.length > 0) {
+          transformedCode = filterComponents(transformedCode, components, includeAtoms);
+        }
+
+        if (!includeAtoms) {
+          transformedCode = removeAtomImports(transformedCode);
+        }
+      }
+
+      return {
+        code: transformedCode,
+        map: null,
+      };
+    },
+
+    /**
+     * Resolve import paths for Atomix components
+     */
+    resolveId(importee, _importer) {
+      if (!importee.startsWith('@shohojdhara/atomix/')) {
+        return null;
+      }
+
+      log.log(`Resolving: ${importee}`);
+
+      // Handle theme imports
+      if (importee === '@shohojdhara/atomix/theme' || importee === '@shohojdhara/atomix/themes') {
+        if (atomixRoot) {
+          const themePath = path.join(atomixRoot, 'themes', theme, 'index.scss');
+          if (fs.existsSync(themePath)) {
+            return themePath;
+          }
+        }
+        return importee;
+      }
+
+      // Handle component imports
+      if (importee.includes('/components/') && optimize && components.length > 0) {
+        log.log(`Component import detected: ${importee}`);
+      }
+
+      return null;
+    },
+
+    /**
+     * Load virtual modules
+     */
+    load(id) {
+      if (id.includes('virtual:atomix-theme')) {
+        log.log('Loading virtual theme module');
+        return generateThemeModule(theme, atomixRoot);
+      }
+
+      if (id.includes('.atomix-theme.css')) {
+        try {
+          return generateThemeCss(theme, atomixRoot);
+        } catch (error) {
+          if (verbose) {
+            this.warn(`[Atomix Rollup Plugin] Error loading theme CSS: ${error.message}`);
+          }
+          return `/* Error loading theme: ${theme} */`;
+        }
+      }
+
+      return null;
+    },
+
+    /**
+     * Generate bundle
+     */
+    generateBundle(outputOptions, bundle) {
+      if (!optimize) return;
+
+      for (const fileName in bundle) {
+        const chunk = bundle[fileName];
+
+        if (chunk.type === 'asset' && chunk.fileName.endsWith('.css')) {
+          if (chunk.fileName.includes('atomix')) {
+            try {
+              chunk.source = applyThemeToCSS(chunk.source.toString(), theme, atomixRoot);
+              log.log(`Applied theme ${theme} to ${fileName}`);
+            } catch (error) {
+              if (verbose) {
+                this.warn(`[Atomix Rollup Plugin] Error applying theme to ${fileName}: ${error.message}`);
+              }
+            }
+          }
+        }
+      }
+    },
+  };
+}
+
+/**
+ * Validate that requested components exist on disk.
+ * @param {string[]} components - Requested components.
+ * @param {string} atomixRoot - Atomix root path.
+ * @param {import('rollup').PluginContext} context - Rollup plugin context.
+ */
+function validateComponentsExist(components, atomixRoot, context) {
+  const componentsDir = path.join(atomixRoot, 'src', 'components');
+
+  if (!fs.existsSync(componentsDir)) {
+    context.warn('[Atomix Rollup Plugin] Could not find components directory');
+    return;
+  }
+
+  try {
+    const availableComponents = fs.readdirSync(componentsDir)
+      .filter(item => {
+        try {
+          return fs.statSync(path.join(componentsDir, item)).isDirectory();
+        } catch {
+          return false;
+        }
+      });
+
+    const missingComponents = components.filter(comp => !availableComponents.includes(comp));
+
+    if (missingComponents.length > 0) {
+      const available = availableComponents.slice(0, 10).join(', ');
+      const suffix = availableComponents.length > 10 ? '...' : '';
+      context.warn(`[Atomix Rollup Plugin] Requested components not found: ${missingComponents.join(', ')}. Available: ${available}${suffix}`);
+    }
+  } catch {
+    context.warn('[Atomix Rollup Plugin] Error validating components');
+  }
+}
+
+// Re-export helpers for external consumption
+export { resolveAtomixRoot as getAtomixPackageLocation, getAvailableThemes } from './utils.js';

package/build-tools/types.d.ts

@@ -0,0 +1,163 @@
+/**
+ * Type definitions for Atomix Build Tool Integrations
+ */
+
+// ─── Plugin Option Interfaces ────────────────────────────────────────────────
+
+/** Options for the Vite plugin */
+export interface AtomixVitePluginOptions {
+  /** Theme to use (default: 'default') */
+  theme?: string;
+  /** Specific components to include (default: all) */
+  components?: string[];
+  /** Whether to optimize CSS (default: true) */
+  optimizeCss?: boolean;
+  /** Whether to include atomic styles (default: false) */
+  includeAtoms?: boolean;
+  /** Enable verbose logging (default: false) */
+  verbose?: boolean;
+}
+
+/** Options for the Webpack loader */
+export interface AtomixLoaderOptions {
+  /** Whether to include atomic styles (default: false) */
+  includeAtoms?: boolean;
+  /** Specific components to include (default: all) */
+  components?: string[];
+  /** Enable verbose logging (default: false) */
+  verbose?: boolean;
+  /** Theme to use (default: 'default') */
+  theme?: string;
+}
+
+/** Options for the Rollup plugin */
+export interface AtomixRollupPluginOptions {
+  /** Theme to use (default: 'default') */
+  theme?: string;
+  /** Specific components to include (default: all) */
+  components?: string[];
+  /** Whether to optimize imports (default: true) */
+  optimize?: boolean;
+  /** Whether to include atoms (default: false) */
+  includeAtoms?: boolean;
+  /** Enable verbose logging (default: false) */
+  verbose?: boolean;
+}
+
+/** Generic options accepted by `getIntegration` / `initAutoIntegration` */
+export interface AtomixBuildToolOptions {
+  /** Theme to use */
+  theme?: string;
+  /** Specific components to include */
+  components?: string[];
+  /** Whether to optimize */
+  optimize?: boolean;
+  /** Whether to include atomic styles */
+  includeAtoms?: boolean;
+  /** Enable verbose logging */
+  verbose?: boolean;
+}
+
+// ─── Plugin Return Types ─────────────────────────────────────────────────────
+
+/** Shape of the object returned by the Vite plugin factory */
+export interface VitePluginResult {
+  name: string;
+  configResolved?(config: unknown): void;
+  transform?(code: string, id: string): Promise<TransformResult | null>;
+  configureServer?(server: unknown): void;
+  generateBundle?(options: unknown, bundle: Record<string, unknown>): void;
+  buildStart?(): void;
+}
+
+/** Shape of the object returned by the Rollup plugin factory */
+export interface RollupPluginResult {
+  name: string;
+  buildStart?(): void;
+  transform?(code: string, id: string): TransformResult | null;
+  resolveId?(importee: string, importer?: string): string | null;
+  load?(id: string): string | null;
+  generateBundle?(options: unknown, bundle: Record<string, unknown>): void;
+}
+
+// ─── Theme Types ─────────────────────────────────────────────────────────────
+
+export interface ThemeConfig {
+  /** Theme name */
+  name: string;
+  /** Theme CSS custom properties */
+  variables: Record<string, string>;
+  /** Theme CSS content */
+  css: string;
+}
+
+// ─── Component Types ─────────────────────────────────────────────────────────
+
+export interface ComponentInfo {
+  /** Component name */
+  name: string;
+  /** Component path */
+  path: string;
+  /** Whether component is available */
+  available: boolean;
+}
+
+// ─── Build Tool Detection ────────────────────────────────────────────────────
+
+export type BuildTool = 'vite' | 'webpack' | 'rollup' | null;
+
+export interface BuildToolDetectionResult {
+  /** Detected build tool */
+  tool: BuildTool;
+  /** Confidence level (0-1) */
+  confidence: number;
+  /** Detection method used */
+  method: string;
+}
+
+// ─── Transform Result ────────────────────────────────────────────────────────
+
+export interface TransformResult {
+  /** Transformed code */
+  code: string;
+  /** Source map (null when not generated) */
+  map: null | object;
+}
+
+// ─── Error Types ─────────────────────────────────────────────────────────────
+
+export interface AtomixBuildError extends Error {
+  /** Error code */
+  code: string;
+  /** Additional error details */
+  details?: Record<string, unknown>;
+  /** Suggested solutions */
+  suggestions?: string[];
+}
+
+// ─── Utility Types ───────────────────────────────────────────────────────────
+
+export interface Logger {
+  log(message: string): void;
+  warn(message: string): void;
+  error(message: string, err?: unknown): void;
+}
+
+// ─── Configuration ───────────────────────────────────────────────────────────
+
+export interface AtomixConfig {
+  /** Theme configuration */
+  theme: string;
+  /** Optimization settings */
+  optimize: boolean;
+  /** Include atoms */
+  includeAtoms: boolean;
+  /** Component list */
+  components: string[];
+  /** Build tool specific settings */
+  buildTools: {
+    vite?: Partial<AtomixVitePluginOptions>;
+    webpack?: Partial<AtomixLoaderOptions>;
+    rollup?: Partial<AtomixRollupPluginOptions>;
+  };
+}

package/build-tools/utils.js

@@ -0,0 +1,203 @@
+/**
+ * @fileoverview Shared utilities for Atomix build tool integrations
+ * Centralizes common functions used across Vite, Rollup, and Webpack plugins.
+ * @module @shohojdhara/atomix/build-tools/utils
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+
+// ─── Package Resolution ──────────────────────────────────────────────────────
+
+/**
+ * Resolve the root directory of the installed Atomix package.
+ * Uses createRequire for ESM-safe resolution.
+ * @returns {string | null} Absolute path to the Atomix package root, or null.
+ */
+export function resolveAtomixRoot() {
+  try {
+    return path.dirname(require.resolve('@shohojdhara/atomix/package.json'));
+  } catch {
+    return null;
+  }
+}
+
+// ─── Theme Helpers ───────────────────────────────────────────────────────────
+
+/**
+ * Read the raw SCSS content of a theme.
+ * @param {string} themeName - Theme directory name.
+ * @param {string | null} atomixRoot - Atomix package root (from resolveAtomixRoot).
+ * @returns {string} Theme SCSS content.
+ * @throws {Error} If atomixRoot is null or the theme file doesn't exist.
+ */
+export function generateThemeCss(themeName, atomixRoot) {
+  if (!atomixRoot) {
+    throw new Error('Atomix package location not found');
+  }
+
+  const themePath = path.join(atomixRoot, 'themes', themeName, 'index.scss');
+
+  if (!fs.existsSync(themePath)) {
+    throw new Error(`Theme '${themeName}' not found at ${themePath}`);
+  }
+
+  return fs.readFileSync(themePath, 'utf-8');
+}
+
+/**
+ * Prepend theme CSS to an existing stylesheet.
+ * Falls back to a comment header if the theme can't be loaded.
+ * @param {string} css - Original stylesheet content.
+ * @param {string} themeName - Theme directory name.
+ * @param {string | null} atomixRoot - Atomix package root.
+ * @returns {string} Stylesheet with theme CSS prepended.
+ */
+export function applyThemeToCSS(css, themeName, atomixRoot) {
+  try {
+    const themeCss = generateThemeCss(themeName, atomixRoot);
+    return `${themeCss}\n\n${css}`;
+  } catch {
+    return `/* Theme: ${themeName} - Error loading theme CSS */\n${css}`;
+  }
+}
+
+/**
+ * List all available theme directories.
+ * Returns an empty array when the themes directory can't be read — never
+ * returns hardcoded fallback values that would mask real errors.
+ * @param {string | null} atomixPath - Atomix package root.
+ * @returns {string[]} Theme directory names.
+ */
+export function getAvailableThemes(atomixPath) {
+  if (!atomixPath) {
+    return [];
+  }
+
+  try {
+    const themesDir = path.join(atomixPath, 'themes');
+    if (fs.existsSync(themesDir)) {
+      return fs.readdirSync(themesDir)
+        .filter(item => {
+          try {
+            return fs.statSync(path.join(themesDir, item)).isDirectory();
+          } catch {
+            return false;
+          }
+        });
+    }
+  } catch {
+    // Intentionally empty — return empty array below.
+  }
+
+  return [];
+}
+
+/**
+ * Generate a virtual module that exports a theme's CSS as a string.
+ * @param {string} themeName - Theme directory name.
+ * @param {string | null} atomixRoot - Atomix package root.
+ * @returns {string} JavaScript module source code.
+ */
+export function generateThemeModule(themeName, atomixRoot) {
+  try {
+    const themeCss = generateThemeCss(themeName, atomixRoot);
+    // Use JSON.stringify to safely embed the CSS string (handles backticks, etc.)
+    return `// Generated theme module for "${themeName}"\nconst themeCss = ${JSON.stringify(themeCss)};\nexport default themeCss;\n`;
+  } catch {
+    return `// Error generating theme module for "${themeName}"\nexport default '/* Error loading theme */';\n`;
+  }
+}
+
+// ─── Import Transform Helpers ────────────────────────────────────────────────
+
+/**
+ * Filter Atomix component imports to only keep selected components.
+ * Strips import statements that reference unselected components.
+ * @param {string} code - Source code.
+ * @param {string[]} selectedComponents - Components to keep.
+ * @param {boolean} includeAtoms - Whether to also keep Atom-prefixed imports.
+ * @returns {string} Transformed source code.
+ */
+export function filterComponents(code, selectedComponents, includeAtoms) {
+  // Matches both '@shohojdhara/atomix/components' and '@shohojdhara/atomix'
+  const componentImportRegex = /import\s+{([^}]+)}\s+from\s+['"]@shohojdhara\/atomix(?:\/components)?['"]/g;
+
+  return code.replace(componentImportRegex, (match, importList) => {
+    const imports = importList.split(',').map(i => i.trim()).filter(Boolean);
+    const filteredImports = imports.filter(imp =>
+      selectedComponents.includes(imp) ||
+      (includeAtoms && imp.startsWith('Atom'))
+    );
+
+    if (filteredImports.length === 0) {
+      return '';
+    }
+
+    // Always rewrite to the root import for consistency, or keep as is if we want to be safe.
+    // But since /components doesn't exist in exports, we should probably rewrite to root.
+    // However, if the user wrote /components, they might have a reason (aliases?).
+    // Given the audit finding that /components isn't exported, let's standardize on the root import.
+    return `import { ${filteredImports.join(', ')} } from '@shohojdhara/atomix'`;
+  });
+}
+
+/**
+ * Remove import statements that pull from any .../atoms path.
+ * @param {string} code - Source code.
+ * @returns {string} Source code without atom imports.
+ */
+export function removeAtomImports(code) {
+  const atomImportRegex = /import\s+{[^}]*}\s+from\s+['"][^'"]*\/atoms['"];?\s*/g;
+  return code.replace(atomImportRegex, '');
+}
+
+/**
+ * Determine whether a file should be processed by an Atomix build tool.
+ * Uses strict matching to avoid false positives on user files that happen
+ * to contain the word "atomix".
+ * @param {string} resourcePath - Absolute path to the file.
+ * @param {string} source - File source code.
+ * @returns {boolean} true if the file should be processed.
+ */
+export function shouldProcessFile(resourcePath, source) {
+  // Files that explicitly import Atomix
+  if (source.includes('@shohojdhara/atomix')) {
+    return true;
+  }
+
+  // Files inside the Atomix node_modules installation
+  if (resourcePath.includes('node_modules/@shohojdhara/atomix')) {
+    return true;
+  }
+
+  return false;
+}
+
+// ─── Logger ──────────────────────────────────────────────────────────────────
+
+/**
+ * Create a prefixed logger that respects a verbose flag.
+ * When verbose is false, only warnings and errors are emitted.
+ * @param {string} prefix - Log prefix, e.g. "[Atomix Vite Plugin]".
+ * @param {boolean} verbose - Whether to enable informational logging.
+ * @returns {{ log: Function, warn: Function, error: Function }}
+ */
+export function createLogger(prefix, verbose = false) {
+  return {
+    log(message) {
+      if (verbose) {
+        console.log(`${prefix} ${message}`);
+      }
+    },
+    warn(message) {
+      console.warn(`${prefix} ${message}`);
+    },
+    error(message, err) {
+      console.error(`${prefix} ${message}`, err || '');
+    },
+  };
+}