@shohojdhara/atomix 0.3.14 → 0.4.0

package/CHANGELOG.md

@@ -1,14 +1,33 @@
 # Changelog
 
+## [0.3.15] - 2026-02-20
+
+### Added
+
+- Standardize component import paths, update build tool plugin import examples, and include themes in package distribution (fda94bac)
+- Add TypeScript declaration files to package for build-tools (fc288744)
+- Update type definitions and improve export documentation for build-tools (13a6dd2c)
+
+### Changed
+
+- Centralize build tool utilities for theme handling, component filtering, and logging (6acdcbfe)
+
+### Fixed
+
+- Add `.js` extension to type import path in build tools definition (e0479944)
+- Resolve duplicate identifiers in `AtomixGlass` (51d82d99)
+
 ## [2.0.0] - 2026-01-20
 
 ### Added
+
 - **Spinner**: Added `aria-label` (default "Loading") and `role` (default "status") props for improved accessibility.
 - **Badge**: Added `onRemove` callback and `aria-label` support. Providing `onRemove` automatically renders a close button.
 - **Input/Textarea**: Added `defaultValue` prop for uncontrolled component support.
 - **JSDoc**: Added `@default` tags to many component props for better developer experience and documentation.
 
 ### Changed (Breaking)
+
 - **Standardized ARIA Props**: All ARIA-related props have been renamed from camelCase to kebab-case (e.g., `ariaLabel` -> `aria-label`) to align with native React/HTML standards.
 - **Toggle Component**: Refactored API to follow standard React form patterns. Removed `initialOn`, `onToggleOn`, and `onToggleOff`. Added `checked`, `defaultChecked`, and `onChange`.
 - **Rating Component**: Renamed `color` prop to `variant` for consistency with other components.
@@ -16,6 +35,7 @@
 - **Callout Component**: Renamed `oneLine` to `compact` and `toast` to `isToast`.
 
 ### Fixed
+
 - Fixed several accessibility issues across navigation components.
 - Improved focus management in `Modal` component.
 

package/build-tools/EXAMPLES.md

@@ -0,0 +1,372 @@
+# Build Tool Integration Examples
+
+This document provides practical examples of how to integrate Atomix with popular build tools. All examples include TypeScript support and comprehensive error handling.
+
+## TypeScript Support
+
+All build tools include full TypeScript definitions:
+
+```ts
+import { type AtomixVitePluginOptions, type AtomixLoaderOptions, type AtomixRollupPluginOptions } from '@shohojdhara/atomix/build-tools';
+```
+
+## Vite Integration
+
+### Basic Setup
+
+```js
+// vite.config.js
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import atomixPlugin from '@shohojdhara/atomix/build-tools/vite-plugin.js';
+
+export default defineConfig({
+  plugins: [
+    react(),
+    atomixPlugin({
+      theme: 'dark',
+      optimizeCss: true,
+      verbose: false
+    })
+  ]
+});
+```
+
+With TypeScript:
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import atomixPlugin, { type AtomixVitePluginOptions } from '@shohojdhara/atomix/build-tools/vite-plugin.js';
+
+const atomixOptions: AtomixVitePluginOptions = {
+  theme: 'dark',
+  components: ['Button', 'Card'],
+  optimizeCss: true,
+  includeAtoms: false,
+  verbose: true
+};
+
+export default defineConfig({
+  plugins: [react(), atomixPlugin(atomixOptions)]
+});
+```
+
+### Advanced Setup
+
+```js
+// vite.config.js
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import atomix from '@shohojdhara/atomix/build-tools';
+
+export default defineConfig({
+  plugins: [
+    react(),
+    atomix.vitePlugin({
+      theme: 'custom-theme',
+      components: ['Button', 'Card', 'Modal'],
+      optimizeCss: true,
+      includeAtoms: true
+    })
+  ],
+  css: {
+    preprocessorOptions: {
+      scss: {
+        // Add Atomix SCSS paths
+        additionalData: `@import "@shohojdhara/atomix/scss/settings";`
+      }
+    }
+  }
+});
+```
+
+## Webpack Integration
+
+### Basic Setup
+
+```js
+// webpack.config.js
+const path = require('path');
+
+module.exports = {
+  // ... other config
+  module: {
+    rules: [
+      {
+        test: /\.(js|jsx|ts|tsx)$/,
+        include: [
+          path.resolve(__dirname, 'src'),
+          path.resolve(__dirname, 'node_modules/@shohojdhara/atomix')
+        ],
+        use: {
+          loader: path.resolve(__dirname, 'node_modules/@shohojdhara/atomix/build-tools/webpack-loader.js'),
+          options: {
+            includeAtoms: false,
+            components: ['Button', 'Input'],
+            excludeUnnecessaryStyles: true,
+            verbose: false
+          }
+        }
+      }
+    ]
+  },
+  resolve: {
+    alias: {
+      '@shohojdhara/atomix': path.resolve(__dirname, 'node_modules/@shohojdhara/atomix')
+    }
+  }
+};
+```
+
+With TypeScript:
+
+```ts
+// webpack.config.ts
+import path from 'path';
+import { type AtomixLoaderOptions } from '@shohojdhara/atomix/build-tools';
+
+const atomixLoaderOptions: AtomixLoaderOptions = {
+  includeAtoms: false,
+  components: ['Button', 'Card', 'Input'],
+  excludeUnnecessaryStyles: true,
+  verbose: true
+};
+
+export default {
+  // ... other config
+  module: {
+    rules: [
+      {
+        test: /\.(js|jsx|ts|tsx)$/,
+        include: [
+          path.resolve(__dirname, 'src'),
+          path.resolve(__dirname, 'node_modules/@shohojdhara/atomix')
+        ],
+        use: {
+          loader: path.resolve(__dirname, 'node_modules/@shohojdhara/atomix/build-tools/webpack-loader.js'),
+          options: atomixLoaderOptions
+        }
+      }
+    ]
+  }
+};
+```
+
+### With CSS Processing
+
+```js
+// webpack.config.js
+const path = require('path');
+const MiniCssExtractPlugin = require('mini-css-extract-plugin');
+
+module.exports = {
+  // ... other config
+  plugins: [
+    new MiniCssExtractPlugin({
+      filename: '[name].[contenthash].css'
+    })
+  ],
+  module: {
+    rules: [
+      {
+        test: /\.(js|jsx)$/,
+        include: [
+          path.resolve(__dirname, 'src'),
+          path.resolve(__dirname, 'node_modules/@shohojdhara/atomix')
+        ],
+        use: [
+          'babel-loader',
+          {
+            loader: '@shohojdhara/atomix/build-tools/webpack-loader',
+            options: {
+              components: ['Button', 'Input', 'Card'],
+              includeAtoms: true
+            }
+          }
+        ]
+      },
+      {
+        test: /\.css$/,
+        use: [
+          MiniCssExtractPlugin.loader,
+          'css-loader',
+          'postcss-loader'
+        ]
+      }
+    ]
+  }
+};
+```
+
+## Rollup Integration
+
+### Basic Setup
+
+```js
+// rollup.config.js
+import atomixPlugin from '@shohojdhara/atomix/build-tools/rollup-plugin.js';
+
+export default {
+  input: 'src/index.js',
+  output: {
+    dir: 'dist',
+    format: 'es'
+  },
+  plugins: [
+    atomixPlugin({
+      theme: 'light',
+      optimize: true,
+      verbose: false
+    })
+  ]
+};
+```
+
+With TypeScript:
+
+```ts
+// rollup.config.ts
+import atomixPlugin, { type AtomixRollupPluginOptions } from '@shohojdhara/atomix/build-tools/rollup-plugin.js';
+
+const atomixOptions: AtomixRollupPluginOptions = {
+  theme: 'dark',
+  components: ['Button', 'Modal', 'Card'],
+  optimize: true,
+  includeAtoms: false,
+  verbose: true
+};
+
+export default {
+  input: 'src/main.js',
+  output: {
+    dir: 'dist',
+    format: 'es'
+  },
+  plugins: [atomixPlugin(atomixOptions)]
+};
+```
+
+### Advanced Setup
+
+```js
+// rollup.config.js
+import resolve from '@rollup/plugin-node-resolve';
+import commonjs from '@rollup/plugin-commonjs';
+import atomix from '@shohojdhara/atomix/build-tools';
+
+export default {
+  input: 'src/main.js',
+  output: {
+    dir: 'dist',
+    format: 'es',
+    assetFileNames: (assetInfo) => {
+      if (assetInfo.name.endsWith('.css')) {
+        return 'assets/[name][extname]';
+      }
+      return '[name][extname]';
+    }
+  },
+  plugins: [
+    resolve(),
+    commonjs(),
+    atomix.rollupPlugin({
+      theme: 'dark',
+      components: ['Button', 'Modal', 'Card'],
+      optimize: true,
+      includeAtoms: false,
+      verbose: true
+    })
+  ]
+};
+```
+
+## Error Handling Examples
+
+All plugins include comprehensive error handling:
+
+```js
+import atomixPlugin from '@shohojdhara/atomix/build-tools/vite-plugin.js';
+
+// This will throw a validation error with helpful details
+try {
+  const plugin = atomixPlugin({
+    theme: 123, // Invalid type - should be string
+    components: 'Button' // Invalid type - should be array
+  });
+} catch (error) {
+  console.error(`${error.code}: ${error.message}`);
+  if (error.details) {
+    console.error('Details:', error.details);
+  }
+  if (error.suggestions) {
+    console.error('Suggestions:', error.suggestions);
+  }
+}
+```
+
+## Auto-Detection Integration
+
+For simpler setups, you can use the auto-detection feature:
+
+```js
+// vite.config.js (works similarly for webpack.config.js or rollup.config.js)
+import { initAutoIntegration } from '@shohojdhara/atomix/build-tools';
+
+const atomixIntegration = initAutoIntegration({
+  theme: 'default',
+  optimize: true
+});
+
+export default {
+  plugins: [
+    // ... other plugins
+    atomixIntegration
+  ]
+};
+```
+
+## Environment-Specific Configurations
+
+### Development vs Production
+
+```js
+// vite.config.js
+import { defineConfig, loadEnv } from 'vite';
+import atomix from '@shohojdhara/atomix/build-tools';
+
+export default defineConfig(({ mode }) => {
+  const env = loadEnv(mode, process.cwd(), '');
+  
+  return {
+    plugins: [
+      atomix.vitePlugin({
+        theme: env.VITE_ATOMIX_THEME || 'default',
+        optimizeCss: mode === 'production',  // Only optimize in production
+        verbose: mode === 'development'      // Show logs in development
+      })
+    ]
+  };
+});
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Theme Not Applied**
+   - Verify the theme name is valid by checking available themes:
+   ```js
+   import { getAvailableThemes } from '@shohojdhara/atomix/build-tools';
+   console.log(getAvailableThemes());
+   ```
+
+2. **Components Not Optimizing**
+   - Make sure the component names match exactly (case-sensitive)
+   - Verify the components exist in the Atomix library
+
+3. **Performance Issues**
+   - Disable verbose logging in production
+   - Limit the components list to only what you use
+   - Use the optimization features appropriately

package/build-tools/README.md

@@ -0,0 +1,242 @@
+# Atomix Build Tool Integrations
+
+This directory contains plugins and loaders for integrating the Atomix design system with popular build tools. All plugins provide comprehensive type safety, error handling, and optimization features.
+
+## Features
+
+- ✅ **Full TypeScript Support**: Comprehensive type definitions included
+- ✅ **Robust Error Handling**: Custom error classes with detailed diagnostics
+- ✅ **Component Optimization**: Tree-shaking and selective component imports
+- ✅ **Theme Integration**: Dynamic theme switching and CSS variable support
+- ✅ **Validation**: Runtime validation of all configuration options
+- ✅ **Verbose Logging**: Detailed logging for debugging and monitoring
+
+## Available Integrations
+
+### Vite Plugin
+
+The Vite plugin provides seamless integration of Atomix components and styles into Vite projects.
+
+#### Installation
+
+The build tools are included with the main Atomix package:
+
+```bash
+npm install @shohojdhara/atomix --save-dev
+```
+
+#### Type Safety
+
+TypeScript definitions are automatically included. For enhanced IDE support:
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import atomixPlugin, { type AtomixVitePluginOptions } from '@shohojdhara/atomix/build-tools';
+
+const options: AtomixVitePluginOptions = {
+  theme: 'dark',
+  components: ['Button', 'Card'],
+  optimizeCss: true,
+  includeAtoms: false,
+  verbose: true,
+};
+
+export default defineConfig({
+  plugins: [atomixPlugin(options)],
+});
+```
+
+#### Usage
+
+```js
+// vite.config.js
+import { defineConfig } from 'vite';
+import { vitePlugin as atomixPlugin } from '@shohojdhara/atomix/build-tools';
+
+export default defineConfig({
+  plugins: [
+    atomixPlugin({
+      theme: 'dark', // Specify theme ('default', 'dark', 'light')
+      components: ['Button', 'Card'], // Specific components to optimize
+      optimizeCss: true, // Enable CSS optimization
+      includeAtoms: false, // Include atomic styles
+    }),
+  ],
+});
+```
+
+#### Features
+
+- Automatic theme injection during development
+- CSS optimization for production builds
+- Component-specific imports optimization
+- Hot module replacement support
+
+### Webpack Loader
+
+The Webpack loader enables processing of Atomix components and styles in Webpack projects.
+
+#### Installation
+
+The build tools are included with the main Atomix package:
+
+```bash
+npm install @shohojdhara/atomix --save-dev
+```
+
+#### Type Safety
+
+```ts
+// webpack.config.ts
+import { type AtomixLoaderOptions } from '@shohojdhara/atomix/build-tools';
+
+const atomixLoaderOptions: AtomixLoaderOptions = {
+  includeAtoms: false,
+  components: ['Button', 'Input'],
+  excludeUnnecessaryStyles: true,
+  verbose: true,
+};
+```
+
+#### Usage
+
+```js
+// webpack.config.js
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.(js|jsx)$/,
+        include: [path.resolve(__dirname, 'node_modules/@shohojdhara/atomix')],
+        use: {
+          loader: require.resolve('@shohojdhara/atomix/build-tools/webpack-loader'),
+          options: {
+            includeAtoms: false, // Include atomic styles
+            components: ['Button', 'Input'], // Specific components to include
+            excludeUnnecessaryStyles: true, // Remove unused styles
+          },
+        },
+      },
+    ],
+  },
+};
+```
+
+#### Features
+
+- Component import optimization
+- Tree-shaking enhancement
+- Conditional atom inclusion
+- Style optimization
+
+### Rollup Plugin
+
+The Rollup plugin provides integration for projects using Rollup as their build tool.
+
+#### Installation
+
+The build tools are included with the main Atomix package:
+
+```bash
+npm install @shohojdhara/atomix --save-dev
+```
+
+#### Type Safety
+
+```ts
+// rollup.config.ts
+import { type AtomixRollupPluginOptions } from '@shohojdhara/atomix/build-tools';
+
+const atomixOptions: AtomixRollupPluginOptions = {
+  theme: 'default',
+  components: [],
+  optimize: true,
+  includeAtoms: false,
+  verbose: false,
+};
+```
+
+#### Usage
+
+```js
+// rollup.config.js
+import { rollupPlugin as atomixPlugin } from '@shohojdhara/atomix/build-tools';
+
+export default {
+  input: 'src/index.js',
+  output: {
+    dir: 'dist',
+    format: 'es',
+  },
+  plugins: [
+    atomixPlugin({
+      theme: 'default', // Specify theme
+      components: [], // Specific components to include
+      optimize: true, // Enable optimizations
+      includeAtoms: false, // Include atomic styles
+      verbose: false, // Enable verbose logging
+    }),
+  ],
+};
+```
+
+#### Features
+
+- Component import resolution
+- Bundle optimization
+- Theme-specific CSS processing
+- Virtual module generation
+
+## Common Options
+
+All plugins support these common options:
+
+- `theme`: Specifies which theme to use (default: 'default')
+- `components`: Array of specific components to include (default: [])
+- `optimize`: Enables optimization features (default: depends on plugin)
+- `includeAtoms`: Includes atomic styles (default: false)
+- `verbose`: Enable detailed logging for debugging (default: false)
+
+## Error Handling
+
+All plugins include comprehensive error handling with custom error types:
+
+```js
+try {
+  const plugin = atomixPlugin({
+    theme: 'nonexistent-theme', // This will throw a validation error
+    components: ['Button'],
+  });
+} catch (error) {
+  if (error.code === 'THEME_NOT_FOUND') {
+    console.error('Theme not found:', error.message);
+    console.log('Available themes:', error.details.availableThemes);
+  }
+}
+```
+
+Common error codes:
+
+- `INVALID_THEME_TYPE`: Theme option is not a string
+- `EMPTY_THEME`: Theme option is empty
+- `THEME_NOT_FOUND`: Specified theme doesn't exist
+- `INVALID_COMPONENTS_TYPE`: Components option is not an array
+- `INVALID_COMPONENT_NAMES`: Component names are not strings
+- `COMPONENTS_NOT_FOUND`: Some requested components don't exist
+
+## Best Practices
+
+1. **Optimize for Production**: Use the optimization features to reduce bundle size
+2. **Select Components Wisely**: Only include the components you actually use
+3. **Theme Management**: Specify your theme at build time to optimize CSS delivery
+4. **Tree Shaking**: Ensure your bundler supports tree shaking to remove unused code
+5. **Validation**: Always validate your configuration in development
+6. **Logging**: Enable verbose logging during troubleshooting
+7. **Type Safety**: Use TypeScript definitions for better IDE support and early error detection
+
+## Troubleshooting
+
+- If you encounter issues with theme resolution, ensure the specified theme exists in your Atomix installation
+- For problems with component imports, verify that component names match exactly
+- Enable verbose logging to get more information about the processing steps