shru-design-system 0.5.4 → 0.6.1

package/README.md

@@ -1,224 +1,62 @@
 # shru-design-system
 
-A React component library with atoms and molecules built on Radix UI and Tailwind CSS, featuring a dynamic theme system.
-
-## Project Structure
-
-### Root Files
-
-- **`package.json`** - Package configuration, dependencies, and scripts
-- **`tsconfig.json`** - TypeScript configuration
-- **`tsup.config.ts`** - Build configuration for bundling (ESM/CJS)
-- **`tailwind.config.js`** - Tailwind CSS configuration (for library development)
-- **`postcss.config.js`** - PostCSS configuration (for library development)
-- **`.gitignore`** - Git ignore rules
-
-### Source Code (`src/`)
-
-- **`src/index.ts`** - Main entry point, exports all components and utilities
-- **`src/utils.ts`** - Utility functions (cn helper for class merging)
-
-#### Atoms (`src/atoms/`)
-Basic UI building blocks:
-- **`Alert.tsx`** - Alert component for notifications
-- **`Avatar.tsx`** - Avatar component with image and fallback
-- **`Badge.tsx`** - Badge component for labels and tags
-- **`Button.tsx`** - Button component with variants and sizes
-- **`Checkbox.tsx`** - Checkbox input component
-- **`Empty.tsx`** - Empty state component
-- **`ErrorBoundary.tsx`** - Error boundary component
-- **`Image.tsx`** - Image component with loading states
-- **`InputOTP.tsx`** - OTP input component
-- **`Kbd.tsx`** - Keyboard key display component
-- **`Label.tsx`** - Form label component
-- **`Progress.tsx`** - Progress bar component
-- **`Radio.tsx`** - Radio button group component
-- **`Separator.tsx`** - Horizontal/vertical divider component
-- **`Skeleton.tsx`** - Skeleton loading component
-- **`SkeletonGrid.tsx`** - Grid layout skeleton component
-- **`SkeletonText.tsx`** - Text lines skeleton component
-- **`Slider.tsx`** - Slider input component
-- **`Spinner.tsx`** - Loading spinner component
-- **`Switch.tsx`** - Toggle switch component
-- **`Text.tsx`** - Typography text component
-- **`TextInput.tsx`** - Text input field component
-- **`Textarea.tsx`** - Multi-line text input component
-- **`Toggle.tsx`** - Toggle button component
-- **`Upload.tsx`** - File upload component
-
-#### Molecules (`src/molecules/`)
-Composite components:
-- **`Accordion.tsx`** - Collapsible accordion component
-- **`AlertDialog.tsx`** - Alert dialog component
-- **`Breadcrumb.tsx`** - Breadcrumb navigation component
-- **`Calendar.tsx`** - Calendar date picker component
-- **`Carousel.tsx`** - Image/content carousel component
-- **`Chart.tsx`** - Chart component (Recharts wrapper)
-- **`Collapsible.tsx`** - Collapsible content component
-- **`Command.tsx`** - Command palette component
-- **`ConfirmModal.tsx`** - Confirmation modal component
-- **`ContextMenu.tsx`** - Right-click context menu
-- **`CopyButton.tsx`** - Copy to clipboard button
-- **`Drawer.tsx`** - Drawer/side panel component
-- **`DropdownMenu.tsx`** - Dropdown menu component
-- **`Field.tsx`** - Form field wrapper component
-- **`Form.tsx`** - Form component (react-hook-form)
-- **`FormInput.tsx`** - Form input with label and error
-- **`FormModal.tsx`** - Modal with form integration
-- **`HistoryControlButtons.tsx`** - Browser history controls
-- **`HoverCard.tsx`** - Hover card component
-- **`InfoBanner.tsx`** - Information banner component
-- **`InlineEdit.tsx`** - Inline editing component
-- **`InputGroup.tsx`** - Input with addons/buttons
-- **`SearchInput.tsx`** - Search input with debounce and clearable
-- **`Menubar.tsx`** - Menu bar component
-- **`Modal.tsx`** - Modal dialog component
-- **`NavigationMenu.tsx`** - Navigation menu component
-- **`Pagination.tsx`** - Pagination component
-- **`Popover.tsx`** - Popover component
-- **`Select.tsx`** - Dropdown select component
-- **`Sheet.tsx`** - Sheet/side panel component
-- **`Snackbar.tsx`** - Snackbar notification component
-- **`StatusText.tsx`** - Status text with icons
-- **`Stepper.tsx`** - Step indicator component
-- **`Tabs.tsx`** - Tabs component
-- **`Toast.tsx`** - Toast notification component
-- **`Toaster.tsx`** - Toast provider component
-- **`ToggleGroup.tsx`** - Toggle group component
-- **`Tooltip.tsx`** - Tooltip component
-- **`TriggerModal.tsx`** - Modal with trigger component
-
-#### Layout (`src/layout/`)
-Layout and container components:
-- **`AspectRatio.tsx`** - Aspect ratio container
-- **`Box.tsx`** - Generic box container
-- **`Card.tsx`** - Card container component
-- **`CollapsiblePanel.tsx`** - Collapsible panel component
-- **`Container.tsx`** - Responsive container component
-- **`EmptyScreen.tsx`** - Empty screen component
-- **`Footer.tsx`** - Footer component
-- **`Grid.tsx`** - Grid layout component
-- **`Header.tsx`** - Header component
-- **`List.tsx`** - Enhanced list component with search, grid/list views, empty/loading states
-- **`Resizable.tsx`** - Resizable panels component
-- **`ResizeContainer.tsx`** - Resizable container wrapper
-- **`ScrollArea.tsx`** - Scrollable area component
-- **`Sidebar.tsx`** - Sidebar navigation component
-- **`Stack.tsx`** - Stack layout component
-- **`Table.tsx`** - Table component
-
-#### Theme System (`src/themes/`)
-- **`themeConfig.ts`** - Theme configuration and category definitions
-- **`themeUtils.ts`** - Theme utility functions (loading, merging, flattening)
-- **`applyThemeSync.ts`** - Synchronous theme application (prevents FOUC)
-- **`useTheme.tsx`** - React hook for theme management
-- **`ui/ThemeToggle/`** - Theme toggle UI component and related files
-  - **`ThemeToggle.tsx`** - Main theme toggle component
-  - **`useThemeToggle.ts`** - Hook for theme toggle UI state
-  - **`themeToggleConfig.ts`** - Theme toggle configuration
-  - **`themeToggleUtils.ts`** - Theme toggle utility functions
-  - **`index.ts`** - Theme toggle exports
-
-### Build Output (`dist/`)
-
-- **`index.js`** - CommonJS bundle
-- **`index.mjs`** - ESM bundle
-- **`index.d.ts`** - TypeScript declarations (CJS)
-- **`index.d.mts`** - TypeScript declarations (ESM)
-
-### Scripts (`scripts/`)
-
-Setup and runtime scripts:
-- **`init.js`** - Postinstall script that sets up Tailwind, PostCSS, and token files in consuming apps
-- **`apply-theme-sync.js`** - Standalone synchronous theme script (injected into HTML)
-- **`applyThemeSync.js`** - Synchronous theme application module
-- **`themeConfig.js`** - Theme configuration (JavaScript version)
-- **`themeUtils.js`** - Theme utilities (JavaScript version)
-- **`tokens/`** - Default token files (copied to consuming apps)
-  - **`base.json`** - Base design tokens
-  - **`palettes.json`** - Color palette definitions
-  - **`themes/`** - Theme category files
-    - **`color/`** - Color theme variants (white, dark)
-    - **`typography/`** - Typography themes (sans, serif)
-    - **`shape/`** - Shape themes (smooth, sharp)
-    - **`density/`** - Density themes (comfortable, compact)
-    - **`animation/`** - Animation themes (gentle, brisk)
-    - **`custom/`** - Custom theme examples (brand, minimal)
-
-### Test Application (`test/`)
-
-Local test environment for developing and testing the library:
-- **`package.json`** - Test app dependencies
-- **`vite.config.ts`** - Vite configuration for test app
-- **`index.html`** - Test app HTML entry point
-- **`src/App.tsx`** - Test app component showcasing all library components
-- **`src/main.tsx`** - Test app entry point
-- **`src/index.css`** - Test app global styles
-- **`tailwind.config.js`** - Tailwind config for test app
-- **`postcss.config.js`** - PostCSS config for test app
-- **`public/tokens/`** - Token files for testing (generated by init script)
-- **`dist/`** - Vite build output (ignored in git)
-
-## Usage
-
-Install:
+React component library — **98 components**, multi-axis token themes, Tailwind + CVA.
+
 ```bash
 npm install shru-design-system
+npx shru-design-system-init
 ```
 
-### Theme setup (new flow)
-- Tokens are embedded in the bundle, so the theme system works out-of-the-box (no `/public/tokens` required).
-- If you want to self-host tokens (for custom themes or CDN):
-  - Set `window.__THEME_TOKENS_BASE__ = "/tokens"` (or your URL) before the app renders, or set `DESIGN_SYSTEM_TOKENS_BASE` env at build/runtime.
-  - Serve token JSONs at `<base>/base.json`, `<base>/palettes.json`, `<base>/themes/<category>/<theme>.json`.
-- Blocking HTML injection is removed; the runtime/applyThemeSync appends `#dynamic-theme` at the end of `<head>` so its CSS vars override compiled CSS.
+Published: `dist/` components, `styles.css`, Tailwind preset.
 
-Optional token copy:
-```bash
-npx shru-design-system-init   # copies tokens into public/tokens if you want static hosting
-```
+**Prop-level API:** TypeScript `XxxProps` · local dev: `npm run dev` → `/gallery`
 
-Import components:
-```tsx
-import { 
-  Button, 
-  Modal, 
-  ThemeToggle, 
-  Alert,
-  Avatar,
-  Accordion,
-  Calendar,
-  Carousel,
-  Form,
-  Field,
-  // ... and many more
-  registerThemeFromFile 
-} from 'shru-design-system'
-```
+---
 
-### Available Components
+## Documentation
 
-The library includes 67+ components organized into:
-- **Atoms** (23): Basic UI elements like Button, Input, Badge, etc.
-- **Molecules** (35): Composite components like Modal, Form, Calendar, etc.
-- **Layout** (16): Layout components like Grid, Stack, Sidebar, etc.
+| Audience | Start here |
+|----------|------------|
+| **Consumer** — install & use in your app | [docs/use/INSTALL.md](./docs/use/INSTALL.md) |
+| **Contributor** — change this repo | [docs/build/CONTRIBUTING.md](./docs/build/CONTRIBUTING.md) |
+| **Architecture** — system structure | [docs/reference/ARCHITECTURE.md](./docs/reference/ARCHITECTURE.md) |
 
-Registering themes:
-- Add a custom theme file at your token base, e.g. `/tokens/themes/custom/my-brand.json`.
-- Call at runtime (after page load):
-```ts
-registerThemeFromFile('custom', 'my-brand', '/tokens/themes/custom/my-brand.json')
-```
-The theme toggle will pick it up automatically.
+### Consumers — `docs/use/`
 
-## Development
+| Doc | Covers |
+|-----|--------|
+| [Install](./docs/use/INSTALL.md) | Peers, init, styles, Tailwind, first component |
+| [Theming](./docs/use/THEMING.md) | Presets, `useTheme`, `applyPreset`, ThemeToggle |
+| [Recipes](./docs/use/RECIPES.md) | App shell, TreeView, forms, modals |
+| [Features](./docs/use/FEATURES.md) | Overlays, toasts, forms, input API contracts |
 
-Build the library:
-```bash
-npm run build
-```
+### Contributors — `docs/build/`
+
+| Doc | Covers |
+|-----|--------|
+| [Contributing](./docs/build/CONTRIBUTING.md) | Layout, conventions, tokens, checks |
+| [Components](./docs/build/COMPONENTS.md) | Add / update component checklist |
+| [Gallery](./docs/build/GALLERY.md) | Metadata pipeline, wrappers |
+| [Release](./docs/build/RELEASE.md) | `npm run check`, build, publish |
+
+### Architecture — `docs/reference/`
+
+| Doc | Covers |
+|-----|--------|
+| [Architecture](./docs/reference/ARCHITECTURE.md) | Repo map, build pipeline, check gates |
+| [Components](./docs/reference/COMPONENTS.md) | 98 shipped spec |
+| [Component graph](./docs/reference/COMPONENT_GRAPH.md) | Composition flowcharts |
+| [Tokens](./docs/reference/TOKENS.md) | Token JSON layout, pipeline |
+
+---
+
+## Local preview
 
-Test locally:
 ```bash
-cd test && npm run dev
+npm run dev
 ```
+
+| Route | Purpose |
+|-------|---------|
+| `/gallery` | Component catalog + props panel |
+| `/showcase` | Mini admin app (composed patterns) |