aural-ui 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Pocket FM
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,456 @@
+# Aural UI
+
+[![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
+
+- **Core**:
+
+  - React (>=19.1.0)
+  - TypeScript
+  - Node.js (>=14.16)
+
+- **Styling**:
+
+  - Tailwind CSS
+  - CSS Variables for theming
+
+- **Component Design**:
+
+  - Radix UI (headless components)
+  - ARIA-compliant patterns
+
+- **Development Tools**:
+
+  - Storybook
+  - Changesets (for versioning)
+  - Vitest (testing)
+  - TSup (bundling)
+
+- **CLI Framework**:
+  - Commander.js
+  - Inquirer
+  - Chalk
+  - Ora
+
+## Installation
+
+```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
+
+```bash
+npx aural-ui init
+```
+
+This command will:
+
+- Create configuration for your project
+- Detect your project structure
+- Set up the component directory
+
+### Adding Components
+
+```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"
+  }
+}
+```
+
+You can modify this file to customize how Aural UI integrates with your project.
+
+## Project Setup
+
+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
+   ```
+
+2. Install dependencies:
+
+   ```bash
+   npm install
+   ```
+
+3. Run validation:
+
+   ```bash
+   npm run validate
+   ```
+
+4. Start development mode:
+   ```bash
+   npm run dev
+   ```
+
+### Building the Project
+
+```bash
+npm run build
+```
+
+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`
+
+### 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
+
+```bash
+# Install dependencies
+npm install
+
+# Generate theme files (automatically runs before storybook)
+npm run theme
+
+# Start Storybook development server
+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:
+
+- 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
+
+To create a custom theme:
+
+1. Create a new theme file in `src/ui/styles/themes/your-theme.ts`
+
+## Deployment
+
+### Storybook Deployment
+
+The Storybook documentation is automatically deployed to Netlify whenever
+changes are pushed to the main branch:
+
+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
+
+## Contributing
+
+Contributions are welcome! Please feel free to submit a Pull Request.
+
+### Development Workflow
+
+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
+
+### Contribution Guidelines
+
+- 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
+
+### Setup Development Environment
+
+```bash
+# Clone your fork
+git clone https://github.com/your-username/aural-ui.git
+cd aural-ui
+
+# Install dependencies
+npm install
+
+# Create a branch
+git checkout -b feature/your-feature-name
+
+# Run development mode
+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.
+
+### 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:
+
+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
+
+#### Setting up NPM_TOKEN for GitHub Actions
+
+To enable automated publishing, you need to add your npm token as a repository
+secret:
+
+1. Generate an npm access token:
+
+   - 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)
+
+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
+
+MIT © [Sawan Kumar](mailto:sawan.kumar@pocketfm.com)
+
+---
+
+Built with ❤️ by the team at [Pocket FM](https://pocketfm.com/)