@hellboy/ds 0.1.2 → 0.2.7

package/README.md

@@ -1,111 +1,608 @@
-# Hellboy Design System - Core
+# 🔥 @hellboy/ds - Hellboy Design System
 
-Base package for the Hellboy Design System containing foundational components, tokens, and styling utilities.
+> _Where chaos meets precision: A comprehensive, accessible-first design system for modern React applications_
 
-## 📦 Package Contents
+[![npm version](https://img.shields.io/npm/v/@hellboy/ds.svg)](https://www.npmjs.com/package/@hellboy/ds)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue)](https://www.typescriptlang.org/)
+[![React](https://img.shields.io/badge/React-18%20%7C%2019-blue)](https://reactjs.org/)
 
-### Tokens
-- **Colors**: Primary, neutral, and semantic colors
-- **Typography**: Font families, sizes, weights, and line heights
-- **Spacing**: Consistent spacing scale
+A complete design system with **42+ production-ready components**, dual theming (light/dark), and comprehensive accessibility features built with React, TypeScript, and modern web standards.
 
-### Foundations
-- **Global Reset**: Base HTML and element resets
-- **Utilities**: Helper functions for style injection
+## ✨ Features
 
-### Components
-- **Button**: Accessible interactive component with multiple variants and sizes (powered by AriaKit)
+- 🎨 **42+ Components** - Buttons, inputs, dialogs, tables, and more
+- 🌓 **Dual Theme System** - Light and dark modes with customizable colors (HSLA-based)
+- ♿ **Accessibility First** - WCAG 2.1 AA compliant with AriaKit primitives
+- 📱 **Desktop Priority** - Optimized for desktop (1024px+), tablet/mobile in roadmap
+- 🎯 **TypeScript Native** - Full type safety and IntelliSense support
+- 🔌 **Auto Dependencies** - Components automatically include all required dependencies
+- 🎭 **150,000+ Icons** - Iconify integration for extensive icon library
+- 📦 **Tree-shakeable** - Import only what you need
+- 🚀 **CSS-First** - Minimal runtime overhead with CSS custom properties
+- 💾 **Persistent Preferences** - User theme and color choices saved locally
 
-## 🚀 Getting Started
-
-### Installation
+## 🚀 Installation
 
 ```bash
-npm install @hellboy-ds/core @ariakit/react react react-dom
+npm install @hellboy/ds
+
+# Peer dependencies (if not already installed)
+npm install react react-dom
 ```
 
-### Usage
+**That's it!** All component dependencies are automatically included in the CSS bundles.
 
-```tsx
-import { Button, injectGlobalStyles } from '@hellboy-ds/core';
+## 📖 Quick Start
 
-// Inject global styles once at app initialization
-injectGlobalStyles();
+### Basic Usage
+
+```tsx
+import '@hellboy/ds/dist/index.css';
+import { Button, Input, Dialog, Banner, ThemeControl } from '@hellboy/ds';
 
-// Use the Button component
 export function App() {
   return (
     <div>
-      <Button>Primary Button</Button>
-      <Button variant="secondary">Secondary Button</Button>
-      <Button variant="tertiary">Tertiary Button</Button>
-      <Button size="lg">Large Button</Button>
-      <Button isLoading>Loading...</Button>
-      <Button disabled>Disabled Button</Button>
+      {/* Theme switcher in top-right corner */}
+      <ThemeControl />
+      
+      {/* Components work out of the box */}
+      <Banner type="info">
+        Welcome to Hellboy Design System!
+      </Banner>
+      
+      <Button variant="primary">Primary Action</Button>
+      <Input label="Email" type="email" placeholder="you@example.com" />
     </div>
   );
 }
 ```
 
-## 🎨 Customization
+### Advanced: Tree-shaking (Individual Components)
 
-All tokens are exported and can be imported directly:
+Import only specific components to reduce bundle size:
 
 ```tsx
-import { colors, typography, spacing } from '@hellboy-ds/core';
+// Option 1: Single component import (recommended)
+import '@hellboy/ds/dist/index.css';
+import { Button } from '@hellboy/ds';
 
-// Use tokens in your components
-const customStyle = {
-  color: colors.primary,
-  fontSize: typography.fontSize.lg,
-  padding: spacing[4],
-};
+// Option 2: Subpath imports (maximum tree-shaking)
+import '@hellboy/ds/components/button/css';
+import { Button } from '@hellboy/ds/components/button';
 ```
 
-## 📝 Building
+**Note**: Each component's CSS already includes all its dependencies (foundations, themes, utilities), so you never need to import foundation files manually.
 
-```bash
-npm run build      # Build the package
-npm run dev        # Watch mode
-npm run clean      # Clean dist directory
+## 🔌 Auto-Dependency Injection
+
+Every component automatically includes everything it needs:
+
+```tsx
+// ✅ This works - button.css includes:
+//    - Component styles
+//    - Foundation CSS (typography, spacing, colors)
+//    - Theme variables (light/dark)
+//    - Shared utilities
+import '@hellboy/ds/components/button/css';
+import { Button } from '@hellboy/ds/components/button';
+```
+
+**Zero configuration required!** Just import and use.
+
+## 🧱 Available Components (42+)
+
+### Layout & Structure
+- **Layout** - Main application layout with navigation
+- **Page** - Page wrapper with consistent spacing  
+- **Header** - Page headers with titles, subtitles, and tags
+- **Hero** - Hero sections for landing pages
+- **Section** - Content sections with automatic indexing
+- **Grid** - Responsive grid system
+- **Card** - Content cards with variants
+- **Footer** - Page footer component
+- **Divider** - Visual content separators
+
+### Forms & Inputs
+- **Button** - Interactive buttons (4 variants, 4 sizes, icons, loading states)
+  - Dependencies: foundations, icons, theme
+- **ButtonGroup** - Grouped button controls
+- **Checkbox** - Accessible checkboxes with label support
+  - Dependencies: foundations, theme
+- **Radio** - Radio button groups
+  - Dependencies: foundations, theme
+- **Select** - Dropdown selection component
+  - Dependencies: foundations, popover, theme
+- **Input** - Text inputs with multiple types
+  - `InputText`, `InputEmail`, `InputPassword`, `InputNumber`, `InputTel`, `InputUrl`, `InputSearch`, `InputDate`, `InputTime`, `InputDateTime`
+  - Dependencies: foundations, icons, theme, popover (for date/time)
+- **Textarea** - Multi-line text input
+  - Dependencies: foundations, theme
+- **RichTextarea** - Rich text editor with formatting toolbar
+  - Dependencies: foundations, icons, floatingbar, select, tooltip, theme
+  - External: DOMPurify for HTML sanitization
+- **Slider** - Range slider control
+  - Dependencies: foundations, theme
+- **Switch** - Toggle switch component
+  - Dependencies: foundations, theme
+
+### Navigation
+- **Navbar** - Main navigation bar with routing and tooltips
+  - Dependencies: foundations, button, tooltip, backdrop, theme
+- **Breadcrumbs** - Breadcrumb navigation
+  - Dependencies: foundations, theme
+- **FloatingBar** - Floating action bar
+  - Dependencies: foundations, theme
+- **PageIndex** - Auto-generated page navigation from sections
+  - Dependencies: foundations, theme
+
+### Feedback & Display
+- **Badge** - Status and label badges (8 variants)
+  - Dependencies: foundations, theme
+- **Tag** - Categorization tags (8 variants, 3 sizes)
+  - Dependencies: foundations, theme
+- **Banner** - Alert and notification banners (4 types: info, success, warning, error)
+  - Dependencies: foundations, icons, button, theme
+- **Dialog** - Modal dialogs with backdrop
+  - Dependencies: foundations, backdrop, theme
+  - External: React Portal
+- **Drawer** - Slide-out panel component
+  - Dependencies: foundations, backdrop, theme
+- **Tooltip** - Contextual tooltips with auto-positioning
+  - Dependencies: foundations, theme
+  - External: React Portal
+- **CodeBlock** - Syntax-highlighted code display
+  - Dependencies: foundations, button, theme
+- **List** - Structured list component
+  - Dependencies: foundations, theme
+- **Table** - Data tables with headers, rows, cells
+  - Components: `Table`, `TableContainer`, `TableHead`, `TableBody`, `TableRow`, `TableCell`
+  - Dependencies: foundations, theme
+
+### Interactive
+- **ThemeControl** - Theme switcher component (light/dark toggle)
+  - Dependencies: foundations, button, theme
+- **ColorControl** - Color customization interface
+  - Dependencies: foundations, input, button, theme
+- **DragHandle** - Drag and drop handles
+  - Dependencies: foundations, icons, theme
+- **Popover** - Floating popover component with positioning
+  - Dependencies: foundations, theme
+  - External: React Portal
+- **Icon** - Icon component with Iconify integration
+  - Dependencies: foundations
+  - External: @iconify/react (150,000+ icons)
+
+### Shared Components
+- **Backdrop** - Modal/dialog backdrop overlay
+  - Dependencies: foundations, theme
+
+## 📦 Dependencies
+
+### Included Dependencies (Auto-installed with package)
+```json
+{
+  "@ariakit/react": "^0.4.0",      // Accessible component primitives
+  "@iconify/react": "^6.0.2",       // Icon framework (150,000+ icons)
+  "dompurify": "^3.2.2"             // HTML sanitization (RichTextarea)
+}
+```
+
+### Peer Dependencies (Required by your app)
+```json
+{
+  "react": "^18.0.0 || ^19.0.0",
+  "react-dom": "^18.0.0 || ^19.0.0"
+}
+```
+
+**Note**: Components automatically handle their CSS dependencies. When you import a component's CSS, it includes all required foundation styles, theme variables, and utilities.
+
+## 🎨 Theme System
+
+### Using Themes
+
+```tsx
+import { setTheme, getTheme, getUserPreferences, setUserPreferences } from '@hellboy/ds';
+
+// Get current theme
+const currentTheme = getTheme(); // 'light' | 'dark'
+
+// Set theme (persists to localStorage)
+setTheme('dark');
+
+// Get all user preferences
+const prefs = getUserPreferences();
+console.log(prefs.theme); // 'light' | 'dark' | 'auto'
+
+// Update preferences
+setUserPreferences({ 
+  theme: 'dark',
+  colors: {
+    primary: { hue: 220, saturation: 70, lightness: 50 }
+  }
+});
+```
+
+### Theme Features
+- 🌓 **Dual Modes**: Light and dark themes included
+- 🎨 **Customizable**: 7 color hues (primary, secondary, accent, success, warning, error, info)
+- 💾 **Persistent**: Preferences saved to localStorage
+- 🔄 **Auto Detection**: Respects system preference (prefers-color-scheme)
+- 📐 **HSLA-based**: Hue, Saturation, Lightness, Alpha for easy customization
+
+### CSS Custom Properties
+
+Themes use CSS custom properties that you can override:
+
+```css
+:root {
+  /* Color hues (0-360) */
+  --primary-hue: 330;
+  --secondary-hue: 240;
+  --accent-hue: 180;
+  
+  /* Semantic colors */
+  --color-primary: hsl(var(--primary-hue), 70%, 50%);
+  --color-on-primary: hsl(var(--primary-hue), 70%, 10%);
+  
+  /* Typography */
+  --font-family-heading: 'Signika', sans-serif;
+  --font-family-body: 'Rubik', sans-serif;
+  
+  /* Spacing scale */
+  --spacing-1: 0.25rem;  /* 4px */
+  --spacing-2: 0.5rem;   /* 8px */
+  /* ... up to spacing-16 */
+}
 ```
 
-## 📋 Features
+## 🔄 Component API Examples
+
+### Button
+
+**Variants:** `primary` | `secondary` | `tertiary` | `ghost`  
+**Sizes:** `xs` | `sm` | `md` (default) | `lg`
+
+```tsx
+import { Button } from '@hellboy/ds';
 
-- ✅ Built with AriaKit for accessibility
-- ✅ Full ARIA support out of the box
-- ✅ CSS-in-JS styling with inline tokens
-- ✅ Strongly typed TypeScript components
-- ✅ Consistent design tokens system
-- ✅ Semantic color palette
-- ✅ Responsive and accessible components
-- ✅ Loading and disabled states
+// Variants
+<Button variant="primary">Primary</Button>
+<Button variant="secondary">Secondary</Button>
+<Button variant="tertiary">Tertiary</Button>
+<Button variant="ghost">Ghost</Button>
 
-## 🔄 Component Variants
+// Sizes
+<Button size="xs">Extra Small</Button>
+<Button size="sm">Small</Button>
+<Button size="md">Medium</Button>
+<Button size="lg">Large</Button>
 
-### Button Variants
-- `primary` - Main action button
-- `secondary` - Alternative action button
-- `tertiary` - Low emphasis action button
+// With icons (150,000+ from Iconify)
+<Button startIcon="mdi:check">Save</Button>
+<Button endIcon="mdi:arrow-right">Next</Button>
+<Button iconOnly aria-label="Settings" startIcon="mdi:cog" />
 
-### Button Sizes
-- `sm` - Small (32px height)
-- `md` - Medium (40px height) - default
-- `lg` - Large (48px height)
+// States
+<Button isLoading>Saving...</Button>
+<Button disabled>Disabled</Button>
+<Button fullWidth>Full Width</Button>
+```
 
-### Button Props
-- `variant` - Button style variant
+**Props:**
+- `variant` - Visual style
 - `size` - Button size
 - `isLoading` - Show loading spinner
-- `disabled` - Disable the button
-- `fullWidth` - Make button full width
-- All standard AriaKit button attributes are supported
+- `disabled` - Disable interaction
+- `fullWidth` - Expand to container width
+- `startIcon` / `endIcon` - Icon names from Iconify
+- `iconOnly` - Icon-only button (requires `aria-label`)
+
+### Input Components
+
+All input types: `InputText`, `InputEmail`, `InputPassword`, `InputNumber`, `InputTel`, `InputUrl`, `InputSearch`, `InputDate`, `InputTime`, `InputDateTime`
+
+```tsx
+import { InputText, InputEmail, InputPassword, InputNumber } from '@hellboy/ds';
+
+// Basic inputs
+<InputText label="Name" placeholder="Enter your name" />
+<InputEmail label="Email" required />
+<InputPassword label="Password" />
+
+// With states
+<InputText 
+  label="Username" 
+  helperText="Choose a unique username"
+  error={errors.username}
+/>
+
+// Number input with constraints
+<InputNumber 
+  label="Age" 
+  min={0} 
+  max={120} 
+  step={1}
+/>
+
+// Date/Time pickers
+<InputDate label="Birthday" />
+<InputTime label="Meeting Time" />
+<InputDateTime label="Event Start" />
+
+// Sizes
+<InputText size="sm" label="Small" />
+<InputText size="md" label="Medium" />
+<InputText size="lg" label="Large" />
+```
+
+**Props:**
+- `label` - Input label text
+- `helperText` - Helper text below input
+- `error` - Error message (triggers error state)
+- `fullWidth` - Expand to container width
+- `size` - Input size: `sm` | `md` | `lg`
+
+### Textarea
+
+```tsx
+import { Textarea, RichTextarea } from '@hellboy/ds';
+
+// Simple textarea
+<Textarea 
+  label="Comments" 
+  placeholder="Enter your feedback..."
+  rows={4}
+/>
+
+// Rich text editor
+<RichTextarea
+  value={content}
+  onChange={setContent}
+  placeholder="Start typing..."
+  toolbarOptions={['bold', 'italic', 'link', 'orderedList', 'unorderedList']}
+  showTopToolbar={true}
+/>
+```
+
+### Banner
+
+**Types:** `info` | `success` | `warning` | `error`
+
+```tsx
+import { Banner } from '@hellboy/ds';
+
+<Banner type="info">
+  This is an informational message.
+</Banner>
+
+<Banner type="success" onDismiss={() => console.log('Dismissed')}>
+  <strong>Success!</strong> Your changes have been saved.
+</Banner>
+
+<Banner type="warning">
+  <strong>Warning:</strong> This action cannot be undone.
+</Banner>
+
+<Banner type="error">
+  <strong>Error:</strong> Something went wrong.
+</Banner>
+```
+
+### Dialog
+
+```tsx
+import { Dialog, Button } from '@hellboy/ds';
+import { useState } from 'react';
+
+function MyComponent() {
+  const [isOpen, setIsOpen] = useState(false);
+  
+  return (
+    <>
+      <Button onClick={() => setIsOpen(true)}>Open Dialog</Button>
+      
+      <Dialog
+        open={isOpen}
+        onClose={() => setIsOpen(false)}
+        title="Confirm Action"
+        size="md" // sm | md | lg
+      >
+        <p>Are you sure you want to continue?</p>
+        
+        <div style={{ display: 'flex', gap: '1rem', marginTop: '1rem' }}>
+          <Button variant="secondary" onClick={() => setIsOpen(false)}>
+            Cancel
+          </Button>
+          <Button onClick={() => setIsOpen(false)}>
+            Confirm
+          </Button>
+        </div>
+      </Dialog>
+    </>
+  );
+}
+```
+
+### Table
+
+```tsx
+import { Table, TableContainer, TableHead, TableBody, TableRow, TableCell } from '@hellboy/ds';
+
+<TableContainer>
+  <Table bordered striped hover>
+    <TableHead>
+      <TableRow>
+        <TableCell header>ID</TableCell>
+        <TableCell header>Name</TableCell>
+        <TableCell header>Email</TableCell>
+      </TableRow>
+    </TableHead>
+    <TableBody>
+      {users.map(user => (
+        <TableRow key={user.id}>
+          <TableCell>{user.id}</TableCell>
+          <TableCell>{user.name}</TableCell>
+          <TableCell>{user.email}</TableCell>
+        </TableRow>
+      ))}
+    </TableBody>
+  </Table>
+</TableContainer>
+```
+
+### Tooltip
+
+```tsx
+import { Tooltip, Button } from '@hellboy/ds';
+
+<Tooltip content="This is a helpful tip" placement="top">
+  <Button>Hover me</Button>
+</Tooltip>
+
+<Tooltip 
+  content={<strong>Rich content</strong>}
+  placement="bottom"
+  delay={500}
+>
+  <span>Delayed tooltip</span>
+</Tooltip>
+```
+
+### Tag & Badge
+
+```tsx
+import { Tag, Badge } from '@hellboy/ds';
+
+// Tags (8 variants, 3 sizes)
+<Tag variant="primary">Primary</Tag>
+<Tag variant="success" size="sm">Small Success</Tag>
+<Tag variant="warning" size="lg">Large Warning</Tag>
+
+// Badges
+<Badge variant="primary">New</Badge>
+<Badge variant="error">5</Badge>
+```
+
+### Theme Control
+
+```tsx
+import { ThemeControl } from '@hellboy/ds';
+
+// Theme switcher component
+<ThemeControl />
+
+// Or use programmatically
+import { setTheme, getTheme } from '@hellboy/ds';
+
+const currentTheme = getTheme(); // 'light' | 'dark'
+setTheme('dark');
+```
+
+## 🖥️ Platform Support
+
+**Current Focus: Desktop Applications (1024px+)**
+
+Hellboy Design System is currently optimized for desktop experiences. All components are designed, tested, and optimized primarily for desktop interfaces.
+
+**Roadmap:**
+- 📱 **Tablet Support** (768px - 1023px) - Q2 2026
+- 📲 **Mobile Support** (< 768px) - Q3 2026
+- 🎯 **Responsive Utilities** - Q2 2026
 
 ## ♿ Accessibility
 
-All components are built with accessibility in mind:
-- Full keyboard navigation support
-- ARIA attributes automatically managed
-- Screen reader friendly
-- Focus management
-- Semantic HTML
+Every component is built with accessibility as a core principle:
+
+- ✅ **WCAG 2.1 AA Compliant** - Color contrast, focus indicators, semantic HTML
+- ⌨️ **Keyboard Navigation** - Full keyboard support with logical tab order
+- 🔊 **Screen Reader Support** - Proper ARIA labels, roles, and live regions
+- 🎯 **Focus Management** - Visible focus indicators respecting user preferences
+- 🏗️ **Semantic HTML** - Native elements enhanced with ARIA when needed
+- 🎨 **Color Contrast** - AA compliant in both light and dark themes
+- ⚡ **Motion Respect** - Honors `prefers-reduced-motion` for animations
+- 🔧 **AriaKit Foundation** - Built on battle-tested accessibility primitives from AriaKit
+
+## 📐 Package Architecture
+
+### Build Output
+
+```
+dist/
+├── index.css              # Complete CSS bundle (~120 KB minified)
+├── index.js               # All components (CommonJS)
+├── index.mjs              # All components (ESM)
+├── index.d.ts             # TypeScript declarations
+├── theme.css              # Theme variables only
+└── components/
+    ├── button.js          # Button component (CommonJS)
+    ├── button.mjs         # Button component (ESM)
+    ├── button.d.ts        # Button TypeScript types
+    ├── button.css         # Button styles + all dependencies
+    └── ... (42 components)
+```
+
+### Import Patterns
+
+```tsx
+// ✅ Recommended: Full bundle
+import '@hellboy/ds/dist/index.css';
+import { Button, Input, Dialog } from '@hellboy/ds';
+
+// ✅ Advanced: Individual components (maximum tree-shaking)
+import '@hellboy/ds/components/button/css';
+import { Button } from '@hellboy/ds/components/button';
+
+// ✅ Theme only (if building custom CSS)
+import '@hellboy/ds/dist/theme.css';
+```
+
+**Note**: Each component's CSS file includes all its dependencies, so you never need to manually import foundation files.
+
+## 🚀 Getting Started Examples
+
+### Simple Page
+
+```tsx
+import '@hellboy/ds/dist/index.css';
+import { Button, Input, Banner } from '@hellboy/ds';
+
+function App() {
+  return (
+    <div style={{ padding: '2rem' }}>
+      <Banner type="info">Welcome to Hellboy DS!</Banner>
+      
+      <form style={{ marginTop: '1rem' }}>
+        <Input label="Email" type="email" />
+        <Input label="Password" type="password" />
+        <Button type="submit" fullWidth>Sign In</Button>
+      </form>
+    </div>
+  );
+}
+```
+
+### With Theme Switching
+
+```tsx
+import '@hellboy/ds/dist/index.css';
+import { ThemeControl, Button, Card } from '@hellboy/ds';
+
+function App() {
+  return (
+    <div style={{ padding: '2rem' }}>
+      <div style={{ position: 'fixed', top: '1rem', right: '1rem' }}>
+        <ThemeControl />
+      </div>
+      
+      <Card>
+        <h1>My App</h1>
+        <p>Theme automatically applies to all components!</p>
+        <Button>Click me</Button>
+      </Card>
+    </div>
+  );
+}
+```