aural-ui 2.0.2 → 2.0.4

package/README.md

@@ -1,456 +1,331 @@
-# Aural UI
+# 🎨 Aural UI
+
+<div align="center">
 
 [![npm version](https://img.shields.io/npm/v/aural-ui.svg)](https://www.npmjs.com/package/aural-ui)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![npm downloads](https://img.shields.io/npm/dm/aural-ui.svg)](https://www.npmjs.com/package/aural-ui)
-[![bundle size](https://img.shields.io/bundlephobia/minzip/aural-ui)](https://img.shields.io/bundlephobia/minzip/aural-ui)
-[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://img.shields.io/badge/TypeScript-Ready-blue.svg)
-
-A modern CLI toolkit for seamlessly integrating customizable UI components into
-React projects. Quickly scaffold, add, and manage production-ready components
-with minimal configuration.
-
-## Table of Contents
-
-- [Features](#features)
-- [Architecture](#architecture)
-- [Technology Stack](#technology-stack)
-- [Installation](#installation)
-- [Getting Started](#getting-started)
-- [Usage Examples](#usage-examples)
-- [Configuration](#configuration)
-- [Project Setup](#project-setup)
-- [Component Development](#component-development)
-  - [Adding a New Component](#adding-a-new-component)
-  - [Adding a New Hook](#adding-a-new-hook)
-  - [Adding a New Icon](#adding-a-new-icon)
-  - [Adding a New Utility](#adding-a-new-utility)
-- [Storybook](#storybook)
-  - [Running Storybook Locally](#running-storybook-locally)
-  - [Theme Support](#theme-support)
-- [Deployment](#deployment)
-- [Pros and Cons](#pros-and-cons)
-- [Contributing](#contributing)
-- [Publishing to npm](#publishing-to-npm)
-- [License](#license)
-
-## Features
-
-- 🚀 **Quick Setup**: Initialize your project with a single command
-- 🧩 **Component Library**: Ready-to-use React components styled with Tailwind
-  CSS
-- 🔌 **Plug & Play**: Automatically adds components to your project structure
-- ✨ **Modern UI**: Components built with modern design patterns
-- 🎨 **Customizable**: Easy to customize and extend components
-- 📦 **Zero Config**: Works out of the box with sensible defaults
-- 🌙 **Theme Support**: Built-in theming capabilities
-- 📚 **Storybook Integration**: Full documentation and visual testing
-
-## Architecture
-
-Aural UI follows a modular architecture designed for flexibility and easy
-maintenance:
-
-```
-aural-ui/
-├── src/
-│   ├── cli/            # CLI commands and utilities
-│   ├── core/           # Core library functionalities
-│   │   ├── constants/  # Shared constants
-│   │   ├── services/   # Core services
-│   │   ├── templates/  # Component and project templates
-│   │   ├── utils/      # Shared utility functions
-│   │   └── validation/ # Validation utilities
-│   └── ui/             # UI components and related files
-│       ├── components/ # React component library
-│       ├── hooks/      # React custom hooks
-│       ├── icons/      # SVG icon components
-│       ├── lib/        # UI library utilities
-│       └── styles/     # Theme and styling utilities
-├── dist/               # Built distribution files
-└── storybook-static/   # Built Storybook documentation
-```
-
-### Key Architectural Concepts
-
-- **CLI-First Approach**: Primary interaction through command-line interface
-- **Component Isolation**: Components are self-contained with their own logic
-  and styling
-- **Theme System**: Centralized theming with token-based design
-- **Documentation as Code**: Integrated documentation with Storybook
-
-## Technology Stack
+[![bundle size](https://img.shields.io/bundlephobia/minzip/aural-ui)](https://bundlephobia.com/package/aural-ui)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Storybook](https://img.shields.io/badge/Storybook-FF4785?style=flat&logo=storybook&logoColor=white)](https://aural-ui.netlify.app)
 
-- **Core**:
+A modern CLI toolkit for seamlessly integrating customizable UI components into React projects. Quickly scaffold, add, and manage production-ready components with minimal configuration.
 
-  - React (>=19.1.0)
-  - TypeScript
-  - Node.js (>=14.16)
+[📚 Documentation](https://aural-ui.netlify.app) • [🎨 Storybook](https://aural-ui.netlify.app) • [📦 NPM](https://www.npmjs.com/package/aural-ui) • [🐛 Issues](https://github.com/Pocket-Fm/fm-ui/issues)
 
-- **Styling**:
+</div>
 
-  - Tailwind CSS
-  - CSS Variables for theming
+## ✨ Features
 
-- **Component Design**:
+- 🚀 **CLI-First Approach** - Scaffold and manage components via intuitive CLI commands
+- 🎯 **Production Ready** - Battle-tested components used in production applications
+- 🎨 **Highly Customizable** - Full theming support with CSS variables and Tailwind CSS
+- 📱 **Accessible** - Built on Radix UI primitives for maximum accessibility
+- 🔧 **Type Safe** - Written in TypeScript with comprehensive type definitions
+- 📖 **Storybook Integration** - Interactive component documentation and testing
+- 🌙 **Dark Mode Support** - Built-in dark mode with easy theme switching
+- ⚡ **Performance Optimized** - Tree-shakeable components with minimal bundle impact
+- 🔄 **Hot Reloading** - Development experience with instant updates
+- 📦 **Zero Config** - Works out of the box with sensible defaults
 
-  - Radix UI (headless components)
-  - ARIA-compliant patterns
+## 🛠️ Tech Stack
 
-- **Development Tools**:
+### Core Technologies
+- **React** - Component library foundation
+- **TypeScript** - Type-safe development
+- **Tailwind CSS** - Utility-first styling
+- **Radix UI** - Accessible component primitives
+- **Class Variance Authority** - Component variant management
 
-  - Storybook
-  - Changesets (for versioning)
-  - Vitest (testing)
-  - TSup (bundling)
+### Build & Development
+- **Vite** - Fast build tool and dev server
+- **Tsup** - TypeScript bundler
+- **Storybook** - Component documentation and testing
+- **Vitest** - Unit testing framework
+- **Playwright** - End-to-end testing
 
-- **CLI Framework**:
-  - Commander.js
-  - Inquirer
-  - Chalk
-  - Ora
+### CLI & Tooling
+- **Commander.js** - CLI framework
+- **Inquirer.js** - Interactive command line prompts
+- **Chalk** - Terminal string styling
+- **Handlebars** - Template engine for code generation
+- **ESLint & Prettier** - Code quality and formatting
 
-## Installation
+## 📦 Installation
 
+### npm
 ```bash
-# Install globally (recommended)
 npm install -g aural-ui
-
-# Or install as a project dependency
-npm install aural-ui --save-dev
-
-# Or use directly with npx
-npx aural-ui [command]
 ```
 
-## Getting Started
-
-### Initialize Your Project
-
+### yarn
 ```bash
-npx aural-ui init
+yarn global add aural-ui
 ```
 
-This command will:
-
-- Create configuration for your project
-- Detect your project structure
-- Set up the component directory
-
-### Adding Components
-
+### pnpm
 ```bash
-npx aural-ui add [component-name]
-```
-
-## Configuration
-
-Aural UI creates a configuration file (`aural-ui.json`) in your project root
-with the following default settings:
-
-```json
-{
-  "framework": "react",
-  "styling": "tailwind",
-  "componentsDir": "src/components/aural-ui",
-  "libDir": "src/lib",
-  "tailwind": {
-    "css": "src/index.css",
-    "theme": "rose"
-  }
-}
+pnpm add -g aural-ui
 ```
 
-You can modify this file to customize how Aural UI integrates with your project.
-
-## Project Setup
+## 🚀 Quick Start
 
-For developers who want to contribute to Aural UI itself:
-
-1. Clone the repository:
-
-   ```bash
-   git clone https://github.com/YourOrganization/aural-ui.git
-   cd aural-ui
-   ```
+### 1. Initialize your project
+```bash
+# Create a new React project (if you don't have one)
+npx create-react-app my-app --template typescript
+cd my-app
 
-2. Install dependencies:
+# Initialize aural-ui
+aural-ui init
+```
 
-   ```bash
-   npm install
-   ```
+### 2. Add components
+```bash
+# Add individual components
+aural-ui add button
+aural-ui add card
+aural-ui add dialog
 
-3. Run validation:
+# Add multiple components
+aural-ui add button card dialog avatar
+```
 
-   ```bash
-   npm run validate
-   ```
+### 3. Configure themes
+```bash
+# Set up custom theme
+aural-ui theme
 
-4. Start development mode:
-   ```bash
-   npm run dev
-   ```
+# Update existing components
+aural-ui update
+```
 
-### Building the Project
+## 📋 Available Commands
+
+| Command | Description | Example |
+|---------|-------------|---------|
+| `init` | Initialize aural-ui in your project | `aural-ui init` |
+| `add <components>` | Add one or more components | `aural-ui add button card` |
+| `remove <components>` | Remove components from project | `aural-ui remove button` |
+| `update [components]` | Update components to latest version | `aural-ui update` |
+| `theme` | Configure theme and design tokens | `aural-ui theme` |
+
+## 🧩 Available Components
+
+### Layout & Structure
+- **AspectRatio** - Maintain consistent aspect ratios
+- **Card** - Flexible content containers
+- **Divider** - Visual content separation
+- **Resizable** - Resizable panel layouts
+- **ScrollArea** - Custom scrollable areas
+
+### Form Controls
+- **Button** - Interactive buttons with variants
+- **Input** - Text input fields
+- **Textarea** - Multi-line text input
+- **Checkbox** - Binary choice inputs
+- **Radio** - Single choice from multiple options
+- **Select** - Dropdown selection menus
+- **Slider** - Range value selection
+- **Switch** - Toggle controls
+
+### Navigation
+- **Tabs** - Tabbed content organization
+- **Pagination** - Page navigation controls
+- **Command** - Command palette interface
+
+### Feedback
+- **Toast** - Notification messages
+- **Dialog** - Modal dialogs
+- **Banner** - Important announcements
+- **Badge** - Status indicators
+- **Tooltip** - Contextual information
+
+### Data Display
+- **Avatar** - User profile images
+- **Table** - Data tables
+- **Typography** - Text styling components
+- **Chip** - Compact information display
+- **Tag** - Categorization labels
+
+### Utilities
+- **If-Else** - Conditional rendering helper
+- **Switch-Case** - Multi-condition rendering
+- **Overlay** - Modal overlays
+- **Skelton** - Loading placeholders
+
+## 🎨 Theming
+
+Aural UI provides a powerful theming system built on CSS variables and Tailwind CSS:
+
+```css
+:root {
+  --background: 0 0% 100%;
+  --foreground: 222.2 84% 4.9%;
+  --primary: 222.2 47.4% 11.2%;
+  --primary-foreground: 210 40% 98%;
+  /* ... more variables */
+}
+```
 
+### Custom Theme Configuration
 ```bash
-npm run build
+# Interactive theme setup
+aural-ui theme
+
+# This will:
+# 1. Generate CSS variables
+# 2. Create Tailwind config
+# 3. Set up component styles
+# 4. Configure Storybook themes
 ```
 
-This command runs the validation script first and then builds the project using
-TSup.
-
-## Component Development
-
-### Adding a New Component
-
-1. Create a new directory in `src/ui/components/[component-name]` with:
-
-   - `[component-name].tsx` - Component implementation
-   - `[component-name].stories.tsx` - Storybook documentation
-   - `[component-name].test.tsx` - Component tests
-   - `meta.ts` - Meta registration
-
-2. Follow the component structure pattern:
-
-   ```tsx
-   import { cn } from "src/lib/utils"
-
-   export interface ComponentNameProps {
-     className?: string
-     // Other props...
-   }
-
-   export function ComponentName({ className, ...props }: ComponentNameProps) {
-     return (
-       <div className={cn("aui-component-base", className)} {...props}>
-         {/* Component content */}
-       </div>
-     )
-   }
-   ```
-
-3. Export the component in the appropriate index file.
-
-### Adding a New Hook
-
-1. Create a new file in `src/ui/hooks/use-hook-name.ts`:
-
-   ```tsx
-   export function useHookName(params) {
-     // Hook implementation
-     return {
-       // Hook return values
-     }
-   }
-   ```
-
-2. Create tests in `src/ui/hooks/use-hook-name.test.tsx`
-
-3. Create a story in `src/ui/hooks/use-hook-name.stories.tsx` with usage
-   examples
-
-4. Export the hook in `src/ui/hooks/index.ts`
-
-5. Create meta registration in `src/ui/hooks/meta.ts`
+## 📖 Storybook
 
-### Adding a New Icon
-
-1. Optimize the SVG using a tool like SVGO
-
-2. Create a new file in `src/ui/icons/icon-name.tsx`:
-
-   ```tsx
-   export function IconName(props: React.SVGProps<SVGSVGElement>) {
-     return (
-       <svg
-         xmlns="http://www.w3.org/2000/svg"
-         viewBox="0 0 24 24"
-         fill="none"
-         stroke="currentColor"
-         {...props}
-       >
-         {/* SVG paths */}
-       </svg>
-     )
-   }
-   ```
-
-3. Export the icon in `src/ui/icons/index.ts`
-
-4. Create tests in `src/ui/icons/icon-name.test.tsx`
-
-5. Create story in `src/ui/icons/icon-name.stories.tsx`
-
-6. Create meta registration in `src/ui/hooks/meta.ts`
-
-### Adding a New Utility
-
-1. Create a new file in `src/core/utils/utility-name.ts` with appropriate
-   functionality
-
-2. Add tests in `src/core/utils/utility-name.test.ts`
-
-3. Add story in `src/core/utils/utility-name.stories.ts`
-
-4. Export the utility in `src/core/utils/index.ts`
-
-5. Create meta registration in `src/ui/hooks/meta.ts`
-
-## Storybook
-
-Aural UI uses Storybook for component documentation and development.
-
-### Running Storybook Locally
+Interactive component documentation is available at: **[https://aural-ui.netlify.app](https://aural-ui.netlify.app)**
 
+### Local Development
 ```bash
 # Install dependencies
 npm install
 
-# Generate theme files (automatically runs before storybook)
-npm run theme
-
-# Start Storybook development server
+# Start Storybook
 npm run storybook
 ```
 
-This will start the Storybook development server at `http://localhost:6006`.
-
-### Theme Support
-
-Aural UI includes integrated theme support that is automatically initialized
-when running Storybook:
+### Building Storybook
+```bash
+# Build static Storybook
+npm run build-storybook
 
-- Theme tokens are defined in `src/ui/styles/themes/`
-- The `npm run theme` command generates CSS variables from these tokens
-- Storybook includes a theme switcher to preview components in different themes
+# Deploy to Netlify
+npm run deploy-storybook
+```
 
-To create a custom theme:
+## 📁 Project Structure
 
-1. Create a new theme file in `src/ui/styles/themes/your-theme.ts`
+```
+aural-ui/
+├── 📁 src/
+│   ├── 📁 cli/               # CLI commands and utilities
+│   │   ├── 📁 commands/      # Individual command implementations
+│   │   │   ├── add.ts        # Add components command
+│   │   │   ├── init.ts       # Initialize project command
+│   │   │   ├── remove.ts     # Remove components command
+│   │   │   ├── theme.ts      # Theme configuration command
+│   │   │   └── update.ts     # Update components command
+│   │   └── index.ts          # CLI entry point
+│   ├── 📁 core/              # Core utilities and services
+│   │   ├── 📁 services/      # Business logic services
+│   │   ├── 📁 templates/     # Code generation templates
+│   │   ├── 📁 utils/         # Utility functions
+│   │   ├── 📁 validation/    # Input validation
+│   │   └── constants.ts      # Global constants
+│   ├── 📁 ui/                # UI components and assets
+│   │   ├── 📁 components/    # React components
+│   │   ├── 📁 hooks/         # Custom React hooks
+│   │   ├── 📁 lib/           # Utility libraries
+│   │   ├── 📁 styles/        # Global styles and themes
+│   │   ├── 📁 icons/         # Icon components
+│   │   └── 📁 fonts/         # Font assets
+│   └── 📁 stories/           # Storybook stories
+├── 📁 aural-ui-example/      # Example implementation
+├── 📁 storybook-static/      # Built Storybook output
+├── 📄 package.json           # Package configuration
+├── 📄 tsconfig.json          # TypeScript configuration
+├── 📄 vite.config.mts        # Vite configuration
+└── 📄 README.md              # This file
+```
 
-## Deployment
+## 🌍 Deployment
 
 ### Storybook Deployment
+The component documentation is automatically deployed to Netlify:
 
-The Storybook documentation is automatically deployed to Netlify whenever
-changes are pushed to the main branch:
+1. **Build**: `npm run build-storybook`
+2. **Deploy**: `npm run deploy-storybook`
+3. **Live URL**: [https://aural-ui.netlify.app](https://aural-ui.netlify.app)
 
-1. Build the Storybook for production:
-
-   ```bash
-   npm run build-storybook
-   ```
-
-2. The built Storybook is available in the `storybook-static` directory
-
-3. CI/CD automatically deploys this directory to Netlify
-
-### Live Storybook
-
-The Storybook documentation is available online:
-
-[https://aural-ui.netlify.app/](https://aural-ui.netlify.app/)
-
-## Pros and Cons
-
-### Pros
-
-- ✅ **Easy Integration**: Simple CLI commands to add components to any project
-- ✅ **Modern Stack**: Built with modern React patterns and TypeScript
-- ✅ **Theming**: Robust theme system for customization
-- ✅ **Accessibility**: Components follow WAI-ARIA guidelines
-- ✅ **Well-Documented**: Thorough documentation with Storybook
-- ✅ **Minimum Dependencies**: Core library has minimal external dependencies
-- ✅ **TypeScript Support**: Full type definitions for all components
+### NPM Package
+```bash
+# Build for production
+npm run build
 
-## Contributing
+# Publish to NPM
+npm run release
+```
 
-Contributions are welcome! Please feel free to submit a Pull Request.
+## 💡 Benefits
 
-### Development Workflow
+### For Developers
+- **Rapid Development** - Add production-ready components in seconds
+- **Consistent Design** - Maintain design system consistency across projects
+- **Type Safety** - Full TypeScript support with IntelliSense
+- **Customization** - Easy theming and component customization
+- **Documentation** - Interactive Storybook documentation
 
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing-feature`)
-3. Run validation and tests (`npm run validate && npm test`)
-4. Commit your changes with a descriptive message
-5. Push to the branch (`git push origin feature/amazing-feature`)
-6. Open a Pull Request
+### For Teams
+- **Standardization** - Consistent component library across projects
+- **Productivity** - Reduce time spent building common UI components
+- **Maintainability** - Centralized component updates and bug fixes
+- **Accessibility** - Built-in accessibility best practices
+- **Scalability** - Modular architecture for large applications
 
-### Contribution Guidelines
+### For Projects
+- **Performance** - Optimized bundle size with tree-shaking
+- **Modern Stack** - Latest React, TypeScript, and tooling
+- **Cross-Platform** - Works with any React framework (Next.js, Vite, CRA)
+- **Future-Proof** - Regular updates and modern development practices
 
-- Follow the existing code style and conventions
-- Write tests for new functionality
-- Update documentation for any new or changed features
-- Add a changeset for version management (`npm run changeset`)
-- Ensure all tests pass before submitting a pull request
+## 🤝 Contributing
 
-### Setup Development Environment
+We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
 
+### Development Setup
 ```bash
-# Clone your fork
-git clone https://github.com/your-username/aural-ui.git
+# Clone the repository
+git clone https://github.com/Pocket-Fm/fm-ui.git
 cd aural-ui
 
 # Install dependencies
 npm install
 
-# Create a branch
-git checkout -b feature/your-feature-name
-
-# Run development mode
+# Start development
 npm run dev
-```
-
-## Publishing to npm
-
-### Manual Publishing
-
-If you're a maintainer of this package, follow these steps to publish to npm
-manually:
-
-1. Update the version in `package.json` (follow [semver](https://semver.org/))
-2. Make sure all tests pass with `npm test`
-3. Build the package with `npm run build`
-4. Log in to npm with `npm login`
-5. Publish with `npm publish`
 
-The `prepublishOnly` script will automatically run the build before publishing.
+# Run tests
+npm test
 
-### Automated Publishing with GitHub Actions
-
-This project uses GitHub Actions to automatically publish to npm when changes
-are pushed to the main branch. The workflow:
+# Start Storybook
+npm run storybook
+```
 
-1. Checks out the repository
-2. Sets up Node.js
-3. Configures Git and npm authentication
-4. Installs dependencies and builds the package
-5. Uses [Changesets](https://github.com/changesets/changesets) to create a
-   release PR or publish to npm
+### Development Scripts
+| Script | Description |
+|--------|-------------|
+| `npm run dev` | Start development build with watch mode |
+| `npm run build` | Build for production |
+| `npm run test` | Run unit tests |
+| `npm run lint` | Lint code with ESLint |
+| `npm run format` | Format code with Prettier |
+| `npm run storybook` | Start Storybook development server |
 
-#### Setting up NPM_TOKEN for GitHub Actions
+## 📄 License
 
-To enable automated publishing, you need to add your npm token as a repository
-secret:
+This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
 
-1. Generate an npm access token:
+## 🙏 Acknowledgments
 
-   - Log in to your npm account at https://www.npmjs.com/
-   - Click on your profile picture → Access Tokens
-   - Click "Generate New Token" and select "Automation" type
-   - Copy the generated token (you won't see it again)
+- [Radix UI](https://radix-ui.com/) - For accessible component primitives
+- [Tailwind CSS](https://tailwindcss.com/) - For utility-first CSS framework
+- [Shadcn/ui](https://ui.shadcn.com/) - For design inspiration
+- [Storybook](https://storybook.js.org/) - For component documentation
 
-2. Add the token to GitHub repository secrets:
-   - Go to your GitHub repository → Settings → Secrets and variables → Actions
-   - Click "New repository secret"
-   - Set the name as "NPM_TOKEN" and paste your npm token as the value
-   - Click "Add secret"
+---
 
-## License
+<div align="center">
 
-MIT © [Sawan Kumar](mailto:sawan.kumar@pocketfm.com)
+**Built with ❤️ by the Pocket FM team**
 
----
+[Website](https://pocketfm.com) • [GitHub](https://github.com/Pocket-Fm) • [NPM](https://www.npmjs.com/package/aural-ui)
 
-Built with ❤️ by the team at [Pocket FM](https://pocketfm.com/)
+</div>