hakumi_components 0.1.15.pre → 0.1.17.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dee2a6845009c4f594be77b7b37bf05143dc2c7a5cfadb6df4d4dea340274c86
-  data.tar.gz: 71344d054a21dfe967ca4c5d27847d532c0915451325d191b42bd1f3bcd1f0bb
+  metadata.gz: 266fdc5f238c66ebd468b2d65efc3293197442f23f724a6685aa27f76c719b80
+  data.tar.gz: 50c5490c4f78725878a12a517ff9de18e8c376922e47df1dcc9a6c9783e1a7d2
 SHA512:
-  metadata.gz: ca90dc371abc4a096347693523d7a5add17ba0c687e4562ab226b64f9f58b428cc900a003a8a90a82dfb2b23ed874121495bea768a92f4856457a716b8d5afb2
-  data.tar.gz: f4af1a6799f1ba6b410f89857458a50440673b659a0b78c8a0513118166defe9b978ba79ecb98cee3b0bc14ab15694f5bbcef132aed1de531b686aedce30f059
+  metadata.gz: b0bf88beaabfa3c7cbd2bfbe8018f17f78c6426626ce02e7fa25930f9d006aa6a39929388311ee22ba4e4f84a3f973495224f1a307251b26cb264c8878d7885c
+  data.tar.gz: 130f98a4e79a8262acf6113ca5738078a236cf2baf6a2fc809248eeb0e699a192670d06809144d1bcffc6613caede8bba045ed33a26ff82b8da2b34795218699

data/README.md

@@ -0,0 +1,487 @@
+<div align="center">
+  <a href="https://github.com/hakumi-dev/hakumi-components">
+    <img src="logo-hakumi-full.png" alt="Logo" width="250">
+  </a>
+
+  <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
+
+**🎮 [Try the Interactive Playground](https://components.hakumi.dev)** - See all components in action with live examples
+
+## Built With
+
+[![Ruby][Ruby-badge]][Ruby-url] [![ViewComponent][ViewComponent-badge]][ViewComponent-url] [![Stimulus][Stimulus-badge]][Stimulus-url]
+
+**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
+
+## Getting Started
+
+### 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.)
+
+**Recommended:**
+- Vite (via `vite_rails` gem)
+- Yarn or npm for package management
+
+### Installation
+
+#### Option A: Automatic Installation (Recommended)
+
+**1. Add the gem to your Gemfile:**
+
+```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:**
+
+```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
+
+If you prefer manual setup or the generator doesn't work for your setup:
+
+**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:**
+
+```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
+npm install @hakumi-dev/hakumi-components@pre
+
+# Using npm - specific version
+npm install @hakumi-dev/hakumi-components@0.1.16-pre
+```
+
+**3. Setup 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"
+
+const application = Application.start()
+window.HakumiComponents = HakumiComponents
+registerHakumiControllers(application)
+```
+
+**4. Setup stylesheets:**
+
+```scss
+// For Vite/Webpack (modern bundlers)
+// app/javascript/stylesheets/application.scss
+@use '@hakumi-dev/hakumi-components/styles';
+
+// OR for Sprockets/traditional setup
+// app/assets/stylesheets/application.scss
+@import "@hakumi-dev/hakumi-components/styles";
+```
+
+**5. (Optional) Configure FormBuilder:**
+
+```ruby
+# config/initializers/hakumi_components.rb
+Rails.application.config.action_view.default_form_builder = Hakumi::FormBuilder
+```
+
+## Usage
+
+### Basic Component Example
+
+```erb
+<%# Simple button %>
+<%= render Hakumi::Button::Component.new(type: :primary) do %>
+  Click me
+<% end %>
+
+<%# Form with automatic validation detection %>
+<%= form_with model: @user, builder: Hakumi::FormBuilder do |f| %>
+  <%= f.text_field :email %>
+  <%= f.text_field :name %>
+  <%= f.submit "Save", type: :primary %>
+<% end %>
+
+<%# Modal with programmatic control %>
+<%= render Hakumi::Modal::Component.new(
+  id: "my-modal",
+  title: "Confirm Action"
+) do %>
+  Are you sure you want to proceed?
+<% 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/button/docs/README.md) - Clickable button element
+- [Float Button](./app/components/hakumi/float_button/docs/README.md) - Floating action button
+- [Icon](./app/components/hakumi/icon/docs/README.md) - Icon display component
+- [Typography](./app/components/hakumi/typography/docs/README.md) - Text styling and formatting
+
+#### Layout (6)
+- [Divider](./app/components/hakumi/divider/docs/README.md) - Horizontal or vertical divider line
+- [Flex](./app/components/hakumi/flex/docs/README.md) - Flexbox layout container
+- [Grid](./app/components/hakumi/grid/docs/README.md) - Grid layout system
+- [Layout](./app/components/hakumi/layout/docs/README.md) - Page layout structure
+- [Space](./app/components/hakumi/space/docs/README.md) - Spacing between elements
+- [Splitter](./app/components/hakumi/splitter/docs/README.md) - Resizable split panels
+
+#### Navigation (6)
+- [Anchor](./app/components/hakumi/anchor/docs/README.md) - Anchor navigation for page sections
+- [Breadcrumb](./app/components/hakumi/breadcrumb/docs/README.md) - Breadcrumb navigation trail
+- [Dropdown](./app/components/hakumi/dropdown/docs/README.md) - Dropdown menu
+- [Menu](./app/components/hakumi/menu/docs/README.md) - Navigation menu
+- [Pagination](./app/components/hakumi/pagination/docs/README.md) - Pagination controls
+- [Steps](./app/components/hakumi/steps/docs/README.md) - Step-by-step navigation
+
+#### Data Entry (18)
+- [Autocomplete](./app/components/hakumi/autocomplete/docs/README.md) - Input with autocomplete suggestions
+- [Cascader](./app/components/hakumi/cascader/docs/README.md) - Cascading selection dropdown
+- [Checkbox](./app/components/hakumi/checkbox/docs/README.md) - Checkbox input
+- [Color Picker](./app/components/hakumi/color_picker/docs/README.md) - Color selection input
+- [Date Picker](./app/components/hakumi/date_picker/docs/README.md) - Date selection input
+- [Form](./app/components/hakumi/form/docs/README.md) - Form wrapper with validation
+- [Input](./app/components/hakumi/input/docs/README.md) - Text input field
+- [Input Number](./app/components/hakumi/input_number/docs/README.md) - Numeric input field
+- [Mentions](./app/components/hakumi/mentions/docs/README.md) - @mentions input
+- [Radio](./app/components/hakumi/radio/docs/README.md) - Radio button input
+- [Rate](./app/components/hakumi/rate/docs/README.md) - Star rating input
+- [Select](./app/components/hakumi/select/docs/README.md) - Dropdown select input
+- [Slider](./app/components/hakumi/slider/docs/README.md) - Range slider input
+- [Switch](./app/components/hakumi/switch/docs/README.md) - Toggle switch input
+- [Time Picker](./app/components/hakumi/time_picker/docs/README.md) - Time selection input
+- [Transfer](./app/components/hakumi/transfer/docs/README.md) - Dual list transfer
+- [Tree Select](./app/components/hakumi/tree_select/docs/README.md) - Tree structure select
+- [Upload](./app/components/hakumi/upload/docs/README.md) - File upload component
+
+#### Data Display (20)
+- [Avatar](./app/components/hakumi/avatar/docs/README.md) - User avatar display
+- [Badge](./app/components/hakumi/badge/docs/README.md) - Badge and status dot
+- [Calendar](./app/components/hakumi/calendar/docs/README.md) - Calendar display
+- [Card](./app/components/hakumi/card/docs/README.md) - Card container
+- [Carousel](./app/components/hakumi/carousel/docs/README.md) - Image/content carousel
+- [Collapse](./app/components/hakumi/collapse/docs/README.md) - Collapsible accordion panels
+- [Descriptions](./app/components/hakumi/descriptions/docs/README.md) - Description list display
+- [Empty](./app/components/hakumi/empty/docs/README.md) - Empty state placeholder
+- [Image](./app/components/hakumi/image/docs/README.md) - Image display with preview
+- [Popover](./app/components/hakumi/popover/docs/README.md) - Popover overlay
+- [QR Code](./app/components/hakumi/qr_code/docs/README.md) - QR code generator
+- [Segmented](./app/components/hakumi/segmented/docs/README.md) - Segmented control
+- [Statistic](./app/components/hakumi/statistic/docs/README.md) - Statistic display
+- [Table](./app/components/hakumi/table/docs/README.md) - Data table
+- [Tabs](./app/components/hakumi/tabs/docs/README.md) - Tab navigation
+- [Tag](./app/components/hakumi/tag/docs/README.md) - Tag label
+- [Timeline](./app/components/hakumi/timeline/docs/README.md) - Timeline display
+- [Tooltip](./app/components/hakumi/tooltip/docs/README.md) - Tooltip overlay
+- [Tour](./app/components/hakumi/tour/docs/README.md) - Guided tour
+- [Tree](./app/components/hakumi/tree/docs/README.md) - Tree structure display
+
+#### Feedback (10)
+- [Alert](./app/components/hakumi/alert/docs/README.md) - Alert message display
+- [Drawer](./app/components/hakumi/drawer/docs/README.md) - Slide-out drawer panel
+- [Message](./app/components/hakumi/message/docs/README.md) - Global message notification
+- [Modal](./app/components/hakumi/modal/docs/README.md) - Modal dialog
+- [Notification](./app/components/hakumi/notification/docs/README.md) - Notification message
+- [Popconfirm](./app/components/hakumi/popconfirm/docs/README.md) - Confirmation popover
+- [Progress](./app/components/hakumi/progress/docs/README.md) - Progress indicator
+- [Result](./app/components/hakumi/result/docs/README.md) - Result status page
+- [Skeleton](./app/components/hakumi/skeleton/docs/README.md) - Skeleton loading placeholder
+- [Spin](./app/components/hakumi/spin/docs/README.md) - Loading spinner
+
+#### Other (1)
+- [Affix](./app/components/hakumi/affix/docs/README.md) - Pin element to viewport
+
+## JavaScript API
+
+Components with interactivity expose programmatic APIs:
+
+```javascript
+// Access component API via element
+const modal = document.getElementById('my-modal')
+modal.hakumiComponent.api.open()
+modal.hakumiComponent.api.close()
+
+// Or 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
+```
+
+## Updating
+
+To update to the latest version:
+
+```bash
+# Update Ruby gem
+bundle update hakumi_components
+
+# Update npm package to latest pre-release
+yarn add @hakumi-dev/hakumi-components@pre
+# or
+npm install @hakumi-dev/hakumi-components@pre
+```
+
+**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
+
+**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:
+
+```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
+
+The playground is located in `test/dummy/` and is **not included** in the published gem.
+
+### Adding Examples
+
+To add a new example for testing:
+
+```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]`.
+
+### Running Tests
+
+```bash
+# All tests
+bundle exec rake test
+
+# Specific test file
+bundle exec rake test TEST=test/components/hakumi/button/component_test.rb
+
+# System tests (browser tests)
+bundle exec rake test:system
+```
+
+## Contributing
+
+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
+```
+
+## License
+
+Distributed under the MIT License. See `LICENSE` for more information.
+
+## Contact
+
+Project Link: [https://github.com/hakumi-dev/hakumi-components](https://github.com/hakumi-dev/hakumi-components)
+
+## Acknowledgments
+
+- Inspired by [Ant Design](https://ant.design/)
+- Built with [ViewComponent](https://viewcomponent.org/)
+- Powered by [Stimulus](https://stimulus.hotwired.dev/)
+
+<!-- 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/