@shohojdhara/atomix 0.3.4 → 0.3.6

package/README.md

@@ -1,250 +1,152 @@
 # Atomix Design System
 
-> A modern, accessible design system and component library for building beautiful user interfaces.
-
-[![npm version](https://img.shields.io/npm/v/@shohojdhara/atomix)](https://www.npmjs.com/package/@shohojdhara/atomix)
-[![License](https://img.shields.io/npm/l/@shohojdhara/atomix)](https://github.com/Shohojdhara/atomix/blob/main/LICENSE)
-[![Downloads](https://img.shields.io/npm/dm/@shohojdhara/atomix)](https://www.npmjs.com/package/@shohojdhara/atomix)
-
-## Overview
-
-Atomix is a modern, accessible design system and component library for building beautiful user interfaces. It provides a comprehensive set of 40+ production-ready components with consistent design language, accessibility compliance, and performance optimization.
-
-### Key Features
-
-- **40+ Production-Ready Components**: Buttons, cards, forms, navigation, and more
-- **Design System Compliance**: Consistent design language with design tokens
-- **Accessibility First**: WCAG 2.1 AA compliant components
-- **TypeScript Support**: Full TypeScript definitions for all components
-- **Responsive Design**: Mobile-first responsive components
-- **Dark Mode Support**: Built-in dark mode support for all components
-- **Tree-Shaking Support**: Optimized for modern bundlers
-- **Multiple Themes**: Multiple built-in themes with easy customization
-- **React & Vanilla JavaScript**: Support for both React and vanilla JavaScript
+> A modern, extensible design system for building scalable web applications
+
+[![npm version](https://img.shields.io/npm/v/@shohojdhara/atomix.svg)](https://www.npmjs.com/package/@shohojdhara/atomix)
+[![License](https://img.shields.io/npm/l/@shohojdhara/atomix.svg)](LICENSE)
+[![Downloads](https://img.shields.io/npm/dm/@shohojdhara/atomix.svg)](https://www.npmjs.com/package/@shohojdhara/atomix)
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Basic Usage](#basic-usage)
+  - [Theming](#theming)
+  - [React Integration](#react-integration)
+- [Components](#components)
+- [API](#api)
+- [Contributing](#contributing)
+- [License](#license)
+
+## Features
+
+- 🚀 **Fast & Lightweight** - Tree-shaking ready with minimal bundle impact
+- 🎨 **Themeable** - Advanced theme system with CSS variable support
+- ♿ **Accessible** - Built with WCAG accessibility standards in mind
+- 📱 **Responsive** - Mobile-first responsive design
+- 🔧 **Customizable** - Easy to customize and extend
+- 🧩 **Modular** - Pick only the components you need
+- 🔒 **TypeScript** - Full TypeScript support with definitions
+- 🛠 **Framework Agnostic** - Works with React, Vue, vanilla JS, etc.
 
 ## Installation
 
 ```bash
 npm install @shohojdhara/atomix
+# or
+yarn add @shohojdhara/atomix
+# or
+pnpm add @shohojdhara/atomix
 ```
 
 ## Usage
 
-### React
+### Basic Usage
 
-import { Button } from '@shohojdhara/atomix';
-import '@shohojdhara/atomix/css';
+```tsx
+import { Button } from '@shohojdhara/atomix/components';
+import '@shohojdhara/atomix/styles/index.css';
 
 function App() {
-  return <Button variant="primary">Hello World</Button>;
+  return (
+    <Button variant="primary" onClick={() => console.log('Hello Atomix!')}>
+      Click me
+    </Button>
+  );
 }
 ```
 
-### 🎨 Theme Management
-
-Atomix provides a powerful, developer-friendly theming system with **Tailwind-like configuration**:
-
-#### Tailwind-like Configuration (Recommended)
+### Theming
 
-Create `atomix.config.ts` in your project root:
+Atomix provides a flexible theme system that supports both CSS and JavaScript themes:
 
-```typescript
-import { defineConfig } from '@shohojdhara/atomix/config';
+```tsx
+import { ThemeProvider, createTheme } from '@shohojdhara/atomix/theme';
 
-export default defineConfig({
-  theme: {
-    extend: {
-      colors: {
-        primary: { main: '#7AFFD7' },
-        secondary: { main: '#FF5733' },
-      },
+// Create a custom theme
+const customTheme = createTheme({
+  palette: {
+    primary: { main: '#7AFFD7' },
+    secondary: { main: '#FF5733' },
+  },
+  spacing: 8,
+  breakpoints: {
+    values: {
+      xs: 0,
+      sm: 600,
+      md: 960,
+      lg: 1280,
+      xl: 1920,
     },
   },
 });
-```
-
-Use it in your app:
-
-```tsx
-import { loadAtomixConfig } from '@shohojdhara/atomix/config';
-import { createThemeFromConfig, ThemeProvider } from '@shohojdhara/atomix/theme';
-
-const config = loadAtomixConfig();
-const theme = createThemeFromConfig(config);
 
 function App() {
   return (
-    <ThemeProvider defaultTheme={theme}>
+    <ThemeProvider 
+      themes={{ 
+        'custom-theme': { name: 'Custom Theme', class: 'custom-theme' } 
+      }}
+      defaultTheme="custom-theme"
+    >
       <YourApp />
     </ThemeProvider>
   );
 }
 ```
 
-#### Quick Start with Themes
+### React Integration
 
-```jsx
-import { ThemeProvider, useTheme } from '@shohojdhara/atomix/theme';
+For React applications, we provide a complete set of hooks and context providers:
 
-function App() {
+```tsx
+import { useTheme } from '@shohojdhara/atomix/theme';
+
+function MyComponent() {
+  const { theme, setTheme, availableThemes } = useTheme();
+  
   return (
-    <ThemeProvider>
-      <YourApp />
-    </ThemeProvider>
+    <div>
+      <p>Current theme: {theme}</p>
+      <select 
+        value={theme} 
+        onChange={(e) => setTheme(e.target.value)}
+      >
+        {availableThemes.map(t => (
+          <option key={t.class} value={t.class}>
+            {t.name}
+          </option>
+        ))}
+      </select>
+    </div>
   );
 }
 ```
 
-#### Programmatic Theme Creation
-
-```jsx
-import { createTheme, ThemeProvider } from '@shohojdhara/atomix/theme';
-
-const myTheme = createTheme({
-  palette: {
-    primary: { main: '#7AFFD7' },
-  },
-});
-
-<ThemeProvider defaultTheme={myTheme}>
-  <App />
-</ThemeProvider>
-```
-
-For complete documentation, see:
-- [Getting Started - Theme System](docs/getting-started/theme-system.md) - Quick start guide
-- [Theme System Guide](docs/THEME_SYSTEM.md) - Complete reference (includes guides for both external developers and library developers)
-
-
-## Styles
-
-Atomix provides comprehensive styling through CSS or SCSS:
-
-### CSS
-
-```js
-// Import the main CSS file
-import '@shohojdhara/atomix/css';
-
-// Or import the minified version
-import '@shohojdhara/atomix/css/min';
-```
-
-### SCSS
-
-```scss
-// Import the main SCSS file
-@use '~@shohojdhara/atomix/scss' as atomix;
-
-// Or import individual modules
-@use '~@shohojdhara/atomix/scss/settings' as settings;
-@use '~@shohojdhara/atomix/scss/tools' as tools;
-@use '~@shohojdhara/atomix/scss/components' as components;
-```
-
-## Build Process
-
-The Atomix Design System uses a comprehensive build process to generate optimized assets:
-
-### Main Build
-
-```bash
-npm run build
-```
-
-This command will:
-1. Build the main JavaScript library (ESM and CJS formats)
-2. Generate TypeScript definitions
-3. Build the main CSS styles (`dist/atomix.css` and `dist/atomix.min.css`)
-
-### Individual Builds
-
-```bash
-# Build only the main styles
-npm run build:styles
-
-# Build only the themes
-npm run build:themes
-
-# Build only the main library
-npm run rollup -c
-```
-
-### Development
-
-```bash
-# Start Storybook for component development
-npm run dev
-
-# Run tests
-npm test
-
-# Run tests in watch mode
-npm run test:watch
-
-# Generate test coverage
-npm run test:coverage
-```
-
-### Storybook styles convention
-
-To keep visual docs and any snapshots stable, choose one of the following and stick to it:
-
-- Preferred: load the built CSS from dist.
-  - In your Storybook preview (e.g., .storybook/preview.ts/preview.js), import the bundled CSS once:
-    import '@shohojdhara/atomix/css'
-  - Before taking snapshots or publishing Storybook, ensure styles are compiled:
-    yarn build:styles
-
-- Alternative (for live theming/dev): load the source SCSS.
-  - Import from the SCSS entry point:
-    import '@shohojdhara/atomix/scss'
-  - This relies on your builder's SCSS pipeline; avoid mixing SCSS and built CSS in the same Storybook to prevent drift.
-
-Notes:
-- CSS bundles produced by the styles build are deterministic: dist/atomix.css and dist/atomix.min.css.
-- CI should run yarn attw to validate package exports and types after changes.
-
 ## Components
 
-Atomix provides 40+ production-ready components organized into categories:
-
-- **Actions**: [Button](src/components/Button), [Dropdown](src/components/Dropdown), [Pagination](src/components/Pagination)
-- **Data Display**: [Badge](src/components/Badge), [Card](src/components/Card), [DataTable](src/components/DataTable)
-- **Feedback**: [Callout](src/components/Callout), [Spinner](src/components/Spinner), [Progress](src/components/Progress)
-- **Forms**: [Checkbox](src/components/Checkbox), [Input](src/components/Input), [Select](src/components/Select)
-- **Navigation**: [Breadcrumb](src/components/Breadcrumb), [Navbar](src/components/Navbar), [Tabs](src/components/Tabs)
-- **Surfaces**: [Accordion](src/components/Accordion), [Callout](src/components/Callout), [Modal](src/components/Modal)
-- **Utilities**: [ColorModeToggle](src/components/ColorModeToggle), [Icon](src/components/Icon), [AtomixGlass](src/components/AtomixGlass), [AtomixLogo](src/components/AtomixLogo)
-
-## Design Tokens
-
-Atomix uses design tokens for consistent design language:
-
-- **Colors**: Consistent color palette with light and dark mode variants
-- **Spacing**: Consistent spacing scale based on 4px grid
-- **Typography**: Consistent typography scale with responsive adjustments
-- **Borders**: Consistent border radius and width system
-- **Shadows**: Consistent shadow system for depth and elevation
-
-## Accessibility
+The library includes over 50+ components including:
 
-All Atomix components are built with accessibility in mind:
+- **Layout**: Grid, Container, Section
+- **Navigation**: Navbar, Breadcrumb, Pagination
+- **Forms**: Input, Button, Select, Checkbox, Radio
+- **Feedback**: Alert, Modal, Tooltip, Toast
+- **Data Display**: Table, Card, Badge, Avatar
+- **Surfaces**: Accordion, Tabs, Expansion Panel
 
-- **WCAG 2.1 AA Compliant**: All components meet WCAG 2.1 AA standards
-- **Keyboard Navigation**: Full keyboard navigation support
-- **Screen Reader Support**: Proper ARIA attributes and semantic HTML
-- **Focus Management**: Consistent focus indicators and management
-- **Color Contrast**: Proper color contrast ratios for readability
+For a complete list, see [components documentation](./src/components/).
 
-## Browser Support
+## API
 
-Atomix supports all modern browsers:
+- [Components API](./docs/COMPONENTS_API.md)
+- [Theme API](./docs/THEME_API.md)
+- [Configuration](./docs/CONFIGURATION.md)
 
 ## Contributing
 
-Contributions are welcome! Please read our [contributing guidelines](CONTRIBUTING.md) for details on our code of conduct and development process.
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for more details.
 
 ## License
 
-Apache 2.0 © [Shohojdhara](https://github.com/Shohojdhara)
+MIT © [Shohojdhara](https://github.com/shohojdhara)

package/atomix.config.ts

@@ -0,0 +1,241 @@
+/**
+ * Atomix Configuration
+ * 
+ * This file is for external developers to customize the Atomix Design System.
+ * 
+ * External developers can create this file in their project root to customize
+ * design tokens, colors, spacing, typography, and more. The theme system will
+ * automatically load this configuration when using `createTheme()`.
+ * 
+ * @example
+ * ```typescript
+ * // atomix.config.ts (in your project)
+ * import { defineConfig } from '@shohojdhara/atomix/config';
+ * 
+ * export default defineConfig({
+ *   prefix: 'myapp',
+ *   theme: {
+ *     extend: {
+ *       colors: {
+ *         primary: { main: '#7AFFD7' },
+ *       },
+ *     },
+ *   },
+ * });
+ * ```
+ * 
+ * @example
+ * ```typescript
+ * // In your application code
+ * import { createTheme, injectTheme } from '@shohojdhara/atomix/theme';
+ * 
+ * // Automatically loads from atomix.config.ts
+ * const css = createTheme();
+ * injectTheme(css);
+ * ```
+ * 
+ * @see https://atomix.design/docs/configuration for full documentation
+ */
+
+// For library development, use local import
+// For external developers, use: import { defineConfig } from '@shohojdhara/atomix/config';
+import { defineConfig } from './src/lib/config';
+
+export default defineConfig({
+    /**
+     * CSS Variable Prefix
+     * 
+     * Change this to customize all CSS variable names.
+     * Example: prefix: 'myapp' → --myapp-primary instead of --atomix-primary
+     * 
+     * This prefix is automatically used by createTheme() when loading from config.
+     */
+    prefix: 'atomix',
+
+    /**
+     * Theme Customization
+     * 
+     * Tailwind-like configuration for customizing design tokens.
+     * Use `extend` to override or extend base tokens (recommended).
+     * Use `tokens` to completely replace the token system (advanced).
+     */
+    theme: {
+        /**
+         * Extend Default Design Tokens
+         * 
+         * These values will override or extend the base Atomix tokens.
+         * This is the recommended approach for customization.
+         */
+        extend: {
+            /**
+             * Color Customization
+             * 
+             * You can customize colors in multiple ways:
+             * 
+             * 1. Simple main color:
+             *    primary: { main: '#7AFFD7' }
+             * 
+             * 2. With light/dark variants:
+             *    primary: { main: '#7AFFD7', light: '#B3FFE8', dark: '#4DFFC4' }
+             * 
+             * 3. Full color scale (1-10):
+             *    primary: { 1: '#f0f9ff', 2: '#dbeafe', ..., 10: '#1e3a8a' }
+             * 
+             * 4. Main color (maps to step 6):
+             *    primary: { main: '#3b82f6', 6: '#3b82f6' }
+             */
+            colors: {
+                primary: {
+                    main: '#3b82f6', // Your brand primary color
+                    // Optional: provide full color scale (1-10)
+                    // 1: '#f0f9ff',  // lightest
+                    // 2: '#dbeafe',
+                    // 3: '#bfdbfe',
+                    // 4: '#93c5fd',
+                    // 5: '#60a5fa',
+                    // 6: '#3b82f6',  // main (default)
+                    // 7: '#2563eb',
+                    // 8: '#1d4ed8',
+                    // 9: '#1e40af',
+                    // 10: '#1e3a8a', // darkest
+                },
+                // Customize other semantic colors
+                // secondary: { main: '#10b981' },
+                // success: { main: '#22c55e' },
+                // error: { main: '#ef4444' },
+                // warning: { main: '#eab308' },
+                // info: { main: '#3b82f6' },
+            },
+
+            /**
+             * Spacing Scale
+             * 
+             * Customize spacing values used throughout the design system.
+             * These map to tokens like 'spacing-4', 'spacing-8', etc.
+             */
+            // spacing: {
+            //   '1': '0.25rem',   // 4px
+            //   '2': '0.5rem',    // 8px
+            //   '3': '0.75rem',   // 12px
+            //   '4': '1rem',      // 16px
+            //   '5': '1.25rem',   // 20px
+            //   '6': '1.5rem',    // 24px
+            //   '8': '2rem',      // 32px
+            //   '10': '2.5rem',   // 40px
+            //   '12': '3rem',     // 48px
+            //   '16': '4rem',     // 64px
+            //   '20': '5rem',     // 80px
+            // },
+
+            /**
+             * Typography Customization
+             * 
+             * Customize fonts, sizes, weights, and line heights.
+             */
+            // typography: {
+            //   // Font families
+            //   fontFamilies: {
+            //     sans: ['Inter', 'system-ui', 'sans-serif'],
+            //     serif: ['Georgia', 'serif'],
+            //     mono: ['Fira Code', 'monospace'],
+            //   },
+            //   // Font sizes
+            //   fontSizes: {
+            //     'xs': '0.75rem',   // 12px
+            //     'sm': '0.875rem',  // 14px
+            //     'base': '1rem',    // 16px
+            //     'lg': '1.125rem',  // 18px
+            //     'xl': '1.25rem',   // 20px
+            //     '2xl': '1.5rem',    // 24px
+            //     '3xl': '1.875rem', // 30px
+            //     '4xl': '2.25rem',  // 36px
+            //   },
+            //   // Font weights
+            //   fontWeights: {
+            //     'light': 300,
+            //     'normal': 400,
+            //     'medium': 500,
+            //     'semibold': 600,
+            //     'bold': 700,
+            //   },
+            //   // Line heights
+            //   lineHeights: {
+            //     'tight': 1.2,
+            //     'normal': 1.5,
+            //     'relaxed': 1.75,
+            //   },
+            // },
+
+            /**
+             * Border Radius
+             * 
+             * Customize border radius values.
+             */
+            // borderRadius: {
+            //   'sm': '0.25rem',   // 4px
+            //   'md': '0.5rem',     // 8px (default)
+            //   'lg': '0.75rem',   // 12px
+            //   'xl': '1rem',       // 16px
+            //   'full': '9999px',   // Fully rounded
+            // },
+
+            /**
+             * Shadows
+             * 
+             * Customize box shadow values.
+             */
+            // shadows: {
+            //   'sm': '0 1px 2px 0 rgba(0, 0, 0, 0.05)',
+            //   'md': '0 4px 6px -1px rgba(0, 0, 0, 0.1)',
+            //   'lg': '0 10px 15px -3px rgba(0, 0, 0, 0.1)',
+            //   'xl': '0 20px 25px -5px rgba(0, 0, 0, 0.1)',
+            // },
+
+            /**
+             * Z-Index Scale
+             * 
+             * Customize z-index values for layering.
+             */
+            // zIndex: {
+            //   'base': 0,
+            //   'dropdown': 1000,
+            //   'sticky': 1020,
+            //   'fixed': 1030,
+            //   'modal-backdrop': 1040,
+            //   'modal': 1050,
+            //   'popover': 1060,
+            //   'tooltip': 1070,
+            // },
+
+            /**
+             * Transitions
+             * 
+             * Customize transition durations and easings.
+             */
+            // transitions: {
+            //   durations: {
+            //     'fast': '150ms',
+            //     'base': '200ms',
+            //     'slow': '300ms',
+            //   },
+            //   easings: {
+            //     'ease-in': 'cubic-bezier(0.4, 0, 1, 1)',
+            //     'ease-out': 'cubic-bezier(0, 0, 0.2, 1)',
+            //     'ease-in-out': 'cubic-bezier(0.4, 0, 0.2, 1)',
+            // },
+            // },
+        },
+
+        /**
+         * Complete Token Override (Advanced)
+         * 
+         * Use with caution - this replaces the entire token system.
+         * Most users should use `extend` instead.
+         */
+        // tokens: {
+        //   colors: { /* your full color system */ },
+        //   spacing: { /* your full spacing scale */ },
+        //   // ... other token categories
+        // },
+    },
+});