kiso 0.5.2.pre → 0.6.0.pre

data/app/helpers/kiso/app_component_helper.rb

@@ -4,52 +4,91 @@ module Kiso
   # View helpers for rendering host app components.
   #
   # Mirrors {ComponentHelper#kui} but resolves partials from
-  # +app/views/components/+ and themes from +AppThemes::+.
-  # No global config layer — host apps own the source directly.
+  # +app/views/components/+ and themes from the +AppThemes::+ namespace
+  # (loaded from +app/themes/<theme_name>/+).
   #
-  # Included in all views automatically by {Engine}.
+  # == Key difference from +kui()+
+  #
+  # +appui()+ does *not* merge global config overrides (Layer 2). Host apps
+  # own their component source directly, so there is no need for a
+  # boot-time override layer. The three layers for +appui()+ are:
+  #
+  # 1. **Theme default** -- the +ClassVariants+ definition in
+  #    +app/themes/<theme_name>/+.
+  # 2. **Instance +ui:+** -- per-render slot overrides.
+  # 3. **Instance +css_classes:+** -- per-render root-element overrides.
+  #
+  # == Generating host app components
+  #
+  # Use the generator to scaffold theme and partial files:
+  #
+  #   bin/rails generate kiso:component pricing_card --sub-parts header body footer
+  #
+  # This creates files in +app/themes/default/+ and +app/views/components/+.
+  #
+  # Included in all views automatically by {Kiso::Engine}.
+  #
+  # @see ComponentHelper#kui  the equivalent helper for engine-shipped components
+  # @see ComponentHelper#kui_tag  the themed +content_tag+ shorthand (aliased as {#appui_tag})
   module AppComponentHelper
     # Renders a host app component partial.
     #
     # Components live in +app/views/components/+. Sub-parts are nested
-    # in a directory matching the parent component name.
+    # in a directory matching the parent component name (e.g.
+    # +components/pricing_card/_header.html.erb+).
     #
-    # @param component [Symbol] the component name (e.g. +:pricing_card+)
-    # @param part [Symbol, nil] optional sub-part name (e.g. +:header+, +:footer+)
-    # @param collection [Array, nil] renders the partial once per item when present
-    # @param ui [Hash{Symbol => String}, nil] per-slot class overrides keyed by sub-part name.
-    #   For parent components, the hash is pushed onto a context stack so sub-parts
-    #   inherit overrides automatically. For self-rendering components, the hash is
-    #   also passed as a local so the partial can apply overrides to internally
-    #   rendered elements.
-    # @param scope [Hash, nil] domain locals shared from parent to sub-parts via context stack.
-    #   Sub-parts receive scope values as kwargs automatically. Explicit kwargs on sub-part
-    #   calls override scope values. One level deep only — no ancestor resolution.
-    # @param kwargs [Hash] locals passed to the partial (e.g. +css_classes:+)
+    # Behaves identically to {ComponentHelper#kui} except:
+    # - Partials resolve from +app/views/components/+ instead of
+    #   +app/views/kiso/components/+.
+    # - Global config +ui:+ overrides are *not* merged (host apps own the
+    #   source and can edit themes directly).
+    #
+    # @param component [Symbol] the component name (e.g. +:pricing_card+).
+    #   Must match a partial at +app/views/components/_<name>.html.erb+.
+    # @param part [Symbol, nil] optional sub-part name (e.g. +:header+,
+    #   +:footer+). Resolves to
+    #   +app/views/components/<component>/_<part>.html.erb+.
+    # @param collection [Array, nil] when present, renders the partial once
+    #   per item using Rails collection rendering.
+    # @param ui [Hash{Symbol => String}, nil] per-slot class overrides keyed
+    #   by sub-part name. Pushed onto the context stack for composed
+    #   sub-parts, and also passed as a +ui:+ local to self-rendering
+    #   partials.
+    # @param scope [Hash, nil] domain locals shared from parent to sub-parts
+    #   via context stack. Sub-parts receive scope values as kwargs
+    #   automatically. Explicit kwargs on sub-part calls override scope
+    #   values. One level deep only -- no ancestor resolution.
+    # @param kwargs [Hash] locals forwarded to the partial (e.g.
+    #   +css_classes:+, +plan:+, +featured:+). Must match the partial's
+    #   strict locals declaration.
     # @yield optional block for component content
-    # @return [ActiveSupport::SafeBuffer] rendered HTML
+    # @return [ActiveSupport::SafeBuffer] rendered HTML string
     #
     # @example Render a pricing card
-    #   appui(:pricing_card) { "Content" }
+    #   <%= appui(:pricing_card, plan: @plan) { "Content" } %>
     #
-    # @example Render a pricing card with sub-parts
-    #   appui(:pricing_card) do
-    #     appui(:pricing_card, :header) { "Header" }
-    #   end
+    # @example Render a pricing card with composed sub-parts
+    #   <%= appui(:pricing_card) do %>
+    #     <%= appui(:pricing_card, :header) { "Pro Plan" } %>
+    #     <%= appui(:pricing_card, :body) do %>
+    #       <p>Everything you need to get started.</p>
+    #     <% end %>
+    #     <%= appui(:pricing_card, :footer) { "Sign up" } %>
+    #   <% end %>
     #
     # @example Render with per-slot overrides
-    #   appui(:pricing_card, ui: { header: "p-8" }) do
-    #     appui(:pricing_card, :header) { "Header" }
-    #   end
+    #   <%= appui(:pricing_card, ui: { header: "p-8 bg-muted" }) do %>
+    #     <%= appui(:pricing_card, :header) { "Enterprise" } %>
+    #   <% end %>
     #
-    # @example Share domain locals with sub-parts
-    #   appui(:room_card, scope: { room: room }) do
-    #     appui(:room_card, :status)
-    #     appui(:room_card, :meta)
-    #   end
+    # @example Share domain locals with sub-parts via scope
+    #   <%= appui(:room_card, scope: { room: room }) do %>
+    #     <%= appui(:room_card, :status) %>
+    #     <%= appui(:room_card, :meta) %>
+    #   <% end %>
     #
     # @example Render a collection
-    #   appui(:pricing_card, collection: @plans)
+    #   <%= appui(:pricing_card, collection: @plans) %>
     def appui(component, part = nil, collection: nil, ui: nil, scope: nil, **kwargs, &block)
       kiso_render_component(
         component, part,
@@ -61,10 +100,20 @@ module Kiso
 
     # Renders a themed HTML element for host app components.
     #
-    # Identical to {ComponentHelper#kui_tag} — provided as a naming
-    # convenience so host app partials use +appui_tag+ alongside +appui()+.
+    # This is an alias for {ComponentHelper#kui_tag}, provided as a naming
+    # convenience so host app partials use +appui_tag+ alongside +appui()+
+    # for visual consistency.
+    #
+    # @see ComponentHelper#kui_tag  for full parameter documentation
     #
-    # @see ComponentHelper#kui_tag
+    # @example In a host app component partial
+    #   <%# app/views/components/_pricing_card.html.erb %>
+    #   <%= appui_tag :div, theme: AppThemes::Default::PricingCard,
+    #       slot: "pricing-card", css_classes: css_classes,
+    #       variants: { featured: featured },
+    #       **component_options do %>
+    #     <%= yield %>
+    #   <% end %>
     def appui_tag(...)
       kui_tag(...)
     end

data/app/helpers/kiso/component_helper.rb

@@ -1,48 +1,111 @@
+# frozen_string_literal: true
+
 module Kiso
-  # View helpers for rendering Kiso components.
+  # View helpers for rendering Kiso UI components in ERB templates.
+  #
+  # This module is the primary public API for the Kiso component library.
+  # It provides {#kui} for rendering engine-shipped components,
+  # {#kiso_prepare_options} for building +data-slot+ attributes in partials,
+  # and {#kui_tag} for collapsing the common +content_tag+ boilerplate.
+  #
+  # Included in all views automatically by {Kiso::Engine}.
+  #
+  # == Override layers
   #
-  # Included in all views automatically by {Engine}.
+  # Kiso resolves Tailwind classes through four layers (lowest to highest
+  # priority):
+  #
+  # 1. **Theme default** -- the +ClassVariants+ definition in
+  #    +lib/kiso/themes/+.
+  # 2. **Global config** -- +Kiso.configure { |c| c.theme[:button] = ... }+,
+  #    applied once at boot via +ClassVariants::Instance#merge+.
+  # 3. **Instance +ui:+** -- per-render slot overrides passed to +kui()+.
+  # 4. **Instance +css_classes:+** -- per-render root-element overrides,
+  #    merged via +tailwind_merge+ at render time.
+  #
+  # @see AppComponentHelper#appui  the equivalent helper for host app components
+  # @see UiContextHelper  the request-scoped context stack that powers +ui:+
+  # @see Kiso::Configuration  global theme and icon configuration
   module ComponentHelper
     # Renders a Kiso component partial.
     #
+    # This is the main entry point for rendering any Kiso UI component.
     # Components live in +app/views/kiso/components/+. Sub-parts are nested
-    # in a directory matching the parent component name.
-    #
-    # @param component [Symbol] the component name (e.g. +:badge+, +:card+)
-    # @param part [Symbol, nil] optional sub-part name (e.g. +:header+, +:footer+)
-    # @param collection [Array, nil] renders the partial once per item when present
-    # @param ui [Hash{Symbol => String}, nil] per-slot class overrides keyed by sub-part name.
-    #   For parent components, the hash is pushed onto a context stack so sub-parts
-    #   inherit overrides automatically. For self-rendering components, the hash is
-    #   also passed as a local so the partial can apply overrides to internally
-    #   rendered elements.
-    # @param scope [Hash, nil] domain locals shared from parent to sub-parts via context stack.
-    #   Sub-parts receive scope values as kwargs automatically. Explicit kwargs on sub-part
-    #   calls override scope values. One level deep only — no ancestor resolution.
-    # @param kwargs [Hash] locals passed to the partial (e.g. +color:+, +variant:+, +css_classes:+)
-    # @yield optional block for component content
-    # @return [ActiveSupport::SafeBuffer] rendered HTML
+    # in a directory matching the parent component name (e.g.
+    # +card/_header.html.erb+).
     #
-    # @example Render a badge
-    #   kui(:badge, color: :success, variant: :soft) { "Active" }
+    # Internally wraps Rails +render+ with Kiso-specific behavior:
+    # - Injects an empty +proc+ when no block is given, preventing +yield+
+    #   from bubbling up the ERB rendering chain (see implementation notes)
+    # - Pushes +ui:+ and +scope:+ onto request-scoped context stacks so
+    #   sub-parts inherit them automatically
+    # - Merges global config +ui:+ overrides (Layer 2) with instance +ui:+
+    #   (Layer 3)
+    #
+    # @param component [Symbol] the component name (e.g. +:badge+, +:card+,
+    #   +:button+). Must match a partial at
+    #   +app/views/kiso/components/_<name>.html.erb+.
+    # @param part [Symbol, nil] optional sub-part name (e.g. +:header+,
+    #   +:footer+, +:title+). Resolves to
+    #   +app/views/kiso/components/<component>/_<part>.html.erb+.
+    # @param collection [Array, nil] when present, renders the partial once
+    #   per item using Rails collection rendering.
+    # @param ui [Hash{Symbol => String}, nil] per-slot class overrides keyed
+    #   by sub-part name. For parent components, the hash is pushed onto a
+    #   context stack so composed sub-parts inherit overrides automatically.
+    #   For self-rendering components (Alert, Dialog, Switch, etc.), the
+    #   hash is also passed as a +ui:+ local so the partial can apply
+    #   overrides to internally rendered elements via
+    #   +Kiso::Themes::SubPart.render(class: ui[:slot_name])+.
+    # @param scope [Hash, nil] domain locals shared from parent to sub-parts
+    #   via context stack. Sub-parts receive scope values as kwargs
+    #   automatically. Explicit kwargs on sub-part calls override scope
+    #   values. One level deep only -- no ancestor resolution.
+    # @param kwargs [Hash] locals forwarded to the partial (e.g. +color:+,
+    #   +variant:+, +size:+, +css_classes:+, +icon:+). These must match the
+    #   partial's +strict locals+ declaration.
+    # @yield optional block for component content. When omitted, an empty
+    #   proc is injected so partials can safely use
+    #   +capture { yield }.presence+ for optional block overrides.
+    # @return [ActiveSupport::SafeBuffer] rendered HTML string
+    #
+    # @example Render a simple badge
+    #   <%= kui(:badge, color: :success, variant: :soft) { "Active" } %>
+    #
+    # @example Render a card with composed sub-parts
+    #   <%= kui(:card) do %>
+    #     <%= kui(:card, :header) do %>
+    #       <%= kui(:card, :title) { "Dashboard" } %>
+    #       <%= kui(:card, :description) { "Overview of your projects" } %>
+    #     <% end %>
+    #     <%= kui(:card, :content) do %>
+    #       <p>Card body content here.</p>
+    #     <% end %>
+    #   <% end %>
     #
     # @example Render a card with per-slot overrides
-    #   kui(:card, ui: { header: "p-8", title: "text-xl" }) do
-    #     kui(:card, :header) do
-    #       kui(:card, :title) { "Dashboard" }
-    #     end
-    #   end
+    #   <%= kui(:card, ui: { header: "p-8", title: "text-xl" }) do %>
+    #     <%= kui(:card, :header) do %>
+    #       <%= kui(:card, :title) { "Dashboard" } %>
+    #     <% end %>
+    #   <% end %>
     #
     # @example Render an alert with inner element overrides
-    #   kui(:alert, icon: "info", ui: { close: "opacity-50" })
+    #   <%= kui(:alert, icon: "info", ui: { close: "opacity-50" }) %>
+    #
+    # @example Override root element classes
+    #   <%= kui(:badge, css_classes: "uppercase tracking-wide") { "New" } %>
     #
-    # @example Share domain locals with sub-parts
-    #   kui(:card, scope: { project: @project }) do
-    #     kui(:card, :header) # sub-part receives project: automatically
-    #   end
+    # @example Pass HTML attributes through to the root element
+    #   <%= kui(:button, id: "submit-btn", data: { turbo: false }) { "Submit" } %>
+    #
+    # @example Share domain locals with sub-parts via scope
+    #   <%= kui(:card, scope: { project: @project }) do %>
+    #     <%= kui(:card, :header) %>  <%# receives project: automatically %>
+    #   <% end %>
     #
     # @example Render a collection
-    #   kui(:badge, collection: @tags)
+    #   <%= kui(:badge, collection: @tags) %>
     def kui(component, part = nil, collection: nil, ui: nil, scope: nil, **kwargs, &block)
       kiso_render_component(
         component, part,
@@ -52,55 +115,125 @@ module Kiso
       )
     end
 
-    # Prepares +component_options+ for use with +content_tag+.
+    # Prepares +component_options+ for use with +content_tag+ in component
+    # partials.
     #
-    # Sets +data-slot+ for component identity (shadcn v4 convention) and
-    # merges any additional data attributes. Raises if +class:+ is passed
-    # (use +css_classes:+ instead).
+    # Extracts the caller's +data:+ hash from +component_options+, merges it
+    # with the mandatory +data-slot+ attribute (shadcn v4 convention) and any
+    # additional data attributes (typically Stimulus bindings). Returns the
+    # merged data hash ready for +content_tag+.
     #
-    # @param component_options [Hash] the +**component_options+ splat from the partial.
-    #   Any +data:+ key is extracted and merged with +slot+ and +data_attrs+.
-    # @param slot [String] the +data-slot+ value (kebab-case, e.g. +"card-header"+)
-    # @param data_attrs [Hash] additional data attributes (e.g. +controller: "kiso--toggle"+)
-    # @return [Hash] merged data attributes hash for +content_tag+
-    # @raise [ArgumentError] if +component_options+ contains a +class:+ key
+    # This method mutates +component_options+ by deleting the +data:+ key so
+    # it is not double-passed when the partial splats +**component_options+
+    # onto +content_tag+.
     #
-    # @example In a component partial
-    #   data: kiso_prepare_options(component_options, slot: "badge")
+    # @param component_options [Hash] the +**component_options+ splat from
+    #   the partial's strict locals. Callers pass arbitrary HTML attributes
+    #   here (e.g. +id:+, +aria:+, +data:+). The +data:+ key is extracted
+    #   and merged; all other keys pass through to +content_tag+.
+    # @param slot [String] the +data-slot+ value in kebab-case
+    #   (e.g. +"badge"+, +"card-header"+, +"alert-title"+). Every component
+    #   and sub-part must have a unique slot name.
+    # @param data_attrs [Hash] additional data attributes merged into the
+    #   result (e.g. +controller: "kiso--toggle"+, +action: "click->..."+).
+    #   For +action:+ and +controller:+, user and component values are
+    #   concatenated (space-separated) so both Stimulus bindings apply.
+    #   All other keys use standard merge (component wins on conflict).
+    # @return [Hash] merged data attributes hash suitable for the +data:+
+    #   kwarg of +content_tag+.
+    # @raise [ArgumentError] if +component_options+ contains a +class:+ key.
+    #   Kiso uses +css_classes:+ to avoid conflicts with Ruby's +class+
+    #   method and to make the override intent explicit.
+    #
+    # @example Basic usage in a component partial
+    #   <%# _badge.html.erb %>
+    #   <%= content_tag :span,
+    #       class: Kiso::Themes::Badge.render(color: color, class: css_classes),
+    #       data: kiso_prepare_options(component_options, slot: "badge"),
+    #       **component_options do %>
+    #     <%= yield %>
+    #   <% end %>
     #
     # @example With a Stimulus controller
-    #   data: kiso_prepare_options(component_options, slot: "toggle", controller: "kiso--toggle")
+    #   data: kiso_prepare_options(component_options, slot: "toggle",
+    #       controller: "kiso--toggle")
+    #
+    # @example Caller passes data attributes through
+    #   <%# In the view: %>
+    #   <%= kui(:badge, data: { turbo_frame: "results" }) { "Active" } %>
+    #   <%# Inside the partial, kiso_prepare_options merges caller's data
+    #       with { slot: "badge" }, producing:
+    #       { slot: "badge", turbo_frame: "results" } %>
     def kiso_prepare_options(component_options, slot:, **data_attrs)
       if component_options.key?(:class)
         raise ArgumentError, "Use css_classes: instead of class: for Kiso components"
       end
 
-      (component_options.delete(:data) || {}).merge(slot: slot, **data_attrs)
+      user_data = component_options.delete(:data) || {}
+      component_data = {slot: slot, **data_attrs}
+
+      # Stimulus data-action and data-controller are space-separated and
+      # additive — concatenate rather than overwrite so both the component's
+      # and user's bindings apply.
+      CONCATENABLE_DATA_KEYS.each do |key|
+        if user_data.key?(key) && component_data.key?(key)
+          component_data[key] = "#{user_data.delete(key)} #{component_data[key]}"
+        end
+      end
+
+      user_data.merge(component_data)
     end
 
+    # Data attribute keys whose values are space-separated lists in Stimulus.
+    # When both the user and the component provide these, values are
+    # concatenated rather than overwritten.
+    CONCATENABLE_DATA_KEYS = %i[action controller].freeze
+
     # Renders a themed HTML element with Kiso conventions.
     #
-    # Collapses the common +content_tag+ + +kiso_prepare_options+ + theme
-    # rendering boilerplate into a single call. Use in component partials
-    # instead of manually wiring +content_tag+.
+    # A convenience method that collapses the common three-step boilerplate
+    # in component partials:
+    #
+    # 1. +theme.render(**variants, class: css_classes)+ -- compute classes
+    # 2. +kiso_prepare_options(component_options, slot: ...)+ -- build data attrs
+    # 3. +content_tag(tag, class: ..., data: ..., **component_options)+ -- render
+    #
+    # Into a single call. Prefer this over manual +content_tag+ wiring in
+    # component partials for consistency.
     #
     # @param tag [Symbol] HTML element name (e.g. +:div+, +:span+, +:button+)
-    # @param theme [ClassVariants::Instance] the theme module to render classes from
-    # @param slot [String] the +data-slot+ value (kebab-case)
-    # @param css_classes [String] caller's class overrides, merged via +tailwind_merge+
-    # @param variants [Hash] variant values forwarded to +theme.render+
-    #   (e.g. +{ size: :md, color: :primary }+)
-    # @param component_options [Hash] HTML attributes forwarded to +content_tag+
-    #   (e.g. +id:+, +aria:+). A +data:+ key is extracted and merged with slot.
+    # @param theme [ClassVariants::Instance] the theme module to render
+    #   classes from (e.g. +Kiso::Themes::Badge+, +Kiso::Themes::Card+).
+    #   Must respond to +#render(**variants, class:)+.
+    # @param slot [String] the +data-slot+ value in kebab-case
+    #   (e.g. +"badge"+, +"card-header"+).
+    # @param css_classes [String] caller's class overrides, merged via
+    #   +tailwind_merge+ inside the theme's +#render+ method. Defaults to
+    #   an empty string.
+    # @param variants [Hash] variant key-value pairs forwarded to
+    #   +theme.render+ (e.g. +{ size: :md, color: :primary, variant: :soft }+).
+    # @param component_options [Hash] HTML attributes forwarded to
+    #   +content_tag+ (e.g. +id:+, +aria:+, +type:+). A +data:+ key is
+    #   extracted and merged with the slot and any Stimulus bindings.
     # @yield optional block for element content
     # @return [ActiveSupport::SafeBuffer] rendered HTML
     #
     # @example In a component partial
-    #   kui_tag :div, theme: Kiso::Themes::Badge, slot: "badge",
-    #       css_classes: css_classes, variants: { color: color, variant: variant },
-    #       **component_options do
-    #     yield
-    #   end
+    #   <%# _badge.html.erb %>
+    #   <%= kui_tag :span, theme: Kiso::Themes::Badge, slot: "badge",
+    #       css_classes: css_classes,
+    #       variants: { color: color, variant: variant, size: size },
+    #       **component_options do %>
+    #     <%= yield %>
+    #   <% end %>
+    #
+    # @example Button with type attribute
+    #   <%= kui_tag :button, theme: Kiso::Themes::Button, slot: "button",
+    #       css_classes: css_classes,
+    #       variants: { color: color, variant: variant, size: size },
+    #       type: "button", **component_options do %>
+    #     <%= yield %>
+    #   <% end %>
     def kui_tag(tag, theme:, slot:, css_classes: "", variants: {}, **component_options, &block)
       html_options = {
         class: theme.render(**variants, class: css_classes),
@@ -117,15 +250,33 @@ module Kiso
 
     private
 
-    # Shared rendering pipeline for both kui() and appui().
+    # Shared rendering pipeline for both {#kui} and {AppComponentHelper#appui}.
+    #
+    # Handles two distinct code paths:
+    #
+    # - **Parent components** (+part+ is +nil+): merges global and instance
+    #   +ui:+ layers, pushes +ui:+ and +scope:+ onto their respective
+    #   context stacks, renders the partial, then pops the stacks in an
+    #   +ensure+ block.
+    # - **Sub-parts** (+part+ is present): reads the parent's context stacks
+    #   to inherit +ui:+ slot overrides and +scope:+ domain locals, then
+    #   renders the partial with the merged kwargs.
+    #
+    # The empty +proc {}+ guard is critical: without it, partials that call
+    # +capture { yield }.presence+ for optional block overrides would have
+    # their +yield+ bubble through nested +content_tag+ blocks all the way
+    # to the layout's +<%= yield %>+, capturing the entire page template.
     #
     # @param component [Symbol] the component name
     # @param part [Symbol, nil] optional sub-part name
-    # @param path_prefix [String] partial path prefix (e.g. "kiso/components" or "components")
-    # @param collection [Array, nil] renders the partial once per item when present
-    # @param ui [Hash, nil] per-slot class overrides
+    # @param path_prefix [String] partial path prefix
+    #   (+"kiso/components"+ for engine, +"components"+ for host app)
+    # @param collection [Array, nil] renders the partial once per item
+    # @param ui [Hash{Symbol => String}, nil] per-slot class overrides
     # @param scope [Hash, nil] domain locals shared from parent to sub-parts
-    # @param merge_global_ui [Boolean] whether to merge global config ui layer
+    # @param merge_global_ui [Boolean] whether to merge global config ui
+    #   layer. +true+ for {#kui} (engine components have global config),
+    #   +false+ for {AppComponentHelper#appui} (host apps own the source).
     # @param kwargs [Hash] locals passed to the partial
     # @param block [Proc] optional block for component content
     # @return [ActiveSupport::SafeBuffer] rendered HTML
@@ -198,12 +349,18 @@ module Kiso
       end
     end
 
-    # Merge global config ui overrides with instance ui overrides.
-    # Global config is Layer 2, instance +ui:+ is Layer 3.
+    # Merges global config +ui:+ overrides (Layer 2) with per-instance
+    # +ui:+ overrides (Layer 3).
     #
-    # @param component [Symbol] the component name
-    # @param instance_ui [Hash, nil] per-instance ui overrides
-    # @return [Hash{Symbol => String}] merged ui hash
+    # When both layers define the same slot, their class strings are
+    # concatenated (space-separated). Conflicts are resolved later by
+    # +tailwind_merge+ when the sub-part calls +theme.render(class:)+.
+    #
+    # @param component [Symbol] the component name (e.g. +:card+)
+    # @param instance_ui [Hash{Symbol => String}, nil] per-instance ui
+    #   overrides passed to +kui(:card, ui: { ... })+
+    # @return [Hash{Symbol => String}] merged ui hash with all slot
+    #   overrides from both layers
     def kiso_merge_ui_layers(component, instance_ui)
       global_ui = Kiso.config.theme.dig(component, :ui)
       return instance_ui || {} if global_ui.nil? || global_ui.empty?