kiso 0.5.2.pre → 0.6.0.pre

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

@@ -20,7 +20,8 @@ import { startPositioning } from "kiso-ui/utils/positioning"
  *
  * @property {HTMLElement} triggerTarget - Button that opens/closes the popover
  * @property {HTMLElement} contentTarget - The floating panel
- * @property {HTMLElement} [anchorTarget] - Optional alternate positioning reference
+ * @property {HTMLElement} [anchorTarget] - Optional alternate positioning reference element.
+ *   When present, the popover is positioned relative to this element instead of the trigger.
  */
 export default class extends Controller {
   static targets = ["trigger", "content", "anchor"]
@@ -164,7 +165,12 @@ export default class extends Controller {
     }
   }
 
-  /** @private */
+  /**
+   * Maps `data-align` attribute values to Floating UI placement strings.
+   *
+   * @type {Record<string, string>}
+   * @private
+   */
   static _alignToPlacement = {
     start: "bottom-start",
     center: "bottom",
@@ -240,13 +246,21 @@ export default class extends Controller {
     }
   }
 
-  /** @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/select_controller.js

@@ -293,13 +293,21 @@ export default class extends Controller {
     }
   }
 
-  /** @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/sidebar_controller.js

@@ -9,6 +9,9 @@ import { Controller } from "@hotwired/stimulus"
  * boolean attribute and persists the preference to a cookie for
  * FOUC-free server-side restoration on the next page load.
  *
+ * On mobile, the sidebar auto-closes when a nav item link is clicked
+ * so users don't have to manually dismiss it after every navigation.
+ *
  * Register as `kiso--sidebar` (the engine index does this automatically).
  *
  * @example
@@ -35,12 +38,31 @@ import { Controller } from "@hotwired/stimulus"
  *        aria-hidden="true"></div>
  * </div>
  *
- * @property {Element[]} triggerTargets - Toggle/collapse buttons that control the sidebar
- * @property {Element} scrimTarget   - The mobile overlay scrim
+ * @property {HTMLElement[]} triggerTargets - Toggle/collapse buttons that control the sidebar
+ * @property {HTMLElement} scrimTarget - The mobile overlay scrim element
  */
 export default class extends Controller {
   static targets = ["trigger", "scrim"]
 
+  /**
+   * Sets up event delegation for auto-closing the sidebar on mobile
+   * when a nav item link is clicked.
+   */
+  connect() {
+    this._handleNavClick = (event) => {
+      // Matches both: nav-item that IS a link (current Kiso markup: <a data-slot="nav-item">)
+      // and a link nested inside a nav-item (defensive for host app customization)
+      if (event.target.closest('[data-slot="nav-item"][href], [data-slot="nav-item"] a')) {
+        this.closeOnMobile()
+      }
+    }
+    this.element.addEventListener("click", this._handleNavClick)
+  }
+
+  disconnect() {
+    this.element.removeEventListener("click", this._handleNavClick)
+  }
+
   /**
    * Toggles the sidebar open/closed state.
    *
@@ -56,8 +78,8 @@ export default class extends Controller {
   /**
    * Closes the sidebar on mobile viewports only.
    *
-   * Connected to the scrim click event. Tapping the overlay outside
-   * the mobile sidebar dismisses it without affecting desktop layout.
+   * Connected to the scrim click event and nav item click delegation.
+   * Dismisses the sidebar without affecting desktop layout.
    */
   closeOnMobile() {
     if (matchMedia("(max-width: 767px)").matches) {

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

@@ -30,9 +30,9 @@ import { Controller } from "@hotwired/stimulus"
  * @property {HTMLElement} trackTarget - The background track element
  * @property {HTMLElement} rangeTarget - The filled range portion
  * @property {HTMLElement} thumbTarget - The draggable thumb handle
- * @property {Number} minValue - Minimum slider value
- * @property {Number} maxValue - Maximum slider value
- * @property {Number} stepValue - Step increment
+ * @property {number} minValue - Minimum slider value (default: 0)
+ * @property {number} maxValue - Maximum slider value (default: 100)
+ * @property {number} stepValue - Step increment (default: 1)
  *
  * @fires kiso--slider:change - When the slider value changes.
  *   Detail: `{ value: number }`

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

@@ -25,7 +25,8 @@ import { Controller } from "@hotwired/stimulus"
  *   <!-- kui(:select) with light/dark/system items -->
  * </div>
  *
- * @fires kiso:theme-change on document.documentElement when theme changes
+ * @fires kiso:theme-change - Dispatched on `document.documentElement` when the theme changes.
+ *   Detail: `{ theme: "light" | "dark" | "system" }`.
  */
 export default class extends Controller {
   /**

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

@@ -4,6 +4,8 @@ import { Controller } from "@hotwired/stimulus"
  * Manages pressed state for a standalone toggle button.
  * Toggles `data-state` between "on" and "off" and updates `aria-pressed`.
  *
+ * For grouped toggles, use the `kiso--toggle-group` controller instead.
+ *
  * @example
  *   <button data-controller="kiso--toggle"
  *           data-action="click->kiso--toggle#toggle"

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

@@ -77,6 +77,7 @@ export default class extends Controller {
    * Wraps around at boundaries.
    *
    * @param {KeyboardEvent} event
+   * @private
    */
   #handleKeydown = (event) => {
     const items = this.itemTargets.filter((item) => !item.disabled)
@@ -113,6 +114,8 @@ export default class extends Controller {
    * Dispatches a "change" event with the currently selected value(s).
    * Single mode emits `{ value: string | null }`,
    * multiple mode emits `{ value: string[] }`.
+   *
+   * @private
    */
   #dispatchChange() {
     const selectedValues = this.itemTargets

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

@@ -30,6 +30,9 @@ import { startPositioning } from "kiso-ui/utils/positioning"
  * @property {HTMLElement} triggerTarget - Element that activates the tooltip on hover/focus
  * @property {HTMLElement} contentTarget - The floating tooltip panel (popover)
  * @property {HTMLElement} arrowTarget - Arrow element positioned by Floating UI
+ * @property {string} sideValue - Which side to place the tooltip: "top", "bottom", "left", or "right" (default: "top")
+ * @property {string} alignValue - Alignment along the side: "start", "center", or "end" (default: "center")
+ * @property {number} delayValue - Delay in milliseconds before showing the tooltip (default: 0)
  *
  * @fires kiso--tooltip:show - When the tooltip becomes visible
  * @fires kiso--tooltip:hide - When the tooltip is hidden

data/app/javascript/kiso/utils/focusable.js

@@ -1,8 +1,22 @@
+/**
+ * Shared focusable element utilities.
+ * Provides a CSS selector for querying focusable elements in the DOM.
+ *
+ * Used by popover, dropdown_menu, and other controllers that need
+ * focus trapping or focus management.
+ *
+ * @module utils/focusable
+ */
+
 /**
  * CSS selector for all natively focusable elements that are not disabled
  * or explicitly removed from the tab order.
  *
  * @type {string}
+ *
+ * @example
+ *   const focusable = container.querySelectorAll(FOCUSABLE_SELECTOR)
+ *   focusable[0]?.focus()
  */
 export const FOCUSABLE_SELECTOR =
   'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), textarea:not([disabled]), [tabindex]:not([tabindex="-1"])'

data/app/javascript/kiso/utils/highlight.js

@@ -10,11 +10,19 @@
  * clearItems, then sets it on the item at `index` within `items` and
  * scrolls it into view.
  *
- * @param {HTMLElement[]} clearItems - Items to remove the attribute from
+ * @param {HTMLElement[]} clearItems - Items to remove the attribute from (may differ from `items` to clear a broader set)
  * @param {HTMLElement[]} items - Items to index into for highlighting
  * @param {number} index - Index to highlight, or -1 to clear only
  * @param {Object} [options]
  * @param {string} [options.attr="data-highlighted"] - The attribute to toggle
+ *
+ * @example
+ *   // Highlight the third item, clearing all item targets first
+ *   highlightItem(this.itemTargets, this._visibleEnabledItems, 2)
+ *
+ * @example
+ *   // Use a custom attribute for command palette selection
+ *   highlightItem(this.itemTargets, enabledItems, 0, { attr: "data-selected" })
  */
 export function highlightItem(clearItems, items, index, { attr = "data-highlighted" } = {}) {
   clearItems.forEach((item) => item.removeAttribute(attr))
@@ -32,6 +40,12 @@ export function highlightItem(clearItems, items, index, { attr = "data-highlight
  * @param {number} direction - +1 for next, -1 for previous
  * @param {number} length - Total number of items
  * @returns {number} The wrapped index, or -1 if length is 0
+ *
+ * @example
+ *   wrapIndex(2, 1, 5)   // => 3
+ *   wrapIndex(4, 1, 5)   // => 0 (wraps to start)
+ *   wrapIndex(0, -1, 5)  // => 4 (wraps to end)
+ *   wrapIndex(0, 1, 0)   // => -1 (empty list)
  */
 export function wrapIndex(current, direction, length) {
   if (length === 0) return -1

data/app/views/kiso/components/_alert.html.erb

@@ -1,4 +1,6 @@
 <%# locals: (icon: nil, color: :primary, variant: :soft, close: false, ui: {}, css_classes: "", **component_options) %>
+<%# Dismissible alert banner with optional icon. Composes with alert/title, alert/description,
+    and alert/actions sub-parts. The close: prop adds a Stimulus-powered dismiss button. %>
 <%= content_tag :div,
     role: :alert,
     class: Kiso::Themes::Alert.render(color: color, variant: variant, class: css_classes),

data/app/views/kiso/components/_alert_dialog.html.erb

@@ -1,9 +1,12 @@
 <%# locals: (open: false, size: :default, ui: {}, css_classes: "", **component_options) %>
+<%# Non-dismissible confirmation dialog using native <dialog> with showModal().
+    Requires role="alertdialog" for screen readers. Pass id: to enable automatic
+    aria-labelledby/aria-describedby linking with title and description sub-parts. %>
 <%
   # Store the dialog id on the view context so child sub-part partials
   # (_title, _description) can auto-generate matching aria-labelledby /
-  # aria-describedby id attributes without requiring the caller to pass
-  # the id through each nested kui() call.
+  # aria-describedby ids without requiring the caller to thread the id
+  # through each nested kui() call.
   @_kiso_alert_dialog_id = component_options[:id]
   aria = {}
   if @_kiso_alert_dialog_id

data/app/views/kiso/components/_app.html.erb

@@ -1,4 +1,6 @@
 <%# locals: (center: false, css_classes: "", **component_options) %>
+<%# Top-level app layout wrapper. Composes with Header, Main, Footer sub-components.
+    Set center: true to constrain content width. %>
 <%= content_tag :div,
     class: Kiso::Themes::App.render(center: center, class: css_classes),
     data: kiso_prepare_options(component_options, slot: "app"),

data/app/views/kiso/components/_aspect_ratio.html.erb

@@ -1,4 +1,5 @@
 <%# locals: (ratio: 16.0/9, css_classes: "", **component_options) %>
+<%# Constrains child content to a fixed aspect ratio via inline style. %>
 <%= content_tag :div,
     style: "aspect-ratio: #{ratio}",
     class: Kiso::Themes::AspectRatio.render(class: css_classes),

data/app/views/kiso/components/_avatar.html.erb

@@ -1,10 +1,14 @@
-<%# locals: (src: nil, alt: "", text: nil, size: :md, color: nil, ui: {}, css_classes: "", **component_options) %>
-<% text_color = Kiso::ColorUtils.contrast_text_color(color) if color %>
+<%# locals: (src: nil, alt: "", text: nil, size: :md, color: nil, contrast_threshold: nil, ui: {}, css_classes: "", **component_options) %>
+<%# User avatar with image, text fallback, and optional status badge. Supports
+    arbitrary background colors via color: with automatic contrast text selection.
+    Yield a block to fully override internal structure, or use props for defaults. %>
+<% text_color = Kiso::ColorUtils.contrast_text_color(color, threshold: contrast_threshold) if color %>
 <%= content_tag :span,
     class: Kiso::Themes::Avatar.render(size: size, class: css_classes),
     style: (color ? "background-color: #{color}; color: #{text_color};" : nil),
     data: kiso_prepare_options(component_options, slot: "avatar", size: size),
     **component_options do %>
+  <%# Block override: if caller yields content, render it instead of the default image+fallback. %>
   <% content = capture { yield }.presence %>
   <% if content %>
     <%= content %>

data/app/views/kiso/components/_button.html.erb

@@ -1,6 +1,9 @@
 <%# locals: (color: :primary, variant: :solid, size: :md, block: false,
              type: :button, href: nil, method: nil, disabled: false,
              form: {}, css_classes: "", **component_options) %>
+<%# Polymorphic button that renders as <button>, <a>, or button_to depending on props.
+    With href: renders an anchor tag. With href: + method: (non-GET) renders a Rails
+    button_to form for safe non-GET navigation. Without href: renders a plain <button>. %>
 <%
   css = Kiso::Themes::Button.render(
     color: color, variant: variant, size: size, block: block, class: css_classes)

data/app/views/kiso/components/_checkbox.html.erb

@@ -1,4 +1,5 @@
 <%# locals: (color: :primary, checked: false, css_classes: "", **component_options) %>
+<%# Native <input type="checkbox"> styled with accent-color theming. %>
 <% component_options[:type] = :checkbox
    component_options[:checked] = true if checked %>
 <%= tag.input(

data/app/views/kiso/components/_color_mode_button.html.erb

@@ -1,4 +1,6 @@
 <%# locals: (size: :md, css_classes: "", **component_options) %>
+<%# Light/dark mode toggle button. Swaps sun/moon icons via CSS visibility
+    controlled by the .dark class on <html>. Uses the kiso--theme Stimulus controller. %>
 <%= content_tag :button,
     class: Kiso::Themes::ColorModeButton.render(size: size, class: css_classes),
     data: kiso_prepare_options(component_options, slot: "color-mode-button",

data/app/views/kiso/components/_color_mode_select.html.erb

@@ -1,4 +1,6 @@
 <%# locals: (size: :md, css_classes: "", **component_options) %>
+<%# Color mode dropdown with Light/Dark/System options. Composes a Select component
+    and dispatches kiso--select:change events to the kiso--theme controller. %>
 <%= content_tag :div,
     class: Kiso::Themes::ColorModeSelect.render(class: css_classes),
     data: kiso_prepare_options(component_options, slot: "color-mode-select",

data/app/views/kiso/components/_combobox.html.erb

@@ -1,4 +1,7 @@
 <%# locals: (name: nil, multiple: false, css_classes: "", **component_options) %>
+<%# Autocomplete combobox with keyboard navigation and optional multi-select.
+    Composes with combobox/input, combobox/content, combobox/item sub-parts.
+    Pass name: to include a hidden input for form submission. %>
 <%= content_tag :div,
     class: Kiso::Themes::Combobox.render(class: css_classes),
     data: kiso_prepare_options(component_options, slot: "combobox",

data/app/views/kiso/components/_command.html.erb

@@ -1,4 +1,6 @@
 <%# locals: (css_classes: "", **component_options) %>
+<%# Command palette with search filtering and keyboard navigation.
+    Composes with command/input, command/list, command/group, command/item sub-parts. %>
 <%= content_tag :div,
     class: Kiso::Themes::Command.render(class: css_classes),
     data: kiso_prepare_options(component_options, slot: "command", controller: "kiso--command"),

data/app/views/kiso/components/_dashboard_group.html.erb

@@ -1,4 +1,8 @@
 <%# locals: (sidebar_open: nil, layout: :sidebar, css_classes: "", **component_options) %>
+<%# Root wrapper for the dashboard layout system. Reads sidebar state from cookies
+    by default, or accepts an explicit sidebar_open: override. Renders a scrim
+    overlay for mobile sidebar dismissal. %>
+<%# Default to cookie-based sidebar state; explicit prop overrides. %>
 <% sidebar_open = cookies[:sidebar_open] != "false" if sidebar_open.nil? %>
 <%= content_tag :div,
     class: Kiso::Themes::DashboardGroup.render(class: css_classes),

data/app/views/kiso/components/_dashboard_navbar.html.erb

@@ -1,4 +1,6 @@
 <%# locals: (css_classes: "", **component_options) %>
+<%# Top navigation bar for the dashboard layout. Typically contains sidebar toggle
+    buttons, breadcrumbs, and user actions. %>
 <%= content_tag :header,
     class: Kiso::Themes::DashboardNavbar.render(class: css_classes),
     data: kiso_prepare_options(component_options, slot: "dashboard-navbar"),

data/app/views/kiso/components/_dashboard_panel.html.erb

@@ -1,4 +1,5 @@
 <%# locals: (css_classes: "", **component_options) %>
+<%# Main content area of the dashboard layout, adjacent to the sidebar. %>
 <%= content_tag :main,
     class: Kiso::Themes::DashboardPanel.render(class: css_classes),
     data: kiso_prepare_options(component_options, slot: "dashboard-panel"),

data/app/views/kiso/components/_dashboard_sidebar.html.erb

@@ -1,4 +1,6 @@
 <%# locals: (css_classes: "", **component_options) %>
+<%# Dashboard sidebar <aside> with a fixed id for aria-controls references.
+    The inner wrapper div provides the scrollable content area. %>
 <%= content_tag :aside,
     id: "dashboard-sidebar",
     class: Kiso::Themes::DashboardSidebar.render(class: css_classes),

data/app/views/kiso/components/_dashboard_toolbar.html.erb

@@ -1,4 +1,6 @@
 <%# locals: (css_classes: "", **component_options) %>
+<%# Secondary toolbar below the navbar. Composes with dashboard_toolbar/left
+    and dashboard_toolbar/right for split layouts. %>
 <%= content_tag :div,
     class: Kiso::Themes::DashboardToolbar.render(class: css_classes),
     data: kiso_prepare_options(component_options, slot: "dashboard-toolbar"),

data/app/views/kiso/components/_dialog.html.erb

@@ -1,4 +1,7 @@
 <%# locals: (open: false, ui: {}, css_classes: "", **component_options) %>
+<%# Modal dialog using native <dialog> with showModal(). Dismissable via Escape
+    key or backdrop click (unlike AlertDialog). Composes with dialog/header,
+    dialog/title, dialog/description, dialog/body, dialog/footer, dialog/close. %>
 <%= content_tag :dialog,
     class: Kiso::Themes::Dialog.render(class: css_classes),
     data: kiso_prepare_options(component_options, slot: "dialog",

data/app/views/kiso/components/_dropdown_menu.html.erb

@@ -1,4 +1,6 @@
 <%# locals: (css_classes: "", **component_options) %>
+<%# Dropdown menu with keyboard navigation, checkbox/radio items, and nested submenus.
+    Composes with dropdown_menu/trigger, dropdown_menu/content, dropdown_menu/item, etc. %>
 <%= content_tag :div,
     class: Kiso::Themes::DropdownMenu.render(class: css_classes),
     data: kiso_prepare_options(component_options, slot: "dropdown-menu", controller: "kiso--dropdown-menu"),

data/app/views/kiso/components/_empty.html.erb

@@ -1,4 +1,6 @@
 <%# locals: (css_classes: "", **component_options) %>
+<%# Empty state placeholder. Composes with empty/media, empty/header, empty/title,
+    empty/description, empty/content, and empty/actions sub-parts. %>
 <%= content_tag :div,
     class: Kiso::Themes::Empty.render(class: css_classes),
     data: kiso_prepare_options(component_options, slot: "empty"),

data/app/views/kiso/components/_field.html.erb

@@ -1,4 +1,6 @@
 <%# locals: (orientation: :vertical, invalid: false, disabled: false, css_classes: "", **component_options) %>
+<%# Form field wrapper that groups a label, input, description, and error message.
+    Sets data-invalid and data-disabled attributes for CSS-driven state styling. %>
 <%= content_tag :div,
     role: :group,
     class: Kiso::Themes::Field.render(orientation: orientation, class: css_classes),

data/app/views/kiso/components/_field_group.html.erb

@@ -1,4 +1,5 @@
 <%# locals: (css_classes: "", **component_options) %>
+<%# Vertical stack of Field components with consistent spacing. %>
 <%= content_tag :div,
     class: Kiso::Themes::FieldGroup.render(class: css_classes),
     data: kiso_prepare_options(component_options, slot: "field-group"),

data/app/views/kiso/components/_field_set.html.erb

@@ -1,4 +1,5 @@
 <%# locals: (css_classes: "", **component_options) %>
+<%# Native <fieldset> for grouping related form fields. Use with field_set/legend. %>
 <%= content_tag :fieldset,
     class: Kiso::Themes::FieldSet.render(class: css_classes),
     data: kiso_prepare_options(component_options, slot: "field-set"),

data/app/views/kiso/components/_input_group.html.erb

@@ -1,4 +1,5 @@
 <%# locals: (css_classes: "", **component_options) %>
+<%# Groups an Input with leading/trailing addons (icons, text, buttons). %>
 <%= content_tag :div,
     role: :group,
     class: Kiso::Themes::InputGroup.render(class: css_classes),

data/app/views/kiso/components/_input_otp.html.erb

@@ -1,4 +1,7 @@
 <%# locals: (length: 6, name: nil, id: nil, value: nil, pattern: "\\d", disabled: false, autocomplete: "one-time-code", aria_label: nil, css_classes: "", **component_options) %>
+<%# One-time password input with individual character slots. A hidden real input
+    captures keystrokes while visible slot divs display each character. Compose
+    with input_otp/group and input_otp/slot sub-parts for the visual layout. %>
 <%= content_tag :div,
     class: Kiso::Themes::InputOtp.render(class: css_classes),
     data: kiso_prepare_options(component_options, slot: "input-otp",

data/app/views/kiso/components/_nav.html.erb

@@ -1,4 +1,6 @@
 <%# locals: (css_classes: "", **component_options) %>
+<%# Sidebar navigation container. Composes with nav/section, nav/section_title,
+    and nav/item sub-parts. Typically placed inside a dashboard_sidebar. %>
 <%= content_tag :nav,
     class: Kiso::Themes::Nav.render(class: css_classes),
     data: kiso_prepare_options(component_options, slot: "nav"),

data/app/views/kiso/components/_page_card.html.erb

@@ -1,4 +1,6 @@
 <%# locals: (variant: :outline, icon: nil, title: nil, description: nil, ui: {}, css_classes: "", **component_options) %>
+<%# Page-level card with optional icon, title, and description props.
+    Yield a block to fully override the internal structure. %>
 <%= content_tag :div,
     class: Kiso::Themes::PageCard.render(variant: variant, class: css_classes),
     data: kiso_prepare_options(component_options, slot: "page-card"),
@@ -9,6 +11,7 @@
     <%= content_tag :div,
         class: Kiso::Themes::PageCardWrapper.render(class: ui[:wrapper]),
         data: { slot: "page-card-wrapper" } do %>
+      <%# Block override: yield replaces default icon/title/description layout. %>
       <% content = capture { yield }.presence %>
       <% if content %>
         <%= content %>

data/app/views/kiso/components/_page_header.html.erb

@@ -1,4 +1,6 @@
 <%# locals: (headline: nil, title: nil, description: nil, ui: {}, css_classes: "", **component_options) %>
+<%# Page header with optional headline, title, and description props.
+    Yield a block to fully override the internal structure (e.g., to add action buttons). %>
 <%= content_tag :div,
     class: Kiso::Themes::PageHeader.render(class: css_classes),
     data: kiso_prepare_options(component_options, slot: "page-header"),
@@ -6,6 +8,7 @@
   <%= content_tag :div,
       class: Kiso::Themes::PageHeaderWrapper.render(class: ui[:wrapper]),
       data: { slot: "page-header-wrapper" } do %>
+    <%# Block override: yield replaces default headline/title/description layout. %>
     <% content = capture { yield }.presence %>
     <% if content %>
       <%= content %>

data/app/views/kiso/components/_page_section.html.erb

@@ -1,4 +1,6 @@
 <%# locals: (orientation: :horizontal, ui: {}, css_classes: "", **component_options) %>
+<%# Page content section with horizontal or vertical orientation. Composes with
+    page_section/header, page_section/body, page_section/title, page_section/description. %>
 <%= content_tag :section,
     class: Kiso::Themes::PageSection.render(orientation: orientation, class: css_classes),
     data: kiso_prepare_options(component_options, slot: "page-section"),

data/app/views/kiso/components/_pagination.html.erb

@@ -1,4 +1,6 @@
 <%# locals: (css_classes: "", **component_options) %>
+<%# Pagination navigation. Composes with pagination/content, pagination/item,
+    pagination/link, pagination/previous, pagination/next, pagination/ellipsis. %>
 <%= content_tag :nav,
     role: "navigation",
     aria: {label: t("kiso.pagination.label")},

data/app/views/kiso/components/_popover.html.erb

@@ -1,4 +1,7 @@
 <%# locals: (css_classes: "", **component_options) %>
+<%# Floating popover positioned via Floating UI. Uses position: relative as the
+    anchor reference for absolute positioning of the content panel.
+    Composes with popover/trigger, popover/anchor, and popover/content sub-parts. %>
 <%= content_tag :div,
     class: css_classes.presence,
     data: kiso_prepare_options(component_options, slot: "popover", controller: "kiso--popover"),

data/app/views/kiso/components/_select.html.erb

@@ -1,4 +1,7 @@
 <%# locals: (name: nil, css_classes: "", **component_options) %>
+<%# Custom select with keyboard navigation and Stimulus-driven open/close.
+    Pass name: to include a hidden input for form submission. For a native
+    <select>, use select_native instead. %>
 <%= content_tag :div,
     class: Kiso::Themes::Select.render(class: css_classes),
     data: kiso_prepare_options(component_options, slot: "select", controller: "kiso--select"),

data/app/views/kiso/components/_select_native.html.erb

@@ -1,4 +1,6 @@
 <%# locals: (variant: :outline, size: :md, disabled: false, ui: {}, css_classes: "", **component_options) %>
+<%# Native <select> element with a styled chevron icon overlay. Yield <option>
+    elements as the block content. For a custom dropdown, use select instead. %>
 <%= content_tag :div,
     class: Kiso::Themes::SelectNativeWrapper.render(class: ui[:wrapper]),
     data: {slot: "select-native-wrapper"} do %>

data/app/views/kiso/components/_separator.html.erb

@@ -1,4 +1,6 @@
 <%# locals: (orientation: :horizontal, decorative: true, css_classes: "", **component_options) %>
+<%# Visual divider line. Set decorative: false to expose a semantic separator
+    role to assistive technology. %>
 <%= tag.div(
     role: (decorative ? "none" : "separator"),
     aria: (decorative ? {} : { orientation: orientation }),

data/app/views/kiso/components/_skeleton.html.erb

@@ -1,4 +1,5 @@
 <%# locals: (css_classes: "", **component_options) %>
+<%# Animated placeholder for content that is loading. Style dimensions via css_classes:. %>
 <%= tag.div(
     class: Kiso::Themes::Skeleton.render(class: css_classes),
     data: kiso_prepare_options(component_options, slot: "skeleton"),

data/app/views/kiso/components/_slider.html.erb

@@ -1,5 +1,9 @@
 <%# locals: (min: 0, max: 100, step: 1, value: nil, name: nil, id: nil, disabled: false, size: :md, aria_label: nil, ui: {}, css_classes: "", **component_options) %>
+<%# Range slider with a hidden native <input type="range"> for form submission and an
+    accessible ARIA slider thumb for keyboard/pointer interaction. The Stimulus controller
+    syncs the visual position with the hidden input value. %>
 <% slider_value = value || min %>
+<%# Calculate initial thumb/range position as a percentage for inline styles. %>
 <% percent = ((slider_value.to_f - min) / (max - min) * 100).clamp(0, 100) %>
 <%= content_tag :div,
     class: Kiso::Themes::Slider.render(class: css_classes),

data/app/views/kiso/components/_spinner.html.erb

@@ -1,4 +1,6 @@
 <%# locals: (label: nil, css_classes: "", **component_options) %>
+<%# Animated loading spinner rendered via kiso_component_icon. Uses role="status"
+    for screen reader announcements. %>
 <%= kiso_component_icon(:spinner,
     role: "status",
     aria: { label: label || t("kiso.spinner.loading") },

data/app/views/kiso/components/_stats_card.html.erb

@@ -1,4 +1,6 @@
 <%# locals: (variant: :outline, css_classes: "", **component_options) %>
+<%# Metric display card. Composes with stats_card/header, stats_card/label,
+    stats_card/value, and stats_card/description sub-parts. %>
 <%= content_tag :div,
     class: Kiso::Themes::StatsCard.render(variant: variant, class: css_classes),
     data: kiso_prepare_options(component_options, slot: "stats-card"),

data/app/views/kiso/components/_stats_grid.html.erb

@@ -1,4 +1,5 @@
 <%# locals: (columns: 4, css_classes: "", **component_options) %>
+<%# Responsive grid layout for stats_card components. %>
 <%= content_tag :div,
     class: Kiso::Themes::StatsGrid.render(columns: columns, class: css_classes),
     data: kiso_prepare_options(component_options, slot: "stats-grid"),

data/app/views/kiso/components/_switch.html.erb

@@ -1,4 +1,6 @@
 <%# locals: (color: :primary, size: :md, checked: false, ui: {}, css_classes: "", **component_options) %>
+<%# Toggle switch built on a hidden checkbox with role="switch". The <label> wraps
+    the hidden input and a visible thumb span, using peer-checked: for state styling. %>
 <% component_options[:type] = :checkbox
    component_options[:role] = :switch
    component_options[:checked] = true if checked %>

data/app/views/kiso/components/_table.html.erb

@@ -1,4 +1,6 @@
 <%# locals: (css_classes: "", **component_options) %>
+<%# Data table wrapped in a horizontally-scrollable container. Composes with table/header,
+    table/body, table/row, table/head, table/cell, table/footer, and table/caption. %>
 <div class="relative w-full overflow-x-auto">
   <%= content_tag :table,
       class: Kiso::Themes::Table.render(class: css_classes),