hakumi_components 0.1.15.pre → 0.1.16.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dee2a6845009c4f594be77b7b37bf05143dc2c7a5cfadb6df4d4dea340274c86
-  data.tar.gz: 71344d054a21dfe967ca4c5d27847d532c0915451325d191b42bd1f3bcd1f0bb
+  metadata.gz: 3a8dd617e9d2de8d3db3296397eb5f8d452ad1632b5021033951a063cf2638f1
+  data.tar.gz: e0c7cd5b4e0a481780bfd23d21484f868f27af1634cf16fd68a6411479843980
 SHA512:
-  metadata.gz: ca90dc371abc4a096347693523d7a5add17ba0c687e4562ab226b64f9f58b428cc900a003a8a90a82dfb2b23ed874121495bea768a92f4856457a716b8d5afb2
-  data.tar.gz: f4af1a6799f1ba6b410f89857458a50440673b659a0b78c8a0513118166defe9b978ba79ecb98cee3b0bc14ab15694f5bbcef132aed1de531b686aedce30f059
+  metadata.gz: d877aebe66b66b309762d09077ebe6ac27c89a7a0c9a25d8af8b8bcf97ef1a266ac88a025df216a985354b2018f6240b1a941b6b557838c318e1488beaef17bb
+  data.tar.gz: d2f887ac18633b53d081442a81a9cb4753af33020a189a5056893cbf315b69ac52f5e213dbec740775caee9ff385629a71c4aa3e4660d452960fc16132c22bb6

data/README.md

@@ -0,0 +1,341 @@
+<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 55+ production-ready, accessible components with light/dark theme support, combining the power of ViewComponent, Stimulus, and modern CSS.
+
+**✨ Key Features:**
+- 🎨 **55+ 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
+gem 'hakumi_components', '~> 0.1.0.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
+gem 'hakumi_components', '~> 0.1.0.pre'
+```
+
+**2. Install dependencies:**
+
+```bash
+bundle install
+
+# Using Yarn
+yarn add @hakumi-dev/hakumi-components@pre
+
+# Using npm
+npm install @hakumi-dev/hakumi-components@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 Categories
+
+- **Layout**: Divider, Flex, Grid, Layout, Space, Splitter
+- **Navigation**: Breadcrumb, Dropdown, Menu, Pagination, Steps, Tabs
+- **Data Display**: Avatar, Badge, Card, Table, Tag, Timeline, Tooltip, Tree
+- **Form Controls**: Button, Checkbox, ColorPicker, DatePicker, Input, Select, Radio, Slider, Switch
+- **Feedback**: Alert, Drawer, Message, Modal, Notification, Progress, Spin
+- **Typography**: Link, Paragraph, Text, Title
+
+_For detailed component documentation, please refer to the [Component Guide](#) (coming soon)_
+
+## 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
+gem 'hakumi_components', '~> 0.1.15.pre'
+```
+```bash
+# package.json
+yarn add @hakumi-dev/hakumi-components@0.1.15-pre
+```
+
+## Updating
+
+To update to the latest version:
+
+```bash
+# Update Ruby gem
+bundle update hakumi_components
+
+# Update npm package (always use latest pre-release)
+yarn add @hakumi-dev/hakumi-components@pre
+# or
+npm install @hakumi-dev/hakumi-components@pre --save
+```
+
+**Note:** Currently in pre-release. Use `@pre` tag to get the latest version.
+
+## 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/

data/lib/generators/hakumi/install_generator.rb

@@ -8,125 +8,208 @@ module Hakumi
 
     def add_npm_package
       say "Adding @hakumi-dev/hakumi-components to package.json...", :green
-      run "yarn add @hakumi-dev/hakumi-components"
+
+      # Install latest pre-release version
+      if package_manager == :npm
+        run "npm install @hakumi-dev/hakumi-components@pre --save"
+      else
+        run "yarn add @hakumi-dev/hakumi-components@pre"
+      end
     end
 
     def setup_javascript
       say "Setting up JavaScript...", :green
 
-      js_file = "app/javascript/controllers/index.js"
+      js_file = detect_js_entry_point
 
-      if File.exist?(js_file)
+      if js_file
         content = File.read(js_file)
 
         unless content.include?("hakumi-components")
-          # Add import at the top
-          import_line = 'import { registerHakumiControllers } from "@hakumi-dev/hakumi-components"'
-
-          # Add registration after Stimulus setup
-          register_line = "registerHakumiControllers(application)"
-
-          # Insert import after other imports
-          if content.include?("import")
-            # Find the last import line and add after it
-            lines = content.split("\n")
-            last_import_index = lines.rindex { |line| line.start_with?("import ") }
-
-            if last_import_index
-              lines.insert(last_import_index + 1, import_line)
-              content = lines.join("\n")
+          # Full import with default export and named export
+          import_lines = [
+            'import HakumiComponents, { registerHakumiControllers } from "@hakumi-dev/hakumi-components"'
+          ]
+
+          # Add global window assignment and registration
+          register_lines = [
+            "window.HakumiComponents = HakumiComponents",
+            "registerHakumiControllers(application)"
+          ]
+
+          # Insert imports after other imports
+          lines = content.split("\n")
+          last_import_index = lines.rindex { |line| line.match?(/^import\s/) }
+
+          if last_import_index
+            # Insert after last import
+            import_lines.reverse_each do |line|
+              lines.insert(last_import_index + 1, line)
             end
           else
-            content = "#{import_line}\n#{content}"
+            # Add at the top
+            lines = import_lines + [ "" ] + lines
           end
 
-          # Add registration at the end if not present
-          unless content.include?("registerHakumiControllers")
-            content += "\n#{register_line}\n"
+          # Find where to add registration (after Stimulus application setup)
+          application_index = lines.index { |line| line.include?("Application.start()") || line.include?("application = Application") }
+
+          if application_index
+            # Add after application setup
+            register_lines.reverse_each do |line|
+              lines.insert(application_index + 1, line)
+            end
+          else
+            # Add at the end
+            lines += [ "" ] + register_lines
           end
 
+          content = lines.join("\n")
           File.write(js_file, content)
-          say "  Updated #{js_file}", :green
+          say "  ✓ Updated #{js_file}", :green
         else
-          say "  #{js_file} already configured", :yellow
+          say "  ✓ #{js_file} already configured", :yellow
         end
       else
-        say "  Could not find #{js_file}. Please add manually:", :yellow
-        say '    import { registerHakumiControllers } from "@hakumi-dev/hakumi-components"'
+        say "  ⚠ Could not find JavaScript entry point. Please add manually:", :yellow
+        say ""
+        say "    import HakumiComponents, { registerHakumiControllers } from \"@hakumi-dev/hakumi-components\""
+        say "    window.HakumiComponents = HakumiComponents"
         say "    registerHakumiControllers(application)"
+        say ""
       end
     end
 
     def setup_stylesheets
       say "Setting up stylesheets...", :green
 
-      # Check for different stylesheet configurations
-      scss_files = [
-        "app/assets/stylesheets/application.scss",
-        "app/assets/stylesheets/application.css.scss",
-        "app/javascript/stylesheets/application.scss"
-      ]
-
-      css_files = [
-        "app/assets/stylesheets/application.css"
-      ]
-
-      scss_file = scss_files.find { |f| File.exist?(f) }
-      css_file = css_files.find { |f| File.exist?(f) }
+      scss_file = detect_scss_file
 
       if scss_file
         content = File.read(scss_file)
-        import_line = '@import "@hakumi-dev/hakumi-components/styles";'
 
         unless content.include?("hakumi-components")
+          # Use modern @use syntax for Vite/Webpack, @import for Sprockets
+          import_line = if using_modern_bundler?
+            '@use "@hakumi-dev/hakumi-components/styles";'
+          else
+            '@import "@hakumi-dev/hakumi-components/styles";'
+          end
+
+          # Add at the top of the file
           File.write(scss_file, "#{import_line}\n#{content}")
-          say "  Updated #{scss_file}", :green
+          say "  ✓ Updated #{scss_file}", :green
+          say "    Using #{using_modern_bundler? ? '@use' : '@import'} syntax", :cyan
         else
-          say "  #{scss_file} already configured", :yellow
+          say "  ✓ #{scss_file} already configured", :yellow
         end
-      elsif css_file
-        say "  Found CSS file. For full styling support, rename to .scss and add:", :yellow
-        say '    @import "@hakumi-dev/hakumi-components/styles";'
       else
-        say "  Could not find stylesheet. Please add manually:", :yellow
-        say '    @import "@hakumi-dev/hakumi-components/styles";'
+        say "  ⚠ Could not find SCSS file. Please add manually:", :yellow
+        say ""
+        if using_modern_bundler?
+          say "    // For Vite/Webpack (modern bundlers):"
+          say "    @use \"@hakumi-dev/hakumi-components/styles\";"
+        else
+          say "    // For Sprockets:"
+          say "    @import \"@hakumi-dev/hakumi-components/styles\";"
+        end
+        say ""
       end
     end
 
     def setup_form_builder
-      say "Setting up FormBuilder...", :green
+      say "Setting up FormBuilder (optional)...", :green
 
       initializer_file = "config/initializers/hakumi_components.rb"
 
       if File.exist?(initializer_file)
-        say "  #{initializer_file} already exists", :yellow
+        say "  ✓ #{initializer_file} already exists", :yellow
       else
         create_file initializer_file, <<~RUBY
           # frozen_string_literal: true
 
           # Configure default form builder for Hakumi Components
+          # This enables automatic validation styling and label generation
           Rails.application.config.action_view.default_form_builder = Hakumi::FormBuilder
         RUBY
-        say "  Created #{initializer_file}", :green
+        say "  ✓ Created #{initializer_file}", :green
       end
     end
 
     def show_post_install
       say ""
-      say "=" * 60, :green
-      say "Hakumi Components installed successfully!", :green
-      say "=" * 60, :green
+      say "=" * 70, :green
+      say "🎉 Hakumi Components installed successfully!", :green
+      say "=" * 70, :green
+      say ""
+      say "📋 Next steps:", :cyan
       say ""
-      say "Next steps:"
-      say "  1. Restart your Rails server"
-      say "  2. Start using components in your views:"
+      say "  1. Restart your Rails server and asset pipeline"
+      say "  2. Try using a component in your views:"
       say ""
-      say "     <%= render Hakumi::Button::Component.new(type: :primary) do %>"
-      say "       Click me"
-      say "     <% end %>"
+      say "     <%= render Hakumi::Button::Component.new(type: :primary) do %>", :cyan
+      say "       Click me", :cyan
+      say "     <% end %>", :cyan
       say ""
-      say "Documentation: https://github.com/hakumi-dev/hakumi-components"
+      say "  3. Check the browser console for confirmation:"
+      say "     → Should see: \"[HakumiComponents] Registered X controllers\""
       say ""
+      say "📚 Resources:", :cyan
+      say "  • Live Playground: https://antrails.kb714.com"
+      say "  • Documentation:   https://github.com/hakumi-dev/hakumi-components"
+      say "  • npm Package:     https://www.npmjs.com/package/@hakumi-dev/hakumi-components"
+      say ""
+
+      if needs_manual_setup?
+        say "⚠️  Manual setup required:", :yellow
+        say "  Some files could not be configured automatically."
+        say "  Please refer to the output above for manual instructions."
+        say ""
+      end
+    end
+
+    private
+
+    def detect_js_entry_point
+      # Check common JavaScript entry points in order of preference
+      candidates = [
+        "app/javascript/entrypoints/application.js",  # Vite
+        "app/javascript/application.js",              # esbuild, Webpack
+        "app/assets/javascripts/application.js"       # Sprockets
+      ]
+
+      candidates.find { |file| File.exist?(file) }
+    end
+
+    def detect_scss_file
+      # Check common SCSS file locations
+      candidates = [
+        "app/javascript/stylesheets/application.scss", # Vite/Webpack
+        "app/assets/stylesheets/application.scss",     # Sprockets
+        "app/assets/stylesheets/application.css.scss"  # Old Sprockets
+      ]
+
+      candidates.find { |file| File.exist?(file) }
+    end
+
+    def using_modern_bundler?
+      # Detect if using Vite, Webpack, or esbuild (modern bundlers)
+      File.exist?("vite.config.js") ||
+        File.exist?("vite.config.ts") ||
+        File.exist?("vite.config.mts") ||
+        File.exist?("webpack.config.js") ||
+        File.exist?("config/webpack") ||
+        (File.exist?("Gemfile") && File.read("Gemfile").include?("vite_rails"))
+    end
+
+    def package_manager
+      return :yarn if File.exist?("yarn.lock")
+      return :npm if File.exist?("package-lock.json")
+      :yarn # default
+    end
+
+    def needs_manual_setup?
+      !detect_js_entry_point || !detect_scss_file
     end
   end
 end

data/lib/hakumi_components/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module HakumiComponents
-  VERSION = "0.1.15.pre"
+  VERSION = "0.1.16.pre"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: hakumi_components
 version: !ruby/object:Gem::Version
-  version: 0.1.15.pre
+  version: 0.1.16.pre
 platform: ruby
 authors:
 - kb714
@@ -74,6 +74,7 @@ extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - LICENSE
+- README.md
 - app/assets/icons/filled/account-book.svg
 - app/assets/icons/filled/alert.svg
 - app/assets/icons/filled/alipay-circle.svg