kiso 0.5.2.pre → 0.6.0.pre

data/app/helpers/kiso/icon_helper.rb

@@ -3,13 +3,36 @@
 require "tailwind_merge"
 
 module Kiso
-  # View helpers for rendering inline SVG icons.
+  # View helpers for rendering inline SVG icons with Tailwind classes.
   #
-  # Included in all views automatically by {Engine}.
-  # Delegates to +kiso_icon_tag+ (provided by the kiso-icons gem) for
-  # actual SVG rendering.
+  # Provides two public methods:
+  #
+  # - {#kiso_icon} -- renders any icon by name. Used in application code
+  #   and templates when the caller knows the exact icon they want.
+  # - {#kiso_component_icon} -- renders a semantic/configurable icon. Used
+  #   inside Kiso component partials for default icons (close button X,
+  #   separator chevrons, pagination arrows) so host apps can swap them
+  #   globally via {Kiso::Configuration#icons}.
+  #
+  # Both methods delegate to +kiso_icon_tag+ (provided by the kiso-icons
+  # gem) for actual SVG rendering. Classes are deduplicated and resolved
+  # via +TailwindMerge::Merger+.
+  #
+  # == Icon sizing
+  #
+  # By default, icons render without an explicit size class. This allows
+  # parent components (Button, Alert, Badge, etc.) to control icon sizing
+  # via CSS selectors like +[&_svg]:size-4+. Pass an explicit +size:+
+  # preset for standalone icons outside of components.
+  #
+  # Included in all views automatically by {Kiso::Engine}.
+  #
+  # @see Kiso::Configuration#icons  the global icon name registry
   module IconHelper
-    # @return [Hash{Symbol => String}] maps size presets to Tailwind size utilities
+    # Maps size preset symbols to Tailwind size utility classes.
+    # These follow Kiso's spatial scale for icon sizing.
+    #
+    # @return [Hash{Symbol => String}]
     SIZE_PRESETS = {
       xs: "size-3",
       sm: "size-4",
@@ -18,23 +41,39 @@ module Kiso
       xl: "size-8"
     }.freeze
 
-    # @return [String] base Tailwind classes applied to every icon
+    # Base Tailwind classes applied to every icon. +shrink-0+ prevents
+    # icons from collapsing in flex containers.
+    #
+    # @return [String]
     BASE_CLASSES = "shrink-0"
 
-    # Renders a configurable component icon.
+    # Renders a configurable component icon by semantic name.
+    #
+    # Component partials call this instead of {#kiso_icon} when the icon
+    # should be overridable by host apps. The semantic name is resolved to
+    # an actual icon identifier via {Kiso::Configuration#icons}, which host
+    # apps can customize in an initializer.
     #
-    # Components call this instead of {#kiso_icon} when the icon name should
-    # be overridable by host apps via {Configuration#icons Kiso.config.icons}.
+    # @param semantic_name [Symbol] a key from the icon registry
+    #   (e.g. +:chevron_right+, +:check+, +:x+, +:spinner+). See
+    #   {Kiso::Configuration} for the full list of registered names.
+    # @param options [Hash] forwarded to {#kiso_icon} (e.g. +size:+,
+    #   +class:+, +aria:+).
+    # @return [ActiveSupport::SafeBuffer] rendered inline SVG
+    # @raise [KeyError] if +semantic_name+ is not registered in
+    #   {Kiso::Configuration#icons}
     #
-    # @param semantic_name [Symbol] a key from {Configuration#icons}
-    #   (e.g. +:chevron_right+, +:check+, +:x+)
-    # @param options [Hash] forwarded to {#kiso_icon}
-    # @return [ActiveSupport::SafeBuffer] rendered SVG
-    # @raise [KeyError] if +semantic_name+ is not registered
+    # @example In a component partial (separator chevron)
+    #   <%= kiso_component_icon(:chevron_right, class: "size-3.5") %>
     #
-    # @example
-    #   kiso_component_icon(:chevron_right, class: "size-3.5")
-    #   kiso_component_icon(:ellipsis, size: :sm)
+    # @example In a component partial (dropdown indicator)
+    #   <%= kiso_component_icon(:chevron_down, size: :sm) %>
+    #
+    # @example Host app overrides the icon globally
+    #   # config/initializers/kiso.rb
+    #   Kiso.configure do |config|
+    #     config.icons[:chevron_right] = "heroicons:chevron-right"
+    #   end
     def kiso_component_icon(semantic_name, **)
       icon_name = Kiso.config.icons.fetch(semantic_name) {
         raise KeyError, "Unknown Kiso icon: #{semantic_name.inspect}. " \
@@ -45,26 +84,41 @@ module Kiso
 
     # Renders an inline SVG icon with Tailwind classes.
     #
-    # Size defaults to +nil+ so parent components (Button, Alert, Badge) can
-    # control icon sizing via CSS selectors like +[&_svg]:size-4+.
-    # Pass an explicit +size:+ for standalone icons outside components.
+    # This is the general-purpose icon helper for use in application
+    # templates and views. Inside Kiso component partials, prefer
+    # {#kiso_component_icon} for default icons so they remain configurable.
+    #
+    # The +size:+ parameter defaults to +nil+ so parent components (Button,
+    # Alert, Badge) can control icon sizing via CSS selectors like
+    # +[&_svg]:size-4+. Pass an explicit +size:+ only for standalone icons
+    # rendered outside of a Kiso component.
     #
-    # @param name [String] icon identifier, optionally prefixed with set
-    #   (e.g. +"check"+, +"lucide:check"+)
+    # @param name [String] icon identifier, optionally prefixed with the
+    #   icon set name separated by a colon (e.g. +"check"+,
+    #   +"lucide:check"+, +"heroicons:arrow-right"+). Without a prefix,
+    #   the default icon set is used.
     # @param size [Symbol, nil] size preset from {SIZE_PRESETS}
-    #   (+:xs+, +:sm+, +:md+, +:lg+, +:xl+)
-    # @param options [Hash] forwarded to +kiso_icon_tag+
-    #   (e.g. +class:+, +aria:+, +data:+)
-    # @return [ActiveSupport::SafeBuffer] rendered SVG
-    #
-    # @example Basic usage
-    #   kiso_icon("check")
-    # @example With size preset
-    #   kiso_icon("check", size: :md)
-    # @example With extra classes
-    #   kiso_icon("check", class: "text-success")
-    # @example Accessible icon
-    #   kiso_icon("check", aria: { label: "Done" })
+    #   (+:xs+ = 12px, +:sm+ = 16px, +:md+ = 20px, +:lg+ = 24px,
+    #   +:xl+ = 32px). Pass +nil+ (default) to let the parent component
+    #   control sizing.
+    # @param options [Hash] forwarded to +kiso_icon_tag+ from the
+    #   kiso-icons gem (e.g. +class:+, +aria:+, +data:+, +title:+).
+    # @return [ActiveSupport::SafeBuffer] rendered inline SVG element
+    #
+    # @example Basic usage in a template
+    #   <%= kiso_icon("check") %>
+    #
+    # @example With a size preset
+    #   <%= kiso_icon("arrow-right", size: :md) %>
+    #
+    # @example With extra Tailwind classes
+    #   <%= kiso_icon("check", class: "text-success") %>
+    #
+    # @example With accessibility label
+    #   <%= kiso_icon("check", aria: { label: "Done" }) %>
+    #
+    # @example From a specific icon set
+    #   <%= kiso_icon("heroicons:check-circle", size: :lg) %>
     def kiso_icon(name, size: nil, **options)
       css_classes = options.delete(:class) || ""
       size_class = size ? SIZE_PRESETS.fetch(size) : nil
@@ -75,16 +129,24 @@ module Kiso
 
     private
 
-    # Merges icon class parts via TailwindMerge, filtering out blanks.
+    # Merges icon class parts via +TailwindMerge+, filtering out blanks.
     #
-    # @param parts [Array<String, nil>] class strings to merge
-    # @return [String] deduplicated class string
+    # When multiple parts specify conflicting Tailwind utilities (e.g.
+    # +size-4+ from a preset and +size-6+ from a caller), the last one
+    # wins -- the same behavior as +tailwind_merge+ in theme rendering.
+    #
+    # @param parts [Array<String, nil>] class strings to merge. +nil+ and
+    #   empty values are filtered out before joining.
+    # @return [String] deduplicated, conflict-resolved class string
     def merge_icon_classes(*parts)
       combined = parts.reject { |p| p.nil? || p.to_s.empty? }.join(" ")
       icon_class_merger.merge(combined)
     end
 
-    # @return [TailwindMerge::Merger] memoized merger instance
+    # Returns a memoized +TailwindMerge::Merger+ instance for icon class
+    # deduplication. Memoized on the view context instance (per-request).
+    #
+    # @return [TailwindMerge::Merger]
     def icon_class_merger
       @icon_class_merger ||= TailwindMerge::Merger.new
     end

data/app/helpers/kiso/theme_helper.rb

@@ -1,10 +1,35 @@
 # frozen_string_literal: true
 
 module Kiso
-  # View helper for dark mode FOUC prevention.
+  # View helper for dark mode FOUC (Flash of Unstyled Content) prevention.
   #
-  # Included in all views automatically by {Engine}.
+  # Provides {#kiso_theme_script}, which outputs a tiny inline +<script>+
+  # that synchronously applies the +.dark+ class to +<html>+ before the
+  # browser paints. This eliminates the bright flash that occurs when a
+  # dark-mode user loads a page and the stylesheet hasn't applied yet.
+  #
+  # Kiso's dark mode system uses CSS variable swapping inside a +.dark {}+
+  # block (not Tailwind +dark:+ prefixes), so the +.dark+ class on +<html>+
+  # is the single toggle that activates the entire dark palette.
+  #
+  # == Theme resolution order
+  #
+  # 1. +localStorage.getItem("theme")+ -- fastest, set by the Stimulus
+  #    +kiso--theme+ controller on toggle.
+  # 2. Cookie named +"theme"+ -- fallback for server-side rendering
+  #    scenarios. Also set by the Stimulus controller.
+  # 3. +matchMedia("(prefers-color-scheme: dark)")+ -- OS-level preference
+  #    when no explicit choice has been stored.
+  #
+  # Included in all views automatically by {Kiso::Engine}.
+  #
+  # @see file:app/javascript/controllers/kiso/theme_controller.js
+  #   the Stimulus controller that handles toggling and persistence
   module ThemeHelper
+    # Minified inline JavaScript that reads the user's theme preference and
+    # sets +.dark+ on +<html>+ synchronously. Frozen to prevent mutation.
+    #
+    # @return [String] minified JavaScript source
     THEME_SCRIPT = <<~JS.squish.freeze
       (function(){
         var k="theme";
@@ -16,21 +41,37 @@ module Kiso
       })()
     JS
 
-    # Outputs an inline script that prevents dark mode FOUC.
+    # Outputs a blocking inline +<script>+ that prevents dark mode FOUC.
     #
-    # Reads the theme preference from localStorage (primary) or cookie
-    # (fallback), respects +prefers-color-scheme+ as default, and sets
-    # +.dark+ on +<html>+ synchronously before first paint.
+    # The script runs synchronously in +<head>+ before stylesheets load,
+    # reading the user's stored theme preference and applying +.dark+ to
+    # +<html>+ if appropriate. This ensures the first paint uses the correct
+    # color scheme.
     #
-    # Call in +<head>+, ideally before stylesheet links.
+    # The script tag is rendered with +nonce: true+ for Content Security
+    # Policy (CSP) compatibility. Rails automatically sets the nonce from
+    # +content_security_policy_nonce+.
     #
-    # @example In a layout
+    # @note Place this call in +<head>+ *before* stylesheet links. The
+    #   script must execute before the browser encounters CSS that uses
+    #   the +.dark+ selector, otherwise the first paint will flash.
+    #
+    # @return [ActiveSupport::SafeBuffer] an HTML +<script>+ tag
+    #
+    # @example Minimal layout setup
     #   <head>
     #     <%= kiso_theme_script %>
     #     <%= stylesheet_link_tag "tailwind" %>
     #   </head>
     #
-    # @return [ActiveSupport::SafeBuffer]
+    # @example With Turbo and other head elements
+    #   <head>
+    #     <meta charset="utf-8">
+    #     <%= csrf_meta_tags %>
+    #     <%= kiso_theme_script %>
+    #     <%= stylesheet_link_tag "tailwind" %>
+    #     <%= javascript_importmap_tags %>
+    #   </head>
     def kiso_theme_script
       javascript_tag(THEME_SCRIPT, nonce: true)
     end

data/app/helpers/kiso/ui_context_helper.rb

@@ -1,106 +1,158 @@
 # frozen_string_literal: true
 
 module Kiso
-  # Manages request-scoped context stacks for component communication.
+  # Manages request-scoped context stacks for parent-to-sub-part
+  # communication in composed Kiso components.
   #
-  # This is ERB's equivalent of Vue's provide/inject pattern. Two stacks:
+  # This is ERB's equivalent of Vue's provide/inject or React's context
+  # pattern. It enables parent components to share data with their sub-parts
+  # without the caller having to thread locals through every nested call.
   #
-  # - **ui:** — per-slot CSS class overrides. When a parent component is
-  #   rendered with +ui:+, the hash is pushed onto a stack. Sub-parts read
-  #   their slot override automatically.
-  # - **scope:** — domain locals shared from parent to sub-parts. When a
-  #   parent is rendered with +scope:+, the hash is pushed onto a stack.
-  #   Sub-parts receive scope values as kwargs, with explicit kwargs
-  #   taking priority. One level deep only — no ancestor resolution.
+  # == Two independent stacks
   #
-  # Thread-safe because Rails creates a fresh view context (and therefore
-  # fresh instance variables) per request.
+  # - **ui** -- per-slot CSS class overrides. When a parent component is
+  #   rendered with +ui:+, the hash is pushed onto a stack keyed by
+  #   component name. Sub-parts read their slot override from the top of
+  #   the stack automatically (handled by {ComponentHelper#kiso_render_component}).
   #
-  # @example ui: stack flow
-  #   # Parent pushes:
+  # - **scope** -- domain locals shared from parent to sub-parts. When a
+  #   parent is rendered with +scope:+, the hash is pushed onto its own
+  #   stack. Sub-parts receive scope values as kwargs, with explicit kwargs
+  #   taking priority. One level deep only -- no ancestor resolution.
+  #
+  # == Thread safety
+  #
+  # Thread-safe because Rails creates a fresh +ActionView::Base+ instance
+  # (and therefore fresh +@kiso_ui_stack+ / +@kiso_scope_stack+ instance
+  # variables) for every request. No shared mutable state exists across
+  # requests.
+  #
+  # == Stack vs simple hash
+  #
+  # A stack (not a simple hash) is necessary because the same component
+  # type can be nested. For example, a Card inside a Card must each
+  # maintain their own +ui:+ context independently. Push/pop ensures the
+  # inner Card's overrides don't leak to the outer Card's sub-parts.
+  #
+  # @note You should not call these methods directly in application code.
+  #   They are used internally by {ComponentHelper#kui} and
+  #   {AppComponentHelper#appui}. The public API for passing context is
+  #   the +ui:+ and +scope:+ keyword arguments on those helpers.
+  #
+  # @example ui: context flow (internal)
+  #   # Parent pushes when rendering:
   #   kiso_push_ui_context(:card, { header: "p-8", title: "text-xl" })
   #
-  #   # Sub-part reads:
-  #   kiso_current_ui(:card)  #=> { header: "p-8", title: "text-xl" }
+  #   # Sub-part reads its slot override:
+  #   kiso_current_ui(:card)[:header]  #=> "p-8"
   #
-  #   # After parent renders:
+  #   # After parent finishes rendering (in ensure block):
   #   kiso_pop_ui_context(:card)
   #
-  # @example scope: stack flow
-  #   # Parent pushes:
+  # @example scope: context flow (internal)
+  #   # Parent pushes when rendering:
   #   kiso_push_scope(:room_card, { room: room })
   #
   #   # Sub-part reads (merged into kwargs before render):
   #   kiso_current_scope(:room_card)  #=> { room: room }
   #
-  #   # After parent renders:
+  #   # After parent finishes rendering (in ensure block):
   #   kiso_pop_scope(:room_card)
   #
-  # @see ComponentHelper#kui
+  # @see ComponentHelper#kui  the public API that drives these stacks
+  # @see AppComponentHelper#appui  the host app equivalent
   module UiContextHelper
-    # Push a ui hash onto the context stack for a component.
+    # Pushes a +ui:+ hash onto the context stack for a component.
+    #
+    # Called by {ComponentHelper#kiso_render_component} when a parent
+    # component is rendered with +ui:+ overrides.
     #
-    # @param component [Symbol] the component name (e.g. +:card+)
+    # @param component [Symbol] the component name (e.g. +:card+, +:alert+)
     # @param ui [Hash{Symbol => String}] slot-name to class-string mapping
+    #   (e.g. +{ header: "p-8", title: "text-xl" }+)
     # @return [void]
     def kiso_push_ui_context(component, ui)
       kiso_ui_stack[component] ||= []
       kiso_ui_stack[component].push(ui || {})
     end
 
-    # Pop the most recent ui hash for a component.
+    # Pops the most recent +ui:+ hash for a component.
+    #
+    # Called in the +ensure+ block of {ComponentHelper#kiso_render_component}
+    # after the parent component finishes rendering, guaranteeing cleanup
+    # even if the partial raises an exception.
     #
     # @param component [Symbol] the component name
-    # @return [Hash, nil] the popped ui hash
+    # @return [Hash, nil] the popped ui hash, or +nil+ if the stack was empty
     def kiso_pop_ui_context(component)
       kiso_ui_stack[component]&.pop
     end
 
-    # Read the current ui hash for a component (top of stack).
+    # Reads the current +ui:+ hash for a component (top of stack).
+    #
+    # Called by {ComponentHelper#kiso_render_component} when rendering a
+    # sub-part, to look up the slot override the parent provided.
     #
     # @param component [Symbol] the component name
-    # @return [Hash{Symbol => String}] the current ui overrides, or empty hash
+    # @return [Hash{Symbol => String}] the current ui overrides, or an
+    #   empty hash if no context is active
     def kiso_current_ui(component)
       kiso_ui_stack.dig(component, -1) || {}
     end
 
-    # Push a scope hash onto the context stack for a component.
+    # Pushes a +scope:+ hash onto the context stack for a component.
     #
-    # Scope shares domain locals from a parent component with its sub-parts
-    # so callers don't have to repeat the same locals on every sub-part call.
+    # Scope shares domain locals from a parent component to its sub-parts
+    # so callers don't have to repeat the same locals on every nested
+    # +kui(:component, :part)+ call.
     #
     # @param component [Symbol] the component name (e.g. +:room_card+)
     # @param scope [Hash] domain locals to share with sub-parts
+    #   (e.g. +{ room: @room, booking: @booking }+)
     # @return [void]
     def kiso_push_scope(component, scope)
       kiso_scope_stack[component] ||= []
       kiso_scope_stack[component].push(scope || {})
     end
 
-    # Pop the most recent scope hash for a component.
+    # Pops the most recent +scope:+ hash for a component.
+    #
+    # Called in the +ensure+ block of {ComponentHelper#kiso_render_component}
+    # after the parent component finishes rendering.
     #
     # @param component [Symbol] the component name
-    # @return [Hash, nil] the popped scope hash
+    # @return [Hash, nil] the popped scope hash, or +nil+ if the stack was empty
     def kiso_pop_scope(component)
       kiso_scope_stack[component]&.pop
     end
 
-    # Read the current scope hash for a component (top of stack).
+    # Reads the current +scope:+ hash for a component (top of stack).
+    #
+    # Called by {ComponentHelper#kiso_render_component} when rendering a
+    # sub-part. The returned hash is merged into the sub-part's kwargs,
+    # with explicit kwargs taking priority over scope values.
     #
     # @param component [Symbol] the component name
-    # @return [Hash] the current scope, or empty hash
+    # @return [Hash] the current scope, or an empty hash if no context
+    #   is active
     def kiso_current_scope(component)
       kiso_scope_stack.dig(component, -1) || {}
     end
 
     private
 
-    # @return [Hash{Symbol => Array<Hash>}] per-component ui stacks
+    # Per-component ui context stacks. Each component name maps to an
+    # array of ui hashes, used as a LIFO stack.
+    #
+    # @return [Hash{Symbol => Array<Hash>}]
     def kiso_ui_stack
       @kiso_ui_stack ||= {}
     end
 
-    # @return [Hash{Symbol => Array<Hash>}] per-component scope stacks
+    # Per-component scope context stacks. Each component name maps to an
+    # array of scope hashes, used as a LIFO stack.
+    #
+    # @return [Hash{Symbol => Array<Hash>}]
     def kiso_scope_stack
       @kiso_scope_stack ||= {}
     end

data/app/javascript/controllers/kiso/combobox_controller.js

@@ -604,12 +604,20 @@ export default class extends Controller {
     }
   }
 
-  /** @private */
+  /**
+   * Attaches global listeners for outside-click detection.
+   *
+   * @private
+   */
   _addGlobalListeners() {
     document.addEventListener("click", this._handleOutsideClick, true)
   }
 
-  /** @private */
+  /**
+   * Removes global listeners for outside-click detection.
+   *
+   * @private
+   */
   _removeGlobalListeners() {
     document.removeEventListener("click", this._handleOutsideClick, true)
   }

data/app/javascript/controllers/kiso/command_controller.js

@@ -29,6 +29,8 @@ import { highlightItem, wrapIndex } from "kiso-ui/utils/highlight"
  *
  * @fires kiso--command:select - When an item is selected.
  *   Detail: `{ value: string, item: HTMLElement }`.
+ * @fires command:escape - When Escape is pressed in the input. Bubbles up to
+ *   the parent `kiso--command-dialog` controller for dialog close handling.
  */
 export default class extends Controller {
   static targets = ["input", "list", "empty", "group", "item"]

data/app/javascript/controllers/kiso/command_dialog_controller.js

@@ -4,6 +4,10 @@ import { Controller } from "@hotwired/stimulus"
  * Command dialog controller. Opens with a configurable keyboard shortcut
  * (default: Cmd/Ctrl+K) and closes with Escape. Wraps the native `<dialog>` element.
  *
+ * Listens for a custom `command:escape` event bubbled from the nested
+ * `kiso--command` controller to close the dialog when Escape is pressed
+ * inside the command input.
+ *
  * @example
  *   <dialog data-controller="kiso--command-dialog"
  *           data-kiso--command-dialog-shortcut-value="k"

data/app/javascript/controllers/kiso/dialog_controller.js

@@ -84,7 +84,12 @@ export default class extends Controller {
   }
 
   /**
-   * Responds to Stimulus Value changes for external open/close control.
+   * Stimulus value change callback. Responds to changes to `openValue`
+   * for external open/close control (e.g., via Turbo morphing or
+   * programmatic attribute updates).
+   *
+   * Skipped during initial `connect()` since that method handles the
+   * initial open state directly.
    */
   openValueChanged() {
     // Skip during connect — handled in connect() directly

data/app/javascript/controllers/kiso/dialog_trigger_controller.js

@@ -64,7 +64,7 @@ export default class extends Controller {
    * Finds the dialog element and its Stimulus controller, then
    * calls the provided callback with the controller instance.
    *
-   * @param {function} callback - Receives the dialog controller
+   * @param {function(Controller): void} callback - Receives the kiso--dialog controller instance
    * @private
    */
   _withDialogController(callback) {

data/app/javascript/controllers/kiso/dropdown_menu_controller.js

@@ -2,10 +2,20 @@ import { Controller } from "@hotwired/stimulus"
 import { highlightItem, wrapIndex } from "kiso-ui/utils/highlight"
 import { startPositioning } from "kiso-ui/utils/positioning"
 
-/** @type {WeakMap<HTMLElement, {enterHandler: Function, leaveHandler: Function}>} */
+/**
+ * Tracks mouseenter/mouseleave handlers attached to sub-content elements,
+ * enabling cleanup when sub-menus close.
+ *
+ * @type {WeakMap<HTMLElement, {enterHandler: Function, leaveHandler: Function}>}
+ */
 const _subHandlers = new WeakMap()
 
-/** @type {WeakMap<HTMLElement, Function>} */
+/**
+ * Tracks Floating UI position cleanup functions for sub-content elements.
+ * Each entry is the cleanup function returned by `startPositioning()`.
+ *
+ * @type {WeakMap<HTMLElement, Function>}
+ */
 const _subPositionCleanups = new WeakMap()
 
 /**
@@ -234,7 +244,7 @@ export default class extends Controller {
    * Opens a sub-menu on hover, closing sibling sub-menus first.
    * Cancels any pending close timeout.
    *
-   * @param {Event} event - Mouseenter event from a sub-trigger element
+   * @param {MouseEvent} event - Mouseenter event from a sub-trigger element
    */
   openSubOnHover(event) {
     if (this._closeSubTimeout) {
@@ -670,13 +680,21 @@ export default class extends Controller {
       .forEach((el) => el.removeAttribute("data-highlighted"))
   }
 
-  /** @private */
+  /**
+   * Attaches global listeners for outside-click and keyboard navigation.
+   *
+   * @private
+   */
   _addGlobalListeners() {
     document.addEventListener("click", this._handleOutsideClick, true)
     document.addEventListener("keydown", this._handleKeydown)
   }
 
-  /** @private */
+  /**
+   * Removes global listeners for outside-click and keyboard navigation.
+   *
+   * @private
+   */
   _removeGlobalListeners() {
     document.removeEventListener("click", this._handleOutsideClick, true)
     document.removeEventListener("keydown", this._handleKeydown)

data/app/javascript/controllers/kiso/index.js

@@ -1,3 +1,23 @@
+/**
+ * Kiso UI Stimulus controller registry.
+ *
+ * Exports all Kiso Stimulus controllers and provides a `start()` helper
+ * to register them with a Stimulus application in one call.
+ *
+ * @module controllers/kiso
+ *
+ * @example Using start() to register all controllers at once
+ *   import KisoUi from "kiso-ui"
+ *   import { Application } from "@hotwired/stimulus"
+ *
+ *   const application = Application.start()
+ *   KisoUi.start(application)
+ *
+ * @example Importing individual controllers
+ *   import { KisoDialogController } from "kiso-ui"
+ *   application.register("kiso--dialog", KisoDialogController)
+ */
+
 import KisoAlertController from "./alert_controller.js"
 import KisoComboboxController from "./combobox_controller.js"
 import KisoCommandController from "./command_controller.js"
@@ -16,6 +36,11 @@ import KisoToggleGroupController from "./toggle_group_controller.js"
 import KisoTooltipController from "./tooltip_controller.js"
 
 const KisoUi = {
+  /**
+   * Registers all Kiso Stimulus controllers with the given application.
+   *
+   * @param {import("@hotwired/stimulus").Application} application - The Stimulus application instance
+   */
   start(application) {
     application.register("kiso--alert", KisoAlertController)
     application.register("kiso--combobox", KisoComboboxController)

data/app/javascript/controllers/kiso/input_otp_controller.js

@@ -27,8 +27,8 @@ import { Controller } from "@hotwired/stimulus"
  *
  * @property {HTMLInputElement} inputTarget - The transparent real input element
  * @property {HTMLElement[]} slotTargets - Visual slot div elements
- * @property {Number} lengthValue - Expected OTP code length
- * @property {String} patternValue - Regex pattern for allowed characters (default: digits only)
+ * @property {number} lengthValue - Expected OTP code length (default: 6)
+ * @property {string} patternValue - Regex pattern for allowed characters (default: "\\d", digits only)
  *
  * @fires kiso--input-otp:change - When the OTP value changes.
  *   Detail: `{ value: string }`
@@ -101,7 +101,9 @@ export default class extends Controller {
 
   /**
    * Re-syncs the active slot after keydown events that may change selection
-   * (arrow keys, backspace, delete, home, end).
+   * (arrow keys, backspace, delete, home, end). Uses `requestAnimationFrame`
+   * to wait until the browser has processed the key event and updated
+   * `selectionStart`.
    *
    * @private
    */