phlex_kit 0.2.0 → 0.2.2

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

@@ -0,0 +1,95 @@
+/* PhlexKit theme: Neutral — translated from a ui.shadcn.com/create export
+   (shadcn's stock neutral palette: pure grayscale, zero chroma throughout).
+   Pure token override: load AFTER the phlex_kit.css manifest and the
+   cascade re-themes every component.
+
+   Translation notes (the recipe for any shadcn/create export):
+   - background → bg; card/popover → surface; secondary/muted/accent →
+     surface-2/accent; foreground → text; secondary-foreground → text-2;
+     muted-foreground → muted; primary/primary-foreground → brand/brand-ink;
+     destructive → red; border/input/ring/chart-1..5/radius map 1:1.
+   - shadcn is light-default with a .dark class; PhlexKit themes are
+     dark-default with data-theme="light" opt-in — blocks swapped.
+   - sidebar-* maps onto the kit's optional --pk-sidebar-* overrides, set
+     only where the export differs from the shared tokens: here that's the
+     dark sidebar-primary (a distinct blue) + its ink. Like the shadcn create
+     page, the blue only shows on active items under Sidebar's menu: :solid —
+     the :default menu highlights with the accent role. shadcn/create exports
+     no green/amber — those fall through to _tokens.css defaults.
+   - dark text-2 has no shadcn source (every dark *-foreground is 0.985);
+     chart-1's 0.87 step (neutral-300) is used, matching the kit's own dark
+     text-2 weight. */
+:root {
+  --pk-bg: oklch(0.145 0 0);
+  --pk-surface: oklch(0.205 0 0);
+  --pk-surface-2: oklch(0.269 0 0);
+  --pk-accent: oklch(0.269 0 0);
+  --pk-border: oklch(1 0 0 / 10%);
+  --pk-input: oklch(1 0 0 / 15%);
+  --pk-ring: oklch(0.556 0 0);
+  --pk-text: oklch(0.985 0 0);
+  --pk-text-2: oklch(0.87 0 0);
+  --pk-muted: oklch(0.708 0 0);
+  --pk-brand: oklch(0.922 0 0);
+  --pk-brand-ink: oklch(0.205 0 0);
+  --pk-red: oklch(0.704 0.191 22.216);
+  --pk-chart-1: oklch(0.87 0 0);
+  --pk-chart-2: oklch(0.556 0 0);
+  --pk-chart-3: oklch(0.439 0 0);
+  --pk-chart-4: oklch(0.371 0 0);
+  --pk-chart-5: oklch(0.269 0 0);
+  --pk-sidebar-primary: oklch(0.488 0.243 264.376);
+  --pk-sidebar-primary-ink: oklch(0.985 0 0);
+  --pk-radius: 0.625rem;
+  color-scheme: dark;
+}
+
+:root[data-theme="light"] {
+  --pk-bg: oklch(1 0 0);
+  --pk-sidebar-primary: oklch(0.205 0 0);
+  --pk-sidebar-primary-ink: oklch(0.985 0 0);
+  --pk-surface: oklch(1 0 0);
+  --pk-surface-2: oklch(0.97 0 0);
+  --pk-accent: oklch(0.97 0 0);
+  --pk-border: oklch(0.922 0 0);
+  --pk-input: oklch(0.922 0 0);
+  --pk-ring: oklch(0.708 0 0);
+  --pk-text: oklch(0.145 0 0);
+  --pk-text-2: oklch(0.205 0 0);
+  --pk-muted: oklch(0.556 0 0);
+  --pk-brand: oklch(0.205 0 0);
+  --pk-brand-ink: oklch(0.985 0 0);
+  --pk-red: oklch(0.577 0.245 27.325);
+  --pk-chart-1: oklch(0.87 0 0);
+  --pk-chart-2: oklch(0.556 0 0);
+  --pk-chart-3: oklch(0.439 0 0);
+  --pk-chart-4: oklch(0.371 0 0);
+  --pk-chart-5: oklch(0.269 0 0);
+  color-scheme: light;
+}
+
+@media (prefers-color-scheme: light) {
+  :root[data-theme="system"] {
+    --pk-bg: oklch(1 0 0);
+    --pk-sidebar-primary: oklch(0.205 0 0);
+    --pk-sidebar-primary-ink: oklch(0.985 0 0);
+    --pk-surface: oklch(1 0 0);
+    --pk-surface-2: oklch(0.97 0 0);
+    --pk-accent: oklch(0.97 0 0);
+    --pk-border: oklch(0.922 0 0);
+    --pk-input: oklch(0.922 0 0);
+    --pk-ring: oklch(0.708 0 0);
+    --pk-text: oklch(0.145 0 0);
+    --pk-text-2: oklch(0.205 0 0);
+    --pk-muted: oklch(0.556 0 0);
+    --pk-brand: oklch(0.205 0 0);
+    --pk-brand-ink: oklch(0.985 0 0);
+    --pk-red: oklch(0.577 0.245 27.325);
+    --pk-chart-1: oklch(0.87 0 0);
+    --pk-chart-2: oklch(0.556 0 0);
+    --pk-chart-3: oklch(0.439 0 0);
+    --pk-chart-4: oklch(0.371 0 0);
+    --pk-chart-5: oklch(0.269 0 0);
+    color-scheme: light;
+  }
+}

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

@@ -0,0 +1,85 @@
+/* PhlexKit theme: Zinc — translated from a ui.shadcn.com/create export
+   (preset b6mHLWLL2u, shadcn's stock zinc palette). Pure token override:
+   load AFTER the phlex_kit.css manifest and the cascade re-themes every
+   component.
+
+   Translation notes (the recipe for any shadcn/create export):
+   - background → bg; card/popover → surface; secondary/muted/accent →
+     surface-2/accent; foreground → text; secondary-foreground → text-2;
+     muted-foreground → muted; primary/primary-foreground → brand/brand-ink;
+     destructive → red; border/input/ring/chart-1..5/radius map 1:1.
+   - shadcn is light-default with a .dark class; PhlexKit themes are
+     dark-default with data-theme="light" opt-in — blocks swapped.
+   - sidebar-* has no --pk-* slots (the kit's sidebar reads the shared
+     surface tokens) and shadcn/create exports no green/amber — both fall
+     through to _tokens.css defaults.
+   - dark text-2 has no shadcn source (every dark *-foreground is 0.985);
+     zinc-300 is used, matching the kit's own dark text-2 weight. */
+:root {
+  --pk-bg: oklch(0.141 0.005 285.823);
+  --pk-surface: oklch(0.21 0.006 285.885);
+  --pk-surface-2: oklch(0.274 0.006 286.033);
+  --pk-accent: oklch(0.274 0.006 286.033);
+  --pk-border: oklch(1 0 0 / 10%);
+  --pk-input: oklch(1 0 0 / 15%);
+  --pk-ring: oklch(0.552 0.016 285.938);
+  --pk-text: oklch(0.985 0 0);
+  --pk-text-2: oklch(0.871 0.006 286.286);
+  --pk-muted: oklch(0.705 0.015 286.067);
+  --pk-brand: oklch(0.92 0.004 286.32);
+  --pk-brand-ink: oklch(0.21 0.006 285.885);
+  --pk-red: oklch(0.704 0.191 22.216);
+  --pk-chart-1: oklch(0.871 0.006 286.286);
+  --pk-chart-2: oklch(0.552 0.016 285.938);
+  --pk-chart-3: oklch(0.442 0.017 285.786);
+  --pk-chart-4: oklch(0.37 0.013 285.805);
+  --pk-chart-5: oklch(0.274 0.006 286.033);
+  --pk-radius: 0.625rem;
+  color-scheme: dark;
+}
+
+:root[data-theme="light"] {
+  --pk-bg: oklch(1 0 0);
+  --pk-surface: oklch(1 0 0);
+  --pk-surface-2: oklch(0.967 0.001 286.375);
+  --pk-accent: oklch(0.967 0.001 286.375);
+  --pk-border: oklch(0.92 0.004 286.32);
+  --pk-input: oklch(0.92 0.004 286.32);
+  --pk-ring: oklch(0.705 0.015 286.067);
+  --pk-text: oklch(0.141 0.005 285.823);
+  --pk-text-2: oklch(0.21 0.006 285.885);
+  --pk-muted: oklch(0.552 0.016 285.938);
+  --pk-brand: oklch(0.21 0.006 285.885);
+  --pk-brand-ink: oklch(0.985 0 0);
+  --pk-red: oklch(0.577 0.245 27.325);
+  --pk-chart-1: oklch(0.871 0.006 286.286);
+  --pk-chart-2: oklch(0.552 0.016 285.938);
+  --pk-chart-3: oklch(0.442 0.017 285.786);
+  --pk-chart-4: oklch(0.37 0.013 285.805);
+  --pk-chart-5: oklch(0.274 0.006 286.033);
+  color-scheme: light;
+}
+
+@media (prefers-color-scheme: light) {
+  :root[data-theme="system"] {
+    --pk-bg: oklch(1 0 0);
+    --pk-surface: oklch(1 0 0);
+    --pk-surface-2: oklch(0.967 0.001 286.375);
+    --pk-accent: oklch(0.967 0.001 286.375);
+    --pk-border: oklch(0.92 0.004 286.32);
+    --pk-input: oklch(0.92 0.004 286.32);
+    --pk-ring: oklch(0.705 0.015 286.067);
+    --pk-text: oklch(0.141 0.005 285.823);
+    --pk-text-2: oklch(0.21 0.006 285.885);
+    --pk-muted: oklch(0.552 0.016 285.938);
+    --pk-brand: oklch(0.21 0.006 285.885);
+    --pk-brand-ink: oklch(0.985 0 0);
+    --pk-red: oklch(0.577 0.245 27.325);
+    --pk-chart-1: oklch(0.871 0.006 286.286);
+    --pk-chart-2: oklch(0.552 0.016 285.938);
+    --pk-chart-3: oklch(0.442 0.017 285.786);
+    --pk-chart-4: oklch(0.37 0.013 285.805);
+    --pk-chart-5: oklch(0.274 0.006 286.033);
+    color-scheme: light;
+  }
+}

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

@@ -12,3 +12,16 @@
 .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; }
+
+/* Disabled items: inert trigger, dimmed. */
+.pk-accordion-item[data-disabled] .pk-accordion-trigger {
+  pointer-events: none;
+  opacity: .5;
+}
+
+/* Bordered flavour (shadcn's "Borders" example): outer border, inset rows. */
+.pk-accordion.bordered {
+  border: 1px solid var(--pk-border);
+  border-radius: var(--pk-radius);
+  padding-inline: 1rem;
+}

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

@@ -4,7 +4,16 @@ module PhlexKit
   # 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), &)
+    # single (default, shadcn's): opening an item closes the others.
+    TYPES = { single: "single", multiple: "multiple" }.freeze
+
+    def initialize(type: :single, **attrs)
+      @type = type.to_sym
+      @attrs = attrs
+    end
+
+    def view_template(&)
+      div(**mix({ class: "pk-accordion", data: { type: TYPES.fetch(@type) } }, @attrs), &)
+    end
   end
 end

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

@@ -6,9 +6,7 @@ module PhlexKit
         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
+          render Icon.new(:chevron_down, size: nil)
         end
       end
     end

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

@@ -1,12 +1,15 @@
 module PhlexKit
   class AccordionItem < BaseComponent
-    def initialize(open: false, rotate_icon: 180, **attrs)
+    def initialize(open: false, disabled: false, rotate_icon: 180, **attrs)
       @open = open
+      @disabled = disabled
       @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), &)
+      data = { controller: "phlex-kit--accordion", phlex_kit__accordion_open_value: @open, phlex_kit__accordion_rotate_icon_value: @rotate_icon }
+      data[:disabled] = "" if @disabled
+      div(**mix({ class: "pk-accordion-item", data: data }, @attrs), &)
     end
   end
 end

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

@@ -8,8 +8,8 @@
   position: fixed;
   inset: 0;
   z-index: 50;
-  background: rgba(0, 0, 0, .8);
-  backdrop-filter: blur(2px);
+  background: rgb(0 0 0 / .5);
+  backdrop-filter: blur(8px);
 }
 .pk-alert-dialog-panel {
   position: fixed;
@@ -28,10 +28,51 @@
   border-radius: var(--pk-radius);
   background: var(--pk-surface);
   color: var(--pk-text);
-  padding: 1.5rem;
+  --pk-dialog-spacing: 1.5rem;
+  padding: var(--pk-dialog-spacing);
   box-shadow: 0 10px 40px rgba(0, 0, 0, .5);
 }
+.pk-alert-dialog-panel.sm { max-width: 24rem; --pk-dialog-spacing: 1rem; gap: .75rem; }
+.pk-alert-dialog-panel.sm .pk-alert-dialog-title { font-size: 1rem; }
+
 .pk-alert-dialog-header { display: flex; flex-direction: column; gap: .5rem; }
+
+/* Media tile: a rounded-square icon chip; a header containing one becomes a
+   centered stack (shadcn's media layout). */
+.pk-alert-dialog-media {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  width: 2.75rem;
+  height: 2.75rem;
+  border-radius: var(--pk-radius);
+  background: var(--pk-surface-2);
+  color: var(--pk-text);
+  margin-bottom: .25rem;
+  font-size: 1.25rem;
+}
+.pk-alert-dialog-media svg { width: 1.25rem; height: 1.25rem; }
+.pk-alert-dialog-media img { width: 100%; height: 100%; object-fit: cover; border-radius: inherit; }
+.pk-alert-dialog-header:has(.pk-alert-dialog-media) {
+  align-items: center;
+  text-align: center;
+}
+/* :sm dialogs pair the centered stack with a full-width 50/50 footer. */
+.pk-alert-dialog-panel.sm .pk-alert-dialog-footer {
+  display: grid;
+  grid-template-columns: 1fr 1fr;
+}
 .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; }
+/* Footer: shadcn's full-bleed muted band (escapes the panel padding). */
+.pk-alert-dialog-footer {
+  display: flex;
+  justify-content: flex-end;
+  gap: .5rem;
+  flex-wrap: wrap;
+  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);
+  background: color-mix(in oklab, var(--pk-surface-2) 50%, transparent);
+}

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

@@ -3,12 +3,13 @@ module PhlexKit
   # 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)
+    def initialize(variant: :primary, **attrs)
+      @variant = variant
       @attrs = attrs
     end
 
     def view_template(&block)
-      render PhlexKit::Button.new(variant: :primary, **@attrs, &block)
+      render PhlexKit::Button.new(variant: @variant, **@attrs, &block)
     end
   end
 end

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

@@ -3,7 +3,11 @@ module PhlexKit
   # 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)
+    # size => panel modifier; :sm is shadcn's compact variant.
+    SIZES = { default: nil, sm: "sm" }.freeze
+
+    def initialize(size: :default, **attrs)
+      @size = size.to_sym
       @attrs = attrs
     end
 
@@ -11,7 +15,7 @@ module PhlexKit
       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)
+          div(role: "alertdialog", "aria-modal": "true", class: [ "pk-alert-dialog-panel", SIZES.fetch(@size) ].compact.join(" "), &block)
         end
       end
     end

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

@@ -0,0 +1,14 @@
+module PhlexKit
+  # Icon/image tile in an AlertDialogHeader — a muted circle above the title
+  # (beside the text column in size :sm dialogs). Ported from shadcn/ui's
+  # AlertDialogMedia (newer than ruby_ui's alert dialog). See alert_dialog.rb.
+  class AlertDialogMedia < BaseComponent
+    def initialize(**attrs)
+      @attrs = attrs
+    end
+
+    def view_template(&)
+      div(**mix({ class: "pk-alert-dialog-media", aria: { hidden: "true" } }, @attrs), &)
+    end
+  end
+end

data/app/components/phlex_kit/attachment/attachment.css

@@ -1,6 +1,10 @@
 /* Co-located with attachment.rb — UI::Attachment, shadcn parity: bordered
-   file chip (icon/preview tile, name + meta, trailing actions). */
+   file chip (icon/image media, name + meta, trailing actions), upload states
+   (uploading/processing shimmer the title; error goes destructive), three
+   sizes, vertical orientation, a full-card trigger behind the actions, and a
+   scrollable snapping group with an edge fade. */
 .pk-attachment {
+  position: relative;
   display: flex;
   align-items: center;
   gap: .5rem;
@@ -39,7 +43,14 @@
   text-overflow: ellipsis;
 }
 .pk-attachment-description { color: var(--pk-muted); font-size: .75rem; }
-.pk-attachment-actions { display: flex; align-items: center; gap: .25rem; flex: none; }
+.pk-attachment-actions {
+  position: relative; /* above the full-card trigger */
+  z-index: 2;
+  display: flex;
+  align-items: center;
+  gap: .25rem;
+  flex: none;
+}
 .pk-attachment-action {
   display: inline-flex;
   align-items: center;
@@ -60,3 +71,92 @@
   box-shadow: 0 0 0 2px color-mix(in oklab, var(--pk-ring) 50%, transparent);
 }
 .pk-attachment-action svg { width: .875rem; height: .875rem; }
+
+/* Sizes. */
+.pk-attachment.sm { padding: .375rem; gap: .375rem; }
+.pk-attachment.sm .pk-attachment-media { width: 2rem; height: 2rem; }
+.pk-attachment.xs { padding: .25rem .375rem; gap: .375rem; font-size: .8125rem; }
+.pk-attachment.xs .pk-attachment-media { width: 1.5rem; height: 1.5rem; border-radius: calc(var(--pk-radius) - 4px); }
+
+/* Vertical: media stacks above the content (image-preview cards). */
+.pk-attachment.vertical {
+  flex-direction: column;
+  align-items: stretch;
+  width: 10rem;
+}
+.pk-attachment.vertical .pk-attachment-media.image {
+  width: 100%;
+  height: auto;
+  aspect-ratio: 4 / 3;
+}
+.pk-attachment.vertical .pk-attachment-actions {
+  position: absolute;
+  top: .75rem;
+  right: .75rem;
+}
+.pk-attachment.vertical .pk-attachment-action {
+  background: color-mix(in oklab, var(--pk-bg) 60%, transparent);
+  color: var(--pk-text);
+  backdrop-filter: blur(4px);
+}
+
+/* Upload states: uploading/processing shimmer the title (same recipe as
+   .pk-shimmer); error goes destructive. */
+.pk-attachment[data-state="uploading"] .pk-attachment-title,
+.pk-attachment[data-state="processing"] .pk-attachment-title {
+  --pk-shimmer-color: oklch(from currentColor calc(l + .25) c h);
+  background-image:
+    linear-gradient(110deg,
+      transparent calc(50% - (3ch + 40px) / 2),
+      var(--pk-shimmer-color) 50%,
+      transparent calc(50% + (3ch + 40px) / 2)),
+    linear-gradient(currentColor, currentColor);
+  background-size: 250% 100%, auto;
+  background-repeat: no-repeat;
+  -webkit-background-clip: text;
+  background-clip: text;
+  -webkit-text-fill-color: transparent;
+  animation: pk-shimmer 2s linear infinite;
+}
+.pk-attachment[data-state="error"] { border-color: color-mix(in oklab, var(--pk-red) 40%, transparent); }
+.pk-attachment[data-state="error"] .pk-attachment-media { color: var(--pk-red); background: color-mix(in oklab, var(--pk-red) 12%, transparent); }
+.pk-attachment[data-state="error"] .pk-attachment-description { color: var(--pk-red); }
+
+/* Full-card trigger — behind the actions, focus ring on the card. */
+.pk-attachment-trigger {
+  position: absolute;
+  inset: 0;
+  z-index: 1;
+  border: 0;
+  border-radius: inherit;
+  background: transparent;
+  cursor: pointer;
+  padding: 0;
+}
+.pk-attachment-trigger:focus-visible { outline: none; }
+.pk-attachment:has(.pk-attachment-trigger:hover) { background: color-mix(in oklab, var(--pk-surface-2) 40%, var(--pk-surface)); }
+.pk-attachment:has(.pk-attachment-trigger:focus-visible) {
+  box-shadow: 0 0 0 3px color-mix(in oklab, var(--pk-ring) 50%, transparent);
+}
+
+/* Scrollable, snapping row with an edge fade (horizontal scroll-fade). */
+.pk-attachment-group {
+  --pk-scroll-fade-size: 2rem;
+  display: flex;
+  gap: .5rem;
+  overflow-x: auto;
+  scroll-snap-type: x mandatory;
+  padding: 2px; /* room for card rings */
+  mask-image: linear-gradient(to right,
+    transparent 0, black var(--pk-scroll-fade-size),
+    black calc(100% - var(--pk-scroll-fade-size)), transparent 100%);
+}
+.pk-attachment-group[data-at-start] {
+  mask-image: linear-gradient(to right,
+    black calc(100% - var(--pk-scroll-fade-size)), transparent 100%);
+}
+.pk-attachment-group[data-at-end] {
+  mask-image: linear-gradient(to right, transparent 0, black var(--pk-scroll-fade-size));
+}
+.pk-attachment-group[data-at-start][data-at-end] { mask-image: none; }
+.pk-attachment-group > .pk-attachment { flex: none; scroll-snap-align: start; }

data/app/components/phlex_kit/attachment/attachment.rb

@@ -1,16 +1,28 @@
 module PhlexKit
-  # File chip, ported from shadcn/ui's Attachment (an AI-chat-era addition, not
-  # in ruby_ui): a bordered row of AttachmentMedia (icon or image preview) +
-  # AttachmentContent(AttachmentTitle + AttachmentDescription) +
-  # AttachmentActions(AttachmentAction — e.g. a remove ×).
+  # File chip, ported from shadcn/ui's Attachment: media (icon or image),
+  # name + metadata, optional actions, upload state and a full-card trigger.
+  # `state:` drives styling — :uploading/:processing shimmer the title, :error
+  # goes destructive; `size:` (:default/:sm/:xs) and `orientation:`
+  # (:horizontal/:vertical) shape the card. Lay several out in an
+  # AttachmentGroup (scrollable, snapping, edge-faded row).
   # `.pk-attachment*` (attachment.css).
   class Attachment < BaseComponent
-    def initialize(**attrs)
+    STATES = { idle: "idle", uploading: "uploading", processing: "processing", error: "error", done: "done" }.freeze
+    SIZES = { default: nil, sm: "sm", xs: "xs" }.freeze
+    ORIENTATIONS = { horizontal: nil, vertical: "vertical" }.freeze
+
+    def initialize(state: :done, size: :default, orientation: :horizontal, **attrs)
+      @state = state.to_sym
+      @size = size.to_sym
+      @orientation = orientation.to_sym
       @attrs = attrs
     end
 
     def view_template(&)
-      div(**mix({ class: "pk-attachment" }, @attrs), &)
+      div(**mix({
+        class: [ "pk-attachment", SIZES.fetch(@size), ORIENTATIONS.fetch(@orientation) ].compact.join(" "),
+        data: { state: STATES.fetch(@state) }
+      }, @attrs), &)
     end
   end
 end

data/app/components/phlex_kit/attachment/attachment_action.rb

@@ -11,12 +11,7 @@ module PhlexKit
         if block
           yield
         else
-          svg(xmlns: "http://www.w3.org/2000/svg", viewbox: "0 0 24 24", fill: "none",
-              stroke: "currentColor", "stroke-width": "2", "stroke-linecap": "round",
-              "stroke-linejoin": "round", "aria-hidden": "true") do |s|
-            s.path(d: "M18 6 6 18")
-            s.path(d: "m6 6 12 12")
-          end
+          render Icon.new(:x, size: nil)
         end
       end
     end

data/app/components/phlex_kit/attachment/attachment_group.rb

@@ -0,0 +1,21 @@
+module PhlexKit
+  # Horizontally scrollable, snapping row of Attachments with an edge fade
+  # (the phlex-kit--scroll-fade controller in horizontal mode).
+  # See attachment.rb.
+  class AttachmentGroup < BaseComponent
+    def initialize(**attrs)
+      @attrs = attrs
+    end
+
+    def view_template(&)
+      div(**mix({
+        class: "pk-attachment-group",
+        role: "group",
+        data: {
+          controller: "phlex-kit--scroll-fade",
+          phlex_kit__scroll_fade_axis_value: "x"
+        }
+      }, @attrs), &)
+    end
+  end
+end

data/app/components/phlex_kit/attachment/attachment_media.rb

@@ -1,8 +1,17 @@
 module PhlexKit
-  # Square preview tile of an Attachment — a file-type icon or an <img>.
-  # See attachment.rb.
+  # Media slot of an Attachment: `variant: :icon` (default, a muted tile) or
+  # `:image` (render an <img> inside; fills the slot, full-width when the
+  # attachment is vertical). See attachment.rb.
   class AttachmentMedia < BaseComponent
-    def initialize(**attrs) = (@attrs = attrs)
-    def view_template(&) = div(**mix({ class: "pk-attachment-media" }, @attrs), &)
+    VARIANTS = { icon: nil, image: "image" }.freeze
+
+    def initialize(variant: :icon, **attrs)
+      @variant = variant.to_sym
+      @attrs = attrs
+    end
+
+    def view_template(&)
+      div(**mix({ class: [ "pk-attachment-media", VARIANTS.fetch(@variant) ].compact.join(" ") }, @attrs), &)
+    end
   end
 end

data/app/components/phlex_kit/attachment/attachment_trigger.rb

@@ -0,0 +1,22 @@
+module PhlexKit
+  # Full-card overlay that activates the attachment (a preview link or dialog
+  # trigger). Sits BEHIND AttachmentActions in the stacking order, so actions
+  # stay independently clickable. Give it an aria-label; pass `as: :a` +
+  # `href:` for a link. See attachment.rb.
+  class AttachmentTrigger < BaseComponent
+    def initialize(as: :button, href: nil, **attrs)
+      @as = as.to_sym
+      @href = href
+      @attrs = attrs
+    end
+
+    def view_template
+      base = { class: "pk-attachment-trigger" }
+      if @as == :a
+        a(**mix(base.merge(href: @href), @attrs))
+      else
+        button(**mix(base.merge(type: :button), @attrs))
+      end
+    end
+  end
+end

data/app/components/phlex_kit/breadcrumb/breadcrumb_ellipsis.rb

@@ -3,11 +3,7 @@ module PhlexKit
     def initialize(**attrs) = (@attrs = attrs)
     def view_template
       span(**mix({ class: "pk-breadcrumb-ellipsis", role: "presentation", aria: { hidden: true } }, @attrs)) do
-        svg(xmlns: "http://www.w3.org/2000/svg", viewbox: "0 0 24 24", fill: "none", stroke: "currentColor", stroke_width: "2", stroke_linecap: "round", stroke_linejoin: "round") do |s|
-          s.circle(cx: "12", cy: "12", r: "1")
-          s.circle(cx: "19", cy: "12", r: "1")
-          s.circle(cx: "5", cy: "12", r: "1")
-        end
+        render Icon.new(:ellipsis, size: nil)
         span(class: "pk-sr-only") { "More" }
       end
     end

data/app/components/phlex_kit/breadcrumb/breadcrumb_separator.rb

@@ -3,7 +3,7 @@ module PhlexKit
     def initialize(**attrs) = (@attrs = attrs)
     def view_template(&block)
       li(**mix({ class: "pk-breadcrumb-separator", role: "presentation", aria: { hidden: true } }, @attrs)) do
-        if block then yield else svg(xmlns: "http://www.w3.org/2000/svg", viewbox: "0 0 24 24", fill: "none", stroke: "currentColor", stroke_width: "2", stroke_linecap: "round", stroke_linejoin: "round") { |s| s.path(d: "m9 18 6-6-6-6") } end
+        if block then yield else render(Icon.new(:chevron_right, size: nil)) end
       end
     end
   end

data/app/components/phlex_kit/calendar/calendar_next.rb

@@ -20,21 +20,7 @@ module PhlexKit
     private
 
     def icon
-      svg(
-        xmlns: "http://www.w3.org/2000/svg",
-        width: "15",
-        height: "15",
-        viewbox: "0 0 15 15",
-        fill: "none",
-        "aria-hidden": "true"
-      ) do |s|
-        s.path(
-          d: "M6.1584 3.13508C6.35985 2.94621 6.67627 2.95642 6.86514 3.15788L10.6151 7.15788C10.7954 7.3502 10.7954 7.64949 10.6151 7.84182L6.86514 11.8418C6.67627 12.0433 6.35985 12.0535 6.1584 11.8646C5.95694 11.6757 5.94673 11.3593 6.1356 11.1579L9.565 7.49985L6.1356 3.84182C5.94673 3.64036 5.95694 3.32394 6.1584 3.13508Z",
-          fill: "currentColor",
-          fill_rule: "evenodd",
-          clip_rule: "evenodd"
-        )
-      end
+      render Icon.new(:chevron_right, size: 15)
     end
   end
 end