@hakumi-dev/hakumi-components 0.1.16-pre → 0.1.18-pre

package/README.md

@@ -20,10 +20,10 @@
 
 ## 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.
+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:**
-- 🎨 **55+ Components** - Button, Form, Table, Modal, Menu, Calendar, and more
+- 🎨 **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
@@ -64,7 +64,11 @@ Hakumi Components is a comprehensive UI component library for Ruby on Rails appl
 **1. Add the gem to your Gemfile:**
 
 ```ruby
-gem 'hakumi_components', '~> 0.1.0.pre'
+# 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:**
@@ -92,7 +96,11 @@ 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'
+# 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:**
@@ -100,11 +108,17 @@ gem 'hakumi_components', '~> 0.1.0.pre'
 ```bash
 bundle install
 
-# Using Yarn
+# Using Yarn - latest pre-release
 yarn add @hakumi-dev/hakumi-components@pre
 
-# Using npm
+# 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:**
@@ -131,11 +145,33 @@ registerHakumiControllers(application)
 @import "@hakumi-dev/hakumi-components/styles";
 ```
 
-**5. (Optional) Configure FormBuilder:**
+## Configuration
+
+You can configure HakumiComponents in an initializer:
 
 ```ruby
 # config/initializers/hakumi_components.rb
-Rails.application.config.action_view.default_form_builder = Hakumi::FormBuilder
+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
+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
+
+HakumiComponents.config.base_path
+# => "hakumi/components"
 ```
 
 ## Usage
@@ -144,19 +180,19 @@ Rails.application.config.action_view.default_form_builder = Hakumi::FormBuilder
 
 ```erb
 <%# Simple button %>
-<%= render Hakumi::Button::Component.new(type: :primary) do %>
+<%= render HakumiComponents::Button::Component.new(type: :primary) do %>
   Click me
 <% end %>
 
 <%# Form with automatic validation detection %>
-<%= form_with model: @user, builder: Hakumi::FormBuilder do |f| %>
+<%= 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 Hakumi::Modal::Component.new(
+<%= render HakumiComponents::Modal::Component.new(
   id: "my-modal",
   title: "Confirm Action"
 ) do %>
@@ -164,16 +200,88 @@ Rails.application.config.action_view.default_form_builder = Hakumi::FormBuilder
 <% 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)_
+### 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
 
 ## JavaScript API
 
@@ -261,13 +369,24 @@ If components don't respond to interactions:
 ### Version mismatches
 
 Keep gem and npm versions in sync:
+
 ```ruby
-# Gemfile
-gem 'hakumi_components', '~> 0.1.15.pre'
+# Gemfile - pin to specific version
+gem 'hakumi_components', '0.1.16.pre'
 ```
 ```bash
-# package.json
-yarn add @hakumi-dev/hakumi-components@0.1.15-pre
+# 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
@@ -278,13 +397,62 @@ To update to the latest version:
 # Update Ruby gem
 bundle update hakumi_components
 
-# Update npm package (always use latest pre-release)
+# Update npm package to latest pre-release
 yarn add @hakumi-dev/hakumi-components@pre
 # or
-npm install @hakumi-dev/hakumi-components@pre --save
+npm install @hakumi-dev/hakumi-components@pre
 ```
 
-**Note:** Currently in pre-release. Use `@pre` tag to get the latest version.
+**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
 

package/app/javascript/hakumi_components/controllers/base/registry_controller.js

@@ -3,6 +3,14 @@ import { ensureId } from "../../core/dom.js"
 import { register, unregister } from "../../core/registry.js"
 
 export default class RegistryController extends Controller {
+  /**
+   * Declarative actions supported by this component.
+   * Each component must explicitly declare which actions it supports.
+   * Actions map to methods: 'close' -> close(), 'confirm' -> handleConfirm()
+   * @type {string[]}
+   */
+  static declarativeActions = []
+
   connect() {
     const isComponentController = this.isHakumiController()
 
@@ -21,6 +29,8 @@ export default class RegistryController extends Controller {
 
     if (typeof this.setup === "function") this.setup()
 
+    this.setupDeclarativeActions()
+
     this.validateContract()
     register(this.element.id, this.element.hakumiComponent.api)
 
@@ -28,12 +38,17 @@ export default class RegistryController extends Controller {
     if (this.element.hakumiComponent.singleton && typeof window !== "undefined" && window.HakumiComponents) {
       window.HakumiComponents[this.element.hakumiComponent.name] = this.element.hakumiComponent.api
     }
+
+    // Mark component as ready for testing
+    this.element.dataset.hakumiReady = "true"
   }
 
 
   disconnect() {
     if (typeof this.teardown === "function") this.teardown()
 
+    this.teardownDeclarativeActions()
+
     const c = this.element?.hakumiComponent
     if (c?.singleton && typeof window !== "undefined" && window.HakumiComponents) {
       if (window.HakumiComponents[c.name] === c.api) {
@@ -84,18 +99,83 @@ export default class RegistryController extends Controller {
     return String(this.identifier || "").startsWith("hakumi--")
   }
 
-  
+
   setup() {
 
   }
 
-  
+
   teardown() {
 
   }
 
-  
+
   registerApi() {
 
   }
+
+  /**
+   * Sets up declarative action handling for data-hakumi-action attributes.
+   * Listens for clicks on elements with data-hakumi-action and routes to
+   * the appropriate handler method (close, open, toggle, confirm, cancel).
+   */
+  setupDeclarativeActions() {
+    this.boundHandleDeclarativeAction = this.handleDeclarativeAction.bind(this)
+    this.element.addEventListener("click", this.boundHandleDeclarativeAction)
+  }
+
+  /**
+   * Cleans up declarative action event listener.
+   */
+  teardownDeclarativeActions() {
+    if (this.boundHandleDeclarativeAction) {
+      this.element.removeEventListener("click", this.boundHandleDeclarativeAction)
+      this.boundHandleDeclarativeAction = null
+    }
+  }
+
+  /**
+   * Handles clicks on elements with data-hakumi-action attribute.
+   * Routes to the appropriate method based on the action value.
+   * Supported actions: close, open, toggle, confirm, cancel
+   * @param {Event} event - The click event
+   */
+  handleDeclarativeAction(event) {
+    const actionElement = event.target.closest("[data-hakumi-action]")
+    if (!actionElement || !this.element.contains(actionElement)) return
+
+    const action = actionElement.dataset.hakumiAction
+    const actionMethod = this.getActionMethod(action)
+
+    if (typeof actionMethod === "function") {
+      event.preventDefault()
+      actionMethod.call(this, event, actionElement)
+    }
+  }
+
+  /**
+   * Returns the method to call for a given action name.
+   * Only returns methods for actions declared in static declarativeActions.
+   * @param {string} action - The action name
+   * @returns {Function|undefined} The method to call
+   */
+  getActionMethod(action) {
+    const allowedActions = this.constructor.declarativeActions || []
+    if (!allowedActions.includes(action)) {
+      return undefined
+    }
+
+    // Try direct method name: close, open, toggle
+    if (typeof this[action] === "function") {
+      return this[action]
+    }
+
+    // Try handleX pattern: confirm -> handleConfirm, cancel -> handleCancel
+    const handlerName = `handle${action.charAt(0).toUpperCase()}${action.slice(1)}`
+    if (typeof this[handlerName] === "function") {
+      return this[handlerName]
+    }
+
+    return undefined
+  }
 }

package/app/javascript/hakumi_components/controllers/hakumi/affix_controller.js

@@ -41,13 +41,6 @@ export default class extends RegistryController {
         setOffsetBottom: (value) => this.setOffsetBottom(value)
       }
     }
-
-    this.#exposeApi()
-  }
-
-  disconnect() {
-    delete this.element.hakumiAffix
-    super.disconnect()
   }
 
   updatePosition() {
@@ -187,20 +180,4 @@ export default class extends RegistryController {
     if (this.hasOffsetBottomValue) return Number(this.offsetBottomValue)
     return null
   }
-
-  #exposeApi() {
-    this.element.hakumiAffix = {
-      check: () => this.updatePosition(),
-      update: () => this.updatePosition(),
-      isAffixed: () => this.affixed,
-      getState: () => ({
-        affixed: this.affixed,
-        offsetTop: this.offsetTop,
-        offsetBottom: this.offsetBottom,
-        targetSelector: this.targetSelectorValue || null
-      }),
-      setOffsetTop: (value) => this.setOffsetTop(value),
-      setOffsetBottom: (value) => this.setOffsetBottom(value)
-    }
-  }
 }

package/app/javascript/hakumi_components/controllers/hakumi/alert_controller.js

@@ -1,6 +1,7 @@
 import RegistryController from "../base/registry_controller.js"
 
 export default class extends RegistryController {
+  static declarativeActions = ["close"]
   static targets = ["message", "description"]
 
   registerApi() {
@@ -20,7 +21,7 @@ export default class extends RegistryController {
 
   close(event) {
     if (event) event.preventDefault()
-    this.element.dispatchEvent(new CustomEvent("hakumi-component:hidden", { bubbles: true }))
+    this.dispatch("hidden")
     this.element.remove()
   }
 

package/app/javascript/hakumi_components/controllers/hakumi/button_controller.js

@@ -14,13 +14,6 @@ export default class extends RegistryController {
     this.element.removeEventListener('click', this.boundRipple)
   }
 
-  handleClick(event) {
-    if (this.loadingValue || this.element.disabled) {
-      event.preventDefault()
-      event.stopImmediatePropagation()
-    }
-  }
-
   createRipple(event) {
     const button = event.currentTarget
     const circle = document.createElement("span")

package/app/javascript/hakumi_components/controllers/hakumi/calendar_controller.js

@@ -41,7 +41,6 @@ export default class extends RegistryController {
   }
 
   teardown() {
-    delete this.element.hakumiCalendar
   }
 
   #bindNestedEvents() {
@@ -1096,6 +1095,5 @@ export default class extends RegistryController {
     }
 
 
-    this.element.hakumiCalendar = api
   }
 }

package/app/javascript/hakumi_components/controllers/hakumi/color_picker_controller.js

@@ -725,11 +725,6 @@ export default class extends RegistryController {
     }
 
     dispatchEvent(name, detail) {
-        this.element.dispatchEvent(
-            new CustomEvent(`hakumi:color-picker:${name}`, {
-                detail,
-                bubbles: true
-            })
-        )
+        this.dispatch(name, { detail })
     }
 }