phlex_kit 0.4.0 → 0.5.0

data/app/components/phlex_kit/context_menu/context_menu_item.rb

@@ -1,18 +1,28 @@
 module PhlexKit
+  # A menu row in a PhlexKit::ContextMenuContent. Matches the dropdown-menu
+  # grammar: gap-based layout (no forced inset), `variant: :destructive`,
+  # `checked:` renders a leading ✓, `shortcut:` a trailing kbd hint (or
+  # compose ContextMenuShortcut yourself). Closes the menu on click.
+  # See context_menu.rb.
   class ContextMenuItem < BaseComponent
-    def initialize(href: "#", checked: false, shortcut: nil, disabled: false, **attrs)
+    VARIANTS = { default: nil, destructive: "destructive" }.freeze
+
+    def initialize(href: "#", checked: false, shortcut: nil, disabled: false, variant: :default, **attrs)
       @href = href
       @checked = checked
       @shortcut = shortcut
       @disabled = disabled
+      @variant = variant.to_sym
       @attrs = attrs
     end
+
     def view_template(&block)
-      a(**mix({ href: @href, role: "menuitem", tabindex: "-1", class: "pk-context-menu-item",
+      classes = [ "pk-context-menu-item", VARIANTS.fetch(@variant) ].compact.join(" ")
+      a(**mix({ href: @href, role: "menuitem", tabindex: "-1", class: classes,
                 data: { action: "click->phlex-kit--context-menu#close", phlex_kit__context_menu_target: "menuItem", disabled: @disabled } }, @attrs)) do
         if @checked
           span(class: "pk-context-menu-check") do
-            render Icon.new(:check, size: 15)
+            render Icon.new(:check, size: nil)
           end
         end
         yield

data/app/components/phlex_kit/context_menu/context_menu_radio_group.rb

@@ -0,0 +1,10 @@
+module PhlexKit
+  # Exclusive-choice group of ContextMenuRadioItems (share the same `name:`).
+  # Mirrors shadcn/ui's ContextMenuRadioGroup. See context_menu.rb.
+  class ContextMenuRadioGroup < BaseComponent
+    def initialize(**attrs) = (@attrs = attrs)
+    def view_template(&)
+      div(**mix({ class: "pk-context-menu-group", role: "radiogroup" }, @attrs), &)
+    end
+  end
+end

data/app/components/phlex_kit/context_menu/context_menu_radio_item.rb

@@ -0,0 +1,30 @@
+module PhlexKit
+  # One choice in a ContextMenuRadioGroup — a <label> around a real (hidden)
+  # radio; the ● shows via CSS and picking doesn't close the menu (matching
+  # Radix). See context_menu.rb.
+  class ContextMenuRadioItem < BaseComponent
+    def initialize(name:, value:, checked: false, **attrs)
+      @name = name
+      @value = value
+      @checked = checked
+      @attrs = attrs
+    end
+
+    def view_template(&block)
+      label(**mix({
+        class: "pk-context-menu-item pk-context-menu-radio-item",
+        role: "menuitemradio"
+      }, @attrs)) do
+        input(type: :radio, class: "pk-context-menu-item-input", name: @name, value: @value, checked: @checked)
+        span(class: "pk-context-menu-item-indicator", aria: { hidden: "true" }) do
+          # A filled selection dot is geometry, not icon-library vocabulary —
+          # identical across icon_library settings (matches the dropdown).
+          svg(xmlns: "http://www.w3.org/2000/svg", viewbox: "0 0 24 24", fill: "currentColor") do |s|
+            s.circle(cx: "12", cy: "12", r: "5")
+          end
+        end
+        yield if block
+      end
+    end
+  end
+end

data/app/components/phlex_kit/context_menu/context_menu_shortcut.rb

@@ -0,0 +1,11 @@
+module PhlexKit
+  # Right-aligned keyboard hint on a ContextMenuItem, mirroring shadcn/ui's
+  # ContextMenuShortcut (the item's `shortcut:` param renders the same span).
+  # See context_menu.rb.
+  class ContextMenuShortcut < BaseComponent
+    def initialize(**attrs) = (@attrs = attrs)
+    def view_template(&block)
+      span(**mix({ class: "pk-context-menu-shortcut" }, @attrs), &block)
+    end
+  end
+end

data/app/components/phlex_kit/context_menu/context_menu_sub.rb

@@ -0,0 +1,11 @@
+module PhlexKit
+  # Nested submenu wrapper: SubTrigger row + SubContent panel, revealed on
+  # hover/focus with pure CSS (no extra controller). Mirrors shadcn/ui's
+  # ContextMenuSub. See context_menu.rb.
+  class ContextMenuSub < BaseComponent
+    def initialize(**attrs) = (@attrs = attrs)
+    def view_template(&)
+      div(**mix({ class: "pk-context-menu-sub" }, @attrs), &)
+    end
+  end
+end

data/app/components/phlex_kit/context_menu/context_menu_sub_content.rb

@@ -0,0 +1,12 @@
+module PhlexKit
+  # The nested panel of a ContextMenuSub — opens beside the trigger.
+  # See context_menu.rb.
+  class ContextMenuSubContent < BaseComponent
+    def initialize(**attrs) = (@attrs = attrs)
+    def view_template(&)
+      div(**mix({ class: "pk-context-menu-sub-content", role: "menu" }, @attrs)) do
+        div(class: "pk-context-menu-sub-viewport", &)
+      end
+    end
+  end
+end

data/app/components/phlex_kit/context_menu/context_menu_sub_trigger.rb

@@ -0,0 +1,17 @@
+module PhlexKit
+  # The row that opens a ContextMenuSub (trailing ▸ chevron). See context_menu.rb.
+  class ContextMenuSubTrigger < BaseComponent
+    def initialize(**attrs) = (@attrs = attrs)
+    def view_template(&block)
+      div(**mix({
+        class: "pk-context-menu-item pk-context-menu-sub-trigger",
+        role: "menuitem",
+        tabindex: "0",
+        aria: { haspopup: "menu" }
+      }, @attrs)) do
+        block&.call
+        render Icon.new(:chevron_right, size: nil, class: "pk-context-menu-sub-chevron")
+      end
+    end
+  end
+end

data/app/components/phlex_kit/dialog/dialog.css

@@ -1,38 +1,56 @@
-/* Co-located with dialog.rb. Native <dialog> centered by the UA; we style the box
-   + ::backdrop. Theme tokens from the global stylesheet. */
+/* Co-located with dialog.rb. Native <dialog> centered by the UA; we style the
+   box + ::backdrop. Matched to shadcn/ui's current dialog (nova): popover
+   surface with a foreground-tint ring, rounded-xl, --pk-dialog-spacing: 1rem
+   driving padding + the full-bleed footer band, text-sm body, close pinned at
+   top-2/right-2. Their default width is max-w-sm (24rem) = our md.
+   Overlays are kit-unified at nova's black/10 + blur-xs (darkening to /50
+   where backdrop-filter is unsupported) — changed across dialog/
+   alert-dialog/sheet/drawer/command in one pass. Tokens global. */
 .pk-dialog-trigger { display: inline-block; }
 .pk-dialog {
-  position: fixed; z-index: 50; width: 100%; max-width: 32rem; max-height: 100vh;
-  overflow-y: auto; gap: 1rem; 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 30px rgb(0 0 0 / .35);
+  --pk-dialog-spacing: 1rem;
+  position: fixed; z-index: 50; width: 100%;
+  max-width: min(24rem, calc(100% - 2rem));
+  max-height: 100vh;
+  overflow-y: auto; gap: 1rem;
+  border: 1px solid color-mix(in oklab, var(--pk-text) 10%, transparent);
+  border-radius: .75rem; background: var(--pk-surface); color: var(--pk-text);
+  padding: var(--pk-dialog-spacing);
+  font-size: .875rem;
+  box-shadow: 0 10px 30px rgb(0 0 0 / .35);
 }
 .pk-dialog[open] { display: flex; flex-direction: column; }
-.pk-dialog::backdrop { background: rgb(0 0 0 / .5); backdrop-filter: blur(8px); }
-.pk-dialog.xs { max-width: 24rem; }
-.pk-dialog.sm { max-width: 28rem; }
-.pk-dialog.lg { max-width: 42rem; }
-.pk-dialog.xl { max-width: 56rem; }
-.pk-dialog.full { max-width: 100%; }
-.pk-dialog-header { display: flex; flex-direction: column; gap: .375rem; text-align: center; }
+.pk-dialog::backdrop { background: rgb(0 0 0 / .1); backdrop-filter: blur(4px); }
+@supports not (backdrop-filter: blur(1px)) {
+  .pk-dialog::backdrop { background: rgb(0 0 0 / .5); }
+}
+.pk-dialog.xs { max-width: min(16rem, calc(100% - 2rem)); }
+.pk-dialog.sm { max-width: min(20rem, calc(100% - 2rem)); }
+.pk-dialog.lg { max-width: min(32rem, calc(100% - 2rem)); }
+.pk-dialog.xl { max-width: min(42rem, calc(100% - 2rem)); }
+.pk-dialog.full { max-width: calc(100% - 2rem); }
+.pk-dialog-header { display: flex; flex-direction: column; gap: .5rem; text-align: center; }
 .pk-dialog-footer {
   display: flex; flex-direction: column-reverse; gap: .5rem;
   margin: 0 calc(-1 * var(--pk-dialog-spacing)) calc(-1 * var(--pk-dialog-spacing));
   padding: var(--pk-dialog-spacing);
   border-top: 1px solid var(--pk-border);
+  border-radius: 0 0 .75rem .75rem;
   background: color-mix(in oklab, var(--pk-surface-2) 50%, transparent);
 }
-.pk-dialog-title { font-size: 1.125rem; font-weight: 600; line-height: 1; letter-spacing: -.01em; }
+.pk-dialog-title { font-size: 1rem; font-weight: 500; line-height: 1; }
 .pk-dialog-description { font-size: .875rem; color: var(--pk-muted); }
+.pk-dialog-description a { text-decoration: underline; text-underline-offset: 3px; color: inherit; }
+.pk-dialog-description a:hover { color: var(--pk-text); }
 .pk-dialog-middle { padding-block: 1rem; }
 .pk-overlay-close {
-  position: absolute; inset-inline-end: 1rem; top: 1rem; border: 0; background: none;
+  position: absolute; inset-inline-end: .5rem; top: .5rem; border: 0; background: none;
   cursor: pointer; border-radius: calc(var(--pk-radius) - 4px); opacity: .7; color: var(--pk-text);
+  padding: .25rem; display: inline-flex;
   transition: opacity .15s ease;
 }
 .pk-overlay-close:hover { opacity: 1; }
 @media (min-width: 640px) {
   .pk-dialog-header { text-align: left; }
   .pk-dialog-footer { flex-direction: row; justify-content: flex-end; }
-  .pk-dialog-footer > * + * { margin-inline-start: .5rem; }
 }

data/app/components/phlex_kit/dialog/dialog_close.rb

@@ -0,0 +1,13 @@
+module PhlexKit
+  # Wraps any element (typically a Button) so clicking it dismisses the
+  # enclosing dialog, mirroring shadcn/ui's DialogClose. See dialog.rb.
+  class DialogClose < BaseComponent
+    def initialize(**attrs)
+      @attrs = attrs
+    end
+
+    def view_template(&)
+      span(**mix({ style: "display: contents", data: { action: "click->phlex-kit--dialog#dismiss" } }, @attrs), &)
+    end
+  end
+end

data/app/components/phlex_kit/dialog/dialog_content.rb

@@ -1,17 +1,25 @@
 module PhlexKit
+  # The <dialog> box. `size:` picks the width tier (md = shadcn's default
+  # max-w-sm); `show_close_button: false` drops the top-right ✕ (their
+  # showCloseButton). See dialog.rb.
   class DialogContent < BaseComponent
     SIZES = { xs: "xs", sm: "sm", md: nil, lg: "lg", xl: "xl", full: "full" }.freeze
-    def initialize(size: :md, **attrs)
+
+    def initialize(size: :md, show_close_button: true, **attrs)
       @size = size.to_sym
+      @show_close_button = show_close_button
       @attrs = attrs
     end
+
     def view_template(&block)
-      cls = ["pk-dialog", SIZES.fetch(@size)].compact.join(" ")
+      cls = [ "pk-dialog", SIZES.fetch(@size) ].compact.join(" ")
       dialog(**mix({ class: cls, data: { phlex_kit__dialog_target: "dialog", action: "click->phlex-kit--dialog#backdropClick" } }, @attrs)) do
         yield
-        button(type: "button", class: "pk-overlay-close", data: { action: "click->phlex-kit--dialog#dismiss" }) do
-          render Icon.new(:x, size: 15)
-          span(class: "pk-sr-only") { "Close" }
+        if @show_close_button
+          button(type: "button", class: "pk-overlay-close", data: { action: "click->phlex-kit--dialog#dismiss" }) do
+            render Icon.new(:x, size: 15)
+            span(class: "pk-sr-only") { "Close" }
+          end
         end
       end
     end

data/app/components/phlex_kit/drawer/drawer.css

@@ -1,47 +1,83 @@
-/* Co-located with drawer.rb — UI::Drawer, shadcn parity (vaul replaced by the
-   kit's sheet clone machinery): dimmed overlay, bottom sheet with grab handle
-   sliding up. */
+/* Co-located with drawer.rb — PhlexKit::Drawer, shadcn parity (vaul replaced
+   by the kit's sheet clone machinery). Matched to nova: popover surface,
+   text-sm body, rounded-xl on the attached edge only, all four sides
+   (bottom default; top/left/right via DrawerContent side:). nova hides the
+   classic grab handle (.cn-drawer-handle is `hidden`) — ours matches, and a
+   host can re-show it with `.pk-drawer-handle { display: block }`. */
 .pk-drawer-trigger, .pk-drawer-close { display: inline-block; }
 .pk-drawer-overlay {
   position: fixed;
   inset: 0;
   z-index: 50;
-  background: rgb(0 0 0 / .5);
-  backdrop-filter: blur(8px);
+  background: rgb(0 0 0 / .1);
+  backdrop-filter: blur(4px);
 }
 .pk-drawer {
   position: fixed;
-  inset-inline: 0;
-  bottom: 0;
   z-index: 50;
   display: flex;
   flex-direction: column;
-  max-height: 85vh;
-  border: 1px solid var(--pk-border);
-  border-bottom: 0;
-  border-top-left-radius: calc(var(--pk-radius) + 4px);
-  border-top-right-radius: calc(var(--pk-radius) + 4px);
   background: var(--pk-surface);
   color: var(--pk-text);
+  font-size: .875rem;
+}
+/* bottom (default) */
+.pk-drawer.bottom {
+  inset-inline: 0;
+  bottom: 0;
+  max-height: 85vh;
+  border-top: 1px solid var(--pk-border);
+  border-radius: .75rem .75rem 0 0;
   animation: pk-drawer-up .3s ease;
 }
+.pk-drawer.top {
+  inset-inline: 0;
+  top: 0;
+  max-height: 85vh;
+  border-bottom: 1px solid var(--pk-border);
+  border-radius: 0 0 .75rem .75rem;
+  animation: pk-drawer-down .3s ease;
+}
+.pk-drawer.left,
+.pk-drawer.right {
+  inset-block: 0;
+  width: 75%;
+  max-width: 24rem;
+  max-height: 100vh;
+}
+.pk-drawer.left {
+  left: 0;
+  border-right: 1px solid var(--pk-border);
+  border-radius: 0 .75rem .75rem 0;
+  animation: pk-drawer-from-left .3s ease;
+}
+.pk-drawer.right {
+  right: 0;
+  border-left: 1px solid var(--pk-border);
+  border-radius: .75rem 0 0 .75rem;
+  animation: pk-drawer-from-right .3s ease;
+}
 @keyframes pk-drawer-up { from { transform: translateY(100%); } to { transform: translateY(0); } }
+@keyframes pk-drawer-down { from { transform: translateY(-100%); } to { transform: translateY(0); } }
+@keyframes pk-drawer-from-left { from { transform: translateX(-100%); } to { transform: translateX(0); } }
+@keyframes pk-drawer-from-right { from { transform: translateX(100%); } to { transform: translateX(0); } }
 .pk-drawer-handle {
+  display: none;
   flex: none;
   width: 100px;
-  height: .5rem;
-  margin: .75rem auto 0;
+  height: .25rem;
+  margin: 1rem auto 0;
   border-radius: 9999px;
   background: var(--pk-surface-2);
 }
 .pk-drawer-header {
   display: flex;
   flex-direction: column;
-  gap: .375rem;
+  gap: .125rem;
   padding: 1rem;
   text-align: center;
 }
-.pk-drawer-title { margin: 0; font-size: 1.125rem; font-weight: 600; }
+.pk-drawer-title { margin: 0; font-size: 1rem; font-weight: 500; color: var(--pk-text); }
 .pk-drawer-description { margin: 0; font-size: .875rem; color: var(--pk-muted); }
 .pk-drawer-footer {
   display: flex;
@@ -50,6 +86,9 @@
   margin-top: auto;
   padding: 1rem;
 }
-@media (min-width: 640px) {
+@media (min-width: 768px) {
   .pk-drawer-header { text-align: left; }
 }
+@supports not (backdrop-filter: blur(1px)) {
+  .pk-drawer-overlay { background: rgb(0 0 0 / .5); }
+}

data/app/components/phlex_kit/drawer/drawer_content.rb

@@ -1,8 +1,12 @@
 module PhlexKit
-  # <template> holding the drawer overlay + bottom panel (cloned into <body>
-  # on open, like SheetContent). See drawer.rb.
+  # <template> holding the drawer overlay + panel (cloned into <body> on open,
+  # like SheetContent). `side:` picks the attached edge — :bottom (default),
+  # :top, :left or :right, matching shadcn's direction prop. See drawer.rb.
   class DrawerContent < BaseComponent
-    def initialize(**attrs)
+    SIDES = { bottom: "bottom", top: "top", left: "left", right: "right" }.freeze
+
+    def initialize(side: :bottom, **attrs)
+      @side = side.to_sym
       @attrs = attrs
     end
 
@@ -10,7 +14,7 @@ module PhlexKit
       template(data: { phlex_kit__sheet_target: "content" }) do
         div(data: { controller: "phlex-kit--sheet-content" }) do
           div(class: "pk-drawer-overlay", data: { action: "click->phlex-kit--sheet-content#close" })
-          div(**mix({ class: "pk-drawer", role: "dialog", aria: { modal: "true" } }, @attrs)) do
+          div(**mix({ class: "pk-drawer #{SIDES.fetch(@side)}", role: "dialog", aria: { modal: "true" } }, @attrs)) do
             div(class: "pk-drawer-handle", aria: { hidden: "true" })
             yield if block
           end

data/app/components/phlex_kit/empty/empty.css

@@ -1,25 +1,30 @@
-/* Co-located with empty.rb. Theme tokens from the global stylesheet. */
+/* Co-located with empty.rb. Matched to shadcn/ui's current empty (nova):
+   borderless by default (their border-dashed sets only the STYLE — the
+   Outline example opts into a visible dashed border via class/style),
+   rounded-xl, p-6, text-sm title. Theme tokens from the global stylesheet. */
 .pk-empty {
   display: flex; width: 100%; min-width: 0; flex: 1; flex-direction: column;
   align-items: center; justify-content: center; gap: 1rem;
-  border: 1px dashed var(--pk-border); border-radius: 1.5rem;
-  padding: 3rem; text-align: center;
+  border: 0 dashed var(--pk-border); border-radius: .75rem;
+  padding: 1.5rem; text-align: center; text-wrap: balance;
 }
+.pk-empty.outline { border-width: 1px; }
 .pk-empty-header { display: flex; max-width: 24rem; flex-direction: column; align-items: center; gap: .5rem; }
 .pk-empty-media {
   margin-bottom: .5rem; display: flex; flex: none;
   align-items: center; justify-content: center;
 }
+.pk-empty-media svg { pointer-events: none; flex: none; }
 .pk-empty-media.icon {
-  height: 2.5rem; width: 2.5rem; border-radius: .75rem;
+  height: 2rem; width: 2rem; border-radius: var(--pk-radius);
   background: var(--pk-surface-2); color: var(--pk-text);
 }
-.pk-empty-media.icon > svg:not([class*="size-"]) { width: 1.25rem; height: 1.25rem; }
-.pk-empty-title { font-size: 1.125rem; font-weight: 500; letter-spacing: -.01em; }
+.pk-empty-media.icon > svg:not([class*="size-"]) { width: 1rem; height: 1rem; }
+.pk-empty-title { font-size: .875rem; font-weight: 500; letter-spacing: -.025em; }
 .pk-empty-description { font-size: .875rem; line-height: 1.625; color: var(--pk-muted); }
-.pk-empty-description a { text-decoration: underline; text-underline-offset: 4px; }
+.pk-empty-description a { text-decoration: underline; text-underline-offset: 4px; color: inherit; }
 .pk-empty-description a:hover { color: var(--pk-brand); }
 .pk-empty-content {
   display: flex; width: 100%; max-width: 24rem; min-width: 0;
-  flex-direction: column; align-items: center; gap: 1rem; font-size: .875rem;
+  flex-direction: column; align-items: center; gap: .625rem; font-size: .875rem;
 }

data/app/components/phlex_kit/field/field.css

@@ -0,0 +1,152 @@
+/* Co-located with field.rb — the PhlexKit::Field system (Set / Legend /
+   Group / Field / Content / Label / Title / Description / Separator /
+   Error), shadcn parity. Field is presentational layout; FormField remains
+   the Stimulus live-validation wrapper — they nest freely. FieldGroup is a
+   size container so orientation: :responsive fields can flip horizontal at
+   ≥28rem of group width. The choice-card recipe is a FieldLabel wrapping a
+   whole Field: it grows a border and highlights while its control is
+   checked (:has(input:checked)). */
+.pk-field-set {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  min-width: 0;
+  margin: 0;
+  padding: 0;
+  border: 0;
+}
+.pk-field-set:has(> .pk-radio-group) { gap: .75rem; }
+.pk-field-legend {
+  margin-bottom: .375rem;
+  padding: 0;
+  font-weight: 500;
+}
+.pk-field-legend.legend { font-size: 1rem; }
+.pk-field-legend.label { font-size: .875rem; }
+.pk-field-group {
+  display: flex;
+  width: 100%;
+  flex-direction: column;
+  gap: 1.25rem;
+  container-type: inline-size;
+}
+.pk-field-group .pk-field-group { gap: 1rem; container-type: normal; }
+
+.pk-field { display: flex; width: 100%; gap: .5rem; }
+.pk-field[data-invalid="true"] { color: var(--pk-red); }
+.pk-field[data-orientation="vertical"] { flex-direction: column; }
+.pk-field[data-orientation="vertical"] > * { width: 100%; }
+.pk-field[data-orientation="vertical"] > .pk-sr-only { width: auto; }
+.pk-field[data-orientation="horizontal"] { flex-direction: row; align-items: center; }
+.pk-field[data-orientation="horizontal"] > .pk-field-label,
+.pk-field[data-orientation="horizontal"] > .pk-field-content { flex: 1 1 auto; }
+.pk-field[data-orientation="horizontal"]:has(> .pk-field-content) { align-items: flex-start; }
+.pk-field[data-orientation="horizontal"]:has(> .pk-field-content) > .pk-checkbox,
+.pk-field[data-orientation="horizontal"]:has(> .pk-field-content) > .pk-radio { margin-top: 1px; }
+.pk-field[data-orientation="responsive"] { flex-direction: column; }
+.pk-field[data-orientation="responsive"] > * { width: 100%; }
+.pk-field[data-orientation="responsive"] > .pk-sr-only { width: auto; }
+@container (min-width: 28rem) {
+  .pk-field[data-orientation="responsive"] { flex-direction: row; align-items: center; }
+  .pk-field[data-orientation="responsive"] > * { width: auto; }
+  .pk-field[data-orientation="responsive"] > .pk-field-label,
+  .pk-field[data-orientation="responsive"] > .pk-field-content { flex: 1 1 auto; }
+  .pk-field[data-orientation="responsive"]:has(> .pk-field-content) { align-items: flex-start; }
+}
+
+.pk-field-content {
+  display: flex;
+  flex: 1;
+  flex-direction: column;
+  gap: .125rem;
+  line-height: 1.375;
+}
+.pk-field-label {
+  gap: .5rem;
+  line-height: 1.375;
+  width: fit-content;
+}
+.pk-field[data-disabled="true"] .pk-field-label,
+.pk-field[data-disabled="true"] .pk-field-title { opacity: .5; }
+
+/* Choice card: a FieldLabel wrapping a whole Field. */
+.pk-field-label:has(> .pk-field) {
+  width: 100%;
+  flex-direction: column;
+  align-items: stretch;
+  border: 1px solid var(--pk-border);
+  border-radius: var(--pk-radius);
+  font-weight: 400;
+  transition: background-color .15s ease, border-color .15s ease;
+}
+.pk-field-label > .pk-field { padding: .625rem; }
+.pk-field-label:has(> .pk-field):has(input:checked) {
+  background: color-mix(in oklab, var(--pk-brand) 10%, transparent);
+  border-color: color-mix(in oklab, var(--pk-brand) 20%, transparent);
+}
+:root[data-theme="light"] .pk-field-label:has(> .pk-field):has(input:checked) {
+  background: color-mix(in oklab, var(--pk-brand) 5%, transparent);
+  border-color: color-mix(in oklab, var(--pk-brand) 30%, transparent);
+}
+@media (prefers-color-scheme: light) {
+  :root[data-theme="system"] .pk-field-label:has(> .pk-field):has(input:checked) {
+    background: color-mix(in oklab, var(--pk-brand) 5%, transparent);
+    border-color: color-mix(in oklab, var(--pk-brand) 30%, transparent);
+  }
+}
+
+.pk-field-title {
+  display: flex;
+  width: fit-content;
+  align-items: center;
+  gap: .5rem;
+  font-size: .875rem;
+  font-weight: 500;
+  line-height: 1.375;
+}
+.pk-field-description {
+  margin: 0;
+  color: var(--pk-muted);
+  font-size: .875rem;
+  font-weight: 400;
+  line-height: 1.5;
+  text-align: left;
+}
+.pk-field-description a { text-decoration: underline; text-underline-offset: 4px; color: inherit; }
+.pk-field-description a:hover { color: var(--pk-brand); }
+.pk-field-legend.legend + .pk-field-description { margin-top: -.375rem; }
+
+.pk-field-separator {
+  position: relative;
+  height: 1.25rem;
+  margin-block: -.5rem;
+  font-size: .875rem;
+}
+.pk-field-separator .pk-field-separator-line {
+  position: absolute;
+  inset-inline: 0;
+  top: 50%;
+}
+.pk-field-separator-content {
+  position: relative;
+  display: block;
+  width: fit-content;
+  margin-inline: auto;
+  padding-inline: .5rem;
+  background: var(--pk-bg);
+  color: var(--pk-muted);
+}
+
+.pk-field-error {
+  color: var(--pk-red);
+  font-size: .875rem;
+  font-weight: 400;
+}
+.pk-field-error-list {
+  display: flex;
+  flex-direction: column;
+  gap: .25rem;
+  margin: 0 0 0 1rem;
+  padding: 0;
+  list-style: disc;
+}

data/app/components/phlex_kit/field/field.rb

@@ -0,0 +1,35 @@
+module PhlexKit
+  # One labeled control row/column, ported from shadcn/ui's Field. PRESENTATIONAL
+  # layout only — pair with PhlexKit::FormField when you want the kit's Stimulus
+  # live-validation (FormField wraps the control; Field arranges label, control,
+  # description and error around it — they nest without conflict).
+  #
+  #   render PhlexKit::Field.new do
+  #     render PhlexKit::FieldLabel.new(for: "email") { "Email" }
+  #     render PhlexKit::Input.new(id: "email", type: :email)
+  #     render PhlexKit::FieldDescription.new { "We never share it." }
+  #   end
+  #
+  # orientation: :vertical (default) stacks; :horizontal puts the label beside
+  # the control (checkbox/switch rows); :responsive is vertical that goes
+  # horizontal when the enclosing FieldGroup is ≥28rem wide (container query).
+  # `invalid: true` tints the whole field; `disabled: true` dims labels.
+  # `.pk-field*` (field.css).
+  class Field < BaseComponent
+    ORIENTATIONS = { vertical: "vertical", horizontal: "horizontal", responsive: "responsive" }.freeze
+
+    def initialize(orientation: :vertical, invalid: false, disabled: false, **attrs)
+      @orientation = orientation.to_sym
+      @invalid = invalid
+      @disabled = disabled
+      @attrs = attrs
+    end
+
+    def view_template(&)
+      data = { slot: "field", orientation: ORIENTATIONS.fetch(@orientation) }
+      data[:invalid] = "true" if @invalid
+      data[:disabled] = "true" if @disabled
+      div(**mix({ class: "pk-field", role: "group", data: data }, @attrs), &)
+    end
+  end
+end

data/app/components/phlex_kit/field/field_content.rb

@@ -0,0 +1,11 @@
+module PhlexKit
+  # Stacks a FieldTitle/FieldLabel + FieldDescription beside a control in a
+  # horizontal Field (e.g. checkbox rows with helper text), ported from
+  # shadcn/ui's FieldContent. See field.rb.
+  class FieldContent < BaseComponent
+    def initialize(**attrs) = (@attrs = attrs)
+    def view_template(&)
+      div(**mix({ class: "pk-field-content", data: { slot: "field-content" } }, @attrs), &)
+    end
+  end
+end

data/app/components/phlex_kit/field/field_description.rb

@@ -0,0 +1,10 @@
+module PhlexKit
+  # Muted helper text under (or beside) a Field's control, ported from
+  # shadcn/ui's FieldDescription. See field.rb.
+  class FieldDescription < BaseComponent
+    def initialize(**attrs) = (@attrs = attrs)
+    def view_template(&)
+      p(**mix({ class: "pk-field-description", data: { slot: "field-description" } }, @attrs), &)
+    end
+  end
+end