atomic_view 0.2.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd4eda901113f75bade919c83f2f6e45bc8e01727ca22aed9b6c4ab85ef55693
-  data.tar.gz: 566969e9ac8ba89e384e85b427f836a15226bf27834524caae0355efef80b39f
+  metadata.gz: 75aad701c9a9b4598ba4a086f8a3c1c37faaac0bbf23f4ef2927b4d667364f1b
+  data.tar.gz: 1a63769c7c94188b829105777227267be43df6480e6b2f864a5c7be4e831a179
 SHA512:
-  metadata.gz: 76933653def4779402ce08951a2dc75642d4e1e5a6e350127944f2a598216b1d09ef929021e204780f2a3957ed7394cdeae40a09819be4c9ddf464c6de9f9711
-  data.tar.gz: e05db9862990d64563fe7310828681d194f08c3ed6c33b9cb5b365c8fd944e121b76e001adeed404b54783b51ae85a4b2ac59f348571df5f039b8aca8bc598f6
+  metadata.gz: ba9732b3bf6ed19951e2c29ac2feafa7af299679135645bf28650808fd9ff6a6c9e9c3d994be9d23319b69a4679e4e7a8d67a73ae46603a963544a11430e0579
+  data.tar.gz: 10aff2eb5c66efb09918961c87cc708941cd30721c769cd3c2402082d09898098b32389cdfffe52519bbd3bedfa34bb8f2f265694cb0ed5226148abcfcbcd058

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/lazy_pagination_component.html.erb

@@ -0,0 +1,8 @@
+<% if next_page? %>
+  <%= tag.turbo_frame(id: id, loading: :lazy, src: next_page_path, class: "flex items-center justify-center gap-2 py-3") do %>
+    <span class="size-3.5 animate-spin rounded-full border-2 border-border border-t-foreground motion-reduce:animate-none" aria-hidden="true"></span>
+    <span class="sr-only">Loading more…</span>
+  <% end %>
+<% else %>
+  <%= tag.turbo_frame(id: id) %>
+<% end %>

data/lib/atomic_view/components/lazy_pagination_component.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module AtomicView
+  module Components
+    # LazyPagination
+    #
+    # The infinite-scroll counterpart to PaginationComponent's page-number
+    # links -- use PaginationComponent for numbered pages, this one for a
+    # list that loads its next page automatically as the user scrolls.
+    # Stays equally pagination-gem agnostic: the caller resolves both
+    # `next_page` (any presence-checkable value, e.g. a Pagy `next` page
+    # number) and `next_page_path` (the URL that lazily loaded page comes
+    # from) themselves.
+    #
+    #   render(AtomicView::Components::LazyPaginationComponent.new(
+    #     next_page: @pagy.next,
+    #     next_page_path: @pagy.next && bookings_path(page: @pagy.next)
+    #   ))
+    #
+    # Renders a `<turbo-frame loading="lazy" src="...">` (the same
+    # `tag.turbo_frame` technique GanttComponent's row/date pagination
+    # uses -- see that class's docs -- rather than a hard dependency on
+    # turbo-rails' view helpers) wrapping a spinner while `next_page` is
+    # present. Once there's no next page, it renders an empty
+    # `<turbo-frame>` with the same `id` instead of nothing at all, so a
+    # later `turbo_stream.replace(id, ...)` response from the last real
+    # page's fetch always has a target to replace.
+    class LazyPaginationComponent < AtomicView::Component
+      attr_reader :next_page, :next_page_path, :id
+
+      def initialize(next_page:, next_page_path: nil, id: :pagination)
+        super()
+        @next_page = next_page
+        @next_page_path = next_page_path
+        @id = id
+      end
+
+      def next_page?
+        next_page.present?
+      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/table_component/cell_component.html.erb

@@ -0,0 +1,6 @@
+<%= tag.td(**html_options, class: html_class) do %>
+  <% if linked? %>
+    <%= link_to "", path, class: "absolute inset-0", tabindex: (first ? 0 : -1), "aria-hidden": (first ? nil : "true"), "aria-label": (first ? label : nil), data: {row_link: true} %>
+  <% end %>
+  <%= tag.span(content, class: "relative") %>
+<% end %>

data/lib/atomic_view/components/table_component/cell_component.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module AtomicView
+  module Components
+    class TableComponent
+      # TableComponent::Cell
+      #
+      # One <td> within a RowComponent -- see that class's docs for the
+      # standalone-render requirement and the per-cell stretched-link
+      # design. `first` and `clickable` are set by RowComponent's `cells`
+      # slot from the row itself, not passed by the caller.
+      #
+      # Visible content renders as a normal sibling of the (empty,
+      # transparent) stretched `<a>`, wrapped in its own `position:
+      # relative` span so a real link nested inside a cell's content (e.g.
+      # a second, more specific action) still stays clickable above the
+      # row-wide overlay.
+      class CellComponent < AtomicView::Component
+        attr_reader :path, :label, :first, :align, :clickable
+
+        def initialize(path:, label:, first:, align: :left, clickable: true, **options)
+          super()
+          @path = path
+          @label = label
+          @first = first
+          @align = align
+          @clickable = clickable
+          @options = options
+        end
+
+        def linked?
+          clickable && path.present?
+        end
+
+        def html_class
+          class_names(base_classes, align_classes, @options[:class])
+        end
+
+        def html_options
+          @options.except(:class)
+        end
+
+        private
+
+        def base_classes
+          "relative px-2.5 py-2.5 border-b border-border/5"
+        end
+
+        def align_classes
+          case align
+          when :center then "text-center font-semibold"
+          when :right then "text-right"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/atomic_view/components/table_component/column_component.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module AtomicView
+  module Components
+    class TableComponent
+      # TableComponent::Column
+      #
+      # One <th> in the header row TableComponent auto-renders once at
+      # least one `with_column` is given -- see TableComponent's docs.
+      #
+      # `label` defaults to `model.human_attribute_name(attribute)`
+      # (mirroring Rails' own form label defaulting) when a `model:` is
+      # given -- TableComponent passes its own `model:` through to every
+      # column automatically, so callers only need `attribute:`. Pass
+      # `label:` directly instead for a column with no backing
+      # attribute (e.g. a blank header over a row of "Edit" links).
+      class ColumnComponent < AtomicView::Component
+        attr_reader :model, :attribute, :align, :width
+
+        def initialize(model: nil, attribute: nil, label: nil, align: :left, width: nil)
+          super()
+          raise ArgumentError, "label is required when model is not given" if model.nil? && label.nil?
+
+          @model = model
+          @attribute = attribute
+          @label = label
+          @align = align
+          @width = width
+        end
+
+        def label
+          @label || model.human_attribute_name(attribute)
+        end
+
+        def call
+          tag.th(label, scope: "col", class: header_class)
+        end
+
+        private
+
+        def header_class
+          class_names("p-2 font-medium", align_class, width)
+        end
+
+        def align_class
+          case align
+          when :center then "text-center"
+          when :right then "text-right"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/atomic_view/components/table_component/row_component.html.erb

@@ -0,0 +1,3 @@
+<%= tag.tr(**html_options, class: html_class) do %>
+  <%= safe_join(cells) %>
+<% end %>

data/lib/atomic_view/components/table_component/row_component.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module AtomicView
+  module Components
+    class TableComponent
+      # TableComponent::Row
+      #
+      # A single <tr>, renderable standalone -- no parent TableComponent
+      # instance required. That matters because a turbo_stream
+      # `append`/`update` response renders exactly one row outside of any
+      # table context, e.g.:
+      #
+      #   turbo_stream.append(:bookings_body, AtomicView::Components::TableComponent::RowComponent.new(
+      #     record: @booking, label: @booking.camper_name, path: booking_path(@booking)
+      #   ) { |row| row.with_cell { @booking.camper_name } })
+      #
+      # `path` defaults to `record` itself so `path_to(record)`-style route
+      # helpers resolve it via `to_model`/`to_param` the same way `link_to`
+      # would; pass `path:` explicitly when the row's destination isn't
+      # just `record`'s own show page.
+      #
+      # Each `with_cell` becomes its own stretched link to `path` -- a
+      # single `<a>` can't span multiple `<td>` siblings the way it could
+      # wrap a `<div>` row -- but only the first cell's link stays in the
+      # tab order (`tabindex="0"`; the rest are `tabindex="-1"` and
+      # `aria-hidden`), so a keyboard/screen-reader user hits one focus
+      # stop per row rather than one per cell. `label` is that first
+      # link's accessible name. Pass `clickable: false` for a row that
+      # shouldn't navigate anywhere -- cells then render as plain,
+      # unlinked content.
+      class RowComponent < AtomicView::Component
+        renders_many :cells, ->(**kwargs) { CellComponent.new(path: path, label: label, first: cells.empty?, clickable: clickable, **kwargs) }
+
+        attr_reader :record, :label, :path, :clickable
+
+        def initialize(record:, label:, path: nil, clickable: true, **options)
+          super()
+          @record = record
+          @label = label
+          @path = path || record
+          @clickable = clickable
+          @options = options
+        end
+
+        def html_class
+          class_names(clickable ? "hover:bg-offset" : nil, @options[:class])
+        end
+
+        def html_options
+          @options.except(:class)
+        end
+      end
+    end
+  end
+end

data/lib/atomic_view/components/table_component.rb

@@ -4,10 +4,10 @@ module AtomicView
   module Components
     # Table
     #
-    # A thin styling wrapper around <table>. Consistent with the rest of the
-    # gem, this does not own row/column iteration -- the consuming view
-    # builds its own <thead>/<tbody> markup and calls the yielded component's
-    # #head_class / #row_class helpers to pick up the shared styling.
+    # A thin styling wrapper around <table>. By default this owns no
+    # row/column concept -- the consuming view builds its own
+    # <thead>/<tbody> markup and calls the yielded component's #head_class
+    # / #row_class helpers to pick up the shared styling:
     #
     #   <%= render AtomicView::Components::TableComponent.new do |table| %>
     #     <thead>
@@ -21,17 +21,53 @@ module AtomicView
     #       </tr>
     #     </tbody>
     #   <% end %>
+    #
+    # `with_column` is an opt-in alternative to hand-building the <thead>:
+    # give it at least one column and TableComponent renders the header row
+    # itself, from `<th>`s built by TableComponent::ColumnComponent -- you
+    # still own `<tbody>` content (typically TableComponent::RowComponent
+    # rows) in the block, same as before:
+    #
+    #   <%= render AtomicView::Components::TableComponent.new(model: Booking) do |table| %>
+    #     <% table.with_column(attribute: :camper_name) %>
+    #     <% table.with_column(attribute: :status, align: :center) %>
+    #     <% table.with_column(label: "") %>
+    #
+    #     <tbody>
+    #       <% @bookings.each do |booking| %>
+    #         <%= render(AtomicView::Components::TableComponent::RowComponent.new(record: booking, label: booking.camper_name, path: booking_path(booking))) do |row| %>
+    #           <% row.with_cell { booking.camper_name } %>
+    #           <% row.with_cell(align: :center) { render(BadgeComponent.new) { booking.status } } %>
+    #           <% row.with_cell { render(LinkComponent.new(edit_booking_path(booking), variant: :outline)) { "Edit" } } %>
+    #         <% end %>
+    #       <% end %>
+    #     </tbody>
+    #   <% end %>
+    #
+    # A table with no columns given renders exactly as before -- `with_column`
+    # is opt-in, not a second required API. `model:` is passed through to
+    # each column so `with_column(attribute: :camper_name)` can default its
+    # label via `model.human_attribute_name(:camper_name)`; a column with no
+    # backing attribute (like the blank "" header above, for an actions
+    # column) just passes `label:` directly instead.
     class TableComponent < AtomicView::Component
       HEAD_ROW_CLASSES = "text-left text-xs font-semibold uppercase tracking-wide text-muted-foreground border-b border-border"
       BODY_ROW_CLASSES = "border-b border-border hover:bg-offset"
 
-      def initialize(**options)
+      renders_many :columns, ->(**kwargs) { ColumnComponent.new(model: model, **kwargs) }
+
+      attr_reader :model
+
+      def initialize(model: nil, **options)
         super()
+        @model = model
         @options = options
       end
 
       def call
-        tag.table(**@options.except(:class), class: class_names(base_classes, @options[:class])) { content }
+        tag.table(**@options.except(:class), class: class_names(base_classes, @options[:class])) do
+          safe_join([columns_header, content].compact)
+        end
       end
 
       def head_class(**options)
@@ -44,6 +80,15 @@ module AtomicView
 
       private
 
+      def columns_header
+        return unless columns?
+        tag.thead { tag.tr(class: head_class) { safe_join(columns) } }
+      end
+
+      def columns?
+        columns.any?
+      end
+
       def base_classes
         "w-full text-sm"
       end

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.2"
+  VERSION = "0.4.0"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: atomic_view
 version: !ruby/object:Gem::Version
-  version: 0.2.2
+  version: 0.4.0
 platform: ruby
 authors:
 - Joel Warrington
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-09-14 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,8 +215,12 @@ 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/lazy_pagination_component.html.erb
+- lib/atomic_view/components/lazy_pagination_component.rb
 - lib/atomic_view/components/link_component.html.erb
 - lib/atomic_view/components/link_component.rb
 - lib/atomic_view/components/modal_component.html.erb
@@ -224,6 +231,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,8 +243,15 @@ 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/table_component/cell_component.html.erb
+- lib/atomic_view/components/table_component/cell_component.rb
+- lib/atomic_view/components/table_component/column_component.rb
+- lib/atomic_view/components/table_component/row_component.html.erb
+- lib/atomic_view/components/table_component/row_component.rb
 - lib/atomic_view/components/tabs_component.html.erb
 - lib/atomic_view/components/tabs_component.rb
 - lib/atomic_view/components/telephone_field_component.rb
@@ -250,6 +266,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