phlex_kit 0.4.0 → 0.5.0

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

@@ -0,0 +1,29 @@
+module PhlexKit
+  # Validation message(s) for a Field, ported from shadcn/ui's FieldError.
+  # Pass `errors:` an array of message strings (deduped; one renders plain,
+  # several render a list) or give a block. Renders nothing when empty —
+  # matching theirs. Distinct from FormFieldError, which is the Stimulus
+  # live-validation slot; server-rendered errors belong here. See field.rb.
+  class FieldError < BaseComponent
+    def initialize(errors: nil, **attrs)
+      @errors = Array(errors).compact.uniq
+      @attrs = attrs
+    end
+
+    def view_template(&block)
+      return if @errors.empty? && !block
+
+      div(**mix({ class: "pk-field-error", role: "alert", data: { slot: "field-error" } }, @attrs)) do
+        if block
+          yield
+        elsif @errors.length == 1
+          plain @errors.first
+        else
+          ul(class: "pk-field-error-list") do
+            @errors.each { |message| li { message } }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+module PhlexKit
+  # Column of Fields with the canonical rhythm, ported from shadcn/ui's
+  # FieldGroup. Also the CONTAINER for responsive fields — a Field with
+  # orientation: :responsive goes horizontal when this group is ≥28rem wide.
+  # See field.rb.
+  class FieldGroup < BaseComponent
+    def initialize(**attrs) = (@attrs = attrs)
+    def view_template(&)
+      div(**mix({ class: "pk-field-group", data: { slot: "field-group" } }, @attrs), &)
+    end
+  end
+end

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

@@ -0,0 +1,12 @@
+module PhlexKit
+  # <label> for a Field's control, ported from shadcn/ui's FieldLabel (their
+  # Label + field styling — ours composes .pk-label the same way). Wrap a
+  # whole Field in it for the choice-card recipe: the label grows a border
+  # and highlights while its control is checked. See field.rb.
+  class FieldLabel < BaseComponent
+    def initialize(**attrs) = (@attrs = attrs)
+    def view_template(&)
+      label(**mix({ class: "pk-label pk-field-label", data: { slot: "field-label" } }, @attrs), &)
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+module PhlexKit
+  # <legend> of a FieldSet, ported from shadcn/ui's FieldLegend.
+  # variant: :legend (text-base, default) or :label (text-sm — matches
+  # FieldLabel when the set sits among plain fields). See field.rb.
+  class FieldLegend < BaseComponent
+    VARIANTS = { legend: "legend", label: "label" }.freeze
+
+    def initialize(variant: :legend, **attrs)
+      @variant = variant.to_sym
+      @attrs = attrs
+    end
+
+    def view_template(&)
+      legend(**mix({ class: "pk-field-legend #{VARIANTS.fetch(@variant)}" }, @attrs), &)
+    end
+  end
+end

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

@@ -0,0 +1,15 @@
+module PhlexKit
+  # Hairline between FieldGroups, optionally with centered text riding the
+  # line ("Or continue with"), ported from shadcn/ui's FieldSeparator.
+  # See field.rb.
+  class FieldSeparator < BaseComponent
+    def initialize(**attrs) = (@attrs = attrs)
+
+    def view_template(&block)
+      div(**mix({ class: "pk-field-separator", data: { content: block ? "true" : "false" } }, @attrs)) do
+        render Separator.new(class: "pk-field-separator-line")
+        span(class: "pk-field-separator-content", &block) if block
+      end
+    end
+  end
+end

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

@@ -0,0 +1,10 @@
+module PhlexKit
+  # Semantic <fieldset> grouping several Fields under a FieldLegend, ported
+  # from shadcn/ui's FieldSet. See field.rb.
+  class FieldSet < BaseComponent
+    def initialize(**attrs) = (@attrs = attrs)
+    def view_template(&)
+      fieldset(**mix({ class: "pk-field-set" }, @attrs), &)
+    end
+  end
+end

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

@@ -0,0 +1,11 @@
+module PhlexKit
+  # Label-looking title that is NOT a <label> (for content inside a
+  # FieldLabel-wrapped choice card, where nesting labels is invalid HTML),
+  # ported from shadcn/ui's FieldTitle. See field.rb.
+  class FieldTitle < BaseComponent
+    def initialize(**attrs) = (@attrs = attrs)
+    def view_template(&)
+      div(**mix({ class: "pk-field-title" }, @attrs), &)
+    end
+  end
+end

data/app/components/phlex_kit/hover_card/hover_card.css

@@ -1,8 +1,16 @@
-/* Co-located with hover_card.rb. Tokens from the global stylesheet. */
+/* Co-located with hover_card.rb. Matched to shadcn/ui's current hover-card
+   (nova): 16rem popover panel, rounded-lg, p-2.5, text-sm, foreground-tint
+   ring. side: top/left/right flip the CSS position (bottom default).
+   Tokens from the global stylesheet. */
 .pk-hover-card { position: relative; display: inline-block; }
 .pk-hover-card-trigger { display: inline-block; }
 .pk-hover-card-content {
-  position: absolute; z-index: 50; top: calc(100% + .5rem); left: 0; width: 16rem;
-  border: 1px solid var(--pk-border); border-radius: calc(var(--pk-radius) - 2px); background: var(--pk-surface);
-  color: var(--pk-text); padding: 1rem; box-shadow: 0 8px 24px rgb(0 0 0 / .3); outline: none;
+  position: absolute; z-index: 50; top: calc(100% + .25rem); left: 0; width: 16rem;
+  border: 1px solid color-mix(in oklab, var(--pk-text) 10%, transparent);
+  border-radius: var(--pk-radius); background: var(--pk-surface);
+  color: var(--pk-text); padding: .625rem; font-size: .875rem;
+  box-shadow: 0 8px 24px rgb(0 0 0 / .3); outline: none;
 }
+.pk-hover-card-content.top { top: auto; bottom: calc(100% + .25rem); }
+.pk-hover-card-content.left { top: 50%; left: auto; right: calc(100% + .25rem); transform: translateY(-50%); }
+.pk-hover-card-content.right { top: 50%; left: calc(100% + .25rem); transform: translateY(-50%); }

data/app/components/phlex_kit/hover_card/hover_card_content.rb

@@ -1,8 +1,17 @@
 module PhlexKit
+  # The floating panel of a PhlexKit::HoverCard. `side:` picks the edge it
+  # opens from (:bottom default, :top/:left/:right — shadcn's side prop).
   class HoverCardContent < BaseComponent
-    def initialize(**attrs) = (@attrs = attrs)
+    SIDES = { bottom: nil, top: "top", left: "left", right: "right" }.freeze
+
+    def initialize(side: :bottom, **attrs)
+      @side = side.to_sym
+      @attrs = attrs
+    end
+
     def view_template(&)
-      div(**mix({ class: "pk-hover-card-content pk-hidden", data: { phlex_kit__hover_card_target: "content", state: "closed" } }, @attrs), &)
+      classes = [ "pk-hover-card-content", "pk-hidden", SIDES.fetch(@side) ].compact.join(" ")
+      div(**mix({ class: classes, data: { phlex_kit__hover_card_target: "content", state: "closed" } }, @attrs), &)
     end
   end
 end

data/app/components/phlex_kit/input/input.css

@@ -1,29 +1,63 @@
-/* Co-located with input.rb — UI::Input. ruby_ui's Tailwind input replaced with
-   our own vanilla CSS: the geometry is ruby_ui's (h-9 / rounded-md / px-3 py-1 /
-   text-sm / shadow-xs / ring-on-focus), realised against this app's palette
-   tokens. Not styled to match the legacy `.field input`; this is the kit's own
-   look and will be revisited in the visual redesign. Theme tokens come from the
-   global stylesheet. */
+/* Co-located with input.rb — PhlexKit::Input. Matched to shadcn/ui's current
+   input (nova): h-8, rounded-lg, px-2.5, translucent input fill in dark /
+   transparent in light, ring focus (border-ring, not brand), invalid ring
+   with the 20/40 light/dark split, tinted disabled fill, styled file
+   selector button. text-base on small screens (prevents iOS zoom), text-sm
+   from md up — their text-base md:text-sm. Theme tokens global. */
 .pk-input {
   height: 2rem;
   width: 100%;
+  min-width: 0;
   border-radius: var(--pk-radius);
   border: 1px solid var(--pk-input);
   background: color-mix(in oklab, var(--pk-input) 30%, transparent);
   color: var(--pk-text);
   padding: .25rem .625rem;
   font: inherit;
-  font-size: .875rem;
-  transition: color .15s ease, border-color .15s ease, box-shadow .15s ease;
+  font-size: 1rem;
+  transition: color .15s ease, border-color .15s ease, box-shadow .15s ease, background-color .15s ease;
+}
+@media (min-width: 768px) {
+  .pk-input { font-size: .875rem; }
 }
 .pk-input::placeholder { color: var(--pk-muted); }
+.pk-input::file-selector-button {
+  display: inline-flex;
+  height: 1.5rem;
+  border: 0;
+  background: transparent;
+  color: var(--pk-text);
+  font: inherit;
+  font-size: .875rem;
+  font-weight: 500;
+  margin-right: .5rem;
+}
 .pk-input:focus-visible {
   outline: none;
-  border-color: var(--pk-brand);
+  border-color: var(--pk-ring);
   box-shadow: 0 0 0 3px color-mix(in oklab, var(--pk-ring) 50%, transparent);
 }
-.pk-input:disabled { cursor: not-allowed; opacity: .5; }
+.pk-input:disabled {
+  pointer-events: none;
+  cursor: not-allowed;
+  opacity: .5;
+  background: color-mix(in oklab, var(--pk-input) 80%, transparent);
+}
 .pk-input[aria-invalid="true"] {
+  border-color: color-mix(in oklab, var(--pk-red) 50%, transparent);
+  box-shadow: 0 0 0 3px color-mix(in oklab, var(--pk-red) 40%, transparent);
+}
+:root[data-theme="light"] .pk-input { background: transparent; }
+:root[data-theme="light"] .pk-input:disabled { background: color-mix(in oklab, var(--pk-input) 50%, transparent); }
+:root[data-theme="light"] .pk-input[aria-invalid="true"] {
   border-color: var(--pk-red);
-  box-shadow: 0 0 0 3px color-mix(in oklab, var(--pk-red) 30%, transparent);
+  box-shadow: 0 0 0 3px color-mix(in oklab, var(--pk-red) 20%, transparent);
+}
+@media (prefers-color-scheme: light) {
+  :root[data-theme="system"] .pk-input { background: transparent; }
+  :root[data-theme="system"] .pk-input:disabled { background: color-mix(in oklab, var(--pk-input) 50%, transparent); }
+  :root[data-theme="system"] .pk-input[aria-invalid="true"] {
+    border-color: var(--pk-red);
+    box-shadow: 0 0 0 3px color-mix(in oklab, var(--pk-red) 20%, transparent);
+  }
 }

data/app/components/phlex_kit/input_group/input_group.css

@@ -1,35 +1,111 @@
-/* Co-located with input_group.rb — UI::InputGroup, shadcn parity: the shell
-   carries the border/fill and focus ring; the inner .pk-input goes naked. */
+/* Co-located with input_group.rb — PhlexKit::InputGroup, shadcn parity: the
+   shell carries the border/fill and focus ring; the inner .pk-input /
+   .pk-textarea go naked. Matched to nova: fixed h-8 (auto with a textarea or
+   block addon), ring-colored focus, invalid + disabled states lifted from
+   the control via :has(), block addons stack the group into a column,
+   theme-forked fill (translucent input in dark / transparent in light). */
 .pk-input-group {
+  position: relative;
   display: flex;
   align-items: center;
   width: 100%;
+  min-width: 0;
+  height: 2rem;
   border: 1px solid var(--pk-input);
   border-radius: var(--pk-radius);
   background: color-mix(in oklab, var(--pk-input) 30%, transparent);
-  transition: border-color .15s ease, box-shadow .15s ease;
+  transition: border-color .15s ease, box-shadow .15s ease, background-color .15s ease;
+}
+.pk-input-group:has(> textarea),
+.pk-input-group:has(> .pk-textarea),
+.pk-input-group:has(> .pk-input-group-addon.block-start),
+.pk-input-group:has(> .pk-input-group-addon.block-end) {
+  height: auto;
+  flex-direction: column;
+  align-items: stretch;
 }
 .pk-input-group:focus-within {
-  border-color: var(--pk-brand);
+  border-color: var(--pk-ring);
   box-shadow: 0 0 0 3px color-mix(in oklab, var(--pk-ring) 50%, transparent);
 }
-.pk-input-group .pk-input {
+.pk-input-group:has([aria-invalid="true"]) {
+  border-color: color-mix(in oklab, var(--pk-red) 50%, transparent);
+  box-shadow: 0 0 0 3px color-mix(in oklab, var(--pk-red) 40%, transparent);
+}
+.pk-input-group:has(:disabled) {
+  opacity: .5;
+  background: color-mix(in oklab, var(--pk-input) 80%, transparent);
+}
+.pk-input-group .pk-input,
+.pk-input-group .pk-textarea {
   border: 0;
   background: transparent;
   box-shadow: none;
   flex: 1;
 }
-.pk-input-group .pk-input:focus-visible { outline: none; box-shadow: none; border: 0; }
+.pk-input-group .pk-input:focus-visible,
+.pk-input-group .pk-textarea:focus-visible { outline: none; box-shadow: none; border: 0; }
+.pk-input-group .pk-input:disabled,
+.pk-input-group .pk-textarea:disabled { background: transparent; }
+/* Tighten the control's near-side padding beside an inline addon. */
+.pk-input-group:has(> .pk-input-group-addon.start) > .pk-input { padding-left: .375rem; }
+.pk-input-group:has(> .pk-input-group-addon.end) > .pk-input { padding-right: .375rem; }
+
 .pk-input-group-addon {
   display: flex;
   align-items: center;
-  gap: .25rem;
+  justify-content: center;
+  gap: .5rem;
   flex: none;
-  padding: 0 .625rem;
+  cursor: text;
+  user-select: none;
+  padding-block: .375rem;
+  color: var(--pk-muted);
+  font-size: .875rem;
+  font-weight: 500;
+}
+.pk-input-group-addon.start { order: -1; padding-left: .5rem; }
+.pk-input-group-addon.end { order: 99; padding-right: .5rem; }
+.pk-input-group-addon.block-start,
+.pk-input-group-addon.block-end {
+  width: 100%;
+  justify-content: flex-start;
+  padding-inline: .625rem;
+}
+.pk-input-group-addon.block-start { order: -1; padding-top: .5rem; }
+.pk-input-group-addon.block-end { order: 99; padding-bottom: .5rem; }
+.pk-input-group-addon.block-start.bordered { border-bottom: 1px solid var(--pk-border); padding-bottom: .5rem; }
+.pk-input-group-addon.block-end.bordered { border-top: 1px solid var(--pk-border); padding-top: .5rem; }
+.pk-input-group-addon svg:not([class*="size-"]) { width: 1rem; height: 1rem; }
+.pk-input-group-addon > kbd { border-radius: calc(var(--pk-radius) - 5px); }
+.pk-input-group-addon.start:has(> .pk-button) { margin-left: -0.3rem; }
+.pk-input-group-addon.end:has(> .pk-button) { margin-right: -0.3rem; }
+
+.pk-button.pk-input-group-button {
+  gap: .25rem;
+  border-radius: calc(var(--pk-radius) - 3px);
+  box-shadow: none;
+}
+.pk-input-group-text {
+  display: flex;
+  align-items: center;
+  gap: .5rem;
   color: var(--pk-muted);
   font-size: .875rem;
 }
-.pk-input-group-addon.start { padding-right: 0; }
-.pk-input-group-addon.end { padding-left: 0; }
-.pk-input-group-addon svg { width: 1rem; height: 1rem; }
-.pk-input-group-text { color: var(--pk-muted); }
+.pk-input-group-text svg { pointer-events: none; }
+
+:root[data-theme="light"] .pk-input-group { background: transparent; }
+:root[data-theme="light"] .pk-input-group:has(:disabled) { background: color-mix(in oklab, var(--pk-input) 50%, transparent); }
+:root[data-theme="light"] .pk-input-group:has([aria-invalid="true"]) {
+  border-color: var(--pk-red);
+  box-shadow: 0 0 0 3px color-mix(in oklab, var(--pk-red) 20%, transparent);
+}
+@media (prefers-color-scheme: light) {
+  :root[data-theme="system"] .pk-input-group { background: transparent; }
+  :root[data-theme="system"] .pk-input-group:has(:disabled) { background: color-mix(in oklab, var(--pk-input) 50%, transparent); }
+  :root[data-theme="system"] .pk-input-group:has([aria-invalid="true"]) {
+    border-color: var(--pk-red);
+    box-shadow: 0 0 0 3px color-mix(in oklab, var(--pk-red) 20%, transparent);
+  }
+}

data/app/components/phlex_kit/input_group/input_group_addon.rb

@@ -1,8 +1,15 @@
 module PhlexKit
-  # Leading/trailing addon inside an InputGroup — icons, text or small buttons.
-  # See input_group.rb.
+  # Addon inside an InputGroup — icons, text or small buttons. `align:` places
+  # it: :start / :end inline beside the control (shadcn's inline-start/-end),
+  # :block_start / :block_end as full-width header/footer rows (the group
+  # stacks into a column). See input_group.rb.
   class InputGroupAddon < BaseComponent
-    ALIGNS = { start: "start", end: "end" }.freeze
+    ALIGNS = {
+      start: "start",
+      end: "end",
+      block_start: "block-start",
+      block_end: "block-end"
+    }.freeze
 
     def initialize(align: :start, **attrs)
       @align = align.to_sym
@@ -10,7 +17,7 @@ module PhlexKit
     end
 
     def view_template(&)
-      div(**mix({ class: "pk-input-group-addon #{ALIGNS.fetch(@align)}" }, @attrs), &)
+      div(**mix({ class: "pk-input-group-addon #{ALIGNS.fetch(@align)}", role: "group" }, @attrs), &)
     end
   end
 end

data/app/components/phlex_kit/input_group/input_group_button.rb

@@ -0,0 +1,18 @@
+module PhlexKit
+  # Small button inside an InputGroupAddon, ported from shadcn/ui's
+  # InputGroupButton — a ghost xs Button tuned to sit flush in the shell
+  # (tighter radius, no shadow). Same knobs as Button (variant:/size:/icon:),
+  # defaulting to variant: :ghost, size: :xs. See input_group.rb.
+  class InputGroupButton < BaseComponent
+    def initialize(variant: :ghost, size: :xs, icon: false, **attrs)
+      @variant = variant
+      @size = size
+      @icon = icon
+      @attrs = attrs
+    end
+
+    def view_template(&block)
+      render Button.new(variant: @variant, size: @size, icon: @icon, **mix({ class: "pk-input-group-button" }, @attrs), &block)
+    end
+  end
+end

data/app/components/phlex_kit/input_otp/input_otp.css

@@ -1,10 +1,12 @@
-/* Co-located with input_otp.rb — UI::InputOTP, shadcn parity: joined cells
-   (shared borders, outer corners rounded), ring on the active cell. */
+/* Co-located with input_otp.rb — PhlexKit::InputOTP, shadcn parity: joined
+   cells (shared borders, outer corners rounded), ring on the active cell,
+   nova metrics (size-8 slots, ring-colored focus, theme-forked fill,
+   invalid states on slot + group). */
 .pk-input-otp { display: flex; align-items: center; gap: .5rem; }
 .pk-input-otp-group { display: flex; align-items: center; }
 .pk-input-otp-slot {
-  width: 2.25rem;
-  height: 2.25rem;
+  width: 2rem;
+  height: 2rem;
   border: 1px solid var(--pk-input);
   background: color-mix(in oklab, var(--pk-input) 30%, transparent);
   color: var(--pk-text);
@@ -26,7 +28,29 @@
 .pk-input-otp-slot:focus {
   position: relative;
   z-index: 1;
-  border-color: var(--pk-brand);
+  border-color: var(--pk-ring);
   box-shadow: 0 0 0 3px color-mix(in oklab, var(--pk-ring) 50%, transparent);
 }
+.pk-input-otp-slot[aria-invalid="true"] { border-color: var(--pk-red); }
+.pk-input-otp-slot[aria-invalid="true"]:focus {
+  border-color: var(--pk-red);
+  box-shadow: 0 0 0 3px color-mix(in oklab, var(--pk-red) 40%, transparent);
+}
+.pk-input-otp-group:has([aria-invalid="true"]) {
+  border-radius: var(--pk-radius);
+  box-shadow: 0 0 0 3px color-mix(in oklab, var(--pk-red) 40%, transparent);
+}
+.pk-input-otp-slot:disabled { cursor: not-allowed; opacity: .5; }
+:root[data-theme="light"] .pk-input-otp-slot { background: transparent; }
+:root[data-theme="light"] .pk-input-otp-slot[aria-invalid="true"]:focus,
+:root[data-theme="light"] .pk-input-otp-group:has([aria-invalid="true"]) {
+  box-shadow: 0 0 0 3px color-mix(in oklab, var(--pk-red) 20%, transparent);
+}
+@media (prefers-color-scheme: light) {
+  :root[data-theme="system"] .pk-input-otp-slot { background: transparent; }
+  :root[data-theme="system"] .pk-input-otp-slot[aria-invalid="true"]:focus,
+  :root[data-theme="system"] .pk-input-otp-group:has([aria-invalid="true"]) {
+    box-shadow: 0 0 0 3px color-mix(in oklab, var(--pk-red) 20%, transparent);
+  }
+}
 .pk-input-otp-separator { color: var(--pk-muted); }

data/app/components/phlex_kit/item/item.css

@@ -1,4 +1,8 @@
-/* Co-located with item.rb — UI::Item family, shadcn parity. */
+/* Co-located with item.rb — PhlexKit::Item family, matched to shadcn/ui's
+   current item (nova): rounded-lg rows, sizes (sm keeps default paddings per
+   nova; xs tightens), media variants (icon glyph / square image thumb sized
+   by the item size), media nudges down beside a description, link items
+   (href:) hover-fill, Header stacks the item into a column. */
 .pk-item {
   display: flex;
   align-items: center;
@@ -6,27 +10,71 @@
   width: 100%;
   border: 1px solid transparent;
   border-radius: var(--pk-radius);
-  padding: .625rem .875rem;
+  padding: .625rem .75rem;
   font-size: .875rem;
+  color: inherit;
+  text-decoration: none;
 }
+a.pk-item:hover { background: var(--pk-surface-2); }
 .pk-item.outline { border-color: var(--pk-border); }
-.pk-item.muted { background: var(--pk-surface-2); }
+.pk-item.muted { background: color-mix(in oklab, var(--pk-surface-2) 50%, transparent); }
+.pk-item.xs { gap: .5rem; padding: .5rem .625rem; }
+.pk-item:has(> .pk-item-header),
+.pk-item:has(> .pk-item-footer) { flex-direction: column; align-items: stretch; }
+
 .pk-item-media {
   display: flex;
   align-items: center;
   justify-content: center;
+  gap: .5rem;
   flex: none;
   color: var(--pk-muted);
 }
-.pk-item-media svg { width: 1rem; height: 1rem; }
-.pk-item-content { display: flex; flex: 1; flex-direction: column; gap: .125rem; min-width: 0; }
-.pk-item-title { font-weight: 500; line-height: 1.25; }
+.pk-item:has(.pk-item-description) > .pk-item-media {
+  transform: translateY(.125rem);
+  align-self: flex-start;
+}
+.pk-item-media.icon svg:not([class*="size-"]) { width: 1rem; height: 1rem; }
+.pk-item-media.image {
+  width: 2.5rem;
+  height: 2.5rem;
+  overflow: hidden;
+  border-radius: calc(var(--pk-radius) - 4px);
+}
+.pk-item.sm .pk-item-media.image { width: 2rem; height: 2rem; }
+.pk-item.xs .pk-item-media.image { width: 1.5rem; height: 1.5rem; }
+.pk-item-media.image img { width: 100%; height: 100%; object-fit: cover; }
+
+.pk-item-content { display: flex; flex: 1; flex-direction: column; gap: .25rem; min-width: 0; }
+.pk-item.xs .pk-item-content { gap: 0; }
+.pk-item-title {
+  display: flex;
+  align-items: center;
+  gap: .5rem;
+  font-weight: 500;
+  font-size: .875rem;
+  line-height: 1.375;
+  text-underline-offset: 4px;
+}
 .pk-item-description {
   color: var(--pk-muted);
   font-size: .875rem;
-  line-height: 1.375;
+  line-height: 1.5;
+  text-align: left;
   overflow: hidden;
   text-overflow: ellipsis;
 }
+.pk-item.xs .pk-item-description { font-size: .75rem; }
 .pk-item-actions { display: flex; align-items: center; gap: .5rem; flex: none; }
-.pk-item-group { display: flex; flex-direction: column; width: 100%; gap: .5rem; }
+.pk-item-header,
+.pk-item-footer {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  gap: .5rem;
+  width: 100%;
+}
+.pk-item-separator { height: 1px; margin-block: .5rem; background: var(--pk-border); }
+.pk-item-group { display: flex; flex-direction: column; width: 100%; gap: 1rem; }
+.pk-item-group:has(.pk-item.sm) { gap: .625rem; }
+.pk-item-group:has(.pk-item.xs) { gap: .5rem; }

data/app/components/phlex_kit/item/item.rb

@@ -1,18 +1,28 @@
 module PhlexKit
   # List row, ported from shadcn/ui's Item: a flex row of ItemMedia +
   # ItemContent(ItemTitle + ItemDescription) + ItemActions, optionally grouped
-  # in an ItemGroup. variant :outline draws a bordered card row.
+  # in an ItemGroup (with ItemSeparator) or stacked under an ItemHeader.
+  # variant :outline draws a bordered card row; `size:` tightens (:sm/:xs);
+  # `href:` renders an <a> (their asChild link item — hover fills apply).
   # `.pk-item*` (item.css).
   class Item < BaseComponent
     VARIANTS = { default: nil, outline: "outline", muted: "muted" }.freeze
+    SIZES = { md: nil, sm: "sm", xs: "xs" }.freeze
 
-    def initialize(variant: :default, **attrs)
+    def initialize(variant: :default, size: :md, href: nil, **attrs)
       @variant = variant.to_sym
+      @size = size.to_sym
+      @href = href
       @attrs = attrs
     end
 
     def view_template(&)
-      div(**mix({ class: [ "pk-item", VARIANTS.fetch(@variant) ].compact.join(" ") }, @attrs), &)
+      classes = [ "pk-item", VARIANTS.fetch(@variant), SIZES.fetch(@size) ].compact.join(" ")
+      if @href
+        a(**mix({ class: classes, href: @href }, @attrs), &)
+      else
+        div(**mix({ class: classes }, @attrs), &)
+      end
     end
   end
 end

data/app/components/phlex_kit/item/item_footer.rb

@@ -0,0 +1,8 @@
+module PhlexKit
+  # Full-width footer band of an Item. Ported from shadcn/ui's ItemFooter.
+  # See item.rb.
+  class ItemFooter < BaseComponent
+    def initialize(**attrs) = (@attrs = attrs)
+    def view_template(&) = div(**mix({ class: "pk-item-footer" }, @attrs), &)
+  end
+end

data/app/components/phlex_kit/item/item_header.rb

@@ -0,0 +1,8 @@
+module PhlexKit
+  # Full-width header band of an Item (e.g. a cover image) — the item stacks
+  # into a column when present. Ported from shadcn/ui's ItemHeader. See item.rb.
+  class ItemHeader < BaseComponent
+    def initialize(**attrs) = (@attrs = attrs)
+    def view_template(&) = div(**mix({ class: "pk-item-header" }, @attrs), &)
+  end
+end

data/app/components/phlex_kit/item/item_media.rb

@@ -1,7 +1,17 @@
 module PhlexKit
-  # Leading icon/avatar slot of an Item. See item.rb.
+  # Leading media slot of an Item. variant :icon sizes a glyph; :image crops a
+  # square thumbnail (sized by the item's size modifier); :default is bare.
+  # See item.rb.
   class ItemMedia < BaseComponent
-    def initialize(**attrs) = (@attrs = attrs)
-    def view_template(&) = div(**mix({ class: "pk-item-media" }, @attrs), &)
+    VARIANTS = { default: nil, icon: "icon", image: "image" }.freeze
+
+    def initialize(variant: :default, **attrs)
+      @variant = variant.to_sym
+      @attrs = attrs
+    end
+
+    def view_template(&)
+      div(**mix({ class: [ "pk-item-media", VARIANTS.fetch(@variant) ].compact.join(" ") }, @attrs), &)
+    end
   end
 end

data/app/components/phlex_kit/item/item_separator.rb

@@ -0,0 +1,10 @@
+module PhlexKit
+  # Hairline between Items in an ItemGroup, ported from shadcn/ui's
+  # ItemSeparator. See item.rb.
+  class ItemSeparator < BaseComponent
+    def initialize(**attrs) = (@attrs = attrs)
+    def view_template
+      div(**mix({ class: "pk-item-separator", role: "separator", aria: { hidden: true } }, @attrs))
+    end
+  end
+end

data/app/components/phlex_kit/kbd/kbd.css

@@ -15,3 +15,13 @@
   font-weight: 500;
 }
 .pk-kbd-group { display: inline-flex; align-items: center; gap: .25rem; font-family: inherit; }
+.pk-kbd svg:not([class*="size-"]) { width: .75rem; height: .75rem; }
+/* Inside an (inverted) tooltip the chip tints from the page background. */
+.pk-tooltip-content .pk-kbd {
+  background: color-mix(in oklab, var(--pk-bg) 10%, transparent);
+  color: var(--pk-bg);
+}
+:root[data-theme="light"] .pk-tooltip-content .pk-kbd { background: color-mix(in oklab, var(--pk-bg) 20%, transparent); }
+@media (prefers-color-scheme: light) {
+  :root[data-theme="system"] .pk-tooltip-content .pk-kbd { background: color-mix(in oklab, var(--pk-bg) 20%, transparent); }
+}