hakumi_components 0.1.16.pre → 0.1.17.pre

data/app/javascript/hakumi_components/controllers/hakumi/theme_controller.js

@@ -20,7 +20,21 @@ export default class extends RegistryController {
 
         this._mediaQuery = window.matchMedia("(prefers-color-scheme: dark)")
 
+        // Check if there's an existing explicit theme set in HTML
+        const existingTheme = document.documentElement.getAttribute("data-theme")
+        const shouldAutoDetect = !existingTheme || existingTheme === "auto"
+
         this._handleSystemThemeChange = (e) => {
+            const currentTheme = document.documentElement.getAttribute("data-theme")
+            // If theme is "auto", don't change the attribute - let CSS media query handle it
+            // Only dispatch event for sync purposes
+            if (currentTheme === "auto") {
+                const effectiveTheme = e.matches ? "dark" : "light"
+                window.dispatchEvent(new CustomEvent("theme-changed", { detail: { theme: effectiveTheme } }))
+                if (this.syncSandboxValue) this.syncSandboxFrames(effectiveTheme)
+                return
+            }
+            // For non-auto themes, only update if no stored preference
             if (!Persistence.storage.get(this.storageKeyValue)) {
                 this.setTheme(e.matches ? "dark" : "light")
             }
@@ -34,7 +48,16 @@ export default class extends RegistryController {
             })
         }
 
-        this.setTheme(this.detectInitialTheme())
+        // Only set theme if there's no explicit theme
+        // If "auto", don't change the attribute - CSS media query handles it
+        if (!existingTheme) {
+            this.setTheme(this.detectInitialTheme())
+        } else if (existingTheme === "auto") {
+            // For "auto", just dispatch event and sync sandboxes without changing attribute
+            const effectiveTheme = this._mediaQuery.matches ? "dark" : "light"
+            window.dispatchEvent(new CustomEvent("theme-changed", { detail: { theme: effectiveTheme } }))
+            if (this.syncSandboxValue) this.syncSandboxFrames(effectiveTheme)
+        }
     }
 
     teardown() {

data/app/javascript/hakumi_components/controllers/hakumi/time_picker_controller.js

@@ -270,8 +270,7 @@ export default class extends RegistryController {
     }
 
     dispatchChange(value, parts) {
-        this.element.dispatchEvent(new CustomEvent("hakumi:time-picker:change", {
-            bubbles: true,
+        this.dispatch("change", {
             detail: {
                 value,
                 hour: parts.hour,
@@ -279,13 +278,10 @@ export default class extends RegistryController {
                 second: parts.second,
                 period: parts.period
             }
-        }))
+        })
     }
 
     dispatchOpenChange(open) {
-        this.element.dispatchEvent(new CustomEvent("hakumi:time-picker:open-change", {
-            bubbles: true,
-            detail: { open }
-        }))
+        this.dispatch("openChange", { detail: { open } })
     }
 }

data/app/javascript/hakumi_components/controllers/hakumi/timeline_controller.js

@@ -22,13 +22,6 @@ export default class extends RegistryController {
         toggleReverse: () => this.toggleReverse()
       }
     }
-
-    this.#exposeApi()
-  }
-
-  disconnect() {
-    delete this.element.hakumiTimeline
-    super.disconnect()
   }
 
   setReverse(value) {
@@ -76,13 +69,4 @@ export default class extends RegistryController {
 
     ordered.forEach((item) => this.itemsContainer.appendChild(item))
   }
-
-  #exposeApi() {
-    this.element.hakumiTimeline = {
-      getItems: () => this.getItems(),
-      getReverse: () => this.reverseValue,
-      setReverse: (value) => this.setReverse(value),
-      toggleReverse: () => this.toggleReverse()
-    }
-  }
 }

data/app/javascript/hakumi_components/controllers/hakumi/transfer_controller.js

@@ -301,7 +301,7 @@ export default class extends RegistryController {
       direction
     }
 
-    this.element.dispatchEvent(new CustomEvent("hakumi:transfer:change", { detail, bubbles: true }))
+    this.dispatch("change", { detail })
   }
 
   #dispatchSelectChange() {
@@ -310,6 +310,6 @@ export default class extends RegistryController {
       targetSelectedKeys: this.#selectedKeys("target")
     }
 
-    this.element.dispatchEvent(new CustomEvent("hakumi:transfer:select-change", { detail, bubbles: true }))
+    this.dispatch("selectChange", { detail })
   }
 }

data/app/javascript/hakumi_components/controllers/hakumi/tree_controller.js

@@ -51,7 +51,6 @@ export default class extends RegistryController {
   }
 
   disconnect() {
-    delete this.element.hakumiTree
     super.disconnect()
   }
 
@@ -81,7 +80,6 @@ export default class extends RegistryController {
       api
     }
 
-    this.element.hakumiTree = api
   }
 
   buildNodeMap() {

data/app/javascript/hakumi_components/controllers/hakumi/tree_select_controller.js

@@ -268,14 +268,14 @@ export default class extends RegistryController {
   }
 
   treeApi() {
-    return this.treeTarget?.hakumiTree || this.treeTarget?.hakumiComponent?.api
+    return this.treeTarget?.hakumiComponent?.api
   }
 
   dispatchSelect(detail) {
-    this.element.dispatchEvent(new CustomEvent("hakumi:tree-select:select", { detail, bubbles: true }))
+    this.dispatch("select", { detail })
   }
 
   dispatchChange(detail) {
-    this.element.dispatchEvent(new CustomEvent("hakumi:tree-select:change", { detail, bubbles: true }))
+    this.dispatch("change", { detail })
   }
 }

data/app/javascript/hakumi_components/controllers/hakumi/upload_controller.js

@@ -742,31 +742,21 @@ export default class extends RegistryController {
   }
 
   dispatchChange(file) {
-    this.element.dispatchEvent(
-      new CustomEvent("hakumi:upload:change", {
-        bubbles: true,
-        detail: { file, fileList: this.getFileList() }
-      })
-    )
+    this.dispatch("change", {
+      detail: { file, fileList: this.getFileList() }
+    })
   }
 
   dispatchProgress(file, event) {
-    this.element.dispatchEvent(
-      new CustomEvent("hakumi:upload:progress", {
-        bubbles: true,
-        detail: { file: file ? { ...file } : null, fileList: this.getFileList(), event }
-      })
-    )
+    this.dispatch("progress", {
+      detail: { file: file ? { ...file } : null, fileList: this.getFileList(), event }
+    })
   }
 
   dispatchSuccess(file) {
-    this.element.dispatchEvent(
-      new CustomEvent("hakumi:upload:success", {
-        bubbles: true,
-        detail: { file: file ? { ...file } : null, fileList: this.getFileList() }
-      })
-    )
-
+    this.dispatch("success", {
+      detail: { file: file ? { ...file } : null, fileList: this.getFileList() }
+    })
 
     if (window.HakumiComponents?.renderComponent && file?.name) {
       window.HakumiComponents.renderComponent("message", {
@@ -781,13 +771,9 @@ export default class extends RegistryController {
   }
 
   dispatchError(file, error) {
-    this.element.dispatchEvent(
-      new CustomEvent("hakumi:upload:error", {
-        bubbles: true,
-        detail: { file: file ? { ...file } : null, fileList: this.getFileList(), error }
-      })
-    )
-
+    this.dispatch("error", {
+      detail: { file: file ? { ...file } : null, fileList: this.getFileList(), error }
+    })
 
     if (window.HakumiComponents?.renderComponent) {
       const errorMsg = error || file?.error || "Upload failed"

data/app/javascript/hakumi_components/core/persistence.js

@@ -21,7 +21,7 @@ const json = {
     },
 }
 
-// --- navegación (Turbo + fallbacks), bind único global al módulo ---
+// Navigation events (Turbo + fallbacks), single global binding per module
 let navBound = false
 const navCallbacks = new Set()
 
@@ -51,7 +51,7 @@ const bindNavigationOnce = () => {
     window.addEventListener("hashchange", scheduleNavCallbacks)
 }
 
-// ✅ Dedupe por key: evita múltiples restores activos si mount() corre más de una vez
+// Dedupe by key: prevents multiple active restores if mount() runs more than once
 const bootstrapsByKey = new Map() // key -> unsubscribe
 
 export const Persistence = {
@@ -80,7 +80,7 @@ export const Persistence = {
             throw new Error("[HakumiComponents] Persistence.bootstrap(key, fn) expects a function")
         }
 
-        // ✅ dedupe
+        // Dedupe: return existing unsubscribe if already bootstrapped
         const existing = bootstrapsByKey.get(key)
         if (existing) return existing
 

data/app/javascript/hakumi_components/core/render_component.js

@@ -149,7 +149,9 @@ export const renderComponent = async (
                 element.remove()
                 unregister(id)
             }
-            element.addEventListener("hakumi-component:hidden", handleHidden, { once: true })
+            // Listen for component-specific hidden event (e.g., hakumi--modal:hidden)
+            const controllerName = name.replace(/_/g, "-")
+            element.addEventListener(`hakumi--${controllerName}:hidden`, handleHidden, { once: true })
         }
 
         await nextFrame()

data/app/javascript/lib/validation_manager.js

@@ -106,6 +106,107 @@ export default class ValidationManager {
                 }
             },
 
+            comparison: (value, rule, formData = {}) => {
+                if (value === null || value === undefined || value === '') return { valid: true }
+
+                const config = rule.value || rule.comparison || {}
+                const operator = config.operator
+                if (!operator) return { valid: true }
+
+                let targetValue
+                if (config.field) {
+                    targetValue = formData[config.field]
+                } else if (config.value !== undefined) {
+                    targetValue = config.value
+                } else {
+                    return { valid: true }
+                }
+
+                if (targetValue === null || targetValue === undefined || targetValue === '') {
+                    return { valid: true }
+                }
+
+                const normalize = (raw) => {
+                    if (raw instanceof Date) {
+                        return { type: 'date', value: raw.getTime() }
+                    }
+
+                    if (typeof raw === 'number') {
+                        return { type: 'number', value: raw }
+                    }
+
+                    const text = String(raw).trim()
+                    if (text === '') return { type: 'empty', value: text }
+
+                    const numeric = Number(text)
+                    if (!Number.isNaN(numeric) && /^-?\d+(\.\d+)?$/.test(text)) {
+                        return { type: 'number', value: numeric }
+                    }
+
+                    const parsedDate = Date.parse(text)
+                    if (!Number.isNaN(parsedDate) && /[-/T:]/.test(text)) {
+                        return { type: 'date', value: parsedDate }
+                    }
+
+                    return { type: 'string', value: text }
+                }
+
+                const left = normalize(value)
+                const right = normalize(targetValue)
+
+                if (left.type === 'empty' || right.type === 'empty') return { valid: true }
+
+                const compareValues = (a, b) => {
+                    if (a.type === 'number' && b.type === 'number') {
+                        return a.value === b.value ? 0 : (a.value > b.value ? 1 : -1)
+                    }
+
+                    if (a.type === 'date' && b.type === 'date') {
+                        return a.value === b.value ? 0 : (a.value > b.value ? 1 : -1)
+                    }
+
+                    if (a.value === b.value) return 0
+                    return a.value > b.value ? 1 : -1
+                }
+
+                const result = compareValues(left, right)
+                let valid
+
+                switch (operator) {
+                    case 'greater_than':
+                        valid = result > 0
+                        break
+                    case 'greater_than_or_equal_to':
+                        valid = result >= 0
+                        break
+                    case 'less_than':
+                        valid = result < 0
+                        break
+                    case 'less_than_or_equal_to':
+                        valid = result <= 0
+                        break
+                    case 'equal_to':
+                        valid = result === 0
+                        break
+                    case 'other_than':
+                        valid = result !== 0
+                        break
+                    default:
+                        valid = true
+                        break
+                }
+
+                const label = config.label || config.field || config.value
+                const fallbackMessage = label
+                    ? `Must be ${operator.replace(/_/g, ' ')} ${label}`
+                    : 'Comparison failed'
+
+                return {
+                    valid,
+                    message: rule.message || fallbackMessage
+                }
+            },
+
             custom: (value, rule) => {
                 if (typeof rule.validator !== 'function') {
                     console.error('Custom validator must be a function')

data/app/javascript/stylesheets/_theme-tokens.scss

@@ -252,8 +252,9 @@
 
 
 
+// Auto-detect theme from OS preference (opt-in with data-theme="auto")
 @media (prefers-color-scheme: dark) {
-    :root:not([data-theme]) {
+    :root[data-theme="auto"] {
 
         --color-primary: #6366f1;
         --color-primary-hover: #818cf8;

data/app/javascript/stylesheets/components/_modal.scss

@@ -207,4 +207,17 @@
     transform: scale(0.2);
     transition: opacity 0.3s cubic-bezier(0.78, 0.14, 0.15, 0.86),
         transform 0.3s cubic-bezier(0.78, 0.14, 0.15, 0.86);
+}
+
+// Modal Confirm variant
+.hakumi-modal-confirm-body-wrapper {
+    display: flex;
+    align-items: flex-start;
+    gap: 12px;
+}
+
+.hakumi-modal-confirm-content {
+    p {
+        margin: 0;
+    }
 }

data/app/services/{hakumi_components → hakumi}/component_handler.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module HakumiComponents
+module Hakumi
   class ComponentHandler
     def initialize(component, params)
       @component = component.to_sym

data/app/services/hakumi/icon/loader.rb

@@ -4,8 +4,8 @@ module Hakumi
   module Icon
     # Loads Ant Design icons from lib/hakumi_components/app/assets/icons
     class Loader
-      ICONS_BASE_PATH = if defined?(HakumiComponents::Engine)
-        HakumiComponents::Engine.root.join("app", "assets", "icons")
+      ICONS_BASE_PATH = if defined?(Hakumi::Engine)
+        Hakumi::Engine.root.join("app", "assets", "icons")
       else
         Rails.root.join("app", "assets", "icons")
       end

data/app/services/hakumi/illustrations/loader.rb

@@ -4,8 +4,8 @@ module Hakumi
   module Illustrations
     # Loads SVG illustrations stored under lib/hakumi_components/app/assets/illustrations
     class Loader
-      ILLUSTRATIONS_PATH = if defined?(HakumiComponents::Engine)
-        HakumiComponents::Engine.root.join("app", "assets", "illustrations")
+      ILLUSTRATIONS_PATH = if defined?(Hakumi::Engine)
+        Hakumi::Engine.root.join("app", "assets", "illustrations")
       else
         Rails.root.join("lib", "hakumi_components", "app", "assets", "illustrations")
       end
@@ -33,7 +33,7 @@ module Hakumi
           svg = File.read(path)
           svg.respond_to?(:html_safe) ? svg.html_safe : svg
         rescue => e
-          Rails.logger.error("Error loading illustration #{filename}: #{e.message}")
+          ::Rails.logger.error("Error loading illustration #{filename}: #{e.message}")
           nil
         end
       end

data/app/views/hakumi/_drawer.html.erb

@@ -0,0 +1,21 @@
+<%= render Hakumi::Drawer::Component.new(
+  id: local_assigns[:id],
+  open: local_assigns[:open],
+  placement: local_assigns[:placement] || :right,
+  size: local_assigns[:size] || :default,
+  width: local_assigns[:width],
+  height: local_assigns[:height],
+  closable: local_assigns.fetch(:closable, true),
+  mask: local_assigns.fetch(:mask, true),
+  mask_closable: local_assigns.fetch(:mask_closable, true),
+  keyboard: local_assigns.fetch(:keyboard, true),
+  destroy_on_close: local_assigns.fetch(:destroy_on_close, false)
+) do |drawer| %>
+  <% if local_assigns[:title].present? %>
+    <% drawer.with_header { local_assigns[:title] } %>
+  <% end %>
+
+  <% if local_assigns[:message].present? %>
+    <p><%= local_assigns[:message] %></p>
+  <% end %>
+<% end %>

data/app/views/hakumi/_modal.html.erb

@@ -0,0 +1,18 @@
+<%
+  # Extract modal-specific params (title, message) from locals
+  title = local_assigns[:title]
+  message = local_assigns[:message]
+
+  # Pass remaining params to Modal::Component
+  component_params = local_assigns.except(:title, :message).compact
+%>
+
+<%= render(Hakumi::Modal::Component.new(**component_params)) do |modal| %>
+  <% if title.present? %>
+    <% modal.with_header { title } %>
+  <% end %>
+
+  <% if message.present? %>
+    <p><%= message %></p>
+  <% end %>
+<% end %>

data/lib/hakumi_components/documentation.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Hakumi
+  # Provides access to component documentation and examples.
+  # Documentation lives in app/components/hakumi/[component]/docs/ and includes:
+  # - meta.yml: Component metadata, API documentation, and example definitions
+  # - examples/*.erb: Example partials that demonstrate component usage
+  #
+  # NOTE: Documentation files are NOT included in the published gem.
+  # This module is primarily useful for:
+  # - Development playgrounds
+  # - Documentation generators
+  # - IDE tooling
+  #
+  # @example List all documented components
+  #   Hakumi::Documentation.components
+  #   # => ["button", "alert", "modal", ...]
+  #
+  # @example Get component metadata
+  #   Hakumi::Documentation.metadata("button")
+  #   # => { "name" => "Button", "description" => "...", "api" => [...] }
+  #
+  # @example Get example content
+  #   Hakumi::Documentation.example("button", "basic_types")
+  #   # => "<%= render(Hakumi::Button::Component.new..."
+  #
+  module Documentation
+    class << self
+      # Root path for component files
+      # @return [Pathname]
+      def components_root
+        @components_root ||= Pathname.new(File.expand_path("../../app/components/hakumi", __dir__.to_s))
+      end
+
+      # List all components that have documentation
+      # @return [Array<String>] component names
+      def components
+        return [] unless components_root.exist?
+
+        components_root.children
+          .select { |path| path.directory? && (path / "docs" / "meta.yml").exist? }
+          .map { |path| path.basename.to_s }
+          .sort
+      end
+
+      # Get metadata for a component
+      # @param component_name [String] the component name (e.g., "button")
+      # @return [Hash, nil] parsed meta.yml content or nil if not found
+      def metadata(component_name)
+        meta_path = meta_path_for(component_name)
+        return nil unless meta_path.exist?
+
+        YAML.load_file(meta_path)
+      end
+
+      # Get list of examples for a component
+      # @param component_name [String] the component name
+      # @return [Array<Hash>] example definitions from meta.yml
+      def examples(component_name)
+        meta = metadata(component_name)
+        return [] unless meta
+
+        meta["examples"] || []
+      end
+
+      # Get the content of an example partial
+      # @param component_name [String] the component name
+      # @param example_name [String] the example name (without underscore or extension)
+      # @return [String, nil] the example ERB content or nil if not found
+      def example(component_name, example_name)
+        example_path = example_path_for(component_name, example_name)
+        return nil unless example_path
+
+        example_path.read
+      end
+
+      # Get the path to an example partial (for rendering in Rails)
+      # @param component_name [String] the component name
+      # @param example_name [String] the example name
+      # @return [Pathname, nil] the path to the example file or nil if not found
+      def example_path_for(component_name, example_name)
+        path = components_root / component_name / "docs" / "examples" / "_#{example_name}.html.erb"
+        path.exist? ? path : nil
+      end
+
+      # Get the API documentation for a component
+      # @param component_name [String] the component name
+      # @return [Array<Hash>] API property definitions
+      def api(component_name)
+        meta = metadata(component_name)
+        return [] unless meta
+
+        meta["api"] || []
+      end
+
+      # Get all documentation as a hash (useful for JSON export)
+      # @return [Hash] all component documentation
+      def all
+        result = Hash.new
+        components.each do |name|
+          result[name] = {
+            metadata: metadata(name),
+            examples: examples(name).map do |ex|
+              ex.merge("content" => example(name, ex["name"]))
+            end
+          }
+        end
+        result
+      end
+
+      # Export all documentation to JSON
+      # @return [String] JSON representation
+      def to_json(*_args)
+        require "json"
+        JSON.pretty_generate(all)
+      end
+
+      private
+
+      def meta_path_for(component_name)
+        components_root / component_name / "docs" / "meta.yml"
+      end
+    end
+  end
+end

data/lib/hakumi_components/engine.rb

@@ -2,9 +2,9 @@
 
 require "pathname"
 
-module HakumiComponents
+module Hakumi
   class Engine < ::Rails::Engine
-    isolate_namespace HakumiComponents
+    isolate_namespace Hakumi
 
     root = Pathname.new(File.expand_path("../..", __dir__ || "."))
     config.root = root
@@ -15,14 +15,23 @@ module HakumiComponents
     config.autoload_paths << root.join("app/form_builders")
     config.eager_load_paths << root.join("app/form_builders")
 
-    initializer "hakumi_components.assets" do |app|
+    config.autoload_paths << root.join("app/helpers")
+    config.eager_load_paths << root.join("app/helpers")
+
+    initializer "hakumi.helpers" do
+      ActiveSupport.on_load(:action_view) do
+        include Hakumi::FormHelper
+      end
+    end
+
+    initializer "hakumi.assets" do |app|
       # Only add assets path if Sprockets is available (Rails < 8 or when explicitly added)
       if app.config.respond_to?(:assets)
         app.config.assets.paths << root.join("app/assets")
       end
     end
 
-    initializer "hakumi_components.views" do |app|
+    initializer "hakumi.views" do |app|
       app.config.paths["app/views"] << root.join("app/views")
     end
   end

data/lib/hakumi_components/rails/attribute_introspection.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module HakumiComponents
+module Hakumi
   module Rails
     # Introspects ActiveRecord schema and I18n translations to automatically
     # configure form field labels, placeholders, and hints