phlex_kit 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d165b8e5ecbb24ef238be1c9472db2d19cdcb30079c85e2e839019547d5324fa
+  data.tar.gz: 89f8058734e7d2745b3ea96e32cea6845e721c4f2e28a8621bc7c4978183c510
+SHA512:
+  metadata.gz: 2c1b8608a4175ae249ed98ecae2c0ffccbb1c8a5f07d9fea298bf29e39d0eee3f401f6accd822da8fb42cc194560690fa4ed72e389bd448e89d2f6f008f494de
+  data.tar.gz: 87773e1fa4628d51cdeef7d93684fe3c91d728fe77f80d3e093fbcfeb1d210d1e176d6fd0f3d89901bb7c2c4ffc67db04104fc44437a017ee7df8cd5d9ca3037

data/MIT-LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aypex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,135 @@
+# PhlexKit
+
+A [ruby_ui](https://ruby-ui.com)-style component kit for [Phlex](https://phlex.fun),
+styled with **vanilla CSS + design tokens instead of Tailwind**, and built so
+[phlex-reactive](https://github.com/mhenrixon/phlex-reactive) is an *optional,
+per-component* integration — never a required dependency.
+
+- **No build step.** Components ship as plain Ruby classes with co-located vanilla
+  CSS. No Tailwind, no Node, no PostCSS. Assets are precompiled-static in the gem.
+- **Theme with CSS custom properties.** Every component reads `--pk-*` tokens via
+  `var()` + `color-mix()`. Redefine `:root` and the whole kit re-themes live —
+  including dark/light/system — with no rebuild.
+- **Reactive when you want it.** Components pass `**attrs` straight through Phlex's
+  `mix`, so a phlex-reactive `**on(:event)` bundle composes onto the root element
+  with zero coupling. Non-reactive components never touch phlex-reactive.
+
+## Install
+
+```ruby
+# Gemfile
+gem "phlex_kit"
+```
+
+```bash
+bundle install
+bin/rails g phlex_kit:install
+```
+
+The installer adds `@import url("phlex_kit/phlex_kit.css");` to your
+`application.css`, drops `config/initializers/phlex_kit.rb`, and prints the
+Stimulus wiring. That's it — no Tailwind config, no content globs.
+
+## Usage
+
+```ruby
+render PhlexKit::Button.new(variant: :primary, size: :lg) { "Save changes" }
+
+render PhlexKit::Card.new do
+  render PhlexKit::CardHeader.new do
+    render PhlexKit::CardTitle.new { "Team" }
+  end
+  render PhlexKit::CardContent.new { "…" }
+end
+
+render PhlexKit::Badge.new(variant: :success) { "Live" }
+```
+
+Prefer revue-style `UI::Button`? Turn on the alias in the initializer:
+
+```ruby
+PhlexKit.configure { |c| c.define_ui_alias = true }   # UI == PhlexKit
+```
+
+## Theming
+
+The gem ships a default dark/light/system token set (`_tokens.css`). Override any
+token in your own stylesheet — your app's CSS sorts ahead of the gem's, so you win:
+
+```css
+@import url("phlex_kit/phlex_kit.css");
+
+:root {
+  --pk-brand: #3b5bdb;
+  --pk-radius: 6px;
+}
+```
+
+Want a completely custom palette? Delete the `_tokens` import line from your
+manifest and define the `--pk-*` properties yourself. Every component has a
+literal fallback in `var(--pk-*, …)`, so nothing breaks if a token is missing.
+
+## Interactive components (Stimulus)
+
+Dialog, Dropdown, Select, and Avatar ship plain Stimulus controllers (no
+phlex-reactive needed). Register them once in your Stimulus entrypoint:
+
+```js
+import { registerPhlexKitControllers } from "phlex_kit/controllers"
+registerPhlexKitControllers(application)
+```
+
+## phlex-reactive (optional)
+
+For components that own server-state behavior (live counters, moderation queues,
+cross-tab updates), add phlex-reactive and include its mixin in a component:
+
+```ruby
+# Gemfile
+gem "phlex-reactive"
+```
+
+```ruby
+class MyCounter < PhlexKit::BaseComponent
+  include Phlex::Reactive::Component
+  action(:increment) { @count += 1 }
+  # view_template uses **on(:increment) on a button — it just flows through mix
+end
+```
+
+PhlexKit does **not** depend on phlex-reactive. `PhlexKit.reactive?` auto-detects
+it; set `config.reactive` to force it on/off.
+
+## Ejecting components (shadcn-style)
+
+Want to own and edit a component's source? Eject it into your app:
+
+```bash
+bin/rails g phlex_kit:component button
+```
+
+This copies `button.rb` + `button.css` into `app/components/phlex_kit/button/`
+and wires its `@import`. Your copy shadows the gem's.
+
+## How the asset wiring works
+
+Three engine initializers reproduce the pattern proven in production (revue):
+
+1. `app/components` and the stylesheet dir go on Propshaft's load path so CSS can
+   sit beside each `.rb`.
+2. Component folders are Zeitwerk-`collapse`d, so `button/button.rb` is
+   `PhlexKit::Button` (not `PhlexKit::Button::Button`) and `card/card_header.rb`
+   is `PhlexKit::CardHeader`.
+3. A private-method guard keeps Propshaft from serving Ruby source out of
+   `public/assets/` (covered by `test/assets/asset_load_path_test.rb`).
+
+Only the `@import url("…")` form is fingerprinted by Propshaft — a bare
+`@import "…"` ships un-digested and 404s. The manifest always uses `url()`.
+
+## Components
+
+See [ROADMAP.md](ROADMAP.md) for the full inventory and porting status.
+
+## License
+
+MIT.

data/app/assets/stylesheets/phlex_kit/_tokens.css

@@ -0,0 +1,91 @@
+/* Kit utilities used by the interactive controllers (Stimulus toggles these). */
+.pk-hidden { display: none !important; }
+
+/* Kit elements size predictably: width includes padding + border, so
+   `width: 100%` controls (inputs, triggers, option rows) never overflow their
+   container. Scoped to pk-* classes and their subtrees — the host's own box
+   model is untouched. */
+[class^="pk-"], [class*=" pk-"],
+[class^="pk-"] *, [class*=" pk-"] *,
+[class^="pk-"] *::before, [class*=" pk-"] *::after { box-sizing: border-box; }
+
+/* PhlexKit default theme tokens — shadcn/ui's current default (neutral)
+   palette, values lifted verbatim from ui.shadcn.com, mapped onto the --pk-*
+   names: bg ← background, surface ← card/popover, surface-2 ← muted,
+   accent ← accent (hover fills — darker than muted in dark mode),
+   input ← input (form-control borders), ring ← ring (focus ring color),
+   brand ← primary (monochrome), red ← destructive, chart-1..5 ← chart-1..5
+   (tailwind blue-300/500/600/700/800), radius ← 0.625rem (components derive
+   smaller/larger radii from it). This file is OPTIONAL — a host that wants
+   its own palette can skip importing it (see phlex_kit.css) and define the
+   --pk-* custom properties itself. Every component reads these via
+   var(--pk-*), so redefining :root after the import re-themes the whole kit
+   with no rebuild.
+
+   Dark is the default; light is opt-in via <html data-theme="light"> (set it
+   server-side to avoid a flash). "system" follows the OS via prefers-color-scheme.
+   Keep the two light token sets in sync. */
+:root {
+  --pk-bg: #0a0a0a;
+  --pk-surface: #171717;
+  --pk-surface-2: #262626;
+  --pk-accent: #404040;
+  --pk-border: #ffffff1a;
+  --pk-input: #ffffff26;
+  --pk-ring: #737373;
+  --pk-text: #fafafa;
+  --pk-text-2: #d4d4d4;
+  --pk-muted: #a1a1a1;
+  --pk-brand: #e5e5e5;
+  --pk-brand-ink: #171717;
+  --pk-green: #22c55e;
+  --pk-amber: #f59e0b;
+  --pk-red: #ff6568;
+  --pk-chart-1: #93c5fd;
+  --pk-chart-2: #3b82f6;
+  --pk-chart-3: #2563eb;
+  --pk-chart-4: #1d4ed8;
+  --pk-chart-5: #1e40af;
+  --pk-radius: 0.625rem;
+  color-scheme: dark;
+}
+
+:root[data-theme="light"] {
+  --pk-bg: #ffffff;
+  --pk-surface: #ffffff;
+  --pk-surface-2: #f5f5f5;
+  --pk-accent: #f5f5f5;
+  --pk-border: #e5e5e5;
+  --pk-input: #e5e5e5;
+  --pk-ring: #a1a1a1;
+  --pk-text: #000000;
+  --pk-text-2: #404040;
+  --pk-muted: #737373;
+  --pk-brand: #000000;
+  --pk-brand-ink: #fafafa;
+  --pk-green: #16a34a;
+  --pk-amber: #d97706;
+  --pk-red: #e40014;
+  color-scheme: light;
+}
+
+@media (prefers-color-scheme: light) {
+  :root[data-theme="system"] {
+    --pk-bg: #ffffff;
+    --pk-surface: #ffffff;
+    --pk-surface-2: #f5f5f5;
+    --pk-accent: #f5f5f5;
+    --pk-border: #e5e5e5;
+    --pk-input: #e5e5e5;
+    --pk-ring: #a1a1a1;
+    --pk-text: #000000;
+    --pk-text-2: #404040;
+    --pk-muted: #737373;
+    --pk-brand: #000000;
+    --pk-brand-ink: #fafafa;
+    --pk-green: #16a34a;
+    --pk-amber: #d97706;
+    --pk-red: #e40014;
+    color-scheme: light;
+  }
+}

data/app/assets/stylesheets/phlex_kit/phlex_kit.css

@@ -0,0 +1,82 @@
+/* PhlexKit manifest — the single stylesheet a host imports:
+
+     @import url("phlex_kit/phlex_kit.css");   in your application.css
+
+   Only the url() form is fingerprinted by Propshaft; a bare @import ships
+   un-digested and 404s. And Propshaft resolves bare url() paths RELATIVE TO
+   THIS FILE'S directory (phlex_kit/), so imports here must be written
+   relative — `_tokens.css`, `button/button.css` — never `phlex_kit/…`, which
+   would double the prefix and 404. Component CSS is co-located beside each
+   .rb and pulled in below. This file is regenerated when a component is added.
+
+   To bring your OWN theme, delete the _tokens import line and define the
+   --pk-* custom properties yourself. */
+@import url("_tokens.css");
+@import url("accordion/accordion.css");
+@import url("alert/alert.css");
+@import url("alert_dialog/alert_dialog.css");
+@import url("aspect_ratio/aspect_ratio.css");
+@import url("attachment/attachment.css");
+@import url("avatar/avatar.css");
+@import url("badge/badge.css");
+@import url("breadcrumb/breadcrumb.css");
+@import url("bubble/bubble.css");
+@import url("button/button.css");
+@import url("button_group/button_group.css");
+@import url("calendar/calendar.css");
+@import url("card/card.css");
+@import url("carousel/carousel.css");
+@import url("chart/chart.css");
+@import url("checkbox/checkbox.css");
+@import url("clipboard/clipboard.css");
+@import url("codeblock/codeblock.css");
+@import url("collapsible/collapsible.css");
+@import url("combobox/combobox.css");
+@import url("command/command.css");
+@import url("context_menu/context_menu.css");
+@import url("data_table/data_table.css");
+@import url("date_picker/date_picker.css");
+@import url("dialog/dialog.css");
+@import url("drawer/drawer.css");
+@import url("dropdown_menu/dropdown_menu.css");
+@import url("empty/empty.css");
+@import url("form/form.css");
+@import url("form_field/form_field.css");
+@import url("hover_card/hover_card.css");
+@import url("input/input.css");
+@import url("input_group/input_group.css");
+@import url("input_otp/input_otp.css");
+@import url("item/item.css");
+@import url("kbd/kbd.css");
+@import url("label/label.css");
+@import url("link/link.css");
+@import url("menubar/menubar.css");
+@import url("message/message.css");
+@import url("message_scroller/message_scroller.css");
+@import url("native_select/native_select.css");
+@import url("navigation_menu/navigation_menu.css");
+@import url("pagination/pagination.css");
+@import url("popover/popover.css");
+@import url("progress/progress.css");
+@import url("radio_button/radio_button.css");
+@import url("radio_group/radio_group.css");
+@import url("resizable/resizable.css");
+@import url("scroll_area/scroll_area.css");
+@import url("select/select.css");
+@import url("separator/separator.css");
+@import url("sheet/sheet.css");
+@import url("shortcut_key/shortcut_key.css");
+@import url("sidebar/sidebar.css");
+@import url("skeleton/skeleton.css");
+@import url("slider/slider.css");
+@import url("spinner/spinner.css");
+@import url("stars/stars.css");
+@import url("switch/switch.css");
+@import url("table/table.css");
+@import url("tabs/tabs.css");
+@import url("textarea/textarea.css");
+@import url("toast/toast.css");
+@import url("toggle/toggle.css");
+@import url("toggle_group/toggle_group.css");
+@import url("tooltip/tooltip.css");
+@import url("typography/typography.css");

data/app/components/phlex_kit/accordion/accordion.css

@@ -0,0 +1,14 @@
+/* Co-located with accordion.rb. Theme tokens from the global stylesheet. */
+.pk-accordion { width: 100%; }
+.pk-accordion-item { border-bottom: 1px solid var(--pk-border); }
+.pk-accordion-trigger {
+  width: 100%; display: flex; flex: 1; align-items: center; justify-content: space-between;
+  padding-block: 1rem; font-size: .875rem; font-weight: 500; text-align: left;
+  background: none; border: 0; cursor: pointer; color: inherit; transition: all .15s ease;
+}
+.pk-accordion-trigger:hover { text-decoration: underline; }
+.pk-accordion-trigger-label { flex: 1; }
+.pk-accordion-icon { display: inline-flex; opacity: .5; transition: transform .2s ease; }
+.pk-accordion-icon svg { width: 1rem; height: 1rem; }
+.pk-accordion-content { overflow-y: hidden; }
+.pk-accordion-default-content { padding-bottom: 1rem; padding-top: 0; font-size: .875rem; }

data/app/components/phlex_kit/accordion/accordion.rb

@@ -0,0 +1,10 @@
+module PhlexKit
+  # Vertically stacked, individually-collapsible sections. Ported from ruby_ui's
+  # RubyUI::Accordion. Compose Accordion > AccordionItem > (AccordionTrigger +
+  # AccordionContent). Animated open/close via the phlex-kit--accordion controller
+  # (native Web Animations API — no `motion` dependency).
+  class Accordion < BaseComponent
+    def initialize(**attrs) = (@attrs = attrs)
+    def view_template(&) = div(**mix({ class: "pk-accordion" }, @attrs), &)
+  end
+end

data/app/components/phlex_kit/accordion/accordion_content.rb

@@ -0,0 +1,8 @@
+module PhlexKit
+  class AccordionContent < BaseComponent
+    def initialize(**attrs) = (@attrs = attrs)
+    def view_template(&)
+      div(**mix({ class: "pk-accordion-content", data: { phlex_kit__accordion_target: "content", state: "closed" }, style: "height: 0px;", hidden: true }, @attrs), &)
+    end
+  end
+end

data/app/components/phlex_kit/accordion/accordion_default_content.rb

@@ -0,0 +1,6 @@
+module PhlexKit
+  class AccordionDefaultContent < BaseComponent
+    def initialize(**attrs) = (@attrs = attrs)
+    def view_template(&) = div(**mix({ class: "pk-accordion-default-content" }, @attrs), &)
+  end
+end

data/app/components/phlex_kit/accordion/accordion_default_trigger.rb

@@ -0,0 +1,12 @@
+module PhlexKit
+  # Convenience trigger: label on the left, chevron icon on the right.
+  class AccordionDefaultTrigger < BaseComponent
+    def initialize(**attrs) = (@attrs = attrs)
+    def view_template(&block)
+      button(**mix({ type: "button", class: "pk-accordion-trigger", data: { action: "click->phlex-kit--accordion#toggle" } }, @attrs)) do
+        span(class: "pk-accordion-trigger-label", &block)
+        render PhlexKit::AccordionIcon.new
+      end
+    end
+  end
+end

data/app/components/phlex_kit/accordion/accordion_icon.rb

@@ -0,0 +1,16 @@
+module PhlexKit
+  class AccordionIcon < BaseComponent
+    def initialize(**attrs) = (@attrs = attrs)
+    def view_template(&block)
+      span(**mix({ class: "pk-accordion-icon", data: { phlex_kit__accordion_target: "icon" } }, @attrs)) do
+        if block
+          yield
+        else
+          svg(xmlns: "http://www.w3.org/2000/svg", viewbox: "0 0 20 20", fill: "currentColor") do |s|
+            s.path(fill_rule: "evenodd", clip_rule: "evenodd", d: "M5.23 7.21a.75.75 0 011.06.02L10 11.168l3.71-3.938a.75.75 0 111.08 1.04l-4.25 4.5a.75.75 0 01-1.08 0l-4.25-4.5a.75.75 0 01.02-1.06z")
+          end
+        end
+      end
+    end
+  end
+end

data/app/components/phlex_kit/accordion/accordion_item.rb

@@ -0,0 +1,12 @@
+module PhlexKit
+  class AccordionItem < BaseComponent
+    def initialize(open: false, rotate_icon: 180, **attrs)
+      @open = open
+      @rotate_icon = rotate_icon
+      @attrs = attrs
+    end
+    def view_template(&)
+      div(**mix({ class: "pk-accordion-item", data: { controller: "phlex-kit--accordion", phlex_kit__accordion_open_value: @open, phlex_kit__accordion_rotate_icon_value: @rotate_icon } }, @attrs), &)
+    end
+  end
+end

data/app/components/phlex_kit/accordion/accordion_trigger.rb

@@ -0,0 +1,8 @@
+module PhlexKit
+  class AccordionTrigger < BaseComponent
+    def initialize(**attrs) = (@attrs = attrs)
+    def view_template(&)
+      button(**mix({ type: "button", class: "pk-accordion-trigger", data: { action: "click->phlex-kit--accordion#toggle" } }, @attrs), &)
+    end
+  end
+end

data/app/components/phlex_kit/alert/alert.css

@@ -0,0 +1,32 @@
+/* Co-located with alert.rb — UI::Alert (+ Title / Description). ruby_ui's
+   structure kept; Tailwind replaced with vanilla CSS on the palette tokens.
+   Geometry from ruby_ui (ring-1 ring-inset → border, rounded-lg, px-4 py-4,
+   text-sm). The variant tints reuse the flash colours (success/destructive/
+   warning) the admin already used. Theme tokens come from the global stylesheet. */
+.pk-alert {
+  position: relative;
+  width: 100%;
+  border: 1px solid var(--pk-border);
+  border-radius: var(--pk-radius);
+  padding: .85rem 1rem;
+  font-size: .875rem;
+  background: color-mix(in oklab, var(--pk-surface) 60%, transparent);
+  color: var(--pk-text);
+}
+.pk-alert.success {
+  border-color: color-mix(in oklab, var(--pk-green) 40%, var(--pk-border));
+  background: color-mix(in oklab, var(--pk-green) 8%, transparent);
+  color: var(--pk-green);
+}
+.pk-alert.destructive {
+  border-color: color-mix(in oklab, var(--pk-red) 40%, var(--pk-border));
+  background: color-mix(in oklab, var(--pk-red) 8%, transparent);
+  color: var(--pk-red);
+}
+.pk-alert.warning {
+  border-color: color-mix(in oklab, var(--pk-amber) 40%, var(--pk-border));
+  background: color-mix(in oklab, var(--pk-amber) 8%, transparent);
+  color: var(--pk-amber);
+}
+.pk-alert-title { margin: 0 0 .25rem; font-weight: 500; line-height: 1.1; letter-spacing: -.01em; }
+.pk-alert-description { font-size: .875rem; }

data/app/components/phlex_kit/alert/alert.rb

@@ -0,0 +1,37 @@
+module PhlexKit
+  # Callout box, ported from ruby_ui's RubyUI::Alert. Presentational, no JS. A
+  # `variant:` selector (same shape as PhlexKit::Button) tints the box; compose with
+  # AlertTitle + AlertDescription:
+  #
+  #   render PhlexKit::Alert.new(variant: :success) do
+  #     render PhlexKit::AlertTitle.new { "Saved" }
+  #     render PhlexKit::AlertDescription.new { "Your changes are live." }
+  #   end
+  #
+  # ruby_ui's variants (nil / warning / success / destructive) map onto the
+  # palette tokens in vanilla CSS (alert.css). `VARIANTS.fetch` fails loud.
+  class Alert < BaseComponent
+    # variant => extra class appended after the base `ui-alert` (nil = neutral).
+    VARIANTS = {
+      default: nil,
+      warning: "warning",
+      success: "success",
+      destructive: "destructive"
+    }.freeze
+
+    def initialize(variant: :default, **attrs)
+      @variant = variant.to_sym
+      @attrs = attrs
+    end
+
+    def view_template(&block)
+      div(**mix({ class: classes }, @attrs), &block)
+    end
+
+    private
+
+    def classes
+      [ "pk-alert", VARIANTS.fetch(@variant) ].compact.join(" ")
+    end
+  end
+end

data/app/components/phlex_kit/alert/alert_description.rb

@@ -0,0 +1,12 @@
+module PhlexKit
+  # Body text of a PhlexKit::Alert. See alert.rb.
+  class AlertDescription < BaseComponent
+    def initialize(**attrs)
+      @attrs = attrs
+    end
+
+    def view_template(&block)
+      div(**mix({ class: "pk-alert-description" }, @attrs), &block)
+    end
+  end
+end

data/app/components/phlex_kit/alert/alert_title.rb

@@ -0,0 +1,12 @@
+module PhlexKit
+  # Heading line of a PhlexKit::Alert. See alert.rb.
+  class AlertTitle < BaseComponent
+    def initialize(**attrs)
+      @attrs = attrs
+    end
+
+    def view_template(&block)
+      h5(**mix({ class: "pk-alert-title" }, @attrs), &block)
+    end
+  end
+end

data/app/components/phlex_kit/alert_dialog/alert_dialog.css

@@ -0,0 +1,37 @@
+/* Co-located with alert_dialog.rb — UI::AlertDialog (+ Trigger / Content / Header
+   / Title / Description / Footer / Cancel / Action). ruby_ui's modal structure as
+   vanilla CSS on the palette tokens. Theme tokens come from the global stylesheet. */
+.pk-alert-dialog { display: inline-block; }
+.pk-alert-dialog-trigger { display: inline-block; }
+
+.pk-alert-dialog-overlay {
+  position: fixed;
+  inset: 0;
+  z-index: 50;
+  background: rgba(0, 0, 0, .8);
+  backdrop-filter: blur(2px);
+}
+.pk-alert-dialog-panel {
+  position: fixed;
+  left: 50%;
+  top: 50%;
+  transform: translate(-50%, -50%);
+  z-index: 50;
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  width: calc(100% - 2rem);
+  max-width: 32rem;
+  max-height: 100vh;
+  overflow-y: auto;
+  border: 1px solid var(--pk-border);
+  border-radius: var(--pk-radius);
+  background: var(--pk-surface);
+  color: var(--pk-text);
+  padding: 1.5rem;
+  box-shadow: 0 10px 40px rgba(0, 0, 0, .5);
+}
+.pk-alert-dialog-header { display: flex; flex-direction: column; gap: .5rem; }
+.pk-alert-dialog-title { margin: 0; font-size: 1.125rem; font-weight: 600; }
+.pk-alert-dialog-description { margin: 0; font-size: .875rem; color: var(--pk-muted); }
+.pk-alert-dialog-footer { display: flex; justify-content: flex-end; gap: .5rem; flex-wrap: wrap; }

data/app/components/phlex_kit/alert_dialog/alert_dialog.rb

@@ -0,0 +1,20 @@
+module PhlexKit
+  # Modal confirm dialog, ported from ruby_ui's RubyUI::AlertDialog. Keeps the
+  # Stimulus controller: the trigger clones the (template) content into <body> as
+  # a modal; Cancel removes it. No floating-ui. Compose Trigger + Content
+  # (Header/Title/Description + Footer with Cancel + the destructive submit).
+  # Tailwind → vanilla `.pk-alert-dialog*` (alert_dialog.css).
+  class AlertDialog < BaseComponent
+    def initialize(open: false, **attrs)
+      @open = open
+      @attrs = attrs
+    end
+
+    def view_template(&block)
+      div(**mix({
+        class: "pk-alert-dialog",
+        data: { controller: "phlex-kit--alert-dialog", phlex_kit__alert_dialog_open_value: @open.to_s }
+      }, @attrs), &block)
+    end
+  end
+end

data/app/components/phlex_kit/alert_dialog/alert_dialog_action.rb

@@ -0,0 +1,14 @@
+module PhlexKit
+  # The confirm action in a PhlexKit::AlertDialog footer — a primary PhlexKit::Button. (For a
+  # non-GET destructive action, use a `button_to` in the footer instead, so it
+  # submits a real form.) See alert_dialog.rb.
+  class AlertDialogAction < BaseComponent
+    def initialize(**attrs)
+      @attrs = attrs
+    end
+
+    def view_template(&block)
+      render PhlexKit::Button.new(variant: :primary, **@attrs, &block)
+    end
+  end
+end

data/app/components/phlex_kit/alert_dialog/alert_dialog_cancel.rb

@@ -0,0 +1,13 @@
+module PhlexKit
+  # The dismiss button in a PhlexKit::AlertDialog footer — an outline PhlexKit::Button wired to
+  # the controller's #dismiss (removes the modal). See alert_dialog.rb.
+  class AlertDialogCancel < BaseComponent
+    def initialize(**attrs)
+      @attrs = attrs
+    end
+
+    def view_template(&block)
+      render PhlexKit::Button.new(variant: :outline, data: { action: "click->phlex-kit--alert-dialog#dismiss" }, **@attrs, &block)
+    end
+  end
+end

data/app/components/phlex_kit/alert_dialog/alert_dialog_content.rb

@@ -0,0 +1,19 @@
+module PhlexKit
+  # The modal body, held in a <template> and cloned into <body> on open. The
+  # cloned div carries its own `phlex-kit--alert-dialog` controller so Cancel
+  # (#dismiss) can remove it. Holds Header + Footer. See alert_dialog.rb.
+  class AlertDialogContent < BaseComponent
+    def initialize(**attrs)
+      @attrs = attrs
+    end
+
+    def view_template(&block)
+      template(**mix({ data: { phlex_kit__alert_dialog_target: "content" } }, @attrs)) do
+        div(data: { controller: "phlex-kit--alert-dialog" }) do
+          div(class: "pk-alert-dialog-overlay", "aria-hidden": "true")
+          div(role: "alertdialog", "aria-modal": "true", class: "pk-alert-dialog-panel", &block)
+        end
+      end
+    end
+  end
+end

data/app/components/phlex_kit/alert_dialog/alert_dialog_description.rb

@@ -0,0 +1,12 @@
+module PhlexKit
+  # Body text of a PhlexKit::AlertDialog. See alert_dialog.rb.
+  class AlertDialogDescription < BaseComponent
+    def initialize(**attrs)
+      @attrs = attrs
+    end
+
+    def view_template(&block)
+      p(**mix({ class: "pk-alert-dialog-description" }, @attrs), &block)
+    end
+  end
+end