kiso 0.1.0.pre → 0.2.0.pre

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

@@ -0,0 +1,307 @@
+import { Controller } from "@hotwired/stimulus"
+import { highlightItem, wrapIndex } from "kiso-ui/utils/highlight"
+import { startPositioning } from "kiso-ui/utils/positioning"
+
+/**
+ * Custom select dropdown with keyboard navigation and form integration.
+ * Renders a trigger button, hidden listbox, and syncs selection to a hidden input.
+ *
+ * @example
+ *   <div data-controller="kiso--select" data-slot="select">
+ *     <button data-kiso--select-target="trigger"
+ *             data-action="click->kiso--select#toggle keydown->kiso--select#triggerKeydown">
+ *       <span data-kiso--select-target="valueDisplay" data-placeholder="Pick one...">
+ *         <span class="text-muted-foreground">Pick one...</span>
+ *       </span>
+ *     </button>
+ *     <div data-kiso--select-target="content" role="listbox" hidden>
+ *       <div data-kiso--select-target="item" data-value="apple"
+ *            data-action="click->kiso--select#selectItem" role="option">
+ *         <span data-kiso--select-target="indicator" hidden>✓</span>
+ *         <span>Apple</span>
+ *       </div>
+ *     </div>
+ *     <input type="hidden" data-kiso--select-target="hiddenInput" name="fruit">
+ *   </div>
+ *
+ * @property {HTMLElement} triggerTarget - Button that opens/closes the dropdown
+ * @property {HTMLElement} contentTarget - The dropdown panel (listbox)
+ * @property {HTMLElement[]} itemTargets - Selectable option elements
+ * @property {HTMLElement[]} indicatorTargets - Checkmark indicators inside items
+ * @property {HTMLInputElement} hiddenInputTarget - Hidden input for form submission
+ * @property {HTMLElement} valueDisplayTarget - Span showing the current selection text
+ *
+ * @fires kiso--select:change - When selection changes. Detail: `{ value: string }`.
+ */
+export default class extends Controller {
+  static targets = ["trigger", "content", "item", "indicator", "hiddenInput", "valueDisplay"]
+
+  connect() {
+    this._open = false
+    this._highlightedIndex = -1
+    this._handleOutsideClick = this._handleOutsideClick.bind(this)
+    this._handleKeydown = this._handleKeydown.bind(this)
+  }
+
+  disconnect() {
+    this._cleanupPosition?.()
+    this._removeGlobalListeners()
+  }
+
+  /**
+   * Toggles the dropdown open or closed.
+   * Skips if the click was auto-generated by a Space keyup (already handled in triggerKeydown).
+   *
+   * @param {Event} event
+   */
+  toggle(event) {
+    if (this._ignoreNextClick) {
+      this._ignoreNextClick = false
+      event.preventDefault()
+      return
+    }
+    event.preventDefault()
+    if (this._open) {
+      this.close()
+    } else {
+      this.open()
+    }
+  }
+
+  /** Opens the dropdown, positions it, and highlights the selected or first item. */
+  open() {
+    if (this._open || this.triggerTarget.disabled) return
+
+    this._open = true
+    this.contentTarget.hidden = false
+    this.triggerTarget.setAttribute("aria-expanded", "true")
+    this._positionContent()
+    this._addGlobalListeners()
+
+    // Highlight the currently selected item, or the first item
+    const selectedIndex = this._enabledItems.findIndex(
+      (item) => item.getAttribute("aria-selected") === "true",
+    )
+    this._highlightIndex(selectedIndex >= 0 ? selectedIndex : 0)
+  }
+
+  /** Closes the dropdown and returns focus to the trigger. */
+  close() {
+    if (!this._open) return
+
+    this._cleanupPosition?.()
+    this._cleanupPosition = null
+    this._open = false
+    this.contentTarget.hidden = true
+    this.triggerTarget.setAttribute("aria-expanded", "false")
+    this._highlightIndex(-1)
+    this._removeGlobalListeners()
+    this.triggerTarget.focus()
+  }
+
+  /**
+   * Selects an item when clicked.
+   *
+   * @param {Event} event - Click event from an item element
+   */
+  selectItem(event) {
+    const item = event.currentTarget
+    if (item.dataset.disabled === "true") return
+
+    const value = item.dataset.value
+    const text = item.querySelector("[data-slot='select-item-text']")?.textContent?.trim() || value
+
+    this._setValue(value, text)
+    this.close()
+  }
+
+  /**
+   * Opens the dropdown on ArrowDown, ArrowUp, Space, or Enter when trigger is focused.
+   *
+   * @param {KeyboardEvent} event
+   */
+  triggerKeydown(event) {
+    switch (event.key) {
+      case "ArrowDown":
+      case "ArrowUp":
+      case " ":
+      case "Enter":
+        event.preventDefault()
+        if (!this._open) {
+          // Stop propagation so the global _handleKeydown (added during open())
+          // does not also process this same keydown event — otherwise Space/Enter
+          // would immediately select the highlighted item and close the dropdown.
+          event.stopPropagation()
+          this._ignoreNextClick = true
+          this.open()
+        }
+        break
+    }
+  }
+
+  // --- Private ---
+
+  /**
+   * Updates the hidden input, display text, aria-selected states, and indicators.
+   *
+   * @param {string} value - The selected value
+   * @param {string} text - The display text for the selection
+   * @private
+   */
+  _setValue(value, text) {
+    // Update hidden input
+    if (this.hasHiddenInputTarget) {
+      this.hiddenInputTarget.value = value
+    }
+
+    // Update displayed value
+    if (this.hasValueDisplayTarget) {
+      this.valueDisplayTarget.textContent = text
+    }
+
+    // Update aria-selected on items and show/hide indicators
+    this.itemTargets.forEach((item) => {
+      const isSelected = item.dataset.value === value
+      item.setAttribute("aria-selected", isSelected)
+
+      // Find the indicator within this item
+      const indicator = item.querySelector("[data-slot='select-item-indicator']")
+      if (indicator) {
+        indicator.hidden = !isSelected
+      }
+    })
+
+    // Dispatch change event
+    this.dispatch("change", { detail: { value } })
+  }
+
+  /**
+   * Returns items that are not disabled.
+   *
+   * @returns {HTMLElement[]}
+   * @private
+   */
+  get _enabledItems() {
+    return this.itemTargets.filter((item) => item.dataset.disabled !== "true")
+  }
+
+  /**
+   * Highlights an item at the given index and scrolls it into view.
+   * Pass -1 to clear all highlights.
+   *
+   * @param {number} index - Index within enabled items, or -1 to clear
+   * @private
+   */
+  _highlightIndex(index) {
+    this._highlightedIndex = index
+    highlightItem(this.itemTargets, this._enabledItems, index)
+  }
+
+  /**
+   * Positions the dropdown relative to the trigger with matching width.
+   * Starts auto-updating on scroll/resize.
+   *
+   * @private
+   */
+  _positionContent() {
+    this._cleanupPosition = startPositioning(this.triggerTarget, this.contentTarget, {
+      matchWidth: true,
+    })
+  }
+
+  /**
+   * Closes the dropdown when clicking outside the component.
+   *
+   * @param {MouseEvent} event
+   * @private
+   */
+  _handleOutsideClick(event) {
+    if (!this.element.contains(event.target)) {
+      this.close()
+    }
+  }
+
+  /**
+   * Handles keyboard navigation while the dropdown is open.
+   * Supports ArrowDown/Up, Enter, Space, Escape, Home, End, Tab, and type-ahead.
+   *
+   * @param {KeyboardEvent} event
+   * @private
+   */
+  _handleKeydown(event) {
+    if (!this._open) return
+
+    const items = this._enabledItems
+
+    switch (event.key) {
+      case "ArrowDown":
+        event.preventDefault()
+        this._highlightIndex(wrapIndex(this._highlightedIndex, 1, items.length))
+        break
+      case "ArrowUp":
+        event.preventDefault()
+        this._highlightIndex(wrapIndex(this._highlightedIndex, -1, items.length))
+        break
+      case "Enter":
+      case " ":
+        event.preventDefault()
+        if (this._highlightedIndex >= 0 && this._highlightedIndex < items.length) {
+          const item = items[this._highlightedIndex]
+          if (item.dataset.disabled !== "true") {
+            const value = item.dataset.value
+            const text =
+              item.querySelector("[data-slot='select-item-text']")?.textContent?.trim() || value
+            this._setValue(value, text)
+            this.close()
+          }
+        }
+        break
+      case "Escape":
+        event.preventDefault()
+        this.close()
+        break
+      case "Home":
+        event.preventDefault()
+        this._highlightIndex(0)
+        break
+      case "End":
+        event.preventDefault()
+        this._highlightIndex(items.length - 1)
+        break
+      case "Tab":
+        this.close()
+        break
+      default:
+        // Type-ahead: focus first item starting with typed character
+        if (event.key.length === 1 && !event.ctrlKey && !event.metaKey) {
+          const char = event.key.toLowerCase()
+          const startIndex = this._highlightedIndex + 1
+          const matchIndex = items.findIndex((item, i) => {
+            const actualIndex = (startIndex + i) % items.length
+            const text = items[actualIndex]
+              .querySelector("[data-slot='select-item-text']")
+              ?.textContent?.trim()
+              .toLowerCase()
+            return text?.startsWith(char)
+          })
+          if (matchIndex >= 0) {
+            const actualIndex = (startIndex + matchIndex) % items.length
+            this._highlightIndex(actualIndex)
+          }
+        }
+        break
+    }
+  }
+
+  /** @private */
+  _addGlobalListeners() {
+    document.addEventListener("click", this._handleOutsideClick, true)
+    document.addEventListener("keydown", this._handleKeydown)
+  }
+
+  /** @private */
+  _removeGlobalListeners() {
+    document.removeEventListener("click", this._handleOutsideClick, true)
+    document.removeEventListener("keydown", this._handleKeydown)
+  }
+}

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

@@ -0,0 +1,84 @@
+import { Controller } from "@hotwired/stimulus"
+
+/**
+ * Kiso sidebar toggle controller.
+ *
+ * Manages the dashboard sidebar open/closed state via a single
+ * `data-sidebar-open` attribute on the controller element. CSS cascade
+ * handles all visual changes — this controller only manages the
+ * boolean attribute and persists the preference to a cookie for
+ * FOUC-free server-side restoration on the next page load.
+ *
+ * Register as `kiso--sidebar` (the engine index does this automatically).
+ *
+ * @example
+ * <div data-slot="dashboard-group"
+ *      data-controller="kiso--sidebar"
+ *      data-sidebar-open="true">
+ *   <header data-slot="dashboard-navbar">
+ *     <button data-kiso--sidebar-target="trigger"
+ *             data-action="click->kiso--sidebar#toggle"
+ *             aria-expanded="true"
+ *             aria-controls="dashboard-sidebar">
+ *       <!-- hamburger icon -->
+ *     </button>
+ *   </header>
+ *   <aside data-slot="dashboard-sidebar" id="dashboard-sidebar">
+ *     <div data-slot="dashboard-sidebar-inner">
+ *       <!-- sidebar content -->
+ *     </div>
+ *   </aside>
+ *   <main data-slot="dashboard-panel"><!-- page content --></main>
+ *   <div data-slot="dashboard-scrim"
+ *        data-kiso--sidebar-target="scrim"
+ *        data-action="click->kiso--sidebar#closeOnMobile"
+ *        aria-hidden="true"></div>
+ * </div>
+ *
+ * @property {Element[]} triggerTargets - Toggle/collapse buttons that control the sidebar
+ * @property {Element} scrimTarget   - The mobile overlay scrim
+ */
+export default class extends Controller {
+  static targets = ["trigger", "scrim"]
+
+  /**
+   * Toggles the sidebar open/closed state.
+   *
+   * Flips `data-sidebar-open` on the controller element, syncs
+   * `aria-expanded` on the trigger target, and persists the new
+   * state to a one-year cookie for FOUC-free server-side restoration.
+   */
+  toggle() {
+    const isOpen = this.element.dataset.sidebarOpen !== "false"
+    this.#setState(!isOpen)
+  }
+
+  /**
+   * 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.
+   */
+  closeOnMobile() {
+    if (matchMedia("(max-width: 767px)").matches) {
+      this.#setState(false)
+    }
+  }
+
+  /**
+   * Sets the sidebar state, syncs aria-expanded, and persists to cookie.
+   *
+   * @param {boolean} open - Whether the sidebar should be open
+   * @private
+   */
+  #setState(open) {
+    const value = String(open)
+
+    this.element.dataset.sidebarOpen = value
+    document.cookie = `sidebar_open=${value};path=/;max-age=31536000;SameSite=Lax`
+
+    for (const trigger of this.triggerTargets) {
+      trigger.setAttribute("aria-expanded", value)
+    }
+  }
+}

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

@@ -0,0 +1,89 @@
+import { Controller } from "@hotwired/stimulus"
+
+/**
+ * Kiso theme toggle controller.
+ *
+ * Toggles the `.dark` class on `<html>` and persists the preference
+ * to both `localStorage` and a cookie. Works in concert with the
+ * `kiso_theme_script` helper which prevents FOUC on initial page load.
+ *
+ * Supports three modes: "light", "dark", "system". The `toggle` action
+ * cycles light ↔ dark. The `set` action accepts any of the three values.
+ *
+ * Register as `kiso--theme` (the engine index does this automatically).
+ *
+ * @example Toggle button (light ↔ dark)
+ * <button data-controller="kiso--theme"
+ *         data-action="click->kiso--theme#toggle"
+ *         aria-label="Toggle dark mode">
+ *   <!-- sun / moon icon -->
+ * </button>
+ *
+ * @example Set a specific mode via kiso--select:change
+ * <div data-controller="kiso--theme"
+ *      data-action="kiso--select:change->kiso--theme#set">
+ *   <!-- kui(:select) with light/dark/system items -->
+ * </div>
+ *
+ * @fires kiso:theme-change on document.documentElement when theme changes
+ */
+export default class extends Controller {
+  /**
+   * Toggles dark mode on the document root.
+   *
+   * Cycles between light and dark. Persists the preference
+   * to `localStorage` and a one-year cookie.
+   */
+  toggle() {
+    const dark = document.documentElement.classList.toggle("dark")
+    this.#persist(dark ? "dark" : "light")
+  }
+
+  /**
+   * Sets a specific theme preference.
+   *
+   * Accepts "light", "dark", or "system" via event detail.
+   * When "system", resolves to the OS preference via matchMedia.
+   *
+   * @param {CustomEvent} event - Event with detail.value
+   */
+  set(event) {
+    const preference = event.detail?.value
+    if (!preference) return
+
+    this.#apply(preference)
+    this.#persist(preference)
+  }
+
+  /**
+   * Resolves a preference to an actual theme and applies it.
+   *
+   * @param {string} preference - "light", "dark", or "system"
+   * @private
+   */
+  #apply(preference) {
+    let resolved = preference
+    if (preference === "system") {
+      resolved = matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light"
+    }
+    document.documentElement.classList.toggle("dark", resolved === "dark")
+  }
+
+  /**
+   * Persists preference and dispatches change event.
+   *
+   * @param {string} preference - "light", "dark", or "system"
+   * @private
+   */
+  #persist(preference) {
+    localStorage.setItem("theme", preference)
+    document.cookie = `theme=${preference};path=/;max-age=31536000;SameSite=Lax`
+
+    document.documentElement.dispatchEvent(
+      new CustomEvent("kiso:theme-change", {
+        detail: { theme: preference },
+        bubbles: true,
+      }),
+    )
+  }
+}

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

@@ -0,0 +1,24 @@
+import { Controller } from "@hotwired/stimulus"
+
+/**
+ * Manages pressed state for a standalone toggle button.
+ * Toggles `data-state` between "on" and "off" and updates `aria-pressed`.
+ *
+ * @example
+ *   <button data-controller="kiso--toggle"
+ *           data-action="click->kiso--toggle#toggle"
+ *           data-state="off" aria-pressed="false">
+ *     Bold
+ *   </button>
+ */
+export default class extends Controller {
+  /**
+   * Toggles the pressed state of the element.
+   * Flips `data-state` between "on"/"off" and syncs `aria-pressed`.
+   */
+  toggle() {
+    const pressed = this.element.dataset.state === "on"
+    this.element.dataset.state = pressed ? "off" : "on"
+    this.element.setAttribute("aria-pressed", !pressed)
+  }
+}

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

@@ -0,0 +1,128 @@
+import { Controller } from "@hotwired/stimulus"
+
+/**
+ * Manages selection state for a group of toggle buttons.
+ * Supports single (radio-like) and multiple (checkbox-like) selection modes.
+ *
+ * @example
+ *   <div data-controller="kiso--toggle-group"
+ *        data-kiso--toggle-group-type-value="single">
+ *     <button data-kiso--toggle-group-target="item"
+ *             data-action="click->kiso--toggle-group#toggle"
+ *             data-value="left" data-state="off" aria-pressed="false">
+ *       Left
+ *     </button>
+ *   </div>
+ *
+ * @property {HTMLElement[]} itemTargets - Toggle buttons in the group
+ * @property {string} typeValue - Selection mode: "single" or "multiple"
+ * @property {string} variantValue - Inherited variant for styling context
+ * @property {string} sizeValue - Inherited size for styling context
+ *
+ * @fires kiso--toggle-group:change - When selection changes.
+ *   Detail: `{ value: string | null }` (single) or `{ value: string[] }` (multiple).
+ */
+export default class extends Controller {
+  static targets = ["item"]
+  static values = {
+    type: { type: String, default: "single" },
+    variant: { type: String, default: "default" },
+    size: { type: String, default: "default" },
+  }
+
+  /**
+   * Handles a toggle click on one of the group items.
+   * In single mode, deselects all others first (allows deselect).
+   * In multiple mode, toggles the clicked item independently.
+   *
+   * @param {Event} event - The click event from a group item
+   */
+  toggle(event) {
+    const item = event.currentTarget
+    const pressed = item.dataset.state === "on"
+
+    if (this.typeValue === "single") {
+      // In single mode, deselect all others first
+      this.itemTargets.forEach((target) => {
+        target.dataset.state = "off"
+        target.setAttribute("aria-pressed", "false")
+      })
+
+      // Toggle the clicked item (allow deselect in single mode)
+      if (!pressed) {
+        item.dataset.state = "on"
+        item.setAttribute("aria-pressed", "true")
+      }
+    } else {
+      // In multiple mode, toggle independently
+      item.dataset.state = pressed ? "off" : "on"
+      item.setAttribute("aria-pressed", !pressed)
+    }
+
+    this.#dispatchChange()
+  }
+
+  /** Sets up arrow-key navigation between items. */
+  connect() {
+    this.element.addEventListener("keydown", this.#handleKeydown)
+  }
+
+  /** Tears down the keydown listener. */
+  disconnect() {
+    this.element.removeEventListener("keydown", this.#handleKeydown)
+  }
+
+  /**
+   * Handles arrow key, Home, and End navigation between items.
+   * Wraps around at boundaries.
+   *
+   * @param {KeyboardEvent} event
+   */
+  #handleKeydown = (event) => {
+    const items = this.itemTargets.filter((item) => !item.disabled)
+    const currentIndex = items.indexOf(document.activeElement)
+
+    if (currentIndex === -1) return
+
+    let nextIndex
+    switch (event.key) {
+      case "ArrowRight":
+      case "ArrowDown":
+        event.preventDefault()
+        nextIndex = (currentIndex + 1) % items.length
+        items[nextIndex].focus()
+        break
+      case "ArrowLeft":
+      case "ArrowUp":
+        event.preventDefault()
+        nextIndex = (currentIndex - 1 + items.length) % items.length
+        items[nextIndex].focus()
+        break
+      case "Home":
+        event.preventDefault()
+        items[0].focus()
+        break
+      case "End":
+        event.preventDefault()
+        items[items.length - 1].focus()
+        break
+    }
+  }
+
+  /**
+   * Dispatches a "change" event with the currently selected value(s).
+   * Single mode emits `{ value: string | null }`,
+   * multiple mode emits `{ value: string[] }`.
+   */
+  #dispatchChange() {
+    const selectedValues = this.itemTargets
+      .filter((item) => item.dataset.state === "on")
+      .map((item) => item.dataset.value)
+
+    this.dispatch("change", {
+      detail: {
+        value: this.typeValue === "single" ? selectedValues[0] || null : selectedValues,
+      },
+    })
+  }
+}

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

@@ -0,0 +1,8 @@
+/**
+ * CSS selector for all natively focusable elements that are not disabled
+ * or explicitly removed from the tab order.
+ *
+ * @type {string}
+ */
+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

@@ -0,0 +1,43 @@
+/**
+ * Shared highlight and index utilities for list-based components.
+ * Used by select, combobox, command, and dropdown_menu controllers.
+ *
+ * @module utils/highlight
+ */
+
+/**
+ * Highlights an item at the given index. Clears the attribute from all
+ * 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[]} 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
+ */
+export function highlightItem(clearItems, items, index, { attr = "data-highlighted" } = {}) {
+  clearItems.forEach((item) => item.removeAttribute(attr))
+
+  if (index >= 0 && index < items.length) {
+    items[index].setAttribute(attr, "")
+    items[index].scrollIntoView({ block: "nearest" })
+  }
+}
+
+/**
+ * Wraps an index within a range, cycling from end to start and vice versa.
+ *
+ * @param {number} current - Current index
+ * @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
+ */
+export function wrapIndex(current, direction, length) {
+  if (length === 0) return -1
+
+  let next = current + direction
+  if (next < 0) next = length - 1
+  if (next >= length) next = 0
+  return next
+}