phlex_kit 0.4.0 → 0.5.0

data/app/components/phlex_kit/popover/popover.css

@@ -1,9 +1,20 @@
-/* Co-located with popover.rb. CSS-positioned panel. Tokens from the global stylesheet. */
+/* Co-located with popover.rb. CSS-positioned panel matched to nova: w-72,
+   rounded-lg, p-2.5 with a gap-2.5 column, foreground-tint ring, text-sm;
+   Header (title + muted description) stacks at gap-0.5. `align: :end`
+   flips the panel to the trigger's end edge. Tokens global. */
 .pk-popover { position: relative; display: inline-block; }
 .pk-popover-trigger { display: inline-block; }
 .pk-popover-content {
-  position: absolute; z-index: 50; top: calc(100% + .5rem); left: 0;
-  min-width: 12rem; border: 1px solid var(--pk-border); border-radius: calc(var(--pk-radius) - 2px);
-  background: var(--pk-surface); color: var(--pk-text); padding: .75rem;
+  position: absolute; z-index: 50; top: calc(100% + .25rem); left: 0;
+  display: flex; flex-direction: column; gap: .625rem;
+  width: 18rem;
+  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-popover-content.end { left: auto; right: 0; }
+.pk-popover-header { display: flex; flex-direction: column; gap: .125rem; font-size: .875rem; }
+.pk-popover-title { margin: 0; font-size: .875rem; font-weight: 500; }
+.pk-popover-description { margin: 0; color: var(--pk-muted); }

data/app/components/phlex_kit/popover/popover_content.rb

@@ -1,8 +1,17 @@
 module PhlexKit
+  # The floating panel of a PhlexKit::Popover. `align: :end` flips it to the
+  # trigger's end edge (their align prop). See popover.rb.
   class PopoverContent < BaseComponent
-    def initialize(**attrs) = (@attrs = attrs)
+    ALIGNS = { start: nil, end: "end" }.freeze
+
+    def initialize(align: :start, **attrs)
+      @align = align.to_sym
+      @attrs = attrs
+    end
+
     def view_template(&)
-      div(**mix({ class: "pk-popover-content pk-hidden", data: { phlex_kit__popover_target: "content", state: "closed" } }, @attrs), &)
+      classes = [ "pk-popover-content", "pk-hidden", ALIGNS.fetch(@align) ].compact.join(" ")
+      div(**mix({ class: classes, data: { phlex_kit__popover_target: "content", state: "closed" } }, @attrs), &)
     end
   end
 end

data/app/components/phlex_kit/popover/popover_description.rb

@@ -0,0 +1,10 @@
+module PhlexKit
+  # Muted body copy of a PopoverHeader, ported from shadcn/ui's
+  # PopoverDescription. See popover.rb.
+  class PopoverDescription < BaseComponent
+    def initialize(**attrs) = (@attrs = attrs)
+    def view_template(&)
+      p(**mix({ class: "pk-popover-description" }, @attrs), &)
+    end
+  end
+end

data/app/components/phlex_kit/popover/popover_header.rb

@@ -0,0 +1,10 @@
+module PhlexKit
+  # Title + description block at the top of a PopoverContent, ported from
+  # shadcn/ui's PopoverHeader. See popover.rb.
+  class PopoverHeader < BaseComponent
+    def initialize(**attrs) = (@attrs = attrs)
+    def view_template(&)
+      div(**mix({ class: "pk-popover-header" }, @attrs), &)
+    end
+  end
+end

data/app/components/phlex_kit/popover/popover_title.rb

@@ -0,0 +1,10 @@
+module PhlexKit
+  # Heading of a PopoverHeader, ported from shadcn/ui's PopoverTitle.
+  # See popover.rb.
+  class PopoverTitle < BaseComponent
+    def initialize(**attrs) = (@attrs = attrs)
+    def view_template(&)
+      h2(**mix({ class: "pk-popover-title" }, @attrs), &)
+    end
+  end
+end

data/app/components/phlex_kit/progress/progress.css

@@ -1,13 +1,13 @@
-/* Co-located with progress.rb — UI::Progress. ruby_ui's Tailwind (h-2 rounded-full
-   bg-primary/20, indicator bg-primary translated by value) as vanilla CSS on the
-   palette tokens. Theme tokens come from the global stylesheet. */
+/* Co-located with progress.rb — PhlexKit::Progress. Matched to nova: an h-1
+   muted track with the brand indicator translated by value. Theme tokens
+   from the global stylesheet. */
 .pk-progress {
   position: relative;
-  height: .5rem;
+  height: .25rem;
   width: 100%;
   overflow: hidden;
   border-radius: 999px;
-  background: color-mix(in oklab, var(--pk-brand) 20%, transparent);
+  background: var(--pk-surface-2);
 }
 .pk-progress-indicator {
   height: 100%;

data/app/components/phlex_kit/radio_button/radio_button.css

@@ -1,9 +1,53 @@
-/* Co-located with radio_button.rb. Theme tokens from the global stylesheet. */
+/* Co-located with radio_button.rb — PhlexKit::RadioButton. Matched to
+   shadcn/ui's current radio-group item (same recipe as the checkbox):
+   appearance:none circle with the input border + translucent dark fill,
+   brand fill with a primary-foreground dot when checked, extended touch
+   target, focus + aria-invalid rings. Native input semantics kept — no JS. */
 .pk-radio {
+  appearance: none;
+  -webkit-appearance: none;
+  position: relative;
+  display: inline-grid;
+  place-content: center;
   height: 1rem;
   width: 1rem;
   flex: none;
+  margin: 0;
   border-radius: 9999px;
-  accent-color: var(--pk-brand);
+  border: 1px solid var(--pk-input);
+  background: color-mix(in oklab, var(--pk-input) 30%, transparent);
+  cursor: pointer;
+  transition: border-color .15s ease, background-color .15s ease, box-shadow .15s ease;
 }
+.pk-radio::before { content: ""; position: absolute; inset: -.5rem; }
+.pk-radio:checked { background: var(--pk-brand); border-color: var(--pk-brand); }
+.pk-radio:checked::after {
+  content: "";
+  width: .5rem;
+  height: .5rem;
+  border-radius: 9999px;
+  background: var(--pk-brand-ink);
+}
+.pk-radio:focus-visible {
+  outline: none;
+  border-color: var(--pk-ring);
+  box-shadow: 0 0 0 3px color-mix(in oklab, var(--pk-ring) 50%, transparent);
+}
+.pk-radio[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-radio[aria-invalid="true"]:checked { border-color: var(--pk-brand); }
 .pk-radio:disabled { cursor: not-allowed; opacity: .5; }
+:root[data-theme="light"] .pk-radio:not(:checked) { background: transparent; }
+:root[data-theme="light"] .pk-radio[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-radio:not(:checked) { background: transparent; }
+  :root[data-theme="system"] .pk-radio[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/radio_group/radio_group.css

@@ -1,3 +1,3 @@
-/* Co-located with radio_group.rb — UI::RadioGroup, shadcn parity (grid gap-3). */
-.pk-radio-group { display: grid; gap: .75rem; }
+/* Co-located with radio_group.rb — UI::RadioGroup, shadcn parity (grid gap-2). */
+.pk-radio-group { display: grid; gap: .5rem; }
 .pk-radio-group .pk-label { gap: .75rem; }

data/app/components/phlex_kit/resizable/resizable.css

@@ -21,3 +21,20 @@
   outline: none;
   box-shadow: 0 0 0 2px color-mix(in oklab, var(--pk-ring) 50%, transparent);
 }
+
+/* Visible grip pill (their withHandle / .cn-resizable-handle-icon). */
+.pk-resizable-handle-grip {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  z-index: 1;
+  width: .25rem;
+  height: 1.5rem;
+  border-radius: var(--pk-radius);
+  background: var(--pk-border);
+  transform: translate(-50%, -50%);
+}
+.pk-resizable-group.vertical > .pk-resizable-handle .pk-resizable-handle-grip {
+  width: 1.5rem;
+  height: .25rem;
+}

data/app/components/phlex_kit/resizable/resizable_handle.rb

@@ -1,7 +1,9 @@
 module PhlexKit
-  # Drag handle between two ResizablePanels. See resizable_panel_group.rb.
+  # Drag handle between two ResizablePanels. `with_handle: true` shows the
+  # visible grip pill (their withHandle). See resizable_panel_group.rb.
   class ResizableHandle < BaseComponent
-    def initialize(**attrs)
+    def initialize(with_handle: false, **attrs)
+      @with_handle = with_handle
       @attrs = attrs
     end
 
@@ -15,7 +17,9 @@ module PhlexKit
           phlex_kit__resizable_target: "handle",
           action: "pointerdown->phlex-kit--resizable#start"
         }
-      }, @attrs))
+      }, @attrs)) do
+        span(class: "pk-resizable-handle-grip", aria: { hidden: "true" }) if @with_handle
+      end
     end
   end
 end

data/app/components/phlex_kit/select/select.css

@@ -21,15 +21,23 @@
   border: 1px solid var(--pk-input);
   background: transparent;
   color: var(--pk-text);
-  padding: .25rem .75rem;
+  padding: .25rem .5rem .25rem .625rem;
+  gap: .375rem;
   font: inherit;
   font-size: .875rem;
-    cursor: pointer;
-  transition: border-color .15s ease, box-shadow .15s ease;
+  cursor: pointer;
+  background: color-mix(in oklab, var(--pk-input) 30%, transparent);
+  transition: border-color .15s ease, box-shadow .15s ease, background-color .15s ease;
+}
+.pk-select-trigger:hover { background: color-mix(in oklab, var(--pk-input) 50%, transparent); }
+.pk-select-trigger.sm { height: 1.75rem; border-radius: min(calc(var(--pk-radius) - 2px), 10px); }
+.pk-select-trigger[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-select-trigger: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-select-trigger:disabled { cursor: not-allowed; opacity: .5; }
@@ -49,15 +57,15 @@
 .pk-select-viewport {
   max-height: 24rem;
   overflow: auto;
-  border-radius: calc(var(--pk-radius) - 2px);
-  border: 1px solid var(--pk-border);
+  border-radius: var(--pk-radius);
+  border: 1px solid color-mix(in oklab, var(--pk-text) 10%, transparent);
   background: var(--pk-surface);
   color: var(--pk-text);
   padding: .25rem;
   box-shadow: 0 4px 16px rgba(0, 0, 0, .4);
 }
 
-.pk-select-label { margin: 0; padding: .375rem .5rem; font-size: .875rem; font-weight: 600; }
+.pk-select-label { margin: 0; padding: .25rem .375rem; font-size: .75rem; font-weight: 400; color: var(--pk-muted); }
 
 .pk-select-item {
   position: relative;
@@ -65,16 +73,44 @@
   align-items: center;
   cursor: pointer;
   user-select: none;
-  border-radius: calc(var(--pk-radius) - 4px);
-  padding: .375rem .5rem;
+  gap: .375rem;
+  border-radius: calc(var(--pk-radius) - 2px);
+  padding: .25rem 2rem .25rem .375rem;
   font-size: .875rem;
   color: var(--pk-text);
   outline: none;
   transition: background-color .12s ease, color .12s ease;
 }
+.pk-select-item svg:not([class*="size-"]) { width: 1rem; height: 1rem; }
 .pk-select-item:hover,
 .pk-select-item:focus,
 .pk-select-item[aria-current="true"],
 .pk-select-item[aria-selected="true"] { background: var(--pk-accent); }
-.pk-select-item-check { visibility: hidden; flex: none; width: 1rem; height: 1rem; margin-right: .5rem; }
+.pk-select-item-check {
+  visibility: hidden;
+  position: absolute;
+  right: .5rem;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 1rem;
+  height: 1rem;
+  pointer-events: none;
+}
 .pk-select-item[aria-selected="true"] .pk-select-item-check { visibility: visible; }
+
+.pk-select-separator { height: 1px; margin: .25rem -.25rem; background: var(--pk-border); }
+:root[data-theme="light"] .pk-select-trigger { background: transparent; }
+:root[data-theme="light"] .pk-select-trigger:hover { background: transparent; }
+:root[data-theme="light"] .pk-select-trigger[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-select-trigger { background: transparent; }
+  :root[data-theme="system"] .pk-select-trigger:hover { background: transparent; }
+  :root[data-theme="system"] .pk-select-trigger[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/select/select_separator.rb

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

data/app/components/phlex_kit/select/select_trigger.rb

@@ -3,7 +3,10 @@ module PhlexKit
   # up/down chevron, and opens the panel on click (`phlex-kit--select#onClick`).
   # See select.rb.
   class SelectTrigger < BaseComponent
-    def initialize(**attrs)
+    SIZES = { md: nil, sm: "sm" }.freeze
+
+    def initialize(size: :md, **attrs)
+      @size = size.to_sym
       @attrs = attrs
     end
 
@@ -11,7 +14,7 @@ module PhlexKit
       button(**mix({
         type: :button,
         role: "combobox",
-        class: "pk-select-trigger",
+        class: [ "pk-select-trigger", SIZES.fetch(@size) ].compact.join(" "),
         aria: { expanded: "false", haspopup: "listbox", autocomplete: "none" },
         data: { action: "phlex-kit--select#onClick", phlex_kit__select_target: "trigger" }
       }, @attrs)) do

data/app/components/phlex_kit/sheet/sheet.css

@@ -1,17 +1,26 @@
-/* Co-located with sheet.rb. Theme tokens from the global stylesheet. */
+/* Co-located with sheet.rb. Matched to nova: the panel carries NO padding
+   (header/footer bring their own p-4; body content adds px-4), gap-4 column,
+   text-sm, title text-base/medium, close pinned top-3/right-3, side panels
+   75%-wide capped at 24rem. Overlay at the kit-unified black/10 + blur-xs
+   (see dialog.css). Theme tokens from the global stylesheet. */
 .pk-sheet-trigger { display: inline-block; }
-.pk-sheet-backdrop { position: fixed; inset: 0; z-index: 50; background: rgb(0 0 0 / .5); backdrop-filter: blur(8px); }
+.pk-sheet-backdrop { position: fixed; inset: 0; z-index: 50; background: rgb(0 0 0 / .1); backdrop-filter: blur(4px); }
+@supports not (backdrop-filter: blur(1px)) {
+  .pk-sheet-backdrop { background: rgb(0 0 0 / .5); }
+}
 .pk-sheet-content {
   position: fixed; z-index: 50; display: flex; flex-direction: column; gap: 1rem;
-  background: var(--pk-surface); color: var(--pk-text); padding: 1.5rem;
+  background: var(--pk-surface); color: var(--pk-text); padding: 0;
+  font-size: .875rem;
   box-shadow: 0 10px 30px rgb(0 0 0 / .35); overflow: auto;
 }
-.pk-sheet-content.right { inset-block: 0; right: 0; height: 100%; width: min(24rem, 100%); border-left: 1px solid var(--pk-border); }
-.pk-sheet-content.left  { inset-block: 0; left: 0;  height: 100%; width: min(24rem, 100%); border-right: 1px solid var(--pk-border); }
+.pk-sheet-content.right { inset-block: 0; right: 0; height: 100%; width: 75%; max-width: 24rem; border-left: 1px solid var(--pk-border); }
+.pk-sheet-content.left  { inset-block: 0; left: 0;  height: 100%; width: 75%; max-width: 24rem; border-right: 1px solid var(--pk-border); }
 .pk-sheet-content.top    { inset-inline: 0; top: 0;    border-bottom: 1px solid var(--pk-border); }
 .pk-sheet-content.bottom { inset-inline: 0; bottom: 0; border-top: 1px solid var(--pk-border); }
-.pk-sheet-header { display: flex; flex-direction: column; gap: .375rem; }
-.pk-sheet-footer { display: flex; flex-direction: column-reverse; gap: .5rem; }
-.pk-sheet-title { font-size: 1.125rem; font-weight: 600; line-height: 1; letter-spacing: -.01em; }
+.pk-sheet-header { display: flex; flex-direction: column; gap: .125rem; padding: 1rem; }
+.pk-sheet-footer { display: flex; flex-direction: column-reverse; gap: .5rem; padding: 1rem; margin-top: auto; }
+.pk-sheet-title { font-size: 1rem; font-weight: 500; line-height: 1; color: var(--pk-text); }
 .pk-sheet-description { font-size: .875rem; color: var(--pk-muted); }
-.pk-sheet-middle { padding-block: 1rem; }
+.pk-sheet-middle { flex: 1; padding-inline: 1rem; }
+.pk-sheet-content > .pk-overlay-close { inset-inline-end: .75rem; top: .75rem; }

data/app/components/phlex_kit/sheet/sheet_close.rb

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

data/app/components/phlex_kit/sheet/sheet_content.rb

@@ -1,8 +1,10 @@
 module PhlexKit
   class SheetContent < BaseComponent
     SIDES = { top: "top", right: "right", bottom: "bottom", left: "left" }.freeze
-    def initialize(side: :right, **attrs)
+
+    def initialize(side: :right, show_close_button: true, **attrs)
       @side = side.to_sym
+      @show_close_button = show_close_button
       @attrs = attrs
     end
     def view_template(&block)
@@ -11,9 +13,11 @@ module PhlexKit
           div(class: "pk-sheet-backdrop", data: { action: "click->phlex-kit--sheet-content#close" })
           div(**mix({ class: ["pk-sheet-content", SIDES.fetch(@side)].join(" ") }, @attrs)) do
             block&.call
-            button(type: "button", class: "pk-overlay-close", data: { action: "click->phlex-kit--sheet-content#close" }) 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--sheet-content#close" }) do
+                render Icon.new(:x, size: 15)
+                span(class: "pk-sr-only") { "Close" }
+              end
             end
           end
         end

data/app/components/phlex_kit/sidebar/sidebar.css

@@ -3,8 +3,10 @@
    / MenuAction / MenuBadge / MenuSkeleton / MenuSub / MenuSubItem / MenuSubButton
    / Separator / Input / Inset). ruby_ui's structure at collapsible:none, extended
    to shadcn/ui's static part set; Tailwind → vanilla CSS on the palette tokens.
-   The collapsible/offcanvas/icon modes (+ their trigger/rail/Stimulus/cookie/
-   Sheet) are deliberately not ported.
+   Collapsible modes: offcanvas (slide away) and icon (3rem rail — labels
+   hide, buttons become icon squares with pure-CSS hover tooltips), both with
+   the mobile drawer + scrim, the SidebarRail grab strip, ⌘B, and cookie
+   persistence via the phlex-kit--sidebar controller.
    Theme tokens come from the global stylesheet. The sidebar reads the shared
    palette by default; --pk-sidebar[-text|-accent|-border|-primary|-primary-ink]
    are optional per-role overrides (shadcn sidebar-* parity), undefined by
@@ -164,11 +166,70 @@
    Mobile (<768px): the rail is a fixed overlay drawer behind a scrim
    (data-open). The trigger only shows inside an offcanvas wrapper. The 767px
    cutoff matches sidebar_controller.js. */
-.pk-sidebar-wrapper.collapsible-offcanvas .pk-sidebar {
-  transition: margin-left .2s ease, transform .2s ease;
+.pk-sidebar-wrapper.collapsible-offcanvas .pk-sidebar,
+.pk-sidebar-wrapper.collapsible-icon .pk-sidebar {
+  position: relative;
+  transition: margin-left .2s ease, transform .2s ease, width .2s ease;
 }
 .pk-sidebar-wrapper.collapsible-offcanvas[data-collapsed] .pk-sidebar { margin-left: -16rem; }
 
+/* Icon mode: the rail shrinks to a 3rem strip — labels and text hide, menu
+   buttons become centered icon squares, hover shows a data-tooltip bubble. */
+.pk-sidebar-wrapper.collapsible-icon[data-collapsed] .pk-sidebar { width: 3rem; }
+.pk-sidebar-wrapper.collapsible-icon[data-collapsed] :is(.pk-sidebar-group-label, .pk-sidebar-group-action, .pk-sidebar-menu-badge, .pk-sidebar-menu-action, .pk-sidebar-menu-sub, .pk-sidebar-input, .pk-sidebar-separator) { display: none; }
+.pk-sidebar-wrapper.collapsible-icon[data-collapsed] :is(.pk-sidebar-header, .pk-sidebar-content, .pk-sidebar-footer) {
+  padding-inline: .5rem;
+  align-items: center;
+}
+.pk-sidebar-wrapper.collapsible-icon[data-collapsed] .pk-sidebar-menu-button {
+  width: 2rem;
+  height: 2rem;
+  padding: .5rem;
+  justify-content: center;
+}
+.pk-sidebar-wrapper.collapsible-icon[data-collapsed] .pk-sidebar-menu-button > :not(svg) { display: none; }
+.pk-sidebar-wrapper.collapsible-icon[data-collapsed] .pk-sidebar-menu-button[data-tooltip] { position: relative; }
+.pk-sidebar-wrapper.collapsible-icon[data-collapsed] .pk-sidebar-menu-button[data-tooltip]:hover::after {
+  content: attr(data-tooltip);
+  position: absolute;
+  left: calc(100% + .625rem);
+  top: 50%;
+  transform: translateY(-50%);
+  z-index: 60;
+  width: max-content;
+  padding: .375rem .75rem;
+  border-radius: calc(var(--pk-radius) - 2px);
+  background: var(--pk-text);
+  color: var(--pk-bg);
+  font-size: .75rem;
+  pointer-events: none;
+}
+
+/* Edge grab strip (SidebarRail) — invisible, click toggles. */
+.pk-sidebar-rail {
+  position: absolute;
+  inset-block: 0;
+  right: -.5rem;
+  z-index: 20;
+  width: 1rem;
+  border: 0;
+  padding: 0;
+  background: transparent;
+  cursor: w-resize;
+  display: none;
+}
+.pk-sidebar-wrapper.collapsible-offcanvas .pk-sidebar-rail,
+.pk-sidebar-wrapper.collapsible-icon .pk-sidebar-rail { display: block; }
+.pk-sidebar-wrapper[data-collapsed] .pk-sidebar-rail { cursor: e-resize; }
+.pk-sidebar-rail:hover::after {
+  content: "";
+  position: absolute;
+  inset-block: 0;
+  left: 50%;
+  width: 2px;
+  background: var(--pk-sidebar-border, var(--pk-border));
+}
+
 .pk-sidebar-trigger {
   display: none;
   align-items: center;
@@ -184,12 +245,18 @@
 }
 .pk-sidebar-trigger:hover { background: var(--pk-accent); }
 .pk-sidebar-trigger svg { width: 1rem; height: 1rem; }
-.collapsible-offcanvas .pk-sidebar-trigger { display: inline-flex; }
+:is(.collapsible-offcanvas, .collapsible-icon) .pk-sidebar-trigger { display: inline-flex; }
 
 .pk-sidebar-scrim { display: none; }
 
 @media (max-width: 767px) {
-  .pk-sidebar-wrapper.collapsible-offcanvas .pk-sidebar {
+  /* Below the cutoff both collapsible modes become the overlay drawer. */
+  .pk-sidebar-wrapper.collapsible-icon[data-collapsed] .pk-sidebar { width: 16rem; }
+  .pk-sidebar-wrapper.collapsible-icon[data-collapsed] :is(.pk-sidebar-group-label, .pk-sidebar-group-action, .pk-sidebar-menu-badge, .pk-sidebar-menu-action, .pk-sidebar-menu-sub, .pk-sidebar-input, .pk-sidebar-separator) { display: revert; }
+  .pk-sidebar-wrapper.collapsible-icon[data-collapsed] .pk-sidebar-menu-button { width: 100%; height: auto; padding: .5rem; justify-content: flex-start; }
+  .pk-sidebar-wrapper.collapsible-icon[data-collapsed] .pk-sidebar-menu-button > :not(svg) { display: revert; }
+  .pk-sidebar-wrapper.collapsible-icon .pk-sidebar-rail { display: none; }
+  .pk-sidebar-wrapper:is(.collapsible-offcanvas, .collapsible-icon) .pk-sidebar {
     position: fixed;
     inset-block: 0;
     left: 0;
@@ -199,8 +266,8 @@
     transform: translateX(-100%);
     box-shadow: 0 8px 30px rgb(0 0 0 / .35);
   }
-  .pk-sidebar-wrapper.collapsible-offcanvas[data-open] .pk-sidebar { transform: none; }
-  .pk-sidebar-wrapper.collapsible-offcanvas[data-open] .pk-sidebar-scrim {
+  .pk-sidebar-wrapper:is(.collapsible-offcanvas, .collapsible-icon)[data-open] .pk-sidebar { transform: none; }
+  .pk-sidebar-wrapper:is(.collapsible-offcanvas, .collapsible-icon)[data-open] .pk-sidebar-scrim {
     display: block;
     position: fixed;
     inset: 0;
@@ -213,5 +280,5 @@
 }
 
 @media (prefers-reduced-motion: reduce) {
-  .pk-sidebar-wrapper.collapsible-offcanvas .pk-sidebar { transition: none; }
+  .pk-sidebar-wrapper:is(.collapsible-offcanvas, .collapsible-icon) .pk-sidebar { transition: none; }
 }

data/app/components/phlex_kit/sidebar/sidebar_controller.js

@@ -1,23 +1,38 @@
 import { Controller } from "@hotwired/stimulus"
 
 // Connects to data-controller="phlex-kit--sidebar" — set by SidebarWrapper when
-// collapsible: :offcanvas. One attribute per surface, both DOM-only so Turbo's
-// page cache never restores an open drawer (the wrapper also closes on
+// collapsible: :offcanvas or :icon. One attribute per surface, both DOM-only so
+// Turbo's page cache never restores an open drawer (the wrapper also closes on
 // turbo:before-cache): `data-open` shows the mobile overlay drawer,
-// `data-collapsed` slides the desktop rail out of the layout. The 767px cutoff
-// matches sidebar.css's offcanvas media query.
+// `data-collapsed` collapses the desktop rail (offcanvas slides it away; icon
+// mode shrinks it to a 3rem strip). The 767px cutoff matches sidebar.css's
+// media query. The desktop state persists in a `pk_sidebar_state` cookie so a
+// host layout can render the collapsed rail server-side (no flash) via
+// SidebarWrapper's `default_collapsed:`.
 export default class extends Controller {
   static MOBILE = "(max-width: 767px)"
+  static COOKIE = "pk_sidebar_state"
 
-  toggle() {
-    if (this.mobile) this.element.toggleAttribute("data-open")
-    else this.element.toggleAttribute("data-collapsed")
+  toggle(event) {
+    if (event?.type === "keydown" && !(event.metaKey || event.ctrlKey)) return
+
+    if (this.mobile) {
+      this.element.toggleAttribute("data-open")
+    } else {
+      this.element.toggleAttribute("data-collapsed")
+      this.persist()
+    }
   }
 
   closeMobile() {
     this.element.removeAttribute("data-open")
   }
 
+  persist() {
+    const state = this.element.hasAttribute("data-collapsed") ? "collapsed" : "expanded"
+    document.cookie = `${this.constructor.COOKIE}=${state}; path=/; max-age=${60 * 60 * 24 * 7}; samesite=lax`
+  }
+
   get mobile() {
     return window.matchMedia(this.constructor.MOBILE).matches
   }

data/app/components/phlex_kit/sidebar/sidebar_menu_button.rb

@@ -2,16 +2,21 @@ module PhlexKit
   # The interactive element of a SidebarMenuItem. `as:` is :button (default) or :a
   # (pass `href:`); `active: true` marks the current page (drives the highlight via
   # data-active — a named kwarg, not an attr, since `mix` would merge a repeated
-  # attribute rather than override). Attrs pass through via mix. See sidebar.rb.
+  # attribute rather than override). `tooltip:` labels the button while an
+  # icon-collapsed rail hides its text (pure-CSS hover bubble). Attrs pass
+  # through via mix. See sidebar.rb.
   class SidebarMenuButton < BaseComponent
-    def initialize(as: :button, active: false, **attrs)
+    def initialize(as: :button, active: false, tooltip: nil, **attrs)
       @as = as
       @active = active
+      @tooltip = tooltip
       @attrs = attrs
     end
 
     def view_template(&block)
-      send(@as, **mix({ class: "pk-sidebar-menu-button", "data-active": (@active ? "true" : "false") }, @attrs), &block)
+      base = { class: "pk-sidebar-menu-button", "data-active": (@active ? "true" : "false") }
+      base["data-tooltip"] = @tooltip if @tooltip
+      send(@as, **mix(base, @attrs), &block)
     end
   end
 end

data/app/components/phlex_kit/sidebar/sidebar_rail.rb

@@ -0,0 +1,21 @@
+module PhlexKit
+  # Invisible grab strip along the sidebar's trailing edge — clicking it
+  # toggles the collapse, like shadcn/ui's SidebarRail. Place it as the last
+  # child of a Sidebar inside a collapsible wrapper. See sidebar.rb.
+  class SidebarRail < BaseComponent
+    def initialize(**attrs)
+      @attrs = attrs
+    end
+
+    def view_template
+      button(**mix({
+        type: :button,
+        class: "pk-sidebar-rail",
+        aria_label: "Toggle sidebar",
+        tabindex: "-1",
+        title: "Toggle sidebar",
+        data: { action: "click->phlex-kit--sidebar#toggle" }
+      }, @attrs))
+    end
+  end
+end