hakumi_components 0.1.18.pre → 0.1.19.pre

data/README.md

@@ -1,130 +1,100 @@
-<div align="center">
-  <a href="https://github.com/hakumi-dev/hakumi-components">
-    <img src="logo-hakumi-full.png" alt="Logo" width="250">
-  </a>
+<p align="center">
+  <br />
+  <img src="logo-hakumi-full.png" alt="Hakumi Components" width="250" />
+  <br />
+</p>
+
+<h1 align="center">Hakumi Components</h1>
+
+<p align="center">
+  ViewComponent-based UI library for Ruby on Rails — 65 components, Ant Design conventions, Stimulus controllers
+  <br />
+  <a href="https://github.com/hakumi-dev/hakumi-components"><strong>Source Code</strong></a>
+  &middot;
+  <a href="https://components.hakumi.dev">Playground</a>
+  &middot;
+  <a href="https://github.com/hakumi-dev/hakumi-components/issues">Report Bug</a>
+  &middot;
+  <a href="https://github.com/hakumi-dev/hakumi-components/blob/main/CHANGELOG.md">Changelog</a>
+</p>
+
+<p align="center">
+  <a href="https://github.com/hakumi-dev/hakumi-components/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" /></a>
+  <a href="https://ruby-doc.org/"><img src="https://img.shields.io/badge/ruby-%3E%3D%203.0-CC342D.svg?logo=ruby" alt="Ruby >= 3.0" /></a>
+</p>
 
-  <h3 align="center">Hakumi Components</h3>
-
-  <p align="center">
-    Elegant UI component library for Ruby on Rails
-    <br />
-    <a href="https://components.hakumi.dev"><strong>View Live Playground »</strong></a>
-    ·
-    <a href="https://github.com/hakumi-dev/hakumi-components/issues">Report Bug</a>
-    ·
-    <a href="https://www.npmjs.com/package/@hakumi-dev/hakumi-components">npm Package</a>
-    ·
-    <a href="https://rubygems.org/gems/hakumi_components">RubyGems</a>
-  </p>
-</div>
-
-## About The Project
-
-Hakumi Components is a comprehensive UI component library for Ruby on Rails applications, inspired by Ant Design. It provides 65 production-ready, accessible components with light/dark theme support, combining the power of ViewComponent, Stimulus, and modern CSS.
+---
 
-**✨ Key Features:**
-- 🎨 **65 Components** - Button, Form, Table, Modal, Menu, Calendar, and more
-- 🌓 **Light/Dark Theme** - Built-in theme support with CSS variables
-- 📦 **Rails Engine** - Drop-in integration with ViewComponent
-- ⚡ **Modern Stack** - Stimulus controllers with clean JavaScript API
-- 🎯 **Ant Design Inspired** - Familiar design patterns and conventions
-- 🔧 **Customizable** - Override styles and behavior easily
+## Table of Contents
 
-**🎮 [Try the Interactive Playground](https://components.hakumi.dev)** - See all components in action with live examples
+| | |
+|---|---|
+| [About](#about) | What Hakumi Components is and why it exists |
+| [Installation](#installation) | Gem and npm setup |
+| [Configuration](#configuration) | Initializer options |
+| [Usage](#usage) | Basic examples |
+| [Components](#components) | All 65 components by category |
+| [JavaScript API](#javascript-api) | Programmatic control |
+| [Architecture](#architecture) | How components are structured |
+| [Development](#development) | Local playground, tests |
+| [Contributing](#contributing) | How to contribute |
 
-## Built With
+---
 
-[![Ruby][Ruby-badge]][Ruby-url] [![ViewComponent][ViewComponent-badge]][ViewComponent-url] [![Stimulus][Stimulus-badge]][Stimulus-url]
+## About
 
-**Core Technologies:**
-- Ruby on Rails 7.1+ as a Rails Engine
-- ViewComponent 3.0+ for Ruby components
-- Stimulus 3.0+ for JavaScript interactivity
-- SCSS with CSS variables for theming
+Hakumi Components is a Rails UI component library built on ViewComponent, Stimulus, and SCSS. It follows Ant Design conventions and ships 65 server-rendered components with optional JavaScript interactivity. Light and dark themes are supported via CSS variables.
 
-## Getting Started
+Stack: ViewComponent 3.0+, Stimulus 3.0+, Rails 7.1+, SCSS.
 
-### Prerequisites
+---
 
-**Required:**
-- Ruby 3.0 or higher
-- Rails 7.1 or higher
-- Node.js 16.9+ (for npm package)
-- A JavaScript bundler (Vite, Webpack, esbuild, etc.)
-- SCSS processor (sass, sass-embedded, etc.)
+## Installation
 
-**Recommended:**
-- Vite (via `vite_rails` gem)
-- Yarn or npm for package management
+### Requirements
 
-### Installation
+- Ruby 3.0+
+- Rails 7.1+
+- Node.js 16.9+
+- A JavaScript bundler (Vite, Webpack, esbuild)
+- SCSS processor
 
-#### Option A: Automatic Installation (Recommended)
+### Automatic (recommended)
 
-**1. Add the gem to your Gemfile:**
+Add the gem:
 
 ```ruby
-# Always use the latest pre-release version (recommended during development)
 gem 'hakumi_components', '>= 0.1.0.pre'
-
-# Or pin to a specific version for stability
-gem 'hakumi_components', '0.1.16.pre'
 ```
 
-**2. Run the installer:**
+Run the installer:
 
 ```bash
 bundle install
 bin/rails generate hakumi:install
 ```
 
-The generator will automatically:
-- ✅ Install the npm package with correct version (`@pre`)
-- ✅ Detect your JavaScript entry point (Vite/Webpack/Sprockets)
-- ✅ Add imports with complete configuration
-- ✅ Setup stylesheets with appropriate syntax (`@use` or `@import`)
-- ✅ Configure the FormBuilder (optional)
-
-**3. Restart your server and you're done! 🎉**
-
----
-
-#### Option B: Manual Installation
+The generator detects your JavaScript entry point and SCSS setup, installs the npm package, and wires up imports automatically.
 
-If you prefer manual setup or the generator doesn't work for your setup:
+### Manual
 
 **1. Add the gem:**
 
 ```ruby
-# Always use the latest pre-release version
 gem 'hakumi_components', '>= 0.1.0.pre'
-
-# Or pin to a specific version
-gem 'hakumi_components', '0.1.16.pre'
 ```
 
-**2. Install dependencies:**
+**2. Install the npm package:**
 
 ```bash
-bundle install
-
-# Using Yarn - latest pre-release
 yarn add @hakumi-dev/hakumi-components@pre
-
-# Using Yarn - specific version
-yarn add @hakumi-dev/hakumi-components@0.1.16-pre
-
-# Using npm - latest pre-release
+# or
 npm install @hakumi-dev/hakumi-components@pre
-
-# Using npm - specific version
-npm install @hakumi-dev/hakumi-components@0.1.16-pre
 ```
 
-**3. Setup JavaScript:**
+**3. JavaScript:**
 
 ```javascript
-// app/javascript/application.js (or entrypoints/application.js for Vite)
 import { Application } from "@hotwired/stimulus"
 import HakumiComponents, { registerHakumiControllers } from "@hakumi-dev/hakumi-components"
 
@@ -133,377 +103,234 @@ window.HakumiComponents = HakumiComponents
 registerHakumiControllers(application)
 ```
 
-**4. Setup stylesheets:**
+**4. Stylesheets:**
 
 ```scss
-// For Vite/Webpack (modern bundlers)
-// app/javascript/stylesheets/application.scss
+// Vite / Webpack
 @use '@hakumi-dev/hakumi-components/styles';
 
-// OR for Sprockets/traditional setup
-// app/assets/stylesheets/application.scss
+// Sprockets
 @import "@hakumi-dev/hakumi-components/styles";
 ```
 
-## Configuration
+---
 
-You can configure HakumiComponents in an initializer:
+## Configuration
 
 ```ruby
 # config/initializers/hakumi_components.rb
 HakumiComponents.configure do |config|
   config.default_form_builder = true      # Use HakumiComponents::FormBuilder as default
-  config.base_path = "hakumi/components"  # Base URL path for component routes
+  config.base_path = "hakumi/components"  # Base URL for modal/drawer routes
 end
 ```
 
-### Available Configuration Options
-
 | Option | Default | Description |
 |--------|---------|-------------|
-| `default_form_builder` | `false` | Use `HakumiComponents::FormBuilder` as the default form builder |
-| `base_path` | `"hakumi/components"` | Base URL path for component routes (modals, drawers, etc.) |
-
-### Accessing Configuration
-
-```ruby
-HakumiComponents.config.default_form_builder
-# => true
+| `default_form_builder` | `false` | Set `HakumiComponents::FormBuilder` as the application default |
+| `base_path` | `"hakumi/components"` | Base URL path for components that require server routes |
 
-HakumiComponents.config.base_path
-# => "hakumi/components"
-```
+---
 
 ## Usage
 
-### Basic Component Example
-
 ```erb
-<%# Simple button %>
 <%= render HakumiComponents::Button::Component.new(type: :primary) do %>
-  Click me
+  Save
 <% end %>
 
-<%# Form with automatic validation detection %>
 <%= form_with model: @user, builder: HakumiComponents::FormBuilder do |f| %>
   <%= f.text_field :email %>
   <%= f.text_field :name %>
   <%= f.submit "Save", type: :primary %>
 <% end %>
 
-<%# Modal with programmatic control %>
-<%= render HakumiComponents::Modal::Component.new(
-  id: "my-modal",
-  title: "Confirm Action"
-) do %>
-  Are you sure you want to proceed?
+<%= render HakumiComponents::Modal::Component.new(id: "confirm-modal", title: "Confirm") do %>
+  Are you sure?
 <% end %>
 ```
 
-### Component Reference
-
-Browse all **65 components** organized by category. Each component includes detailed documentation, examples, and API reference.
-
-#### General (4)
-- [Button](./app/components/hakumi_components/button/docs/README.md) - Clickable button element
-- [Float Button](./app/components/hakumi_components/float_button/docs/README.md) - Floating action button
-- [Icon](./app/components/hakumi_components/icon/docs/README.md) - Icon display component
-- [Typography](./app/components/hakumi_components/typography/docs/README.md) - Text styling and formatting
-
-#### Layout (6)
-- [Divider](./app/components/hakumi_components/divider/docs/README.md) - Horizontal or vertical divider line
-- [Flex](./app/components/hakumi_components/flex/docs/README.md) - Flexbox layout container
-- [Grid](./app/components/hakumi_components/grid/docs/README.md) - Grid layout system
-- [Layout](./app/components/hakumi_components/layout/docs/README.md) - Page layout structure
-- [Space](./app/components/hakumi_components/space/docs/README.md) - Spacing between elements
-- [Splitter](./app/components/hakumi_components/splitter/docs/README.md) - Resizable split panels
-
-#### Navigation (6)
-- [Anchor](./app/components/hakumi_components/anchor/docs/README.md) - Anchor navigation for page sections
-- [Breadcrumb](./app/components/hakumi_components/breadcrumb/docs/README.md) - Breadcrumb navigation trail
-- [Dropdown](./app/components/hakumi_components/dropdown/docs/README.md) - Dropdown menu
-- [Menu](./app/components/hakumi_components/menu/docs/README.md) - Navigation menu
-- [Pagination](./app/components/hakumi_components/pagination/docs/README.md) - Pagination controls
-- [Steps](./app/components/hakumi_components/steps/docs/README.md) - Step-by-step navigation
-
-#### Data Entry (18)
-- [Autocomplete](./app/components/hakumi_components/autocomplete/docs/README.md) - Input with autocomplete suggestions
-- [Cascader](./app/components/hakumi_components/cascader/docs/README.md) - Cascading selection dropdown
-- [Checkbox](./app/components/hakumi_components/checkbox/docs/README.md) - Checkbox input
-- [Color Picker](./app/components/hakumi_components/color_picker/docs/README.md) - Color selection input
-- [Date Picker](./app/components/hakumi_components/date_picker/docs/README.md) - Date selection input
-- [Form](./app/components/hakumi_components/form/docs/README.md) - Form wrapper with validation
-- [Input](./app/components/hakumi_components/input/docs/README.md) - Text input field
-- [Input Number](./app/components/hakumi_components/input_number/docs/README.md) - Numeric input field
-- [Mentions](./app/components/hakumi_components/mentions/docs/README.md) - @mentions input
-- [Radio](./app/components/hakumi_components/radio/docs/README.md) - Radio button input
-- [Rate](./app/components/hakumi_components/rate/docs/README.md) - Star rating input
-- [Select](./app/components/hakumi_components/select/docs/README.md) - Dropdown select input
-- [Slider](./app/components/hakumi_components/slider/docs/README.md) - Range slider input
-- [Switch](./app/components/hakumi_components/switch/docs/README.md) - Toggle switch input
-- [Time Picker](./app/components/hakumi_components/time_picker/docs/README.md) - Time selection input
-- [Transfer](./app/components/hakumi_components/transfer/docs/README.md) - Dual list transfer
-- [Tree Select](./app/components/hakumi_components/tree_select/docs/README.md) - Tree structure select
-- [Upload](./app/components/hakumi_components/upload/docs/README.md) - File upload component
-
-#### Data Display (20)
-- [Avatar](./app/components/hakumi_components/avatar/docs/README.md) - User avatar display
-- [Badge](./app/components/hakumi_components/badge/docs/README.md) - Badge and status dot
-- [Calendar](./app/components/hakumi_components/calendar/docs/README.md) - Calendar display
-- [Card](./app/components/hakumi_components/card/docs/README.md) - Card container
-- [Carousel](./app/components/hakumi_components/carousel/docs/README.md) - Image/content carousel
-- [Collapse](./app/components/hakumi_components/collapse/docs/README.md) - Collapsible accordion panels
-- [Descriptions](./app/components/hakumi_components/descriptions/docs/README.md) - Description list display
-- [Empty](./app/components/hakumi_components/empty/docs/README.md) - Empty state placeholder
-- [Image](./app/components/hakumi_components/image/docs/README.md) - Image display with preview
-- [Popover](./app/components/hakumi_components/popover/docs/README.md) - Popover overlay
-- [QR Code](./app/components/hakumi_components/qr_code/docs/README.md) - QR code generator
-- [Segmented](./app/components/hakumi_components/segmented/docs/README.md) - Segmented control
-- [Statistic](./app/components/hakumi_components/statistic/docs/README.md) - Statistic display
-- [Table](./app/components/hakumi_components/table/docs/README.md) - Data table
-- [Tabs](./app/components/hakumi_components/tabs/docs/README.md) - Tab navigation
-- [Tag](./app/components/hakumi_components/tag/docs/README.md) - Tag label
-- [Timeline](./app/components/hakumi_components/timeline/docs/README.md) - Timeline display
-- [Tooltip](./app/components/hakumi_components/tooltip/docs/README.md) - Tooltip overlay
-- [Tour](./app/components/hakumi_components/tour/docs/README.md) - Guided tour
-- [Tree](./app/components/hakumi_components/tree/docs/README.md) - Tree structure display
-
-#### Feedback (10)
-- [Alert](./app/components/hakumi_components/alert/docs/README.md) - Alert message display
-- [Drawer](./app/components/hakumi_components/drawer/docs/README.md) - Slide-out drawer panel
-- [Message](./app/components/hakumi_components/message/docs/README.md) - Global message notification
-- [Modal](./app/components/hakumi_components/modal/docs/README.md) - Modal dialog
-- [Notification](./app/components/hakumi_components/notification/docs/README.md) - Notification message
-- [Popconfirm](./app/components/hakumi_components/popconfirm/docs/README.md) - Confirmation popover
-- [Progress](./app/components/hakumi_components/progress/docs/README.md) - Progress indicator
-- [Result](./app/components/hakumi_components/result/docs/README.md) - Result status page
-- [Skeleton](./app/components/hakumi_components/skeleton/docs/README.md) - Skeleton loading placeholder
-- [Spin](./app/components/hakumi_components/spin/docs/README.md) - Loading spinner
-
-#### Other (1)
-- [Affix](./app/components/hakumi_components/affix/docs/README.md) - Pin element to viewport
+---
+
+## Components
+
+65 components organized by category. Each links to its own documentation with API reference and examples.
+
+### General
+
+- [Button](./app/components/hakumi_components/button/docs/README.md)
+- [Float Button](./app/components/hakumi_components/float_button/docs/README.md)
+- [Icon](./app/components/hakumi_components/icon/docs/README.md)
+- [Typography](./app/components/hakumi_components/typography/docs/README.md)
+
+### Layout
+
+- [Divider](./app/components/hakumi_components/divider/docs/README.md)
+- [Flex](./app/components/hakumi_components/flex/docs/README.md)
+- [Grid](./app/components/hakumi_components/grid/docs/README.md)
+- [Layout](./app/components/hakumi_components/layout/docs/README.md)
+- [Space](./app/components/hakumi_components/space/docs/README.md)
+- [Splitter](./app/components/hakumi_components/splitter/docs/README.md)
+
+### Navigation
+
+- [Anchor](./app/components/hakumi_components/anchor/docs/README.md)
+- [Breadcrumb](./app/components/hakumi_components/breadcrumb/docs/README.md)
+- [Dropdown](./app/components/hakumi_components/dropdown/docs/README.md)
+- [Menu](./app/components/hakumi_components/menu/docs/README.md)
+- [Pagination](./app/components/hakumi_components/pagination/docs/README.md)
+- [Steps](./app/components/hakumi_components/steps/docs/README.md)
+
+### Data Entry
+
+- [Autocomplete](./app/components/hakumi_components/autocomplete/docs/README.md)
+- [Cascader](./app/components/hakumi_components/cascader/docs/README.md)
+- [Checkbox](./app/components/hakumi_components/checkbox/docs/README.md)
+- [Color Picker](./app/components/hakumi_components/color_picker/docs/README.md)
+- [Date Picker](./app/components/hakumi_components/date_picker/docs/README.md)
+- [Form](./app/components/hakumi_components/form/docs/README.md)
+- [Input](./app/components/hakumi_components/input/docs/README.md)
+- [Input Number](./app/components/hakumi_components/input_number/docs/README.md)
+- [Mentions](./app/components/hakumi_components/mentions/docs/README.md)
+- [Radio](./app/components/hakumi_components/radio/docs/README.md)
+- [Rate](./app/components/hakumi_components/rate/docs/README.md)
+- [Select](./app/components/hakumi_components/select/docs/README.md)
+- [Slider](./app/components/hakumi_components/slider/docs/README.md)
+- [Switch](./app/components/hakumi_components/switch/docs/README.md)
+- [Time Picker](./app/components/hakumi_components/time_picker/docs/README.md)
+- [Transfer](./app/components/hakumi_components/transfer/docs/README.md)
+- [Tree Select](./app/components/hakumi_components/tree_select/docs/README.md)
+- [Upload](./app/components/hakumi_components/upload/docs/README.md)
+
+### Data Display
+
+- [Avatar](./app/components/hakumi_components/avatar/docs/README.md)
+- [Badge](./app/components/hakumi_components/badge/docs/README.md)
+- [Calendar](./app/components/hakumi_components/calendar/docs/README.md)
+- [Card](./app/components/hakumi_components/card/docs/README.md)
+- [Carousel](./app/components/hakumi_components/carousel/docs/README.md)
+- [Collapse](./app/components/hakumi_components/collapse/docs/README.md)
+- [Descriptions](./app/components/hakumi_components/descriptions/docs/README.md)
+- [Empty](./app/components/hakumi_components/empty/docs/README.md)
+- [Image](./app/components/hakumi_components/image/docs/README.md)
+- [Popover](./app/components/hakumi_components/popover/docs/README.md)
+- [QR Code](./app/components/hakumi_components/qr_code/docs/README.md)
+- [Segmented](./app/components/hakumi_components/segmented/docs/README.md)
+- [Statistic](./app/components/hakumi_components/statistic/docs/README.md)
+- [Table](./app/components/hakumi_components/table/docs/README.md)
+- [Tabs](./app/components/hakumi_components/tabs/docs/README.md)
+- [Tag](./app/components/hakumi_components/tag/docs/README.md)
+- [Timeline](./app/components/hakumi_components/timeline/docs/README.md)
+- [Tooltip](./app/components/hakumi_components/tooltip/docs/README.md)
+- [Tour](./app/components/hakumi_components/tour/docs/README.md)
+- [Tree](./app/components/hakumi_components/tree/docs/README.md)
+
+### Feedback
+
+- [Alert](./app/components/hakumi_components/alert/docs/README.md)
+- [Drawer](./app/components/hakumi_components/drawer/docs/README.md)
+- [Message](./app/components/hakumi_components/message/docs/README.md)
+- [Modal](./app/components/hakumi_components/modal/docs/README.md)
+- [Notification](./app/components/hakumi_components/notification/docs/README.md)
+- [Popconfirm](./app/components/hakumi_components/popconfirm/docs/README.md)
+- [Progress](./app/components/hakumi_components/progress/docs/README.md)
+- [Result](./app/components/hakumi_components/result/docs/README.md)
+- [Skeleton](./app/components/hakumi_components/skeleton/docs/README.md)
+- [Spin](./app/components/hakumi_components/spin/docs/README.md)
+
+### Other
+
+- [Affix](./app/components/hakumi_components/affix/docs/README.md)
+
+---
 
 ## JavaScript API
 
-Components with interactivity expose programmatic APIs:
+Interactive components expose a programmatic API:
 
 ```javascript
-// Access component API via element
-const modal = document.getElementById('my-modal')
-modal.hakumiComponent.api.open()
-modal.hakumiComponent.api.close()
+// Via element
+document.getElementById('my-modal').hakumiComponent.api.open()
+document.getElementById('my-modal').hakumiComponent.api.close()
 
-// Or via global registry
+// Via global registry
 window.HakumiComponents.get('my-modal').open()
 ```
 
-Common API methods by component type:
-- **Toggleables** (Modal, Drawer): `open()`, `close()`, `toggle()`, `isOpen()`
-- **Inputs** (Input, Select): `getValue()`, `setValue(value)`, `clear()`, `focus()`
-- **Navigation** (Carousel, Tabs): `next()`, `prev()`, `goTo(index)`, `getCurrent()`
-
-## Architecture
-
-Components follow a three-layer pattern:
-1. **Ruby Component** (`component.rb`) - Props and rendering logic
-2. **ERB Template** (`component.html.erb`) - HTML structure (optional)
-3. **Stimulus Controller** (`{component}_controller.js`) - Interactivity (when needed)
-
-**Note:** Not all components need JavaScript controllers. Many are purely presentational (Typography, Space, Divider, etc.).
-
-## Troubleshooting
-
-### Installation Issues
-
-If you encounter problems during installation:
-
-1. **Try the automatic installer first:**
-   ```bash
-   bin/rails generate hakumi:install
-   ```
-
-2. **If the installer fails**, follow the manual installation steps above
-
-3. **Check compatibility:**
-   - Ruby 3.0+
-   - Rails 7.1+
-   - Node.js 16.9+
-   - A JavaScript bundler (Vite, Webpack, esbuild)
-
-### Controllers not registering
-
-If components don't respond to interactions:
-
-1. **Verify the npm package is installed:**
-   ```bash
-   yarn list @hakumi-dev/hakumi-components
-   # or
-   npm list @hakumi-dev/hakumi-components
-   ```
-
-2. **Check browser console:**
-   - Should see: `"[HakumiComponents] Registered X controllers"`
-   - If you see errors, check your import paths
-
-3. **Verify Stimulus is properly configured:**
-   ```javascript
-   console.log(window.Stimulus) // Should not be undefined
-   console.log(window.HakumiComponents) // Should be an object with methods
-   ```
-
-4. **Ensure imports are complete:**
-   ```javascript
-   // ✅ Correct - includes both exports
-   import HakumiComponents, { registerHakumiControllers } from "@hakumi-dev/hakumi-components"
-
-   // ❌ Wrong - missing default export
-   import { registerHakumiControllers } from "@hakumi-dev/hakumi-components"
-   ```
-
-### Styles not loading
-
-1. Verify you're using SCSS (not plain CSS)
-2. Check your bundler configuration supports node_modules imports
-3. For Vite, ensure `@use` syntax is used (not `@import`)
-
-### Version mismatches
-
-Keep gem and npm versions in sync:
-
-```ruby
-# Gemfile - pin to specific version
-gem 'hakumi_components', '0.1.16.pre'
-```
-```bash
-# package.json - matching version
-yarn add @hakumi-dev/hakumi-components@0.1.16-pre
-```
-
-Or use dynamic versioning to always get the latest:
-```ruby
-# Gemfile - always latest pre-release
-gem 'hakumi_components', '>= 0.1.0.pre'
-```
-```bash
-# package.json - always latest pre-release
-yarn add @hakumi-dev/hakumi-components@pre
-```
+| Component type | Methods |
+|----------------|---------|
+| Toggleables (Modal, Drawer) | `open()`, `close()`, `toggle()`, `isOpen()` |
+| Inputs (Input, Select) | `getValue()`, `setValue(value)`, `clear()`, `focus()` |
+| Navigation (Carousel, Tabs) | `next()`, `prev()`, `goTo(index)`, `getCurrent()` |
 
-## Updating
+---
 
-To update to the latest version:
+## Architecture
 
-```bash
-# Update Ruby gem
-bundle update hakumi_components
+Each component follows a three-layer pattern:
 
-# Update npm package to latest pre-release
-yarn add @hakumi-dev/hakumi-components@pre
-# or
-npm install @hakumi-dev/hakumi-components@pre
-```
+1. **Ruby component** (`component.rb`) — props, validation, rendering logic
+2. **ERB template** (`component.html.erb`) — HTML structure
+3. **Stimulus controller** (`*_controller.js`) — JavaScript interactivity (only when needed)
 
-**Version Strategy:**
-- **During development:** Use `>= 0.1.0.pre` (gem) and `@pre` (npm) to always get the latest features
-- **For production:** Pin to a specific version like `0.1.16.pre` for stability
+Purely presentational components (Typography, Space, Divider, etc.) have no JavaScript layer.
 
-**Note:** Currently in pre-release (`0.1.x.pre`). Stable `1.0.0` release coming soon.
+---
 
 ## Development
 
-### Local Playground
-
-Want to see and test components locally? We have a built-in playground:
+### Playground
 
 ```bash
-# From the gem root directory
 bin/playground
 ```
 
-Then visit http://localhost:3000 to browse all components and examples.
-
-**Features:**
-- 📋 Browse all 65 components
-- 🎨 See examples in action
-- 🔍 Test component behavior
-- 💻 Perfect for development
+Opens a local Rails app at `http://localhost:3000` with all components and examples. Located in `test/dummy/`, not included in the published gem.
 
-The playground is located in `test/dummy/` and is **not included** in the published gem.
-
-### Adding Examples
-
-To add a new example for testing:
+To add an example:
 
 ```bash
-# Create a new example partial
 touch test/dummy/app/views/test_examples/[component]/_[example_name].html.erb
 ```
 
-It will automatically appear in the playground at `/test/[component]/[example_name]`.
+It appears automatically at `/test/[component]/[example_name]`.
 
-### Running Tests
+### Tests
 
 ```bash
-# All tests
-bundle exec rake test
+bundle exec rake test                                                          # all tests
+bundle exec rake test TEST=test/components/hakumi/button/component_test.rb    # single file
+bundle exec rake test:system                                                   # browser tests
+```
 
-# Specific test file
-bundle exec rake test TEST=test/components/hakumi/button/component_test.rb
+### Versioning
 
-# System tests (browser tests)
-bundle exec rake test:system
-```
+Gem and npm versions must be kept in sync:
 
-## Contributing
+```ruby
+# Gemfile
+gem 'hakumi_components', '0.1.16.pre'
+```
 
-Contributions are welcome! This is an open-source project and we'd love your help.
-
-**For Contributors:**
-
-1. Fork the Project
-2. Clone your fork and setup:
-   ```bash
-   git clone https://github.com/your-username/hakumi-components.git
-   cd hakumi-components
-   bin/setup
-   ```
-3. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
-4. Make your changes and add tests
-5. Run tests: `bundle exec rake test`
-6. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
-7. Push to the Branch (`git push origin feature/AmazingFeature`)
-8. Open a Pull Request
-
-**Development Commands:**
 ```bash
-bin/setup              # Initial setup
-bundle exec rake test  # Run Ruby tests
-yarn test             # Run JavaScript tests
-bin/ci                # Run full CI suite locally
+yarn add @hakumi-dev/hakumi-components@0.1.16-pre
 ```
 
-## License
+Use `>= 0.1.0.pre` / `@pre` to always track the latest pre-release.
 
-Distributed under the MIT License. See `LICENSE` for more information.
+---
 
-## Contact
+## Contributing
 
-Project Link: [https://github.com/hakumi-dev/hakumi-components](https://github.com/hakumi-dev/hakumi-components)
+1. Fork the repository
+2. Set up locally: `bin/setup`
+3. Create a branch: `git checkout -b my-feature`
+4. Make changes and add tests
+5. Run the test suite: `bundle exec rake test`
+6. Open a pull request
 
-## Acknowledgments
+---
 
-- Inspired by [Ant Design](https://ant.design/)
-- Built with [ViewComponent](https://viewcomponent.org/)
-- Powered by [Stimulus](https://stimulus.hotwired.dev/)
+## License
 
-<!-- MARKDOWN LINKS & IMAGES -->
-[Ruby-badge]: https://img.shields.io/badge/Ruby-CC342D?style=for-the-badge&logo=ruby&logoColor=white
-[Ruby-url]: https://www.ruby-lang.org/
-[Rails-badge]: https://img.shields.io/badge/Rails-CC0000?style=for-the-badge&logo=ruby-on-rails&logoColor=white
-[Rails-url]: https://rubyonrails.org/
-[ViewComponent-badge]: https://img.shields.io/badge/ViewComponent-FE7A16?style=for-the-badge&logo=ruby&logoColor=white
-[ViewComponent-url]: https://viewcomponent.org/
-[Stimulus-badge]: https://img.shields.io/badge/Stimulus-77E8B9?style=for-the-badge&logo=stimulus&logoColor=black
-[Stimulus-url]: https://stimulus.hotwired.dev/
-[Vite-badge]: https://img.shields.io/badge/Vite-646CFF?style=for-the-badge&logo=vite&logoColor=white
-[Vite-url]: https://vitejs.dev/
+MIT. See [LICENSE](./LICENSE).