kiso 0.4.2.pre → 0.5.0.pre

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e7e4247e68272499ab572c3aa2ed94ad54860cf075f0b4e3240a1b11fd909d6
-  data.tar.gz: 87e9710cb6428055adad01d89a4357e735ac5c8b326c547b01d696d208501cf8
+  metadata.gz: 4bf4475ba64978e58e6321ac224b3912cf463dae75462ee3372f86faf4b69799
+  data.tar.gz: ee8c23fdd9a81b0b4abd8a097371a4720b8327e2c719c6b1a5cb84ea21a22962
 SHA512:
-  metadata.gz: 9f0842c23bdf92f06c826614ac8eb81d427eb136ea5fa2d6f735886387790cccda7943d450e8e771a7405cb9d6017eb2c1a5b00386b499b2c079ff933b520ec2
-  data.tar.gz: 1322bed3abb54da45bb4163e7fa5ca5919efbb6af07f505606dc17e65ac100f5fbc6d438e336347bdb44a09f70a2a7f3c413df876ace869adcd2b7a758ee725a
+  metadata.gz: abdb896617cba586d6906624bb2e30434ad40ccd2c1a12d589284ca43149056724c4ecb6dad7cb4a27915f3dad846e64b2a12bc3efa5a0d0fe82378aaf6494ad
+  data.tar.gz: 00d0ce8bd9933e5f3500d3ac0dfa57a068ae8c3923371943e398122f179e508fe5c7bd39b308df15a92eda836e50a41693be5e295e5a7c1bd3f6aea1bf2a57af

data/app/assets/tailwind/kiso/button.css

@@ -0,0 +1,10 @@
+/* Default display for buttons — lives in @layer components so utility classes
+   (including `hidden`) override via the higher-priority utilities layer. When
+   a utility like `hidden` is removed via JS, this rule restores inline-flex.
+   Fixes: https://github.com/steveclarke/kiso/issues/200 */
+
+@layer components {
+  [data-slot="button"] {
+    display: inline-flex;
+  }
+}

data/app/assets/tailwind/kiso/engine.css

@@ -3,6 +3,7 @@
    that are awkward to express in ERB. Most styling lives in Ruby theme modules
    (lib/kiso/themes/) as computed Tailwind classes. */
 
+@import "./button.css";
 @import "./checkbox.css";
 @import "./radio-group.css";
 @import "./color-mode.css";
@@ -10,6 +11,7 @@
 @import "./dialog.css";
 @import "./input-otp.css";
 @import "./slider.css";
+@import "./tooltip.css";
 
 /* Scan Kiso's own files so host apps don't need to know the gem's internals.
    Paths are relative to THIS file (app/assets/tailwind/kiso/engine.css).

data/app/assets/tailwind/kiso/tooltip.css

@@ -0,0 +1,48 @@
+/* Tooltip entry/exit animations and arrow positioning. */
+
+/* Tooltip root — inline-flex via @layer components so utilities can override */
+@layer components {
+  [data-slot="tooltip"] {
+    display: inline-flex;
+  }
+}
+
+/* The browser UA stylesheet hides [popover]:not(:popover-open) with
+   display: none, but Tailwind's `flex` utility (author layer) overrides it.
+   Explicitly enforce hidden state for non-open popovers. */
+[data-slot="tooltip-content"]:not(:popover-open) {
+  display: none;
+}
+
+/* Reset UA popover styles — browsers apply inset: 0, margin: auto, and
+   width/height: fit-content to [popover]:popover-open, which overrides
+   Floating UI's inline-style positioning. */
+[data-slot="tooltip-content"] {
+  inset: unset;
+  margin: 0;
+}
+
+/* Entry animation — fade + scale from 95% */
+[data-slot="tooltip-content"][data-state="open"] {
+  animation: kiso-tooltip-in 150ms ease-out;
+}
+
+/* Exit animation — fade out + scale to 95% */
+[data-slot="tooltip-content"][data-state="closed"] {
+  animation: kiso-tooltip-out 100ms ease-in forwards;
+}
+
+@keyframes kiso-tooltip-in {
+  from { opacity: 0; transform: scale(0.95); }
+}
+@keyframes kiso-tooltip-out {
+  to { opacity: 0; transform: scale(0.95); }
+}
+
+/* Respect reduced motion */
+@media (prefers-reduced-motion: reduce) {
+  [data-slot="tooltip-content"][data-state="open"],
+  [data-slot="tooltip-content"][data-state="closed"] {
+    animation: none;
+  }
+}

data/app/helpers/kiso/component_helper.rb

@@ -102,10 +102,17 @@ module Kiso
     #     yield
     #   end
     def kui_tag(tag, theme:, slot:, css_classes: "", variants: {}, **component_options, &block)
-      content_tag(tag,
+      html_options = {
         class: theme.render(**variants, class: css_classes),
         data: kiso_prepare_options(component_options, slot: slot),
-        **component_options, &block)
+        **component_options
+      }
+
+      if block
+        content_tag(tag, html_options, &block)
+      else
+        content_tag(tag, nil, html_options)
+      end
     end
 
     private
@@ -172,6 +179,10 @@ module Kiso
         # Push context for composed sub-parts to read (skip when empty)
         kiso_push_ui_context(component, merged_ui) if has_ui
         kiso_push_scope(component, scope) if has_scope
+
+        # Merge scope into parent kwargs so the parent partial receives
+        # scope values as strict locals (scope as defaults, explicit kwargs win)
+        kwargs = scope.merge(kwargs) if has_scope
         begin
           locals = has_ui ? kwargs.merge(ui: merged_ui) : kwargs
 

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

@@ -0,0 +1,80 @@
+import { Controller } from "@hotwired/stimulus"
+
+/**
+ * Opens or closes a dialog from anywhere on the page by ID.
+ *
+ * Use when the trigger button lives outside the dialog's DOM scope
+ * (e.g., a toolbar button opening a confirmation dialog rendered
+ * elsewhere on the page).
+ *
+ * Works with both `kui(:dialog)` and `kui(:alert_dialog)` since
+ * both use the `kiso--dialog` Stimulus controller internally.
+ *
+ * @example
+ *   <!-- Dialog rendered anywhere -->
+ *   <dialog id="invite-dialog" data-controller="kiso--dialog" ...>
+ *     ...
+ *   </dialog>
+ *
+ *   <!-- Trigger from a toolbar, sidebar, or any other scope -->
+ *   <button data-controller="kiso--dialog-trigger"
+ *           data-kiso--dialog-trigger-dialog-id-value="invite-dialog"
+ *           data-action="kiso--dialog-trigger#open">
+ *     Invite
+ *   </button>
+ *
+ * @property {string} dialogIdValue - The DOM id of the target dialog element
+ *
+ * @fires kiso--dialog:open - Forwarded from the target dialog controller
+ * @fires kiso--dialog:close - Forwarded from the target dialog controller
+ */
+export default class extends Controller {
+  static values = {
+    dialogId: String,
+  }
+
+  /**
+   * Opens the target dialog.
+   */
+  open() {
+    this._withDialogController((controller) => controller.open())
+  }
+
+  /**
+   * Closes the target dialog.
+   */
+  close() {
+    this._withDialogController((controller) => controller.close())
+  }
+
+  /**
+   * Toggles the target dialog open or closed.
+   */
+  toggle() {
+    this._withDialogController((controller) => {
+      if (controller.element.open) {
+        controller.close()
+      } else {
+        controller.open()
+      }
+    })
+  }
+
+  /**
+   * Finds the dialog element and its Stimulus controller, then
+   * calls the provided callback with the controller instance.
+   *
+   * @param {function} callback - Receives the dialog controller
+   * @private
+   */
+  _withDialogController(callback) {
+    const dialog = document.getElementById(this.dialogIdValue)
+    if (!dialog) return
+
+    const controller = this.application.getControllerForElementAndIdentifier(dialog, "kiso--dialog")
+
+    if (controller) {
+      callback(controller)
+    }
+  }
+}

data/app/javascript/controllers/kiso/index.d.ts

@@ -5,8 +5,19 @@ declare const KisoUi: {
 }
 
 export default KisoUi
+export const KisoAlertController: typeof Controller
 export const KisoComboboxController: typeof Controller
+export const KisoCommandController: typeof Controller
+export const KisoCommandDialogController: typeof Controller
+export const KisoDialogController: typeof Controller
+export const KisoDialogTriggerController: typeof Controller
 export const KisoDropdownMenuController: typeof Controller
+export const KisoInputOtpController: typeof Controller
+export const KisoPopoverController: typeof Controller
 export const KisoSelectController: typeof Controller
+export const KisoSidebarController: typeof Controller
+export const KisoSliderController: typeof Controller
+export const KisoThemeController: typeof Controller
 export const KisoToggleController: typeof Controller
 export const KisoToggleGroupController: typeof Controller
+export const KisoTooltipController: typeof Controller

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

@@ -3,14 +3,17 @@ import KisoComboboxController from "./combobox_controller.js"
 import KisoCommandController from "./command_controller.js"
 import KisoCommandDialogController from "./command_dialog_controller.js"
 import KisoDialogController from "./dialog_controller.js"
+import KisoDialogTriggerController from "./dialog_trigger_controller.js"
 import KisoDropdownMenuController from "./dropdown_menu_controller.js"
 import KisoInputOtpController from "./input_otp_controller.js"
 import KisoPopoverController from "./popover_controller.js"
 import KisoSelectController from "./select_controller.js"
 import KisoSidebarController from "./sidebar_controller.js"
+import KisoSliderController from "./slider_controller.js"
 import KisoThemeController from "./theme_controller.js"
 import KisoToggleController from "./toggle_controller.js"
 import KisoToggleGroupController from "./toggle_group_controller.js"
+import KisoTooltipController from "./tooltip_controller.js"
 
 const KisoUi = {
   start(application) {
@@ -19,14 +22,17 @@ const KisoUi = {
     application.register("kiso--command", KisoCommandController)
     application.register("kiso--command-dialog", KisoCommandDialogController)
     application.register("kiso--dialog", KisoDialogController)
+    application.register("kiso--dialog-trigger", KisoDialogTriggerController)
     application.register("kiso--dropdown-menu", KisoDropdownMenuController)
     application.register("kiso--input-otp", KisoInputOtpController)
     application.register("kiso--popover", KisoPopoverController)
     application.register("kiso--select", KisoSelectController)
     application.register("kiso--sidebar", KisoSidebarController)
+    application.register("kiso--slider", KisoSliderController)
     application.register("kiso--theme", KisoThemeController)
     application.register("kiso--toggle", KisoToggleController)
     application.register("kiso--toggle-group", KisoToggleGroupController)
+    application.register("kiso--tooltip", KisoTooltipController)
   },
 }
 
@@ -37,12 +43,15 @@ export {
   KisoCommandController,
   KisoCommandDialogController,
   KisoDialogController,
+  KisoDialogTriggerController,
   KisoDropdownMenuController,
   KisoInputOtpController,
   KisoPopoverController,
   KisoSelectController,
   KisoSidebarController,
+  KisoSliderController,
   KisoThemeController,
   KisoToggleController,
   KisoToggleGroupController,
+  KisoTooltipController,
 }

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

@@ -0,0 +1,212 @@
+import { Controller } from "@hotwired/stimulus"
+import { startPositioning } from "kiso-ui/utils/positioning"
+
+/**
+ * Tooltip controller — shows a floating tooltip on hover or keyboard focus.
+ * Uses Floating UI for positioning and the native `[popover]` attribute for
+ * top-layer rendering (no z-index issues).
+ *
+ * @example
+ *   <div data-controller="kiso--tooltip"
+ *        data-kiso--tooltip-side-value="top"
+ *        data-kiso--tooltip-align-value="center"
+ *        data-kiso--tooltip-delay-value="0"
+ *        data-slot="tooltip">
+ *     <div data-kiso--tooltip-target="trigger"
+ *          data-action="mouseenter->kiso--tooltip#show mouseleave->kiso--tooltip#hide
+ *                       focusin->kiso--tooltip#show focusout->kiso--tooltip#hide"
+ *          data-slot="tooltip-trigger">
+ *       <button type="button">Hover me</button>
+ *     </div>
+ *     <div data-kiso--tooltip-target="content"
+ *          data-slot="tooltip-content"
+ *          popover="manual"
+ *          role="tooltip">
+ *       Tooltip text
+ *       <div data-kiso--tooltip-target="arrow" data-slot="tooltip-arrow"></div>
+ *     </div>
+ *   </div>
+ *
+ * @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
+ *
+ * @fires kiso--tooltip:show - When the tooltip becomes visible
+ * @fires kiso--tooltip:hide - When the tooltip is hidden
+ */
+export default class extends Controller {
+  static targets = ["trigger", "content", "arrow"]
+  static values = {
+    side: { type: String, default: "top" },
+    align: { type: String, default: "center" },
+    delay: { type: Number, default: 0 },
+  }
+
+  connect() {
+    this._open = false
+
+    // Link trigger to tooltip content via aria-describedby
+    this._triggerEl =
+      this.triggerTarget.querySelector("button, a, [tabindex]") || this.triggerTarget
+    this._tooltipId = this.contentTarget.id || `tooltip-${crypto.randomUUID().slice(0, 8)}`
+    this.contentTarget.id = this._tooltipId
+    this._triggerEl.setAttribute("aria-describedby", this._tooltipId)
+  }
+
+  disconnect() {
+    this._cleanupPosition?.()
+    this._clearTimers()
+  }
+
+  /**
+   * Shows the tooltip after the configured delay.
+   * Called on mouseenter and focusin on the trigger.
+   */
+  show() {
+    this._clearHideTimeout()
+
+    if (this._open) return
+
+    const delay = this.delayValue
+    if (delay > 0) {
+      this._showTimeout = setTimeout(() => this._doShow(), delay)
+    } else {
+      this._doShow()
+    }
+  }
+
+  /**
+   * Hides the tooltip with a small delay to allow the mouse to cross
+   * the gap between trigger and tooltip content.
+   * Called on mouseleave and focusout on the trigger.
+   */
+  hide() {
+    this._clearShowTimeout()
+
+    if (!this._open) return
+
+    // Small delay lets the mouse cross the offset gap to the content
+    this._hideTimeout = setTimeout(() => this._doHide(), 100)
+  }
+
+  /**
+   * Cancels a pending hide when the mouse enters the tooltip content.
+   * Keeps the tooltip visible while the user reads it.
+   */
+  contentMouseEnter() {
+    this._clearHideTimeout()
+  }
+
+  /**
+   * Hides the tooltip when the mouse leaves the tooltip content.
+   */
+  contentMouseLeave() {
+    this._doHide()
+  }
+
+  // --- Private ---
+
+  /**
+   * Shows the tooltip immediately: opens the popover, positions it,
+   * and triggers the entry animation.
+   *
+   * @private
+   */
+  _doShow() {
+    if (this._open) return
+    this._open = true
+
+    this.contentTarget.showPopover()
+    this.contentTarget.setAttribute("data-state", "open")
+
+    const placement = this._buildPlacement()
+    const options = {
+      placement,
+      strategy: "fixed",
+      offset: 8,
+    }
+    if (this.hasArrowTarget) {
+      options.arrow = this.arrowTarget
+    }
+
+    this._cleanupPosition = startPositioning(this.triggerTarget, this.contentTarget, options)
+
+    this.dispatch("show")
+  }
+
+  /**
+   * Hides the tooltip: triggers exit animation, then hides the popover.
+   *
+   * @private
+   */
+  _doHide() {
+    if (!this._open) return
+    this._open = false
+
+    this._cleanupPosition?.()
+    this._cleanupPosition = null
+    this._clearTimers()
+
+    this.contentTarget.setAttribute("data-state", "closed")
+
+    // Hide after exit animation completes
+    this._animHandler = () => {
+      this.contentTarget.hidePopover()
+      this.contentTarget.removeEventListener("animationend", this._animHandler)
+      this._animHandler = null
+    }
+    this.contentTarget.addEventListener("animationend", this._animHandler)
+
+    // Fallback: hide immediately if no animation runs
+    this._closeTimeout = setTimeout(() => {
+      if (!this._open && this.contentTarget.matches(":popover-open")) {
+        this.contentTarget.hidePopover()
+      }
+    }, 150)
+
+    this.dispatch("hide")
+  }
+
+  /**
+   * Builds a Floating UI placement string from side and align values.
+   *
+   * @returns {string} e.g. "top", "top-start", "bottom-end"
+   * @private
+   */
+  _buildPlacement() {
+    const side = this.sideValue
+    const align = this.alignValue
+    if (align === "center") return side
+    return `${side}-${align}`
+  }
+
+  /** @private */
+  _clearShowTimeout() {
+    if (this._showTimeout) {
+      clearTimeout(this._showTimeout)
+      this._showTimeout = null
+    }
+  }
+
+  /** @private */
+  _clearHideTimeout() {
+    if (this._hideTimeout) {
+      clearTimeout(this._hideTimeout)
+      this._hideTimeout = null
+    }
+  }
+
+  /** @private */
+  _clearTimers() {
+    this._clearShowTimeout()
+    this._clearHideTimeout()
+    if (this._closeTimeout) {
+      clearTimeout(this._closeTimeout)
+      this._closeTimeout = null
+    }
+    if (this._animHandler) {
+      this.contentTarget.removeEventListener("animationend", this._animHandler)
+      this._animHandler = null
+    }
+  }
+}

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

@@ -2,12 +2,20 @@
  * Shared positioning utilities for floating components.
  * Wraps Floating UI for smart positioning with flip, shift, and auto-update.
  *
- * Used by select, combobox, popover, and dropdown_menu controllers.
+ * Used by select, combobox, popover, dropdown_menu, and tooltip controllers.
  *
  * @module utils/positioning
  */
 
-import { autoUpdate, computePosition, flip, offset, shift, size } from "@floating-ui/dom"
+import {
+  arrow as arrowMiddleware,
+  autoUpdate,
+  computePosition,
+  flip,
+  offset,
+  shift,
+  size,
+} from "@floating-ui/dom"
 
 /**
  * Starts positioning a floating element relative to a reference element.
@@ -24,6 +32,7 @@ import { autoUpdate, computePosition, flip, offset, shift, size } from "@floatin
  * @param {number} [options.offset=4] - Pixel gap between reference and floating element
  * @param {"absolute"|"fixed"} [options.strategy="absolute"] - CSS positioning strategy
  * @param {boolean} [options.matchWidth=false] - Set floating element minWidth to reference width
+ * @param {HTMLElement|null} [options.arrow=null] - Arrow element to position via Floating UI arrow middleware
  * @returns {Function} Cleanup function — call on close or disconnect to remove listeners
  *
  * @example
@@ -49,6 +58,7 @@ export function startPositioning(reference, floating, options = {}) {
     offset: offsetDistance = 4,
     strategy = "absolute",
     matchWidth = false,
+    arrow: arrowElement = null,
   } = options
 
   const middleware = [offset(offsetDistance), flip(), shift({ padding: 8 })]
@@ -63,12 +73,19 @@ export function startPositioning(reference, floating, options = {}) {
     )
   }
 
+  if (arrowElement) {
+    middleware.push(arrowMiddleware({ element: arrowElement }))
+  }
+
+  /** @type {Record<string, string>} Maps placement side to the opposite side where the arrow attaches */
+  const ARROW_STATIC_SIDE = { top: "bottom", right: "left", bottom: "top", left: "right" }
+
   const update = () => {
     computePosition(reference, floating, {
       placement,
       strategy,
       middleware,
-    }).then(({ x, y, placement: finalPlacement }) => {
+    }).then(({ x, y, placement: finalPlacement, middlewareData }) => {
       Object.assign(floating.style, {
         position: strategy,
         left: `${x}px`,
@@ -79,6 +96,20 @@ export function startPositioning(reference, floating, options = {}) {
       if (floating.dataset.side !== side) {
         floating.dataset.side = side
       }
+
+      // Position arrow element if provided
+      if (arrowElement && middlewareData.arrow) {
+        const { x: arrowX, y: arrowY } = middlewareData.arrow
+        const staticSide = ARROW_STATIC_SIDE[side]
+
+        Object.assign(arrowElement.style, {
+          left: arrowX != null ? `${arrowX}px` : "",
+          top: arrowY != null ? `${arrowY}px` : "",
+          right: "",
+          bottom: "",
+          [staticSide]: "-4px",
+        })
+      }
     })
   }
 

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

@@ -1,6 +1,7 @@
-<%# locals: (src: nil, alt: "", text: nil, size: :md, ui: {}, css_classes: "", **component_options) %>
+<%# locals: (src: nil, alt: "", text: nil, size: :md, color: nil, ui: {}, css_classes: "", **component_options) %>
 <%= content_tag :span,
     class: Kiso::Themes::Avatar.render(size: size, class: css_classes),
+    style: (color ? "background-color: #{color};" : nil),
     data: kiso_prepare_options(component_options, slot: "avatar", size: size),
     **component_options do %>
   <% content = capture { yield }.presence %>
@@ -8,7 +9,9 @@
     <%= content %>
   <% else %>
     <% if text.present? %>
-      <%= tag.span class: Kiso::Themes::AvatarFallback.render(size: size, class: ui[:fallback]),
+      <% fallback_classes = ui[:fallback].to_s %>
+      <% fallback_classes = "bg-transparent text-inherit #{fallback_classes}" if color %>
+      <%= tag.span class: Kiso::Themes::AvatarFallback.render(size: size, class: fallback_classes),
           data: { slot: "avatar-fallback" } do %>
         <%= text %>
       <% end %>

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

@@ -0,0 +1,7 @@
+<%# locals: (label: nil, css_classes: "", **component_options) %>
+<%= kiso_component_icon(:spinner,
+    role: "status",
+    aria: { label: label || t("kiso.spinner.loading") },
+    class: Kiso::Themes::Spinner.render(class: css_classes),
+    data: kiso_prepare_options(component_options, slot: "spinner"),
+    **component_options) %>

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

@@ -0,0 +1,25 @@
+<%# locals: (text: nil, kbds: nil, side: :top, align: :center, delay: 0, ui: {}, css_classes: "", **component_options) %>
+<%= tag.div(
+    class: css_classes.presence,
+    data: kiso_prepare_options(component_options, slot: "tooltip",
+      controller: "kiso--tooltip",
+      kiso__tooltip_side_value: side,
+      kiso__tooltip_align_value: align,
+      kiso__tooltip_delay_value: delay),
+    **component_options) do %>
+  <% if text %>
+    <%= kui(:tooltip, :trigger) { yield } %>
+    <%= kui(:tooltip, :content, css_classes: ui[:content].to_s) do %>
+      <span data-slot="tooltip-text"><%= text %></span>
+      <% if kbds.present? %>
+        <span data-slot="tooltip-kbds" class="hidden lg:inline-flex items-center shrink-0 gap-0.5">
+          <% Array(kbds).each do |kbd| %>
+            <%= kui(:kbd, size: :sm) { kbd } %>
+          <% end %>
+        </span>
+      <% end %>
+    <% end %>
+  <% else %>
+    <%= yield %>
+  <% end %>
+<% end %>

data/app/views/kiso/components/tooltip/_content.html.erb

@@ -0,0 +1,14 @@
+<%# locals: (css_classes: "", ui: {}, **component_options) %>
+<%= tag.div(
+    class: Kiso::Themes::TooltipContent.render(class: css_classes),
+    role: "tooltip",
+    popover: "manual",
+    data: kiso_prepare_options(component_options, slot: "tooltip-content",
+      kiso__tooltip_target: "content",
+      action: "mouseenter->kiso--tooltip#contentMouseEnter mouseleave->kiso--tooltip#contentMouseLeave"),
+    **component_options) do %>
+  <%= yield %>
+  <%= tag.div(
+      class: Kiso::Themes::TooltipArrow.render(class: ui[:arrow].to_s),
+      data: { slot: "tooltip-arrow", kiso__tooltip_target: "arrow" }) %>
+<% end %>

data/app/views/kiso/components/tooltip/_trigger.html.erb

@@ -0,0 +1,9 @@
+<%# locals: (css_classes: "", **component_options) %>
+<%= tag.div(
+    class: css_classes.presence,
+    data: kiso_prepare_options(component_options, slot: "tooltip-trigger",
+      kiso__tooltip_target: "trigger",
+      action: "mouseenter->kiso--tooltip#show mouseleave->kiso--tooltip#hide focusin->kiso--tooltip#show focusout->kiso--tooltip#hide"),
+    **component_options) do %>
+  <%= yield %>
+<% end %>

data/config/locales/en.yml

@@ -24,6 +24,10 @@ en:
       collapse: "Collapse sidebar"
     dialog:
       close: "Close"
+    spinner:
+      loading: "Loading"
+    tooltip:
+      label: "Tooltip"
     pagination:
       label: "pagination"
       more_pages: "More pages"

data/lib/kiso/configuration.rb

@@ -87,7 +87,8 @@ module Kiso
         menu: "menu",
         minus: "minus",
         panel_left_close: "panel-left-close",
-        panel_left_open: "panel-left-open"
+        panel_left_open: "panel-left-open",
+        spinner: "loader-circle"
       }
     end
   end

data/lib/kiso/presets/rounded.rb

@@ -130,7 +130,10 @@ module Kiso
       nav_item: {base: "rounded-full"},
 
       # Nav item badge: rounded-md → rounded-full
-      nav_item_badge: {base: "rounded-full"}
+      nav_item_badge: {base: "rounded-full"},
+
+      # Tooltip content: rounded-md → rounded-xl
+      tooltip_content: {base: "rounded-xl"}
     }.freeze
   end
 end

data/lib/kiso/presets/sharp.rb

@@ -172,7 +172,10 @@ module Kiso
       nav_item: {base: "rounded-none"},
 
       # Nav item badge: rounded-md → rounded-none
-      nav_item_badge: {base: "rounded-none"}
+      nav_item_badge: {base: "rounded-none"},
+
+      # Tooltip content: rounded-md → rounded-none
+      tooltip_content: {base: "rounded-none"}
     }.freeze
   end
 end

data/lib/kiso/themes/avatar.rb

@@ -4,6 +4,7 @@ module Kiso
       base: "group/avatar relative flex shrink-0 rounded-full select-none items-center justify-center bg-muted",
       variants: {
         size: {
+          xs: "size-5",
           sm: "size-6",
           md: "size-8",
           lg: "size-10"
@@ -20,6 +21,7 @@ module Kiso
       base: "flex size-full items-center justify-center rounded-full bg-muted text-muted-foreground font-medium",
       variants: {
         size: {
+          xs: "text-[10px]",
           sm: "text-xs",
           md: "text-sm",
           lg: "text-base"
@@ -31,6 +33,7 @@ module Kiso
     AvatarBadge = ClassVariants.build(
       base: "bg-primary text-primary-foreground ring-background absolute right-0 bottom-0 z-10 " \
             "inline-flex items-center justify-center rounded-full ring-2 select-none " \
+            "group-data-[size=xs]/avatar:size-1.5 group-data-[size=xs]/avatar:[&>svg]:hidden " \
             "group-data-[size=sm]/avatar:size-2 group-data-[size=sm]/avatar:[&>svg]:hidden " \
             "group-data-[size=md]/avatar:size-2.5 group-data-[size=md]/avatar:[&>svg]:size-2 " \
             "group-data-[size=lg]/avatar:size-3 group-data-[size=lg]/avatar:[&>svg]:size-2"
@@ -44,9 +47,11 @@ module Kiso
     AvatarGroupCount = ClassVariants.build(
       base: "bg-muted text-muted-foreground ring-background relative flex size-8 shrink-0 " \
             "items-center justify-center rounded-full text-sm ring-2 " \
+            "group-has-data-[size=xs]/avatar-group:size-5 " \
             "group-has-data-[size=lg]/avatar-group:size-10 " \
             "group-has-data-[size=sm]/avatar-group:size-6 " \
             "[&>svg]:size-4 group-has-data-[size=lg]/avatar-group:[&>svg]:size-5 " \
+            "group-has-data-[size=xs]/avatar-group:[&>svg]:size-2.5 " \
             "group-has-data-[size=sm]/avatar-group:[&>svg]:size-3"
     )
   end

data/lib/kiso/themes/button.rb

@@ -14,7 +14,7 @@ module Kiso
     # - +size+ — :xs, :sm, :md (default), :lg, :xl
     # - +block+ — +true+ for full-width, +false+ (default)
     Button = ClassVariants.build(
-      base: "inline-flex items-center justify-center gap-2 font-medium whitespace-nowrap shrink-0 " \
+      base: "items-center justify-center gap-2 font-medium whitespace-nowrap shrink-0 " \
             "transition-all " \
             "focus-visible:outline-2 focus-visible:outline-offset-2 " \
             "disabled:pointer-events-none disabled:opacity-50 " \

data/lib/kiso/themes/spinner.rb

@@ -0,0 +1,16 @@
+module Kiso
+  module Themes
+    # Spinning loading indicator.
+    #
+    # @example
+    #   Spinner.render
+    #
+    # No variants — size is controlled via +css_classes:+. Inherits
+    # +currentColor+ from the parent context.
+    #
+    # shadcn base: size-4 animate-spin
+    Spinner = ClassVariants.build(
+      base: "animate-spin size-4"
+    )
+  end
+end

data/lib/kiso/themes/tooltip.rb

@@ -0,0 +1,26 @@
+module Kiso
+  module Themes
+    # Floating tooltip content panel with inverted colors.
+    #
+    # @example
+    #   TooltipContent.render
+    #
+    # No variants — tooltip always uses inverted colors. Inherits position
+    # from Floating UI via the Stimulus controller.
+    #
+    # shadcn base: bg-foreground text-background px-3 py-1.5 text-xs rounded-md
+    # Kiso: bg-inverted text-inverted-foreground (semantic equivalents)
+    TooltipContent = ClassVariants.build(
+      base: "bg-inverted text-inverted-foreground px-3 py-1.5 text-xs rounded-md " \
+            "flex items-center gap-1.5 select-none w-max max-w-xs"
+    )
+
+    # Arrow element pointing from tooltip content to the trigger.
+    #
+    # Positioned by Floating UI arrow middleware. CSS rotates 45° to form
+    # a diamond, with half hidden behind the tooltip edge.
+    TooltipArrow = ClassVariants.build(
+      base: "absolute size-2 rotate-45 bg-inverted"
+    )
+  end
+end

data/lib/kiso/version.rb

@@ -2,5 +2,5 @@
 
 module Kiso
   # @return [String] the current gem version
-  VERSION = "0.4.2.pre"
+  VERSION = "0.5.0.pre"
 end

data/lib/kiso.rb

@@ -49,6 +49,8 @@ require "kiso/themes/nav"
 require "kiso/themes/page"
 require "kiso/themes/avatar"
 require "kiso/themes/skeleton"
+require "kiso/themes/spinner"
+require "kiso/themes/tooltip"
 require "kiso/themes/slider"
 require "kiso/themes/layout"
 require "kiso/icons"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: kiso
 version: !ruby/object:Gem::Version
-  version: 0.4.2.pre
+  version: 0.5.0.pre
 platform: ruby
 authors:
 - Steve Clarke
@@ -73,13 +73,13 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- CHANGELOG.md
 - MIT-LICENSE
 - README.md
 - Rakefile
 - app/assets/fonts/kiso/GeistMonoVF.woff2
 - app/assets/fonts/kiso/GeistVF.woff2
 - app/assets/fonts/kiso/OFL.txt
+- app/assets/tailwind/kiso/button.css
 - app/assets/tailwind/kiso/checkbox.css
 - app/assets/tailwind/kiso/color-mode.css
 - app/assets/tailwind/kiso/dashboard.css
@@ -93,6 +93,7 @@ files:
 - app/assets/tailwind/kiso/palettes/zinc.css
 - app/assets/tailwind/kiso/radio-group.css
 - app/assets/tailwind/kiso/slider.css
+- app/assets/tailwind/kiso/tooltip.css
 - app/helpers/kiso/app_component_helper.rb
 - app/helpers/kiso/component_helper.rb
 - app/helpers/kiso/icon_helper.rb
@@ -103,6 +104,7 @@ files:
 - app/javascript/controllers/kiso/command_controller.js
 - app/javascript/controllers/kiso/command_dialog_controller.js
 - app/javascript/controllers/kiso/dialog_controller.js
+- app/javascript/controllers/kiso/dialog_trigger_controller.js
 - app/javascript/controllers/kiso/dropdown_menu_controller.js
 - app/javascript/controllers/kiso/index.d.ts
 - app/javascript/controllers/kiso/index.js
@@ -114,6 +116,7 @@ files:
 - app/javascript/controllers/kiso/theme_controller.js
 - app/javascript/controllers/kiso/toggle_controller.js
 - app/javascript/controllers/kiso/toggle_group_controller.js
+- app/javascript/controllers/kiso/tooltip_controller.js
 - app/javascript/kiso/utils/focusable.js
 - app/javascript/kiso/utils/highlight.js
 - app/javascript/kiso/utils/positioning.js
@@ -168,6 +171,7 @@ files:
 - app/views/kiso/components/_separator.html.erb
 - app/views/kiso/components/_skeleton.html.erb
 - app/views/kiso/components/_slider.html.erb
+- app/views/kiso/components/_spinner.html.erb
 - app/views/kiso/components/_stats_card.html.erb
 - app/views/kiso/components/_stats_grid.html.erb
 - app/views/kiso/components/_switch.html.erb
@@ -175,6 +179,7 @@ files:
 - app/views/kiso/components/_textarea.html.erb
 - app/views/kiso/components/_toggle.html.erb
 - app/views/kiso/components/_toggle_group.html.erb
+- app/views/kiso/components/_tooltip.html.erb
 - app/views/kiso/components/alert/_actions.html.erb
 - app/views/kiso/components/alert/_description.html.erb
 - app/views/kiso/components/alert/_title.html.erb
@@ -320,6 +325,8 @@ files:
 - app/views/kiso/components/table/_header.html.erb
 - app/views/kiso/components/table/_row.html.erb
 - app/views/kiso/components/toggle_group/_item.html.erb
+- app/views/kiso/components/tooltip/_content.html.erb
+- app/views/kiso/components/tooltip/_trigger.html.erb
 - config/deploy.docs.yml
 - config/deploy.yml
 - config/importmap.rb
@@ -380,12 +387,14 @@ files:
 - lib/kiso/themes/shared.rb
 - lib/kiso/themes/skeleton.rb
 - lib/kiso/themes/slider.rb
+- lib/kiso/themes/spinner.rb
 - lib/kiso/themes/stats_card.rb
 - lib/kiso/themes/switch.rb
 - lib/kiso/themes/table.rb
 - lib/kiso/themes/textarea.rb
 - lib/kiso/themes/toggle.rb
 - lib/kiso/themes/toggle_group.rb
+- lib/kiso/themes/tooltip.rb
 - lib/kiso/version.rb
 - lib/tasks/kiso.rake
 homepage: https://github.com/steveclarke/kiso
@@ -394,7 +403,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/steveclarke/kiso
   source_code_uri: https://github.com/steveclarke/kiso
-  changelog_uri: https://github.com/steveclarke/kiso/blob/master/CHANGELOG.md
+  changelog_uri: https://github.com/steveclarke/kiso/releases
   bug_tracker_uri: https://github.com/steveclarke/kiso/issues
   rubygems_mfa_required: 'true'
   allowed_push_host: https://rubygems.org

data/CHANGELOG.md

@@ -1,130 +0,0 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
-and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
-
-## [Unreleased]
-
-## [0.4.2.pre] - 2026-03-08
-
-### Added
-
-- `scope:` prop for sharing domain locals from parent components to sub-parts — `appui(:room_card, scope: { room: room })` makes `room:` available to all sub-parts automatically without repeating it on every call. Explicit kwargs on sub-part calls override scope values. One level deep only (parent to its own sub-parts).
-
-## [0.4.1.pre] - 2026-03-08
-
-### Added
-
-- `center:` variant on App layout component — `kui(:app, center: true)` applies full-viewport centering for login pages and similar single-focus layouts
-- `kui_tag` / `appui_tag` helpers — collapse the common `content_tag` + `kiso_prepare_options` + theme rendering boilerplate into a single call; component generator templates now use `appui_tag` by default
-- Shade scale auto-wiring — host apps defining `--color-primary-50` through `--color-primary-950` in their Tailwind `@theme` block now automatically feed into Kiso's semantic color tokens (shade 500 for light mode, 400 for dark mode, matching Nuxt UI conventions)
-
-### Fixed
-
-- Palette CSS files are now importable in host apps — a `kiso:palettes` rake task generates CSS stubs so `@import "../builds/tailwind/kiso/palettes/blue.css"` resolves correctly
-
-## [0.4.0.pre] - 2026-03-08
-
-### Added
-
-- Layout component family: App, Container (4 size variants), Header, Footer, Main
-- Page component family: Page (grid with sidebars), PageHeader, PageBody, PageSection, PageGrid, PageCard (4 variants)
-- `appui()` helper for host app components with `app/themes/` and `app/views/components/`
-- `kiso:framework_component` generator for scaffolding engine components
-- `kiso:component` generator for scaffolding host app components
-- Theme presets: `apply_preset(:rounded)` and `apply_preset(:sharp)`
-- 5 OKLCH color palettes (zinc, blue, green, orange, violet)
-- i18n support: all component strings use `t()` with `config/locales/en.yml`
-- [Building Your Own Components](/guide/building-components) guide — how to wrap Kiso components with domain logic and build standalone components with `appui()`, themes, and sub-parts
-- [Detailed release notes](/releases/batch-merge) with upgrade guide and examples for all new features
-
-## [0.3.0.pre] - 2026-03-03
-
-### Added
-
-- Dialog component — modal dialog wrapping the native `<dialog>` element with `showModal()` for focus trapping and backdrop. Sub-parts: header, title, description, body, footer, close. Entry/exit CSS animations with reduced-motion support. Stimulus controller for programmatic open/close.
-- Alert Dialog component — confirmation dialog that requires an explicit user action (`role="alertdialog"`). Cannot be dismissed by Escape or backdrop click. Sub-parts: header, title, description, media, footer, action, cancel. Size variants (default/sm) with responsive media grid layout. Auto-linked `aria-labelledby` and `aria-describedby`.
-- AspectRatio component — lightweight wrapper that applies an aspect ratio via inline style. Accepts any `ratio:` value (defaults to 16:9).
-- Slider component — range input with track, thumb, and fill styling. Supports min/max/step/value, three sizes (sm/md/lg), and disabled state. Stimulus controller for real-time value display.
-- Empty component `:actions` slot for placing buttons below the description.
-- Button `method:` prop — renders a Rails `button_to` form for DELETE/POST/PUT/PATCH actions while preserving all Button styling.
-- Icons guide added to documentation site.
-
-### Fixed
-
-- InputOTP slots missing visible border when a separator is placed inside a group.
-- Sidebar header and footer now use `flex-col` layout matching shadcn structure.
-
-## [0.2.2.pre] - 2026-03-03
-
-### Fixed
-
-- Dashboard layout rendering — components called without a block inside a layout (e.g., sidebar toggle, collapse) would capture the entire page template via ERB yield bubbling, breaking the dashboard grid. The `kui()` helper now passes an empty proc to prevent yield from reaching the layout.
-- Dashboard toggle and collapse icon sizing — SVG icons now render at the correct size via `[&>svg]:size-4`.
-
-## [0.2.1.pre] - 2026-03-03
-
-### Fixed
-
-- Propshaft `stylesheet_link_tag :app` compatibility — the Rails 8.1 default `:app` symbol caused Propshaft to serve `tailwindcss-rails` engine CSS stubs directly to the browser, resulting in 404 errors for absolute filesystem paths. Kiso now filters these build-time intermediates from Propshaft's stylesheet resolution automatically. Host apps using either `:app` or explicit `"tailwind"` work correctly.
-
-## [0.2.0.pre] - 2026-03-03
-
-### Added
-
-- InputOTP component — one-time password input with individual character slots, auto-advance, paste support, and mobile SMS autofill via `autocomplete="one-time-code"`. Stimulus controller distributes a single transparent input to visual slot divs. Sub-parts: group, slot, separator. Dispatches `change` and `complete` events for auto-submit workflows.
-- SelectNative component — styled native `<select>` with chevron icon overlay. Variant × size axes matching Input (outline/soft/ghost, sm/md/lg). No JavaScript required.
-- Sidebar state variants — `kui-sidebar-open:` and `kui-sidebar-closed:` custom Tailwind variants for showing/hiding any element based on sidebar open/closed state. Composable with breakpoints (e.g., `kui-sidebar-open:lg:hidden`).
-- Custom toggle icon override — sidebar toggle and collapse buttons accept a block to replace the default icon.
-- Auto body base styles — engine CSS now applies `bg-background text-foreground antialiased` on `<body>` via `@layer base`, so host apps no longer need to add these classes manually.
-
-## [0.1.1.pre] - 2026-03-03
-
-### Added
-
-- Dashboard layout system — sidebar, navbar, panel, toolbar, and nav components with cookie-persisted sidebar state
-- Avatar component with image, fallback, badge, and group support
-- Form components — Field, Label, Input, Textarea, InputGroup, Checkbox, RadioGroup, Switch, Select, Combobox
-- Overlay components — Popover, DropdownMenu, Command palette
-- Navigation components — Breadcrumb, Pagination
-- Element components — Kbd, Toggle, ToggleGroup
-- Dark mode system — `kiso_theme_script` helper, ColorModeButton, ColorModeSelect
-- Floating UI positioning for popovers and dropdowns
-- Global theme overrides via `Kiso.configure`
-- Configurable default icons via `kiso_component_icon`
-- Getting Started guide
-
-### Changed
-
-- Renamed `kiso()` helper to `kui()` to avoid Rails route proxy collision
-- Renamed `empty_state` to `empty` to match shadcn naming
-- Adopted `data-slot` convention from shadcn v4
-
-## [0.1.0.pre] - 2026-02-25
-
-### Added
-
-- Core engine with `kui()` component helper and `kiso_prepare_options` builder
-- `class_variants` + `tailwind_merge` integration for variant definitions
-- Theme CSS with 7 palettes, surface tokens, and dark mode
-- Badge component (color × variant × size, pill shape, SVG handling)
-- Alert component (color × variant, CSS Grid layout, title/description sub-parts)
-- Button component (6 variants, smart tag, 5 sizes, icon support)
-- Card component (3 variants, 6 sub-parts, shadcn gap-6/py-6 spacing)
-- Separator component (horizontal/vertical, decorative prop)
-- Empty State component (5 sub-parts, media variant)
-- Lookbook component previews
-- Bridgetown documentation site
-
-[Unreleased]: https://github.com/steveclarke/kiso/compare/v0.4.2.pre...HEAD
-[0.4.2.pre]: https://github.com/steveclarke/kiso/releases/tag/v0.4.2.pre
-[0.4.1.pre]: https://github.com/steveclarke/kiso/releases/tag/v0.4.1.pre
-[0.4.0.pre]: https://github.com/steveclarke/kiso/releases/tag/v0.4.0.pre
-[0.3.0.pre]: https://github.com/steveclarke/kiso/releases/tag/v0.3.0.pre
-[0.2.2.pre]: https://github.com/steveclarke/kiso/releases/tag/v0.2.2.pre
-[0.2.1.pre]: https://github.com/steveclarke/kiso/releases/tag/v0.2.1.pre
-[0.2.0.pre]: https://github.com/steveclarke/kiso/releases/tag/v0.2.0.pre
-[0.1.1.pre]: https://github.com/steveclarke/kiso/releases/tag/v0.1.1.pre
-[0.1.0.pre]: https://github.com/steveclarke/kiso/releases/tag/v0.1.0.pre