phlex_kit 0.2.0

data/app/javascript/phlex_kit/controllers/toast_controller.js

@@ -0,0 +1,153 @@
+import { Controller } from "@hotwired/stimulus"
+
+const SWIPE_THRESHOLD = 45
+const TIME_BEFORE_UNMOUNT = 200
+
+// Ported from ruby_ui's toast controller (Stimulus-only upstream), identifiers and
+// events renamed ruby-ui → phlex-kit; behaviour (timer, swipe, Escape) unchanged.
+// Connects to data-controller="phlex-kit--toast"
+export default class extends Controller {
+  static values = {
+    duration: { type: Number, default: 4000 },
+    dismissible: { type: Boolean, default: true },
+    invert: { type: Boolean, default: false },
+    onDismiss: String,
+    onAutoClose: String,
+  }
+
+  connect() {
+    this._timer = null
+    this._startedAt = 0
+    this._remaining = this.durationValue
+    this._paused = false
+    this._swipe = { active: false, x: 0, y: 0, startedAt: 0 }
+
+    this._onPointerDown = this._onPointerDown.bind(this)
+    this._onPointerMove = this._onPointerMove.bind(this)
+    this._onPointerUp = this._onPointerUp.bind(this)
+    this._onPointerEnter = () => this._pause()
+    this._onPointerLeave = () => { if (!this._swipe.active) this._resume() }
+    this._onKeyDown = this._onKeyDown.bind(this)
+    this._onForceDismiss = (e) => { e.stopPropagation(); this._close() }
+    this._onRestart = () => this._restart()
+    this._onRegionPause = () => this._pause()
+    this._onRegionResume = () => this._resume()
+
+    this.element.addEventListener("pointerdown", this._onPointerDown)
+    this.element.addEventListener("pointerenter", this._onPointerEnter)
+    this.element.addEventListener("pointerleave", this._onPointerLeave)
+    this.element.addEventListener("keydown", this._onKeyDown)
+    this.element.addEventListener("phlex-kit:toast:force-dismiss", this._onForceDismiss)
+    this.element.addEventListener("phlex-kit:toast:restart", this._onRestart)
+    document.addEventListener("phlex-kit:toast:pause", this._onRegionPause)
+    document.addEventListener("phlex-kit:toast:resume", this._onRegionResume)
+
+    requestAnimationFrame(() => {
+      this.element.dataset.state = "open"
+      this._start()
+    })
+  }
+
+  disconnect() {
+    this._clearTimer()
+    this.element.removeEventListener("pointerdown", this._onPointerDown)
+    this.element.removeEventListener("pointerenter", this._onPointerEnter)
+    this.element.removeEventListener("pointerleave", this._onPointerLeave)
+    this.element.removeEventListener("keydown", this._onKeyDown)
+    this.element.removeEventListener("phlex-kit:toast:force-dismiss", this._onForceDismiss)
+    this.element.removeEventListener("phlex-kit:toast:restart", this._onRestart)
+    document.removeEventListener("phlex-kit:toast:pause", this._onRegionPause)
+    document.removeEventListener("phlex-kit:toast:resume", this._onRegionResume)
+  }
+
+  dismiss(e) {
+    e?.preventDefault()
+    if (!this.dismissibleValue) return
+    this._close("dismiss")
+  }
+
+  _close(reason) {
+    if (this.element.dataset.state === "closing") return
+    this.element.dataset.state = "closing"
+    this.element.dispatchEvent(new CustomEvent(reason === "auto" ? "phlex-kit:toast:auto-close" : "phlex-kit:toast:dismiss", { bubbles: true, detail: { id: this.element.id } }))
+    setTimeout(() => this.element.remove(), TIME_BEFORE_UNMOUNT)
+  }
+
+  _start() {
+    if (!Number.isFinite(this.durationValue) || this.durationValue <= 0) return
+    this._startedAt = performance.now()
+    this._remaining = this.durationValue
+    this._timer = setTimeout(() => this._close("auto"), this._remaining)
+  }
+
+  _restart() {
+    this._clearTimer()
+    this._start()
+  }
+
+  _pause() {
+    if (this._paused || !this._timer) return
+    this._paused = true
+    clearTimeout(this._timer)
+    this._timer = null
+    this._remaining -= performance.now() - this._startedAt
+  }
+
+  _resume() {
+    if (!this._paused) return
+    this._paused = false
+    if (this._remaining <= 0) return this._close("auto")
+    this._startedAt = performance.now()
+    this._timer = setTimeout(() => this._close("auto"), this._remaining)
+  }
+
+  _clearTimer() {
+    if (this._timer) clearTimeout(this._timer)
+    this._timer = null
+  }
+
+  _onKeyDown(e) {
+    if (e.key === "Escape" && this.dismissibleValue) this.dismiss(e)
+  }
+
+  _onPointerDown(e) {
+    if (!this.dismissibleValue) return
+    if (e.target.closest("button")) return
+    try { this.element.setPointerCapture(e.pointerId) } catch {}
+    this._swipe = { active: true, x: e.clientX, y: e.clientY, startedAt: performance.now(), pointerId: e.pointerId }
+    this.element.dataset.swipe = "start"
+    this.element.addEventListener("pointermove", this._onPointerMove)
+    this.element.addEventListener("pointerup", this._onPointerUp)
+    this.element.addEventListener("pointercancel", this._onPointerUp)
+  }
+
+  _onPointerMove(e) {
+    const dx = e.clientX - this._swipe.x
+    const dy = e.clientY - this._swipe.y
+    this.element.dataset.swipe = "move"
+    this.element.style.transform = `translate(${dx}px, ${dy}px)`
+  }
+
+  _onPointerUp(e) {
+    const dx = e.clientX - this._swipe.x
+    const dy = e.clientY - this._swipe.y
+    const dist = Math.hypot(dx, dy)
+    const dt = performance.now() - this._swipe.startedAt
+    const velocity = dist / Math.max(dt, 1)
+    this.element.removeEventListener("pointermove", this._onPointerMove)
+    this.element.removeEventListener("pointerup", this._onPointerUp)
+    this.element.removeEventListener("pointercancel", this._onPointerUp)
+    this._swipe.active = false
+    if (dist > SWIPE_THRESHOLD || velocity > 0.5) {
+      this.element.style.setProperty("--swipe-end-x", `${Math.sign(dx) * 500}px`)
+      this.element.style.setProperty("--swipe-end-y", `${Math.sign(dy) * 500}px`)
+      this.element.dataset.swipe = "end"
+      this.element.style.transform = ""
+      this._close("dismiss")
+    } else {
+      this.element.dataset.swipe = "cancel"
+      this.element.style.transform = ""
+      this._resume()
+    }
+  }
+}

data/app/javascript/phlex_kit/controllers/toaster_controller.js

@@ -0,0 +1,321 @@
+import { Controller } from "@hotwired/stimulus"
+
+const VARIANTS = ["default", "success", "error", "warning", "info", "loading"]
+
+let streamActionRegistered = false
+
+function registerStreamAction() {
+  if (streamActionRegistered) return
+  if (typeof window === "undefined") return
+  const Turbo = window.Turbo
+  if (!Turbo?.StreamActions) return
+  Turbo.StreamActions.toast = function () {
+    const detail = {}
+    for (const attr of this.attributes) {
+      if (attr.name === "action" || attr.name === "target" || attr.name === "targets") continue
+      detail[attr.name] = attr.value
+    }
+    if (detail.duration != null && detail.duration !== "") detail.duration = Number(detail.duration)
+    if (detail.dismissible != null) detail.dismissible = detail.dismissible !== "false"
+    window.dispatchEvent(new CustomEvent("phlex-kit:toast", { detail }))
+  }
+  streamActionRegistered = true
+}
+
+// Ported from ruby_ui's toaster controller (Stimulus-only upstream) with identifiers,
+// events and the window API renamed ruby-ui/RubyUI → phlex-kit/PhlexKit, and the
+// Tailwind pr-10 spawn class swapped for .pk-toast-with-close (toast.css).
+// Connects to data-controller="phlex-kit--toaster"
+export default class extends Controller {
+  static targets = ["skeleton", "toast", "actionTpl", "cancelTpl", "closeTpl"]
+  static values = {
+    position: { type: String, default: "bottom-right" },
+    expand: { type: Boolean, default: false },
+    max: { type: Number, default: 3 },
+    duration: { type: Number, default: 4000 },
+    gap: { type: Number, default: 14 },
+    offset: { type: Number, default: 24 },
+    theme: { type: String, default: "system" },
+    richColors: { type: Boolean, default: false },
+    closeButton: { type: Boolean, default: false },
+    hotkey: { type: String, default: "alt+t" },
+    dir: { type: String, default: "ltr" },
+  }
+
+  // State the target callbacks touch lives here, NOT in connect(): Stimulus
+  // fires toastTargetConnected() BEFORE connect() for toasts already in the
+  // HTML (server-rendered flash), and upstream's connect()-time init crashes
+  // on that path.
+  initialize() {
+    this._heights = new Map()
+    this._resizeObservers = new WeakMap()
+    this._expanded = false
+  }
+
+  connect() {
+    this._expanded = this.expandValue
+    this._listEl = this.element.querySelector("ol") || (this.element.tagName === "OL" ? this.element : null)
+    this._registerGlobalApi()
+    registerStreamAction()
+    if (!this._listEl) return
+
+    this._onPointerEnter = () => this._setExpanded(true)
+    this._onPointerLeave = () => { if (!this.expandValue) this._setExpanded(false) }
+    this._onWindowToast = (e) => this._spawn(e.detail || {})
+    this._onWindowDismissAll = () => this._dismissById(null)
+    this._onKey = this._onKey.bind(this)
+
+    window.addEventListener("phlex-kit:toast", this._onWindowToast)
+    window.addEventListener("phlex-kit:toast:dismiss-all", this._onWindowDismissAll)
+    this._listEl.addEventListener("pointerenter", this._onPointerEnter)
+    this._listEl.addEventListener("pointerleave", this._onPointerLeave)
+    document.addEventListener("keydown", this._onKey)
+
+    // Settle any server-rendered toasts (their targetConnected ran pre-connect,
+    // before _listEl existed, so their reflow was a no-op).
+    this._reflow()
+  }
+
+  disconnect() {
+    window.removeEventListener("phlex-kit:toast", this._onWindowToast)
+    window.removeEventListener("phlex-kit:toast:dismiss-all", this._onWindowDismissAll)
+    this._listEl?.removeEventListener("pointerenter", this._onPointerEnter)
+    this._listEl?.removeEventListener("pointerleave", this._onPointerLeave)
+    document.removeEventListener("keydown", this._onKey)
+  }
+
+  toastTargetConnected(el) {
+    if (typeof ResizeObserver !== "undefined") {
+      const ro = new ResizeObserver(() => {
+        this._heights.set(el, el.offsetHeight)
+        this._reflow()
+      })
+      ro.observe(el)
+      this._resizeObservers.set(el, ro)
+    }
+    this._heights.set(el, el.offsetHeight || 64)
+    this._reflow()
+  }
+
+  toastTargetDisconnected(el) {
+    this._resizeObservers.get(el)?.disconnect()
+    this._resizeObservers.delete(el)
+    this._heights.delete(el)
+    this._reflow()
+  }
+
+  _spawn(detail) {
+    const variant = VARIANTS.includes(detail.variant) ? detail.variant : "default"
+    const tpl = this._skeletonFor(variant)
+    if (!tpl) return null
+    if (detail.position) {
+      this.element.setAttribute("data-position", detail.position)
+      this.positionValue = detail.position
+    }
+    const node = tpl.content.firstElementChild.cloneNode(true)
+
+    node.id = detail.id || `toast-${this._uuid()}`
+    if (detail.duration != null) {
+      const dur = detail.duration === Infinity ? 0 : detail.duration
+      node.setAttribute("data-phlex-kit--toast-duration-value", String(dur))
+    }
+    if (detail.dismissible === false) {
+      node.setAttribute("data-phlex-kit--toast-dismissible-value", "false")
+    }
+    if (detail.className) node.className += ` ${detail.className}`
+
+    const titleEl = node.querySelector('[data-slot="title"]')
+    if (titleEl) titleEl.textContent = detail.title || detail.message || ""
+    const descEl = node.querySelector('[data-slot="description"]')
+    if (descEl) {
+      if (detail.description) descEl.textContent = detail.description
+      else descEl.remove()
+    }
+
+    if (detail.action && detail.action.label && this.hasActionTplTarget) {
+      const btn = this._cloneSlot(this.actionTplTarget)
+      btn.textContent = detail.action.label
+      btn.addEventListener("click", (ev) => {
+        try { detail.action.onClick?.(ev) } finally {
+          node.dispatchEvent(new CustomEvent("phlex-kit:toast:force-dismiss", { bubbles: true }))
+        }
+      })
+      node.appendChild(btn)
+    }
+
+    if (detail.cancel && detail.cancel.label && this.hasCancelTplTarget) {
+      const btn = this._cloneSlot(this.cancelTplTarget)
+      btn.textContent = detail.cancel.label
+      node.appendChild(btn)
+    }
+
+    if (detail.closeButton && this.hasCloseTplTarget) {
+      const x = this._cloneSlot(this.closeTplTarget)
+      node.classList.add("pk-toast-with-close")
+      node.appendChild(x)
+    }
+
+    this._listEl.appendChild(node)
+    return node.id
+  }
+
+  _dismissById(id) {
+    if (!id) {
+      this.toastTargets.forEach((el) =>
+        el.dispatchEvent(new CustomEvent("phlex-kit:toast:force-dismiss", { bubbles: true }))
+      )
+      return
+    }
+    const el = this._listEl.querySelector(`#${CSS.escape(id)}`)
+    if (el) el.dispatchEvent(new CustomEvent("phlex-kit:toast:force-dismiss", { bubbles: true }))
+  }
+
+  _skeletonFor(variant) {
+    return this.skeletonTargets.find((t) => t.dataset.variant === variant)
+  }
+
+  _cloneSlot(tpl) {
+    return tpl.content.firstElementChild.cloneNode(true)
+  }
+
+  _setExpanded(value) {
+    if (this._expanded === value) return
+    this._expanded = value
+    document.dispatchEvent(new CustomEvent(value ? "phlex-kit:toast:pause" : "phlex-kit:toast:resume"))
+    this._reflow()
+  }
+
+  _reflow() {
+    if (!this._listEl) return
+    const isBottom = this.positionValue.startsWith("bottom")
+    const items = this.toastTargets
+    const order = isBottom ? items.slice().reverse() : items.slice()
+    const heights = order.map(el => this._heights.get(el) || el.offsetHeight || 64)
+    const gap = this.gapValue
+    const peekOffset = 16
+    const peekScaleStep = 0.05
+    const peekOpacityStep = 0.2
+
+    const expandedHeight = heights.reduce((a, b) => a + b, 0) + gap * Math.max(0, heights.length - 1)
+    const collapsedHeight = (heights[0] || 0) + Math.min(2, Math.max(0, heights.length - 1)) * peekOffset
+    this._listEl.style.minHeight = `${this._expanded ? expandedHeight : collapsedHeight}px`
+
+    let acc = 0
+    order.forEach((el, i) => {
+      const visible = i < this.maxValue
+      let yOffset, scale, opacity
+
+      if (this._expanded) {
+        yOffset = acc + i * gap
+        scale = 1
+        opacity = visible ? 1 : 0
+      } else {
+        yOffset = i * peekOffset
+        scale = Math.max(0.85, 1 - i * peekScaleStep)
+        opacity = visible ? Math.max(0, 1 - i * peekOpacityStep) : 0
+      }
+
+      const sign = isBottom ? -1 : 1
+      const ty = sign * yOffset
+
+      el.style.setProperty("--opacity", String(opacity))
+      el.style.setProperty("--scale", String(scale))
+      el.style.setProperty("--y-offset", `${ty}px`)
+      el.style.transformOrigin = isBottom ? "center bottom" : "center top"
+      el.style.top = isBottom ? "auto" : "0"
+      el.style.bottom = isBottom ? "0" : "auto"
+      el.style.transform = `translate3d(0, ${ty}px, 0) scale(${scale})`
+      el.style.zIndex = String(1000 - i)
+      el.style.pointerEvents = visible ? "auto" : "none"
+      el.tabIndex = visible ? 0 : -1
+
+      acc += heights[i] || 0
+    })
+
+    this._enforceMax(items)
+  }
+
+  _enforceMax(items) {
+    if (items.length <= this.maxValue) return
+    const isBottom = this.positionValue.startsWith("bottom")
+    const dropping = items.length - this.maxValue
+    const candidates = isBottom ? items.slice(0, dropping) : items.slice(-dropping)
+    candidates.forEach(el => {
+      if (el.dataset.state !== "closing") {
+        el.dispatchEvent(new CustomEvent("phlex-kit:toast:force-dismiss", { bubbles: true }))
+      }
+    })
+  }
+
+  _onKey(e) {
+    const parts = (this.hotkeyValue || "alt+t").split("+")
+    const key = parts.pop()
+    const wantAlt = parts.includes("alt")
+    const wantCtrl = parts.includes("ctrl")
+    const wantMeta = parts.includes("meta")
+    if (e.key.toLowerCase() !== key.toLowerCase()) return
+    if (wantAlt !== e.altKey) return
+    if (wantCtrl !== e.ctrlKey) return
+    if (wantMeta !== e.metaKey) return
+    e.preventDefault()
+    const first = this._listEl.firstElementChild
+    first?.focus()
+  }
+
+  _registerGlobalApi() {
+    const fire = (variant, message, opts = {}) =>
+      window.dispatchEvent(new CustomEvent("phlex-kit:toast", {
+        detail: { ...opts, variant, message: opts.title || message }
+      }))
+
+    const api = (message, opts) => fire("default", message, opts)
+    api.success = (m, o) => fire("success", m, o)
+    api.error = (m, o) => fire("error", m, o)
+    api.warning = (m, o) => fire("warning", m, o)
+    api.info = (m, o) => fire("info", m, o)
+    api.loading = (m, o = {}) => fire("loading", m, { ...o, duration: o.duration ?? 0 })
+    api.dismiss = (id) => {
+      if (id) this._dismissById(id)
+      else window.dispatchEvent(new CustomEvent("phlex-kit:toast:dismiss-all"))
+    }
+    api.promise = (p, msgs = {}) => {
+      const id = `toast-${this._uuid()}`
+      fire("loading", typeof msgs.loading === "function" ? msgs.loading() : (msgs.loading || "Loading..."), { id, duration: 0 })
+      Promise.resolve(p).then(
+        (val) => this._mutate(id, "success", typeof msgs.success === "function" ? msgs.success(val) : msgs.success),
+        (err) => this._mutate(id, "error", typeof msgs.error === "function" ? msgs.error(err) : msgs.error)
+      )
+      return id
+    }
+
+    window.PhlexKit = window.PhlexKit || {}
+    window.PhlexKit.toast = api
+  }
+
+  _mutate(id, variant, text) {
+    const el = this._listEl.querySelector(`#${CSS.escape(id)}`)
+    if (!el) return
+    el.dataset.variant = variant
+    el.setAttribute("role", variant === "error" ? "alert" : "status")
+    this._swapIcon(el, variant)
+    const t = el.querySelector('[data-slot="title"]')
+    if (t && text) t.textContent = text
+    const dur = String(this.durationValue)
+    el.setAttribute("data-phlex-kit--toast-duration-value", dur)
+    el.dispatchEvent(new CustomEvent("phlex-kit:toast:restart", { bubbles: true }))
+  }
+
+  _swapIcon(el, variant) {
+    const iconHost = el.querySelector('[data-slot="icon"]')
+    if (!iconHost) return
+    const tpl = this._skeletonFor(variant)
+    if (!tpl) return
+    const sourceIcon = tpl.content.firstElementChild?.querySelector('[data-slot="icon"]')
+    iconHost.innerHTML = sourceIcon ? sourceIcon.innerHTML : ""
+  }
+
+  _uuid() {
+    if (typeof crypto !== "undefined" && crypto.randomUUID) return crypto.randomUUID()
+    return Math.random().toString(36).slice(2) + Date.now().toString(36)
+  }
+}

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

@@ -0,0 +1,25 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Connects to data-controller="phlex-kit--toggle"
+export default class extends Controller {
+  static targets = ["button", "input"]
+  static values = { pressed: Boolean, value: String, unpressedValue: String }
+
+  toggle() {
+    if (this.buttonTarget.disabled) return
+    this.pressedValue = !this.pressedValue
+  }
+
+  pressedValueChanged(current, previous) {
+    if (this.hasButtonTarget) {
+      this.buttonTarget.setAttribute("aria-pressed", current ? "true" : "false")
+      this.buttonTarget.dataset.state = current ? "on" : "off"
+    }
+    if (this.hasInputTarget) {
+      this.inputTarget.value = current ? this.valueValue : this.unpressedValueValue
+    }
+    if (previous !== undefined) {
+      this.dispatch("change", { detail: { pressed: current }, bubbles: true })
+    }
+  }
+}

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

@@ -0,0 +1,91 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Connects to data-controller="phlex-kit--toggle-group"
+export default class extends Controller {
+  static targets = ["item", "input"]
+  static values = { type: String, name: String }
+
+  connect() { this.reconcile() }
+
+  select(event) {
+    const item = event.currentTarget
+    if (item.disabled) return
+    if (this.typeValue === "single") {
+      this.itemTargets.forEach((el) => this.setPressed(el, el === item))
+    } else {
+      this.setPressed(item, !this.isPressed(item))
+    }
+    this.rebuildInputs()
+    this.updateRovingTabindex(item)
+  }
+
+  navigate(event) {
+    if (this.typeValue !== "single") return
+    const items = this.enabledItems()
+    if (items.length === 0) return
+    const currentIndex = items.indexOf(event.currentTarget)
+    let nextIndex = currentIndex
+    switch (event.key) {
+      case "ArrowRight": case "ArrowDown": nextIndex = (currentIndex + 1) % items.length; break
+      case "ArrowLeft": case "ArrowUp": nextIndex = (currentIndex - 1 + items.length) % items.length; break
+      case "Home": nextIndex = 0; break
+      case "End": nextIndex = items.length - 1; break
+      case " ": case "Enter": event.preventDefault(); event.currentTarget.click(); return
+      default: return
+    }
+    event.preventDefault()
+    const next = items[nextIndex]
+    this.updateRovingTabindex(next)
+    next.focus()
+  }
+
+  reconcile() {
+    if (this.typeValue === "single") {
+      const pressed = this.itemTargets.find((el) => this.isPressed(el))
+      const first = pressed || this.enabledItems()[0]
+      this.itemTargets.forEach((el) => el.setAttribute("tabindex", el === first ? "0" : "-1"))
+    } else {
+      this.itemTargets.forEach((el) => el.setAttribute("tabindex", "0"))
+    }
+    this.rebuildInputs()
+  }
+
+  isPressed(item) { return item.dataset.state === "on" }
+
+  setPressed(item, pressed) {
+    item.dataset.state = pressed ? "on" : "off"
+    if (this.typeValue === "single") {
+      item.setAttribute("aria-checked", pressed ? "true" : "false")
+    } else {
+      item.setAttribute("aria-pressed", pressed ? "true" : "false")
+    }
+  }
+
+  updateRovingTabindex(focusedItem) {
+    if (this.typeValue !== "single") return
+    this.itemTargets.forEach((el) => el.setAttribute("tabindex", el === focusedItem ? "0" : "-1"))
+  }
+
+  enabledItems() { return this.itemTargets.filter((el) => !el.disabled) }
+
+  rebuildInputs() {
+    if (!this.nameValue) return
+    this.inputTargets.forEach((el) => el.remove())
+    const pressed = this.itemTargets.filter((el) => this.isPressed(el))
+    if (this.typeValue === "single") {
+      const val = pressed[0]?.dataset.value || ""
+      this.element.appendChild(this.buildInput(this.nameValue, val))
+    } else {
+      pressed.forEach((item) => this.element.appendChild(this.buildInput(`${this.nameValue}[]`, item.dataset.value)))
+    }
+  }
+
+  buildInput(name, value) {
+    const input = document.createElement("input")
+    input.type = "hidden"
+    input.name = name
+    input.value = value
+    input.setAttribute("data-phlex-kit--toggle-group-target", "input")
+    return input
+  }
+}

data/config/importmap.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+# Pins the PhlexKit Stimulus controllers so importmap-rails hosts can register
+# them. The engine appends this file to the host's importmap paths.
+pin_all_from PhlexKit::Engine.root.join("app/javascript/phlex_kit/controllers"),
+  under: "phlex_kit/controllers",
+  to: "phlex_kit/controllers"

data/lib/generators/phlex_kit/component/component_generator.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "rails/generators/named_base"
+
+module PhlexKit
+  module Generators
+    # `rails g phlex_kit:component button` — the shadcn-style "eject": copies a
+    # component's folder (.rb parts + co-located .css) out of the gem and into the
+    # host app so the team owns and can edit the source. Appends its @import to
+    # application.css. The ejected copy keeps the PhlexKit namespace; the host's
+    # copy shadows the gem's via Zeitwerk load-path order.
+    class ComponentGenerator < Rails::Generators::NamedBase
+      source_root PhlexKit::Engine.root.join("app/components/phlex_kit").to_s
+
+      def eject_component
+        unless File.directory?(File.join(self.class.source_root, file_name))
+          say_status :error, "no PhlexKit component named '#{file_name}'", :red
+          return
+        end
+        directory file_name, "app/components/phlex_kit/#{file_name}"
+      end
+
+      def wire_import
+        css = "app/assets/stylesheets/application.css"
+        line = %(@import url("phlex_kit/#{file_name}/#{file_name}.css");\n)
+        return unless File.exist?(css)
+        prepend_to_file(css, line) unless File.read(css).include?(line.strip)
+      end
+
+      def remind_collapse
+        say <<~MSG
+          Ejected phlex_kit/#{file_name}. Ensure your app collapses ejected
+          component folders (config/application.rb):
+
+              Rails.autoloaders.main.collapse("app/components/phlex_kit/*")
+
+        MSG
+      end
+    end
+  end
+end

data/lib/generators/phlex_kit/install/install_generator.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "rails/generators/base"
+
+module PhlexKit
+  module Generators
+    # `rails g phlex_kit:install` — wires PhlexKit into a host app:
+    #   - drops an initializer,
+    #   - adds the manifest @import to application.css (url() form),
+    #   - prints the Stimulus registration snippet.
+    class InstallGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+
+      IMPORT_LINE = %(@import url("phlex_kit/phlex_kit.css");\n)
+
+      def create_initializer
+        template "phlex_kit.rb", "config/initializers/phlex_kit.rb"
+      end
+
+      def add_stylesheet_import
+        css = "app/assets/stylesheets/application.css"
+        unless File.exist?(css)
+          say_status :skip, "#{css} not found — add `#{IMPORT_LINE.strip}` to your main stylesheet", :yellow
+          return
+        end
+        if File.read(css).include?("phlex_kit/phlex_kit.css")
+          say_status :identical, css, :blue
+        else
+          # @import must precede every rule, so prepend it.
+          prepend_to_file css, IMPORT_LINE
+        end
+      end
+
+      def print_stimulus_instructions
+        say <<~MSG
+
+          PhlexKit installed. To enable the interactive components (Dialog,
+          Dropdown, Select, Avatar), register the Stimulus controllers:
+
+              import { registerPhlexKitControllers } from "phlex_kit/controllers"
+              registerPhlexKitControllers(application)
+
+          Render a component anywhere a Phlex view is allowed:
+
+              render PhlexKit::Button.new(variant: :primary) { "Save" }
+
+        MSG
+      end
+    end
+  end
+end