atomic_view 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2cfa124ea9d90829cb7c8879e99d63b4c0e5587f4ee294ca19557f9dc0b92699
-  data.tar.gz: 972a88497711cd0d4c1f9e323346886b9eed136c350120ab0e6adfbb62764f25
+  metadata.gz: 35571b6bf96da5419dcc5d10709fb6e391bc3d47991b0914934099003d4e2873
+  data.tar.gz: '09145bc057a978d84c5d21c98fe3c86b5e3db12c52d3726480eb79025a9c0d93'
 SHA512:
-  metadata.gz: 3696f874e0d5e627a572be114d091a18d451427f9e980e79b8b9304a3965b0d5a11060d44b0f7a7711364553199127778dc86ffc8d86d45851a65184250861fb
-  data.tar.gz: db66b0814f6c2b03969d1d4f0b422f1494768d24699d308e522deefcd5a629e77bf4382263a573765188ead91c986e0618b52700c8ff897852852ae823578049
+  metadata.gz: 26248796be4512d71197dae22674290aeab4c8b1b13dbaa4bc220e4c779858369f11e82ed9c645da13f101e8c9da130c8529694543426ff6c84bff0a73677072
+  data.tar.gz: 7220d17e20fca18bff3896b2a31e65846b499a2a453e315af1625c9d181bb118f63659e276bfa0cc3e20766be564525d1d02dec1c12c50d8310d51037c1f8202

data/app/assets/javascripts/atomic_view/controllers/tooltip_controller.js

@@ -0,0 +1,35 @@
+import { Controller } from "@hotwired/stimulus"
+import { computePosition, offset, flip, shift, autoUpdate } from "@floating-ui/dom"
+
+export default class extends Controller {
+  static targets = ["trigger", "content"]
+  static values = { placement: { type: String, default: "top" } }
+
+  show() {
+    this.contentTarget.classList.remove("hidden")
+    this.cleanup = autoUpdate(this.triggerTarget, this.contentTarget, () => {
+      computePosition(this.triggerTarget, this.contentTarget, {
+        strategy: "fixed",
+        placement: this.placementValue,
+        middleware: [offset(8), flip(), shift({ padding: 8 })]
+      }).then(({ x, y }) => {
+        Object.assign(this.contentTarget.style, { left: `${x}px`, top: `${y}px` })
+      })
+    })
+    document.addEventListener("keydown", this.onKeydown)
+  }
+
+  hide() {
+    this.contentTarget.classList.add("hidden")
+    if (this.cleanup) this.cleanup()
+    document.removeEventListener("keydown", this.onKeydown)
+  }
+
+  onKeydown = (event) => {
+    if (event.key === "Escape") this.hide()
+  }
+
+  disconnect() {
+    this.hide()
+  }
+}

data/lib/atomic_view/components/badge_component.rb

@@ -2,6 +2,20 @@
 
 module AtomicView
   module Components
+    # Badge
+    #
+    # A small rectangular status/label pill. `default`/`secondary` are solid
+    # fills for general-purpose emphasis (a count, a category tag);
+    # `success`/`warning`/`destructive`/`info` are soft, bordered/tinted
+    # semantic colors for actual state (active/upcoming/cancelled/etc.) --
+    # the same `border-x bg-x/10 text-x` treatment AlertComponent already
+    # uses for its variants, just as a compact pill instead of a banner.
+    # `outline` is the neutral, colorless version of that same bordered
+    # style, for a status that doesn't map to any of the semantic colors.
+    #
+    # Every variant carries a `border` (transparent on the solid fills) so
+    # badges of different variants sitting side by side stay the same
+    # height regardless of which ones happen to have a visible border.
     class BadgeComponent < AtomicView::Component
       attr_reader :variant
 
@@ -18,19 +32,25 @@ module AtomicView
       private
 
       def base_classes
-        "inline-flex items-center rounded-pill px-1.5 py-0.5 text-xs font-medium"
+        "inline-flex items-center rounded-btn border px-1.5 py-0.5 text-xs font-medium"
       end
 
       def variant_classes
         case variant
         when :secondary
-          "bg-secondary text-secondary-foreground"
+          "border-transparent bg-secondary text-secondary-foreground"
         when :destructive
-          "bg-destructive text-destructive-foreground"
+          "border-destructive bg-destructive/10 text-destructive"
+        when :success
+          "border-success bg-success/10 text-success"
+        when :warning
+          "border-warning bg-warning/10 text-warning"
+        when :info
+          "border-info bg-info/10 text-info"
         when :outline
-          "bg-transparent border border-border text-foreground"
+          "border-border bg-transparent text-foreground"
         else
-          "bg-primary text-primary-foreground"
+          "border-transparent bg-primary text-primary-foreground"
         end
       end
     end

data/lib/atomic_view/components/card_component/section_component.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module AtomicView
+  module Components
+    class CardComponent
+      # CardComponent::Section
+      #
+      # One row of a sectioned card -- see CardComponent's docs. Just a
+      # padded, free-form content block; CardComponent's `divide-y` wrapper
+      # is what adds the border between sections, not this component.
+      class SectionComponent < AtomicView::Component
+        def initialize(**options)
+          super()
+          @options = options
+        end
+
+        def call
+          tag.div(**@options.except(:class), class: class_names(CardComponent::PADDING_CLASSES, @options[:class])) { content }
+        end
+      end
+    end
+  end
+end

data/lib/atomic_view/components/card_component.html.erb

@@ -0,0 +1,11 @@
+<%= tag.div(**@options.except(:class), class: html_class) do %>
+  <% if sectioned? %>
+    <%= tag.div(class: divider_class) do %>
+      <% sections.each do |section| %>
+        <%= section %>
+      <% end %>
+    <% end %>
+  <% else %>
+    <%= content %>
+  <% end %>
+<% end %>

data/lib/atomic_view/components/card_component.rb

@@ -2,23 +2,84 @@
 
 module AtomicView
   module Components
+    # Card
+    #
+    # A generic surface container for grouping related content. `default` is
+    # a plain bordered panel; `destructive` is the same shape with a tinted
+    # red border/background, for a "danger zone" section (e.g. an archive or
+    # delete action with its consequences explained) -- the same
+    # `border-destructive bg-destructive/10` treatment AlertComponent already
+    # uses for its own error variant. The variant only colors the card
+    # itself; any heading/button inside it is the caller's own content.
+    #
+    # Pass plain content for a single padded panel. For a settings-list style
+    # card -- several rows, each with its own label/action, a divider
+    # between them but not around the outside -- use `with_section` instead:
+    #
+    #   render(AtomicView::Components::CardComponent.new(variant: :destructive)) do |card|
+    #     card.with_section do
+    #       tag.div(class: "flex items-center justify-between gap-4") do
+    #         tag.div { tag.p("Archive this rental", class: "font-medium") + tag.p("...", class: "text-sm text-muted-foreground") } +
+    #           render(LinkComponent.new("#", variant: :muted)) { "Archive" }
+    #       end
+    #     end
+    #
+    #     card.with_section { ... }
+    #   end
+    #
+    # Each section gets the card's own padding (rather than the card as a
+    # whole), and a `divide-y` on the section container adds a border
+    # between consecutive sections automatically -- there's no first/last
+    # index to track, Tailwind's `divide-y` only ever borders the boundary
+    # between two siblings. A card with no sections given renders exactly as
+    # before -- `with_section` is opt-in, not a second required API.
     class CardComponent < AtomicView::Component
-      attr_reader :hoverable
+      PADDING_CLASSES = "p-2.5 px-4"
 
-      def initialize(hoverable: false, **options)
+      renders_many :sections, "SectionComponent"
+
+      attr_reader :hoverable, :variant
+
+      def initialize(variant: :default, hoverable: false, **options)
         super()
+        @variant = variant
         @hoverable = hoverable
         @options = options
       end
 
-      def call
-        tag.div(**@options.except(:class), class: class_names(base_classes, hoverable_classes, @options[:class])) { content }
+      def sectioned?
+        sections.any?
+      end
+
+      def html_class
+        class_names(base_classes, variant_classes, hoverable_classes, padding_class, @options[:class])
+      end
+
+      # The divider color between sections is tied to the variant rather
+      # than a flat `divide-border` -- a neutral gray divider reads fine on
+      # the plain surface background, but loses almost all contrast against
+      # a tinted `bg-destructive/10` panel in light mode.
+      def divider_class
+        class_names("divide-y", (variant == :destructive) ? "divide-destructive/30" : "divide-border")
       end
 
       private
 
       def base_classes
-        "bg-surface rounded-card border border-border p-2.5"
+        "bg-surface rounded-card border"
+      end
+
+      def padding_class
+        PADDING_CLASSES unless sectioned?
+      end
+
+      def variant_classes
+        case variant
+        when :destructive
+          "border-destructive bg-destructive/10"
+        else
+          "border-border"
+        end
       end
 
       def hoverable_classes

data/lib/atomic_view/components/concerns/button_variants.rb

@@ -7,7 +7,7 @@ module AtomicView
         private
 
         def base_classes
-          "h-7 rounded-btn px-2.5 inline-flex items-center justify-center gap-2 whitespace-nowrap text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]"
+          "h-9 rounded-btn px-2.5 inline-flex items-center justify-center gap-2 whitespace-nowrap text-sm font-medium transition-all disabled:pointer-events-none disabled:opacity-50 outline-none focus-visible:border-ring focus-visible:ring-ring/50 focus-visible:ring-[3px]"
         end
 
         def variant_classes

data/lib/atomic_view/components/index_page_component.html.erb

@@ -0,0 +1,35 @@
+<% breadcrumbs_content = breadcrumbs.to_s %>
+<% title_content = title.to_s %>
+<% badge_content = badge.to_s %>
+<% subtitle_content = subtitle.to_s %>
+<% actions_content = actions.to_s %>
+
+<%= tag.div(**@options.except(:class, :id), id: html_id, class: html_class) do %>
+  <%= tag.div(class: "mb-4") do %>
+    <%= render(AtomicView::Components::PageHeaderComponent.new) do |header| %>
+      <% header.with_breadcrumbs { breadcrumbs_content } if breadcrumbs? %>
+      <% header.with_title { title_content } if title? %>
+      <% header.with_badge { badge_content } if badge? %>
+      <% header.with_subtitle { subtitle_content } if subtitle? %>
+      <% header.with_actions { actions_content } if actions? %>
+    <% end %>
+  <% end %>
+
+  <% if filters? %>
+    <%= tag.div(filters, class: "mb-4") %>
+  <% end %>
+
+  <% if toolbar? %>
+    <%= tag.div(toolbar, class: "mb-4") %>
+  <% end %>
+
+  <% if empty? %>
+    <%= empty_state if empty_state? %>
+  <% else %>
+    <%= content %>
+
+    <% if pagination? %>
+      <%= tag.div(pagination, class: "mt-4") %>
+    <% end %>
+  <% end %>
+<% end %>

data/lib/atomic_view/components/index_page_component.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module AtomicView
+  module Components
+    # IndexPage
+    #
+    # The layout shell for a collection page: a PageHeaderComponent up top,
+    # an optional `filters` row (e.g. status pills), an optional `toolbar`
+    # row below that (search, dropdowns), then either the default content
+    # block or an `empty_state` slot, and finally an optional `pagination`
+    # slot. This is layout only -- the content region has no idea what's
+    # inside it. It doesn't reference TableComponent, doesn't assume rows or
+    # columns, and doesn't care whether the caller renders a table, a card
+    # grid, or anything else. A smarter, column-aware table is an app-level
+    # concern to build on top of this, not something this component owns.
+    #
+    #   render(AtomicView::Components::IndexPageComponent.new(empty: @rentals.empty?, dom_id: :rentals)) do |page|
+    #     page.with_title { "Rentals" }
+    #     page.with_subtitle { "#{@rental_count} rentals across #{@park_count} parks" }
+    #     page.with_actions { render(LinkComponent.new(new_rental_path)) { "New rental" } }
+    #     page.with_filters { render(SegmentedControlComponent.new(options: STATUS_OPTIONS, selected: params[:status] || "All")) }
+    #     page.with_toolbar { render(SearchFieldComponent.new(...)) }
+    #     page.with_pagination { render(PaginationComponent.new(current_page: @pagy.page, total_pages: @pagy.pages, path_for_page: ->(p) { rentals_path(page: p) })) }
+    #     page.with_empty_state { render(EmptyStateComponent.new(title: "No rentals yet")) }
+    #
+    #     render(AtomicView::Components::TableComponent.new) { ... }
+    #   end
+    #
+    # `breadcrumbs`/`title`/`badge`/`subtitle`/`actions` are forwarded
+    # straight into an internally-rendered PageHeaderComponent -- see its
+    # docs for what each renders. `empty:` and `dom_id:` stay plain
+    # caller-supplied values rather than being derived from a model/Pagy
+    # object, so this component never needs to know about ActiveRecord or a
+    # pagination library -- an app-level wrapper (e.g. a `ListViewComponent`
+    # that already knows about `Pagy`/routes) is the right place to compute
+    # them before calling this one.
+    class IndexPageComponent < AtomicView::Component
+      renders_one :breadcrumbs
+      renders_one :title
+      renders_one :badge
+      renders_one :subtitle
+      renders_one :actions
+      renders_one :filters
+      renders_one :toolbar
+      renders_one :empty_state
+      renders_one :pagination
+
+      attr_reader :dom_id
+
+      def initialize(empty: false, dom_id: nil, **options)
+        super()
+        @empty = empty
+        @dom_id = dom_id
+        @options = options
+      end
+
+      def empty? = @empty
+
+      def html_class
+        class_names(@options[:class])
+      end
+
+      def html_id
+        @options[:id] || dom_id
+      end
+    end
+  end
+end

data/lib/atomic_view/components/navigation_tree_component/item_component.html.erb

@@ -4,10 +4,10 @@
       <% if icon_name.present? %>
         <%= icon(icon_name, options: {class: "size-4 shrink-0"}).to_s.html_safe %>
       <% end %>
-      <%= label %>
-      <%= icon("chevron-right", options: {class: "ml-auto size-4 shrink-0 transition-transform"}).to_s.html_safe %>
+      <span class="truncate group-data-[collapsed]/nav:hidden"><%= label %></span>
+      <%= icon("chevron-right", options: {class: "ml-auto size-4 shrink-0 transition-transform group-data-[collapsed]/nav:hidden"}).to_s.html_safe %>
     <% end %>
-    <div class="ml-6 mt-1 flex flex-col gap-1">
+    <div class="ml-6 mt-1 flex flex-col gap-1 group-data-[collapsed]/nav:hidden">
       <% items.each do |item| %>
         <%= item %>
       <% end %>
@@ -18,6 +18,6 @@
     <% if icon_name.present? %>
       <%= icon(icon_name, options: {class: "size-4 shrink-0"}).to_s.html_safe %>
     <% end %>
-    <%= label %>
+    <span class="truncate group-data-[collapsed]/nav:hidden"><%= label %></span>
   <% end %>
 <% end %>

data/lib/atomic_view/components/navigation_tree_component/item_component.rb

@@ -38,7 +38,8 @@ module AtomicView
         private
 
         def base_classes
-          "flex items-center gap-2 rounded-btn px-2.5 py-1.5 text-sm font-medium"
+          "flex items-center gap-2 rounded-btn px-2.5 py-1.5 text-sm font-medium " \
+            "group-data-[collapsed]/nav:justify-center group-data-[collapsed]/nav:px-2"
         end
 
         def active_classes

data/lib/atomic_view/components/navigation_tree_component.html.erb

@@ -1,8 +1,16 @@
-<%= tag.nav(**@options.except(:class), class: container_class) do %>
-  <% if label.present? %>
+<%= tag.nav(**html_options, class: container_class, data: data_attributes) do %>
+  <% if label.present? && !collapsed? %>
     <div class="px-2.5 pb-1 text-xs font-semibold uppercase tracking-wide text-muted-foreground"><%= label %></div>
   <% end %>
   <% items.each do |item| %>
-    <%= item %>
+    <% if collapsed? %>
+      <%= render(AtomicView::Components::TooltipComponent.new(text: item.label, placement: tooltip_placement)) do |tooltip| %>
+        <% tooltip.with_trigger do %>
+          <%= item %>
+        <% end %>
+      <% end %>
+    <% else %>
+      <%= item %>
+    <% end %>
   <% end %>
 <% end %>

data/lib/atomic_view/components/navigation_tree_component.rb

@@ -21,19 +21,48 @@ module AtomicView
     # as a disclosure (a `<summary>` row with a trailing chevron) whose own
     # `with_item` children render nested inside it once open -- see
     # `ItemComponent` for the per-item API.
+    #
+    # Pass `collapsed: true` for an icon-only rail -- labels, chevrons, and
+    # any open group's nested items are hidden with CSS (a `group/nav`
+    # marker plus `group-data-[collapsed]/nav:*` variants on each item, the
+    # same "no JS" approach as the disclosure groups above), not swapped out
+    # in Ruby. Each top-level item is automatically wrapped in a
+    # `TooltipComponent` showing its `label:` on hover, since the icon alone
+    # loses the item's name -- nested items stay unwrapped, since their
+    # container is hidden while collapsed (unreachable in a rail without a
+    # flyout, which is out of scope here):
+    #
+    #   render(NavigationTreeComponent.new(collapsed: true)) do |tree|
+    #     tree.with_item(label: "Overview", href: "#", icon: "home", active: true)
+    #   end
     class NavigationTreeComponent < AtomicView::Component
       renders_many :items, "ItemComponent"
 
-      attr_reader :label
+      attr_reader :label, :tooltip_placement
 
-      def initialize(label: nil, **options)
+      def initialize(label: nil, collapsed: false, tooltip_placement: "right", **options)
         super()
         @label = label
+        @collapsed = collapsed
+        @tooltip_placement = tooltip_placement
         @options = options
       end
 
+      def collapsed?
+        @collapsed
+      end
+
       def container_class
-        class_names("flex flex-col gap-1", @options[:class])
+        class_names("group/nav flex flex-col gap-1", collapsed? ? "items-center" : nil, @options[:class])
+      end
+
+      def html_options
+        @options.except(:class, :data)
+      end
+
+      def data_attributes
+        attributes = @options[:data] || {}
+        collapsed? ? attributes.merge(collapsed: true) : attributes
       end
     end
   end

data/lib/atomic_view/components/page_header_component.html.erb

@@ -0,0 +1,17 @@
+<%= tag.div(**@options.except(:class), class: html_class) do %>
+  <div>
+    <% if breadcrumbs? %>
+      <div class="mb-1 text-xs font-semibold text-primary"><%= breadcrumbs %></div>
+    <% end %>
+    <div class="flex items-center gap-2">
+      <h1 class="text-2xl font-bold text-foreground sm:text-xl"><%= title %></h1>
+      <% if badge? %><%= badge %><% end %>
+    </div>
+    <% if subtitle? %>
+      <div class="mt-1 text-sm text-muted-foreground"><%= subtitle %></div>
+    <% end %>
+  </div>
+  <% if actions? %>
+    <div class="flex shrink-0 items-center gap-2"><%= actions %></div>
+  <% end %>
+<% end %>

data/lib/atomic_view/components/page_header_component.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module AtomicView
+  module Components
+    # PageHeader
+    #
+    # The title/breadcrumb/badge/actions cluster shared by IndexPageComponent
+    # and ShowPageComponent (and usable standalone, e.g. above a lazily-loaded
+    # turbo-frame fragment that has no page shell of its own). Every region is
+    # a free-form slot -- this component only lays them out, it has no
+    # opinion about hrefs, badge variants, or what an action is.
+    #
+    #   render(AtomicView::Components::PageHeaderComponent.new) do |header|
+    #     header.with_breadcrumbs { link_to "Rentals", rentals_path, class: "text-xs font-semibold text-primary" }
+    #     header.with_title { "RS002 · Karen Wilson" }
+    #     header.with_badge { render(BadgeComponent.new) { "Active" } }
+    #     header.with_subtitle { "rental_9f21ba7c" }
+    #     header.with_actions { render(LinkComponent.new(edit_rental_path(@rental), variant: :outline)) { "Edit" } }
+    #   end
+    #
+    # `title` is the one slot every caller is expected to fill -- there's no
+    # runtime enforcement of that (this gem doesn't raise on missing slots
+    # elsewhere either, e.g. DropdownComponent's `menu`), just a documented
+    # expectation. `badge` renders inline right after the title (e.g. a
+    # status pill); `subtitle` renders on its own line below (a record count,
+    # a copyable reference id); `breadcrumbs` renders above the title as a
+    # small eyebrow link; `actions` renders as a button/link cluster on the
+    # opposite side of the row, wrapping above the title/breadcrumb column on
+    # narrow viewports.
+    class PageHeaderComponent < AtomicView::Component
+      renders_one :breadcrumbs
+      renders_one :title
+      renders_one :badge
+      renders_one :subtitle
+      renders_one :actions
+
+      def initialize(**options)
+        super()
+        @options = options
+      end
+
+      def html_class
+        class_names(base_classes, @options[:class])
+      end
+
+      private
+
+      def base_classes
+        "flex flex-col gap-4 sm:flex-row sm:items-start sm:justify-between"
+      end
+    end
+  end
+end

data/lib/atomic_view/components/show_page_component.html.erb

@@ -0,0 +1,28 @@
+<% breadcrumbs_content = breadcrumbs.to_s %>
+<% title_content = title.to_s %>
+<% badge_content = badge.to_s %>
+<% subtitle_content = subtitle.to_s %>
+<% actions_content = actions.to_s %>
+
+<%= tag.article(**@options.except(:class), class: html_class) do %>
+  <%= tag.div(class: "mb-8") do %>
+    <%= render(AtomicView::Components::PageHeaderComponent.new) do |header| %>
+      <% header.with_breadcrumbs { breadcrumbs_content } if breadcrumbs? %>
+      <% header.with_title { title_content } if title? %>
+      <% header.with_badge { badge_content } if badge? %>
+      <% header.with_subtitle { subtitle_content } if subtitle? %>
+      <% header.with_actions { actions_content } if actions? %>
+    <% end %>
+  <% end %>
+
+  <% if highlight? %>
+    <%= tag.div(highlight, class: "mb-8") %>
+  <% end %>
+
+  <%= tag.div(class: body_class) do %>
+    <% if sidebar? %>
+      <%= tag.div(sidebar, class: sidebar_class) %>
+    <% end %>
+    <%= tag.div(content, class: main_class) %>
+  <% end %>
+<% end %>

data/lib/atomic_view/components/show_page_component.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module AtomicView
+  module Components
+    # ShowPage
+    #
+    # The layout shell for a single-record detail page: a PageHeaderComponent
+    # up top, an optional full-width `highlight` region below it, then a
+    # two-column body -- the default content block as the main column, and an
+    # optional `sidebar` slot as a second column. This is layout only -- it
+    # has no opinion about what a record's detail page actually contains.
+    # `highlight` is deliberately not called "stepper" or "progress": it's
+    # just a full-width slot for whatever sits between the header and the
+    # body (a lifecycle stepper, a banner, nothing at all) -- naming it after
+    # a specific piece of content would smuggle a content assumption into a
+    # layout component. Same reasoning for `sidebar`: it's a column, not a
+    # "details panel" -- fill it with a CardComponent, a plain `<dl>`,
+    # whatever the record calls for.
+    #
+    #   render(AtomicView::Components::ShowPageComponent.new) do |page|
+    #     page.with_breadcrumbs { link_to "Rentals", rentals_path, class: "text-xs font-semibold text-primary" }
+    #     page.with_title { "RS002 · Karen Wilson" }
+    #     page.with_badge { render(BadgeComponent.new) { "Active" } }
+    #     page.with_actions { render(LinkComponent.new(edit_rental_path(@rental), variant: :outline)) { "Edit" } }
+    #     page.with_highlight { render(RentalStepperComponent.new(rental: @rental)) }
+    #     page.with_sidebar { render "rentals/details_panel", rental: @rental }
+    #
+    #     tag.section { tag.h2("Overview", class: "text-lg font-semibold mb-2") + render(CardComponent.new) { @rental.notes } }
+    #   end
+    #
+    # `breadcrumbs`/`title`/`badge`/`subtitle`/`actions` are forwarded
+    # straight into an internally-rendered PageHeaderComponent -- see its
+    # docs for what each renders. The default content block is the main
+    # column; when `sidebar` is omitted, the main column spans full width
+    # rather than leaving an empty second column.
+    #
+    # The two-column grid (sidebar first in document order, reordered after
+    # the main column from `sm:` up) matches every existing hand-rolled show
+    # page in the consuming app -- that's the "good defaults" this component
+    # exists to stop re-typing, not a novel layout choice.
+    class ShowPageComponent < AtomicView::Component
+      renders_one :breadcrumbs
+      renders_one :title
+      renders_one :badge
+      renders_one :subtitle
+      renders_one :actions
+      renders_one :highlight
+      renders_one :sidebar
+
+      def initialize(**options)
+        super()
+        @options = options
+      end
+
+      def html_class
+        class_names(@options[:class])
+      end
+
+      def body_class
+        class_names("grid grid-cols-1 gap-8", {"sm:grid-cols-3 sm:gap-12" => sidebar?})
+      end
+
+      def sidebar_class
+        "flex flex-col gap-8 sm:order-2 sm:col-span-1"
+      end
+
+      def main_class
+        class_names("flex flex-col gap-4 sm:gap-8", {"sm:order-1 sm:col-span-2" => sidebar?})
+      end
+    end
+  end
+end

data/lib/atomic_view/components/timeline_component/item_component.rb

@@ -16,16 +16,23 @@ module AtomicView
       # (aging into a full date over time) client-side once the host app
       # loads local_time's JS -- see `config/importmap.rb`'s "local-time"
       # pin comment for that setup.
+      #
+      # Any other keyword argument (`id:`, `data:`, `class:`, ...) passes
+      # through to the row's outer wrapper `<div>` in
+      # `TimelineComponent`'s template, so a caller can address a whole
+      # row -- marker, meta line, and content -- for e.g. a Turbo Stream
+      # `remove`/`replace`, or wire up a Stimulus target on the row itself.
       class ItemComponent < AtomicView::Component
-        attr_reader :icon_name, :avatar, :actor, :description, :time
+        attr_reader :icon_name, :avatar, :actor, :description, :time, :html_options
 
-        def initialize(description:, icon: nil, avatar: nil, actor: nil, time: nil)
+        def initialize(description:, icon: nil, avatar: nil, actor: nil, time: nil, **html_options)
           super()
           @icon_name = icon
           @avatar = avatar
           @actor = actor
           @description = description
           @time = time
+          @html_options = html_options
         end
 
         def marker

data/lib/atomic_view/components/timeline_component.html.erb

@@ -1,10 +1,10 @@
 <%= tag.div(**@options.except(:class), class: container_class) do %>
   <% items.each_with_index do |item, index| %>
-    <div class="<%= item_wrapper_class(index) %>">
+    <%= tag.div(**item.html_options.except(:class), class: item_wrapper_class(index, item)) do %>
       <% if render_line?(index) %>
         <div class="absolute left-[13px] top-7 -bottom-6 w-px bg-border"></div>
       <% end %>
       <%= item %>
-    </div>
+    <% end %>
   <% end %>
 <% end %>

data/lib/atomic_view/components/timeline_component.rb

@@ -47,8 +47,8 @@ module AtomicView
       # `continues:` says this render is one page of a longer feed -- the connector
       # keeps going past the last item, into whatever the next turbo frame appends
       # or the stream prepends above.
-      def item_wrapper_class(index)
-        class_names("relative flex gap-3.5", "pb-6" => !last?(index) || @continues)
+      def item_wrapper_class(index, item)
+        class_names("relative flex gap-3.5", {"pb-6" => !last?(index) || @continues}, item.html_options[:class])
       end
 
       def render_line?(index)

data/lib/atomic_view/components/tooltip_component.html.erb

@@ -0,0 +1,13 @@
+<%= tag.span(**html_options, class: html_class, data: data_attributes) do %>
+  <%= tag.span(class: "inline-block", data: trigger_data_attributes, aria: {describedby: content_id}) do %>
+    <%= trigger %>
+  <% end %>
+
+  <%= tag.span(id: content_id, role: "tooltip", class: content_class, data: content_data_attributes) do %>
+    <% if body? %>
+      <%= body %>
+    <% else %>
+      <%= text %>
+    <% end %>
+  <% end %>
+<% end %>

data/lib/atomic_view/components/tooltip_component.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module AtomicView
+  module Components
+    # Tooltip
+    #
+    # A trigger plus a floating label, positioned by `@floating-ui/dom` and
+    # wired to `atomic-view--tooltip` (see
+    # `app/assets/javascripts/atomic_view/controllers/tooltip_controller.js`).
+    # The controller shows the tooltip on hover/focus of the trigger and
+    # hides it on mouseleave/blur/Esc, keeping it anchored to the trigger
+    # while the page scrolls or resizes.
+    #
+    # The bubble uses `strategy: "fixed"` (and a `fixed` class, not
+    # `absolute`) rather than `DropdownComponent`'s approach -- an
+    # absolutely-positioned bubble's containing block is the trigger's own
+    # `relative` wrapper span, so its shrink-to-fit width silently caps out
+    # at the *trigger's* rendered width no matter how generous `max-w-*` is.
+    # `fixed` makes the viewport the containing block instead, so
+    # `content_class` (below) actually controls the bubble's width.
+    #
+    # Pass `text:` for the common case of a short plain-text label:
+    #
+    #   render(TooltipComponent.new(text: "Delete")) do |tooltip|
+    #     tooltip.with_trigger { icon_button }
+    #   end
+    #
+    # or a `body` slot for anything richer than plain text.
+    #
+    # The bubble defaults to `max-w-xs` (20rem) -- wide enough for a short
+    # label or two lines of `body` content. Pass `content_class:` to widen
+    # (or otherwise restyle) it for longer text:
+    #
+    #   render(TooltipComponent.new(text: "...", content_class: "max-w-sm"))
+    #
+    # It's a separate option from `class:`, which targets the outer trigger
+    # wrapper -- `content_class:` is merged (via TailwindMerge) onto the
+    # floating bubble itself, so `max-w-sm` here replaces the default
+    # `max-w-xs` rather than fighting it.
+    class TooltipComponent < AtomicView::Component
+      renders_one :trigger
+      renders_one :body
+
+      PLACEMENTS = %w[top bottom left right].freeze
+
+      attr_reader :text, :placement
+
+      def initialize(text: nil, placement: "top", content_class: nil, **options)
+        super()
+        @text = text
+        @placement = PLACEMENTS.include?(placement) ? placement : "top"
+        @id = "tooltip-#{SecureRandom.hex(4)}"
+        @content_class = content_class
+        @options = options
+      end
+
+      def html_options
+        @options.except(:class, :data)
+      end
+
+      def html_class
+        class_names("relative inline-block", @options[:class])
+      end
+
+      def data_attributes
+        (@options[:data] || {}).merge(
+          :controller => "atomic-view--tooltip",
+          "atomic-view--tooltip-placement-value" => placement
+        )
+      end
+
+      def trigger_data_attributes
+        {
+          "atomic-view--tooltip-target" => "trigger",
+          :action => "mouseenter->atomic-view--tooltip#show mouseleave->atomic-view--tooltip#hide " \
+            "focusin->atomic-view--tooltip#show focusout->atomic-view--tooltip#hide"
+        }
+      end
+
+      def content_id
+        @id
+      end
+
+      def content_data_attributes
+        {"atomic-view--tooltip-target" => "content"}
+      end
+
+      def content_class
+        class_names(
+          "pointer-events-none hidden fixed z-50 max-w-xs rounded-well bg-foreground px-2 py-1 text-xs " \
+            "font-medium text-surface shadow-soft",
+          @content_class
+        )
+      end
+    end
+  end
+end

data/lib/atomic_view/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module AtomicView
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atomic_view
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Joel Warrington
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-12 00:00:00.000000000 Z
+date: 2026-09-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: zeitwerk
@@ -148,6 +148,7 @@ files:
 - app/assets/javascripts/atomic_view/controllers/modal_controller.js
 - app/assets/javascripts/atomic_view/controllers/theme_toggle_controller.js
 - app/assets/javascripts/atomic_view/controllers/toast_controller.js
+- app/assets/javascripts/atomic_view/controllers/tooltip_controller.js
 - app/assets/stylesheets/atomic_view/application.css
 - app/assets/stylesheets/atomic_view/application.tailwind.css
 - app/assets/tailwind/atomic_view/engine.css
@@ -171,7 +172,9 @@ files:
 - lib/atomic_view/components/avatar_component.rb
 - lib/atomic_view/components/badge_component.rb
 - lib/atomic_view/components/button_component.rb
+- lib/atomic_view/components/card_component.html.erb
 - lib/atomic_view/components/card_component.rb
+- lib/atomic_view/components/card_component/section_component.rb
 - lib/atomic_view/components/check_box_component.rb
 - lib/atomic_view/components/chip_component.rb
 - lib/atomic_view/components/collection_check_boxes_component.html.erb
@@ -212,6 +215,8 @@ files:
 - lib/atomic_view/components/gantt_component/row_component.html.erb
 - lib/atomic_view/components/gantt_component/row_component.rb
 - lib/atomic_view/components/grouped_collection_select_component.rb
+- lib/atomic_view/components/index_page_component.html.erb
+- lib/atomic_view/components/index_page_component.rb
 - lib/atomic_view/components/kbd_component.rb
 - lib/atomic_view/components/label_component.rb
 - lib/atomic_view/components/link_component.html.erb
@@ -224,6 +229,8 @@ files:
 - lib/atomic_view/components/navigation_tree_component/item_component.html.erb
 - lib/atomic_view/components/navigation_tree_component/item_component.rb
 - lib/atomic_view/components/number_field_component.rb
+- lib/atomic_view/components/page_header_component.html.erb
+- lib/atomic_view/components/page_header_component.rb
 - lib/atomic_view/components/pagination_component.html.erb
 - lib/atomic_view/components/pagination_component.rb
 - lib/atomic_view/components/password_field_component.rb
@@ -234,6 +241,8 @@ files:
 - lib/atomic_view/components/segmented_control_component.rb
 - lib/atomic_view/components/select_component.html.erb
 - lib/atomic_view/components/select_component.rb
+- lib/atomic_view/components/show_page_component.html.erb
+- lib/atomic_view/components/show_page_component.rb
 - lib/atomic_view/components/submit_component.rb
 - lib/atomic_view/components/table_component.rb
 - lib/atomic_view/components/tabs_component.html.erb
@@ -250,6 +259,8 @@ files:
 - lib/atomic_view/components/timeline_component/item_component.rb
 - lib/atomic_view/components/toast_component.html.erb
 - lib/atomic_view/components/toast_component.rb
+- lib/atomic_view/components/tooltip_component.html.erb
+- lib/atomic_view/components/tooltip_component.rb
 - lib/atomic_view/components/url_field_component.rb
 - lib/atomic_view/components/week_field_component.rb
 - lib/atomic_view/components/weekday_select_component.rb