@shohojdhara/atomix 0.3.13 → 0.3.15

package/build-tools/error-handler.js

@@ -0,0 +1,308 @@
+/**
+ * @fileoverview Error handling utilities for Atomix build tools
+ */
+
+/**
+ * Custom error class for Atomix build tool errors
+ * @extends Error
+ */
+export class AtomixBuildError extends Error {
+  /**
+   * @param {string} message - Error message
+   * @param {string} code - Error code
+   * @param {Object} [details] - Additional error details
+   * @param {string[]} [suggestions] - Suggested solutions
+   */
+  constructor(message, code, details = {}, suggestions = []) {
+    super(message);
+    this.name = 'AtomixBuildError';
+    this.code = code;
+    this.details = details;
+    this.suggestions = suggestions;
+    this.timestamp = new Date().toISOString();
+  }
+
+  /**
+   * Get formatted error message
+   * @returns {string} Formatted error message
+   */
+  toString() {
+    let msg = `[AtomixBuildError:${this.code}] ${this.message}`;
+    
+    if (this.details && Object.keys(this.details).length > 0) {
+      msg += `\nDetails: ${JSON.stringify(this.details, null, 2)}`;
+    }
+    
+    if (this.suggestions && this.suggestions.length > 0) {
+      msg += `\nSuggestions:\n${this.suggestions.map((s, i) => `  ${i + 1}. ${s}`).join('\n')}`;
+    }
+    
+    return msg;
+  }
+}
+
+/**
+ * Validation utilities
+ */
+export class Validator {
+  /**
+   * Validate theme name
+   * @param {string} theme - Theme name to validate
+   * @param {string[]} [availableThemes] - List of available themes
+   * @throws {AtomixBuildError} If validation fails
+   */
+  static validateTheme(theme, availableThemes = []) {
+    if (typeof theme !== 'string') {
+      throw new AtomixBuildError(
+        'Theme must be a string',
+        'INVALID_THEME_TYPE',
+        { theme, type: typeof theme },
+        ['Provide a string value for theme option']
+      );
+    }
+
+    if (theme.trim() === '') {
+      throw new AtomixBuildError(
+        'Theme cannot be empty',
+        'EMPTY_THEME',
+        { theme },
+        ['Provide a valid theme name']
+      );
+    }
+
+    if (availableThemes.length > 0 && !availableThemes.includes(theme)) {
+      throw new AtomixBuildError(
+        `Theme '${theme}' not found`,
+        'THEME_NOT_FOUND',
+        { theme, availableThemes },
+        [
+          `Available themes: ${availableThemes.join(', ')}`,
+          'Check if the theme name is spelled correctly',
+          'Verify the theme exists in your Atomix installation'
+        ]
+      );
+    }
+  }
+
+  /**
+   * Validate components array
+   * @param {any} components - Components to validate
+   * @param {string[]} [availableComponents] - List of available components
+   * @throws {AtomixBuildError} If validation fails
+   */
+  static validateComponents(components, availableComponents = []) {
+    if (!Array.isArray(components)) {
+      throw new AtomixBuildError(
+        'Components must be an array',
+        'INVALID_COMPONENTS_TYPE',
+        { components, type: typeof components },
+        ['Provide an array of component names']
+      );
+    }
+
+    const invalidItems = components.filter(item => typeof item !== 'string');
+    if (invalidItems.length > 0) {
+      throw new AtomixBuildError(
+        'All component names must be strings',
+        'INVALID_COMPONENT_NAMES',
+        { invalidItems },
+        ['Ensure all component names are string values']
+      );
+    }
+
+    if (availableComponents.length > 0) {
+      const missingComponents = components.filter(comp => !availableComponents.includes(comp));
+      if (missingComponents.length > 0) {
+        throw new AtomixBuildError(
+          `Some requested components not found: ${missingComponents.join(', ')}`,
+          'COMPONENTS_NOT_FOUND',
+          { missingComponents, availableComponents },
+          [
+            `Available components: ${availableComponents.slice(0, 10).join(', ')}${availableComponents.length > 10 ? '...' : ''}`,
+            'Check component names for typos',
+            'Verify components exist in your Atomix version'
+          ]
+        );
+      }
+    }
+  }
+
+  /**
+   * Validate boolean options
+   * @param {any} value - Value to validate
+   * @param {string} optionName - Name of the option
+   * @throws {AtomixBuildError} If validation fails
+   */
+  static validateBoolean(value, optionName) {
+    if (typeof value !== 'boolean') {
+      throw new AtomixBuildError(
+        `${optionName} must be a boolean`,
+        'INVALID_BOOLEAN_OPTION',
+        { optionName, value, type: typeof value },
+        [`Provide true or false for ${optionName} option`]
+      );
+    }
+  }
+
+  /**
+   * Validate string options
+   * @param {any} value - Value to validate
+   * @param {string} optionName - Name of the option
+   * @param {boolean} [allowEmpty=false] - Whether empty strings are allowed
+   * @throws {AtomixBuildError} If validation fails
+   */
+  static validateString(value, optionName, allowEmpty = false) {
+    if (typeof value !== 'string') {
+      throw new AtomixBuildError(
+        `${optionName} must be a string`,
+        'INVALID_STRING_OPTION',
+        { optionName, value, type: typeof value },
+        [`Provide a string value for ${optionName} option`]
+      );
+    }
+
+    if (!allowEmpty && value.trim() === '') {
+      throw new AtomixBuildError(
+        `${optionName} cannot be empty`,
+        'EMPTY_STRING_OPTION',
+        { optionName, value },
+        [`Provide a non-empty string for ${optionName} option`]
+      );
+    }
+  }
+
+  /**
+   * Validate plugin options object
+   * @param {Object} options - Options to validate
+   * @param {string[]} [availableThemes] - Available themes
+   * @param {string[]} [availableComponents] - Available components
+   * @throws {AtomixBuildError} If validation fails
+   */
+  static validateOptions(options, availableThemes = [], availableComponents = []) {
+    if (typeof options !== 'object' || options === null) {
+      throw new AtomixBuildError(
+        'Options must be an object',
+        'INVALID_OPTIONS_OBJECT',
+        { options, type: typeof options },
+        ['Provide a valid options object']
+      );
+    }
+
+    // Validate individual options
+    if ('theme' in options) {
+      this.validateTheme(options.theme, availableThemes);
+    }
+
+    if ('components' in options) {
+      this.validateComponents(options.components, availableComponents);
+    }
+
+    if ('optimizeCss' in options) {
+      this.validateBoolean(options.optimizeCss, 'optimizeCss');
+    }
+
+    if ('includeAtoms' in options) {
+      this.validateBoolean(options.includeAtoms, 'includeAtoms');
+    }
+
+    if ('verbose' in options) {
+      this.validateBoolean(options.verbose, 'verbose');
+    }
+
+    if ('optimize' in options) {
+      this.validateBoolean(options.optimize, 'optimize');
+    }
+
+    // Check for unknown options
+    const knownOptions = ['theme', 'components', 'optimizeCss', 'includeAtoms', 'verbose', 'optimize'];
+    const unknownOptions = Object.keys(options).filter(key => !knownOptions.includes(key));
+    
+    if (unknownOptions.length > 0) {
+      console.warn(`[AtomixBuildWarning] Unknown options provided: ${unknownOptions.join(', ')}`);
+    }
+  }
+}
+
+/**
+ * Error handling utilities
+ */
+export class ErrorHandler {
+  /**
+   * Wrap a function with error handling
+   * @param {Function} fn - Function to wrap
+   * @param {string} context - Context/error prefix
+   * @returns {Function} Wrapped function
+   */
+  static withErrorHandling(fn, context) {
+    return (...args) => {
+      try {
+        return fn(...args);
+      } catch (error) {
+        if (error instanceof AtomixBuildError) {
+          throw error;
+        }
+        
+        throw new AtomixBuildError(
+          `${context}: ${error.message}`,
+          'UNEXPECTED_ERROR',
+          { originalError: error.message, stack: error.stack },
+          ['Check the error details above', 'Review your configuration', 'Consult the documentation']
+        );
+      }
+    };
+  }
+
+  /**
+   * Create a safe validator function
+   * @param {Function} validator - Validator function
+   * @param {string} context - Context for error messages
+   * @returns {Function} Safe validator function
+   */
+  static createSafeValidator(validator, context) {
+    return (...args) => {
+      try {
+        return validator(...args);
+      } catch (error) {
+        if (error instanceof AtomixBuildError) {
+          throw error;
+        }
+        
+        throw new AtomixBuildError(
+          `${context}: Validation failed`,
+          'VALIDATION_ERROR',
+          { args, originalError: error.message },
+          ['Check the validation rules', 'Review your input data']
+        );
+      }
+    };
+  }
+
+  /**
+   * Log error with proper formatting
+   * @param {Error|AtomixBuildError} error - Error to log
+   * @param {boolean} [verbose=false] - Whether to show verbose output
+   */
+  static logError(error, verbose = false) {
+    if (error instanceof AtomixBuildError) {
+      console.error(error.toString());
+    } else {
+      console.error(`[Error] ${error.message}`);
+      if (verbose && error.stack) {
+        console.error('Stack trace:', error.stack);
+      }
+    }
+  }
+
+  /**
+   * Get error code from error
+   * @param {Error} error - Error object
+   * @returns {string|null} Error code or null
+   */
+  static getErrorCode(error) {
+    if (error instanceof AtomixBuildError) {
+      return error.code;
+    }
+    return null;
+  }
+}
+

package/build-tools/index.d.ts

@@ -0,0 +1,43 @@
+// Import types
+import type {
+  AtomixBuildToolOptions,
+  BuildTool,
+  AtomixVitePluginOptions,
+  AtomixLoaderOptions,
+  AtomixRollupPluginOptions,
+  VitePluginResult,
+  RollupPluginResult,
+} from './types.js';
+
+// ─── Plugin Exports ──────────────────────────────────────────────────────────
+
+/** Vite plugin for Atomix integration */
+export declare function vitePlugin(options?: AtomixVitePluginOptions): VitePluginResult;
+
+/** Webpack loader for Atomix integration (exported as the loader function itself) */
+export declare const webpackLoader: (source: string) => string;
+
+/** Rollup plugin for Atomix integration */
+export declare function rollupPlugin(options?: AtomixRollupPluginOptions): RollupPluginResult;
+
+// ─── Utility Exports ─────────────────────────────────────────────────────────
+
+/**
+ * Gets the appropriate plugin/loader based on the detected build tool.
+ * Returns the instantiated plugin for Vite/Rollup, or the loader function for Webpack.
+ */
+export declare function getIntegration(
+  buildTool: BuildTool,
+  options?: AtomixBuildToolOptions
+): VitePluginResult | RollupPluginResult | typeof webpackLoader | null;
+
+/** Detects the build tool used in the current project by reading package.json */
+export declare function detectBuildTool(): BuildTool;
+
+/** Initialize the appropriate integration based on detected build tool */
+export declare function initAutoIntegration(
+  options?: AtomixBuildToolOptions
+): VitePluginResult | RollupPluginResult | typeof webpackLoader | null;
+
+/** Get available themes from Atomix installation */
+export declare function getAvailableThemes(atomixPath?: string | null): string[];

package/build-tools/index.js

@@ -0,0 +1,88 @@
+/**
+ * @fileoverview Entry point for Atomix Build Tool Integrations
+ * Provides a unified way to access build tool plugins/loaders
+ * @module @shohojdhara/atomix/build-tools
+ */
+
+import fs from 'fs';
+import path from 'path';
+
+/** @typedef {import('./types').AtomixBuildToolOptions} AtomixBuildToolOptions */
+/** @typedef {import('./types').BuildTool} BuildTool */
+
+import vitePluginFn from './vite-plugin.js';
+import webpackLoaderFn from './webpack-loader.js';
+import rollupPluginFn from './rollup-plugin.js';
+
+// Named re-exports
+export { default as vitePlugin } from './vite-plugin.js';
+export { default as webpackLoader } from './webpack-loader.js';
+export { default as rollupPlugin } from './rollup-plugin.js';
+
+/**
+ * Gets the appropriate plugin/loader based on the detected build tool
+ * @param {BuildTool} buildTool - Name of the build tool ('vite', 'webpack', 'rollup')
+ * @param {AtomixBuildToolOptions} [options={}] - Options to pass to the plugin/loader
+ * @returns {Function|null} The appropriate plugin/loader function or null if not found
+ */
+export function getIntegration(buildTool, options = {}) {
+  switch (buildTool?.toLowerCase()) {
+    case 'vite':
+      return vitePluginFn(options);
+    case 'webpack':
+      // Webpack loaders work differently — return the loader function itself
+      return webpackLoaderFn;
+    case 'rollup':
+      return rollupPluginFn(options);
+    default:
+      console.warn(`[Atomix Build Tools] Unsupported build tool: ${buildTool}`);
+      return null;
+  }
+}
+
+/**
+ * Detects the build tool used in the current project
+ * @returns {BuildTool} Detected build tool or null if not found
+ */
+export function detectBuildTool() {
+  try {
+    const pkgPath = path.join(process.cwd(), 'package.json');
+    if (!fs.existsSync(pkgPath)) {
+      return null;
+    }
+
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+    const allDeps = {
+      ...pkg.dependencies,
+      ...pkg.devDependencies,
+    };
+
+    if (allDeps.vite) return 'vite';
+    if (allDeps.webpack) return 'webpack';
+    if (allDeps.rollup) return 'rollup';
+
+    return null;
+  } catch (e) {
+    console.error('[Atomix Build Tools] Error detecting build tool:', e.message);
+    return null;
+  }
+}
+
+/**
+ * Initialize the appropriate integration based on detected build tool
+ * @param {AtomixBuildToolOptions} [options={}] - Options to pass to the plugin/loader
+ * @returns {Function|null} The appropriate plugin/loader function or null if not found
+ */
+export function initAutoIntegration(options = {}) {
+  const buildTool = detectBuildTool();
+  if (!buildTool) {
+    console.warn('[Atomix Build Tools] Could not detect build tool, please use specific integration');
+    return null;
+  }
+
+  console.log(`[Atomix Build Tools] Detected build tool: ${buildTool}, initializing integration...`);
+  return getIntegration(buildTool, options);
+}
+
+// Export helpers
+export { getAvailableThemes } from './utils.js';

package/build-tools/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@shohojdhara/atomix-build-tools",
+  "version": "1.0.0",
+  "description": "Build tool integrations for the Atomix design system",
+  "type": "module",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    },
+    "./vite-plugin": {
+      "types": "./index.d.ts",
+      "import": "./vite-plugin.js"
+    },
+    "./rollup-plugin": {
+      "types": "./index.d.ts",
+      "import": "./rollup-plugin.js"
+    },
+    "./webpack-loader": {
+      "types": "./index.d.ts",
+      "import": "./webpack-loader.js"
+    },
+    "./types": {
+      "types": "./types.d.ts"
+    }
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "vitest run __tests__/"
+  },
+  "peerDependencies": {
+    "vite": "^4.0.0 || ^5.0.0 || ^6.0.0",
+    "webpack": "^5.0.0",
+    "rollup": "^3.0.0 || ^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "vite": { "optional": true },
+    "webpack": { "optional": true },
+    "rollup": { "optional": true }
+  },
+  "keywords": [
+    "atomix",
+    "design-system",
+    "vite",
+    "webpack",
+    "rollup",
+    "plugin",
+    "loader",
+    "ui",
+    "framework"
+  ],
+  "author": "Limon Khan",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Shohojdhara/atomix.git",
+    "directory": "build-tools"
+  },
+  "bugs": {
+    "url": "https://github.com/Shohojdhara/atomix/issues"
+  },
+  "homepage": "https://github.com/Shohojdhara/atomix#readme"
+}