shadcn_view_component 0.3.3

data/app/components/shadcn/input_group/preview.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Shadcn
+  module InputGroup
+    class Preview < ApplicationViewComponentPreview
+      def default
+        render_with_template
+      end
+
+      # Upstream's "Icon", "Kbd", "Dropdown" and "Spinner" — what an addon holds,
+      # where the default preview shows where an addon sits.
+      def addons
+        render_with_template
+      end
+    end
+  end
+end

data/app/components/shadcn/input_group/previews/addons.html.erb

@@ -0,0 +1,53 @@
+<%# Upstream's "Icon", "Kbd", "Dropdown" and "Spinner": four things an addon
+    holds that the default preview does not show, which has text, buttons and a
+    textarea.
+
+    An addon is a slot for anything — its only argument is `align:`, and the
+    default preview covers all four of those. What changes here is what goes
+    inside one. %>
+<div class="flex w-full max-w-md flex-col gap-6">
+  <%# An icon, which is the commonest case and the reason the addon has no
+      padding of its own. %>
+  <%= render(Shadcn::InputGroup::Component.new) do %>
+    <%= render(Shadcn::InputGroup::Addon::Component.new) do %>
+      <%= render(Shadcn::Icon::Component.new("search")) %>
+    <% end %>
+    <%= render(Shadcn::InputGroup::Input::Component.new(placeholder: "Search", "aria-label": "Search")) %>
+  <% end %>
+
+  <%# A shortcut on the trailing edge, which is what `Kbd` is for. %>
+  <%= render(Shadcn::InputGroup::Component.new) do %>
+    <%= render(Shadcn::InputGroup::Input::Component.new(placeholder: "Search commands", "aria-label": "Search commands")) %>
+    <%= render(Shadcn::InputGroup::Addon::Component.new(align: :"inline-end")) do %>
+      <%= render(Shadcn::Kbd::Group::Component.new) do %>
+        <%= render(Shadcn::Kbd::Component.new) { "⌘" } %>
+        <%= render(Shadcn::Kbd::Component.new) { "K" } %>
+      <% end %>
+    <% end %>
+  <% end %>
+
+  <%# A menu hanging off the addon's own button. %>
+  <%= render(Shadcn::InputGroup::Component.new) do %>
+    <%= render(Shadcn::InputGroup::Input::Component.new(placeholder: "you@example.com", "aria-label": "Email")) %>
+    <%= render(Shadcn::InputGroup::Addon::Component.new(align: :"inline-end")) do %>
+      <%= render(Shadcn::DropdownMenu::Component.new) do |m| %>
+        <% m.with_trigger(as: :button, class: "inline-flex items-center gap-1 text-sm text-muted-foreground") do %>
+          Work
+          <%= render(Shadcn::Icon::Component.new("chevron-down")) %>
+        <% end %>
+        <% m.with_menu_content(class: "w-56") do %>
+          <%= render(Shadcn::DropdownMenu::Item::Component.new) { "Work" } %>
+          <%= render(Shadcn::DropdownMenu::Item::Component.new) { "Personal" } %>
+        <% end %>
+      <% end %>
+    <% end %>
+  <% end %>
+
+  <%# A spinner, for a field that is checking something as you type. %>
+  <%= render(Shadcn::InputGroup::Component.new) do %>
+    <%= render(Shadcn::InputGroup::Input::Component.new(value: "octocat", "aria-label": "Username")) %>
+    <%= render(Shadcn::InputGroup::Addon::Component.new(align: :"inline-end")) do %>
+      <%= render(Shadcn::Spinner::Component.new) %>
+    <% end %>
+  <% end %>
+</div>

data/app/components/shadcn/input_group/previews/default.html.erb

@@ -0,0 +1,25 @@
+<div class="flex w-full max-w-md flex-col gap-6">
+  <%= render(Shadcn::InputGroup::Component.new) do %>
+    <%= render(Shadcn::InputGroup::Addon::Component.new) do %>
+      <%= render(Shadcn::InputGroup::Text::Component.new) { "https://" } %>
+    <% end %>
+    <%= render(Shadcn::InputGroup::Input::Component.new(placeholder: "example.com")) %>
+  <% end %>
+
+  <%= render(Shadcn::InputGroup::Component.new) do %>
+    <%= render(Shadcn::InputGroup::Input::Component.new(placeholder: "Search")) %>
+    <%= render(Shadcn::InputGroup::Addon::Component.new(align: :"inline-end")) do %>
+      <%= render(Shadcn::InputGroup::Button::Component.new) { "Go" } %>
+    <% end %>
+  <% end %>
+
+  <%= render(Shadcn::InputGroup::Component.new) do %>
+    <%= render(Shadcn::InputGroup::Addon::Component.new(align: :"block-start")) do %>
+      <%= render(Shadcn::InputGroup::Text::Component.new) { "Describe the issue" } %>
+    <% end %>
+    <%= render(Shadcn::InputGroup::Textarea::Component.new(placeholder: "What happened?")) %>
+    <%= render(Shadcn::InputGroup::Addon::Component.new(align: :"block-end")) do %>
+      <%= render(Shadcn::InputGroup::Button::Component.new(size: :sm)) { "Submit" } %>
+    <% end %>
+  <% end %>
+</div>

data/app/components/shadcn/input_group/text/component.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Shadcn
+  module InputGroup
+    module Text
+      # InputGroupText. A `<span>`, and like ButtonGroupText it carries no
+      # `data-slot` upstream, so it is not given one here.
+      class Component < ApplicationViewComponent
+        default_tag :span
+
+        style do
+          base {
+            "flex items-center gap-2 text-sm text-muted-foreground " \
+            "[&_svg]:pointer-events-none [&_svg:not([class*='size-'])]:size-4"
+          }
+        end
+      end
+    end
+  end
+end

data/app/components/shadcn/input_group/textarea/component.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Shadcn
+  module InputGroup
+    module Textarea
+      # InputGroupTextarea renders the ported Textarea, and shares
+      # `data-slot="input-group-control"` with InputGroupInput — see that file
+      # for why the two must not be told apart.
+      class Component < Shadcn::Textarea::Component
+        slot_name :"input-group-control"
+
+        EXTRA_CLASSES = "flex-1 resize-none rounded-none border-0 bg-transparent py-3 " \
+                        "shadow-none focus-visible:ring-0 dark:bg-transparent"
+
+        def css_classes(extra = nil)
+          super([ EXTRA_CLASSES, extra ].compact.join(" "))
+        end
+      end
+    end
+  end
+end

data/app/components/shadcn/input_otp/component.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Shadcn
+  module InputOtp
+    # Port of registry/new-york-v4/ui/input-otp.tsx
+    #
+    # Upstream builds this on the **input-otp** package, and this port does not.
+    # Measured: of its 715 lines, `input-otp.tsx` uses the root component and,
+    # per box, three values — `char`, `isActive` and `hasFakeCaret`. The rule
+    # behind them is six lines (input.tsx:596-618), and the mechanism under it
+    # is one real `<input>` laid invisibly over the boxes, which is what makes
+    # typing, paste, backspace, the arrow keys and a one-time-code autofill the
+    # browser's problem rather than ours.
+    #
+    # What the 715 lines mostly are is the part that cannot be ported by
+    # reading: 21 of them name Safari, iOS, a password manager or a selection
+    # quirk. features/input-otp.md says which of those this port answers and
+    # which it does not.
+    #
+    # The shape is upstream's, read from the rendered demo rather than from the
+    # TSX, which shows none of it: the boxes come first, and the input sits over
+    # them in an absolutely positioned layer.
+    class Component < ApplicationViewComponent
+      slot_name :"input-otp-container"
+
+      style do
+        base { "flex items-center gap-2 has-disabled:opacity-50" }
+      end
+
+      # Everything the input needs to be a real one. `disabled:cursor-not-allowed`
+      # is upstream's class for it; the rest of its look is a rule in
+      # `shadcn.css`, because it is a technique rather than a style — see there.
+      INPUT_CLASSES = "disabled:cursor-not-allowed"
+
+      attr_reader :max_length, :name, :value, :disabled, :pattern, :autofocus, :input_attributes
+
+      def initialize(max_length: 6, name: nil, value: nil, disabled: false, pattern: nil,
+                     autofocus: false, input: {}, **attributes)
+        @max_length = max_length.to_i
+        @name = name
+        @value = value.to_s
+        @disabled = disabled
+        @pattern = pattern
+        @autofocus = autofocus
+        @input_attributes = input
+        super(**attributes)
+      end
+
+      def element_attributes(**defaults)
+        super(**{
+          style: merged_style("position:relative"),
+          "data-controller" => "shadcn--input-otp",
+          "data-shadcn--input-otp-length-value" => max_length
+        }.merge(defaults))
+      end
+
+      def call
+        render_element(body: safe_join([ content, overlay ]))
+      end
+
+      private
+
+      # Upstream's own arrangement: the boxes are the page, and the input is a
+      # layer over them that takes the pointer while the layer itself does not.
+      def overlay
+        tag.div(input, style: "position:absolute;inset:0;pointer-events:none")
+      end
+
+      def input
+        tag.input(**{
+          "data-slot": "input-otp",
+          "data-shadcn--input-otp-target": "input",
+          "data-action": "input->shadcn--input-otp#entered " \
+                         "select->shadcn--input-otp#refresh " \
+                         "keyup->shadcn--input-otp#refresh " \
+                         "click->shadcn--input-otp#refresh " \
+                         "focus->shadcn--input-otp#focus " \
+                         "blur->shadcn--input-otp#refresh",
+          class: INPUT_CLASSES,
+          value: value.presence,
+          name:,
+          maxlength: max_length,
+          disabled: (true if disabled),
+          autofocus: (true if autofocus),
+          pattern:,
+          # The three that make a phone offer the code from a message, and stop
+          # a keyboard offering everything else.
+          autocomplete: "one-time-code",
+          inputmode: "numeric",
+          spellcheck: "false"
+        }.compact.merge(input_attributes))
+      end
+    end
+  end
+end

data/app/components/shadcn/input_otp/preview.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Shadcn
+  module InputOtp
+    class Preview < ApplicationViewComponentPreview
+      def default
+        render_with_template
+      end
+
+      # Upstream's "Pattern", "Separator" and "Disabled" — and the FormBuilder,
+      # since a code that is not submitted is a code for nothing.
+      def variations
+        render_with_template
+      end
+    end
+  end
+end

data/app/components/shadcn/input_otp/previews/default.html.erb

@@ -0,0 +1,19 @@
+<%# Upstream's own example: six boxes, one real input over them.
+
+    Type into it and the boxes fill; the caret is drawn by the active box rather
+    than by the input, whose own is transparent. Paste a six-digit code and it
+    lands in one go, because the field the browser sees is an ordinary input.
+
+    Labelled, and that is the caller's job here as it is upstream's: there is one
+    input and it takes a name the way any input does. Unlabelled it fails axe,
+    which is how this preview shipped for about an hour. %>
+<div class="flex flex-col gap-2">
+  <%= render(Shadcn::Label::Component.new(for: "otp-code")) { "Verification code" } %>
+  <%= render(Shadcn::InputOtp::Component.new(max_length: 6, name: "code", input: { id: "otp-code" })) do %>
+    <%= render(Shadcn::InputOtp::Group::Component.new) do %>
+      <% 6.times do %>
+        <%= render(Shadcn::InputOtp::Slot::Component.new) %>
+      <% end %>
+    <% end %>
+  <% end %>
+</div>

data/app/components/shadcn/input_otp/previews/variations.html.erb

@@ -0,0 +1,33 @@
+<%# Upstream's "Separator", "Pattern" and "Disabled".
+
+    The separator is markup rather than an argument — two groups with a minus
+    between them — which is why the component takes no "grouping" option. The
+    pattern and the input mode are the input's own attributes, passed through
+    `input:`: this port has one input and hands the caller its keys rather than
+    inventing arguments for each. %>
+<div class="flex flex-col gap-8">
+  <%= render(Shadcn::InputOtp::Component.new(max_length: 6, name: "grouped", input: { "aria-label": "Grouped code" })) do %>
+    <%= render(Shadcn::InputOtp::Group::Component.new) do %>
+      <% 3.times do %><%= render(Shadcn::InputOtp::Slot::Component.new) %><% end %>
+    <% end %>
+    <%= render(Shadcn::InputOtp::Separator::Component.new) %>
+    <%= render(Shadcn::InputOtp::Group::Component.new) do %>
+      <% 3.times do %><%= render(Shadcn::InputOtp::Slot::Component.new) %><% end %>
+    <% end %>
+  <% end %>
+
+  <%= render(Shadcn::InputOtp::Component.new(
+        max_length: 4, name: "letters",
+        input: { inputmode: "text", pattern: "[A-Za-z]*", "aria-label": "Letters only" }
+      )) do %>
+    <%= render(Shadcn::InputOtp::Group::Component.new) do %>
+      <% 4.times do %><%= render(Shadcn::InputOtp::Slot::Component.new) %><% end %>
+    <% end %>
+  <% end %>
+
+  <%= render(Shadcn::InputOtp::Component.new(max_length: 4, value: "1234", disabled: true, input: { "aria-label": "Disabled code" })) do %>
+    <%= render(Shadcn::InputOtp::Group::Component.new) do %>
+      <% 4.times do %><%= render(Shadcn::InputOtp::Slot::Component.new) %><% end %>
+    <% end %>
+  <% end %>
+</div>

data/app/components/shadcn/input_otp/separator/component.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Shadcn
+  module InputOtp
+    module Separator
+      # InputOTPSeparator — a minus between two groups. Upstream gives it a role
+      # and no classes at all.
+      class Component < ApplicationViewComponent
+        slot_name :"input-otp-separator"
+
+        def element_attributes(**defaults)
+          super(**{ role: "separator" }.merge(defaults))
+        end
+
+        def call
+          render_element(body: render(Icon::Component.new("minus")))
+        end
+      end
+    end
+  end
+end

data/app/components/shadcn/input_otp/slot/component.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module Shadcn
+  module InputOtp
+    module Slot
+      # InputOTPSlot — one box. It holds no state of its own: the character, the
+      # active mark and the caret are all written by the controller from the one
+      # input's value and selection.
+      #
+      # Upstream takes an `index`; this reads the boxes in the order they appear,
+      # which is the same answer without a number for a caller to get wrong.
+      class Component < ApplicationViewComponent
+        CARET_CLASSES = "pointer-events-none absolute inset-0 flex items-center justify-center"
+        BAR_CLASSES = "h-4 w-px animate-caret-blink bg-foreground duration-1000"
+
+        slot_name :"input-otp-slot"
+
+        style do
+          base {
+            "relative flex h-9 w-9 items-center justify-center border-y border-r border-input " \
+            "text-sm shadow-xs transition-all outline-none first:rounded-l-md first:border-l " \
+            "last:rounded-r-md aria-invalid:border-destructive data-[active=true]:z-10 " \
+            "data-[active=true]:border-ring data-[active=true]:ring-[3px] " \
+            "data-[active=true]:ring-ring/50 data-[active=true]:aria-invalid:border-destructive " \
+            "data-[active=true]:aria-invalid:ring-destructive/20 dark:bg-input/30 " \
+            "dark:data-[active=true]:aria-invalid:ring-destructive/40"
+          }
+        end
+
+        def element_attributes(**defaults)
+          super(**{
+            "data-active" => "false",
+            "data-shadcn--input-otp-target" => "slot"
+          }.merge(defaults))
+        end
+
+        def call
+          render_element(body: safe_join([ character, caret ]))
+        end
+
+        private
+
+        def character
+          tag.span("data-shadcn--input-otp-target": "char")
+        end
+
+        # Rendered always and hidden until the box is both active and empty,
+        # which is upstream's `hasFakeCaret`. Server-rendered rather than
+        # created on demand: a component that adds elements from JavaScript is a
+        # component `turbo:morph` argues with.
+        def caret
+          tag.div(tag.div(class: BAR_CLASSES),
+                  class: CARET_CLASSES,
+                  hidden: true,
+                  "data-shadcn--input-otp-target": "caret")
+        end
+      end
+    end
+  end
+end

data/app/components/shadcn/input_otp.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module Shadcn
+  # The parts of the InputOTP family that are just an element with a
+  # `data-slot` and a fixed set of classes.
+  module InputOtp
+    extend Parts
+
+    part :group, slot: "input-otp-group", classes: "flex items-center"
+  end
+end

data/app/components/shadcn/item/component.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Shadcn
+  module Item
+    # Port of registry/new-york-v4/ui/item.tsx
+    #
+    # `group/item` is half a mechanism: `ItemMedia`'s
+    # `group-has-[[data-slot=item-description]]/item:…` classes reach back into
+    # this named group to shift the media when a description is present. Both
+    # halves have to stay exactly as upstream wrote them — parity checks that
+    # each class exists, not that they still refer to each other.
+    class Component < ApplicationViewComponent
+      slot_name :item
+
+      style do
+        base {
+          "group/item flex flex-wrap items-center rounded-md border border-transparent " \
+          "text-sm transition-colors duration-100 outline-none focus-visible:border-ring " \
+          "focus-visible:ring-[3px] focus-visible:ring-ring/50 [a]:transition-colors " \
+          "[a]:hover:bg-accent/50"
+        }
+
+        variants {
+          variant {
+            default { "bg-transparent" }
+            outline { "border-border" }
+            muted { "bg-muted/50" }
+          }
+
+          size {
+            default { "gap-4 p-4" }
+            sm { "gap-2.5 px-4 py-3" }
+          }
+        }
+
+        defaults { { variant: :default, size: :default } }
+      end
+
+      attr_reader :variant, :size
+
+      def initialize(variant: :default, size: :default, **attributes)
+        @variant = variant&.to_sym || :default
+        @size = size&.to_sym || :default
+        super(**attributes)
+      end
+
+      def style_variants
+        { variant:, size: }
+      end
+
+      def element_attributes(**defaults)
+        super(**{ "data-variant" => variant, "data-size" => size }.merge(defaults))
+      end
+    end
+  end
+end

data/app/components/shadcn/item/group/component.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Shadcn
+  module Item
+    module Group
+      # ItemGroup. Only a `data-slot` and classes apart from `role="list"`,
+      # which is why it is not a `part` — the macro declares no attributes.
+      #
+      # **`role="list"` obliges its children to be `role="listitem"`, and `Item`
+      # carries no role.** Adding one to `Item` itself would deviate from
+      # upstream's markup, so it is added here instead, through the `items`
+      # slot — the same layer the FormBuilder uses to supply the accessible
+      # name that Select and Switch cannot give themselves. A bare
+      # `Item::Component`, rendered outside this slot, still carries no role,
+      # exactly as upstream has it.
+      #
+      # `ItemSeparator` goes through the same slot rather than the block:
+      # `items` renders before block content (see `Card::Component`), so a
+      # separator placed as plain block content between two `with_item` calls
+      # would land after both of them instead of between them — the trap
+      # CLAUDE.md warns about. A polymorphic slot keeps both in the one
+      # ordered collection, where call order is preserved, and gives the
+      # separator its own setter (`with_separator`) rather than a flag that
+      # would otherwise let `Item` attributes reach a `role="none"` element.
+      class Component < ApplicationViewComponent
+        renders_many :items, types: {
+          item: {
+            renders: ->(**attributes) { Shadcn::Item::Component.new(role: "listitem", **attributes) },
+            as: :item
+          },
+          separator: {
+            renders: ->(**attributes) { Shadcn::Item::Separator::Component.new(**attributes) },
+            as: :separator
+          }
+        }
+
+        slot_name :"item-group"
+
+        style do
+          base { "group/item-group flex flex-col" }
+        end
+
+        def element_attributes(**defaults)
+          super(**{ role: "list" }.merge(defaults))
+        end
+
+        def call
+          render_element(body: safe_join([ *items, content ].compact))
+        end
+      end
+    end
+  end
+end

data/app/components/shadcn/item/media/component.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module Shadcn
+  module Item
+    module Media
+      # ItemMedia. Its base classes reach into the named group `Item` opens
+      # (`group-has-[[data-slot=item-description]]/item:…`) to shift the media
+      # down when the item has a description. That only works while `Item`
+      # still carries `group/item`.
+      class Component < ApplicationViewComponent
+        slot_name :"item-media"
+
+        style do
+          base {
+            "flex shrink-0 items-center justify-center gap-2 " \
+            "group-has-[[data-slot=item-description]]/item:translate-y-0.5 " \
+            "group-has-[[data-slot=item-description]]/item:self-start " \
+            "[&_svg]:pointer-events-none"
+          }
+
+          variants {
+            variant {
+              default { "bg-transparent" }
+              icon {
+                "size-8 rounded-sm border bg-muted [&_svg:not([class*='size-'])]:size-4"
+              }
+              image {
+                "size-10 overflow-hidden rounded-sm [&_img]:size-full [&_img]:object-cover"
+              }
+            }
+          }
+
+          defaults { { variant: :default } }
+        end
+
+        attr_reader :variant
+
+        def initialize(variant: :default, **attributes)
+          @variant = variant&.to_sym || :default
+          super(**attributes)
+        end
+
+        def style_variants
+          { variant: }
+        end
+
+        def element_attributes(**defaults)
+          super(**{ "data-variant" => variant }.merge(defaults))
+        end
+      end
+    end
+  end
+end

data/app/components/shadcn/item/preview.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Shadcn
+  module Item
+    class Preview < ApplicationViewComponentPreview
+      def default
+        render_with_template
+      end
+
+      def outline
+        render_with_template
+      end
+
+      # Upstream's "Link", "Avatar" and "Image".
+      def link
+        render_with_template
+      end
+    end
+  end
+end

data/app/components/shadcn/item/previews/default.html.erb

@@ -0,0 +1,32 @@
+<%= render(Shadcn::Item::Group::Component.new(class: "w-full max-w-md")) do |group| %>
+  <% group.with_item do %>
+    <%= render(Shadcn::Item::Media::Component.new(variant: :icon)) do %>
+      <%= render(Shadcn::Icon::Component.new("circle")) %>
+    <% end %>
+    <%= render(Shadcn::Item::Content::Component.new) do %>
+      <%= render(Shadcn::Item::Title::Component.new) { "Basic plan" } %>
+      <%= render(Shadcn::Item::Description::Component.new) do %>
+        Everything you need to get started, with <a href="#">no card required</a>.
+      <% end %>
+    <% end %>
+    <%= render(Shadcn::Item::Actions::Component.new) do %>
+      <%= render(Shadcn::Button::Component.new(variant: :outline, size: :sm)) { "Choose" } %>
+    <% end %>
+  <% end %>
+
+  <% group.with_separator %>
+
+  <% group.with_item(variant: :muted, size: :sm) do %>
+    <%= render(Shadcn::Item::Header::Component.new) do %>
+      <%= render(Shadcn::Item::Title::Component.new) { "Pro plan" } %>
+      <%= render(Shadcn::Badge::Component.new) { "Popular" } %>
+    <% end %>
+    <%= render(Shadcn::Item::Content::Component.new) do %>
+      <%= render(Shadcn::Item::Description::Component.new) { "For teams shipping every day." } %>
+    <% end %>
+    <%= render(Shadcn::Item::Footer::Component.new) do %>
+      <%= render(Shadcn::Item::Description::Component.new) { "$20 per seat" } %>
+      <%= render(Shadcn::Button::Component.new(size: :sm)) { "Upgrade" } %>
+    <% end %>
+  <% end %>
+<% end %>

data/app/components/shadcn/item/previews/link.html.erb

@@ -0,0 +1,39 @@
+<%# Upstream's "Link", "Avatar" and "Image".
+
+    An item that is a link is the whole element, not a link inside it: `as: :a`
+    is this port's `asChild`, so the row keeps its slots and its variants and
+    becomes an anchor. The media variants are the other half — `icon` is in the
+    default preview, `image` and the plain `default` are not.
+
+    Not inside an `ItemGroup`, and that is the point rather than an omission.
+    The group is `role="list"`, which may only hold `listitem` children, and
+    neither upstream's `Item` nor this one sets that role — so an item that
+    becomes an anchor becomes a `link` inside a `list`, which axe fails and a
+    screen reader reads as a broken list. A row that is a link belongs outside
+    the group, which is how upstream's own example shows it. %>
+<div class="flex w-full max-w-md flex-col gap-4">
+  <%= render(Shadcn::Item::Component.new(as: :a, href: "#", variant: :outline)) do %>
+    <%= render(Shadcn::Item::Media::Component.new) do %>
+      <%= render(Shadcn::Avatar::Component.new) do |a| %>
+        <% a.with_fallback { "EW" } %>
+      <% end %>
+    <% end %>
+    <%= render(Shadcn::Item::Content::Component.new) do %>
+      <%= render(Shadcn::Item::Title::Component.new) { "Evelyn Wood" } %>
+      <%= render(Shadcn::Item::Description::Component.new) { "The whole row is the link." } %>
+    <% end %>
+    <%= render(Shadcn::Item::Actions::Component.new) do %>
+      <%= render(Shadcn::Icon::Component.new("chevron-right")) %>
+    <% end %>
+  <% end %>
+
+  <%= render(Shadcn::Item::Component.new(variant: :outline)) do %>
+    <%= render(Shadcn::Item::Media::Component.new(variant: :image)) do %>
+      <div class="flex size-full items-center justify-center bg-muted text-xs text-foreground/70">IMG</div>
+    <% end %>
+    <%= render(Shadcn::Item::Content::Component.new) do %>
+      <%= render(Shadcn::Item::Title::Component.new) { "A picture, cropped to the box" } %>
+      <%= render(Shadcn::Item::Description::Component.new) { "The image media is size-10, rounded and object-cover." } %>
+    <% end %>
+  <% end %>
+</div>