sdr_view_components 0.4.2 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e8de1e6c4339890803922546b84f23b95b8226034289306bcd9afc7f5a12680b
-  data.tar.gz: 1ba1793859c3b03bb41128682e17c6e4feec4de1509810a2b15773042e0effbf
+  metadata.gz: e251b4177b159e8978b41116e020d3d58d5f95071c6dbccd9b212d3751c9a118
+  data.tar.gz: be45e43ececfc02ed410b67844418c80371a28a1b89596a56630f3d81ce2df22
 SHA512:
-  metadata.gz: b70f694252831c5ce2b9e55e84f0b3aa53447954dea2fb4a29b10efd495a47944f1a27036cbbf82b69746d817234a9ea81b967b344f4e216a5909056bae00e5d
-  data.tar.gz: d53b27ec2eb61c0ff85b9dae7fda11024c748ee70563b16e07a230720ab7f94f6644d51b82376a63072480d996390e27e46e316e735cfc9e5d59a06a7c652274
+  metadata.gz: 638147ae953c62036f9553375bbac77530a7b6dfdc4dcd9243954b4bf702250a70a5953fb9b4444f2d1c5c249f45a797816a0def51f323c57d6fad91a57d566c
+  data.tar.gz: c7a3458363dfe0bc1000fb4b24ce6415fece60c20f3d06722c5f626204eff3582badefe1a9ab0696000aa949777484dbd3c6a50938762c1e600a8782d08907c8

data/README.md

@@ -46,6 +46,38 @@ import ToastController from "sdr_view_components/toast_controller"
 application.register("sdr-toast", ToastController)
 ```
 
+`SdrViewComponents::TabForm::TabListComponent` (see [Tab form components](#tab-form-components) below) similarly ships three controllers: `sdr_view_components/tab_error_controller`, `sdr_view_components/tab_link_controller`, and `sdr_view_components/tab_nav_controller`. Pin and register each the same way, using the `sdr-tab-error`, `sdr-tab-link`, and `sdr-tab-nav` identifiers respectively:
+
+```ruby
+pin "sdr_view_components/tab_error_controller", to: "sdr_view_components/tab_error_controller.js"
+pin "sdr_view_components/tab_link_controller", to: "sdr_view_components/tab_link_controller.js"
+pin "sdr_view_components/tab_nav_controller", to: "sdr_view_components/tab_nav_controller.js"
+```
+
+```javascript
+import { application } from "controllers/application"
+import TabErrorController from "sdr_view_components/tab_error_controller"
+import TabLinkController from "sdr_view_components/tab_link_controller"
+import TabNavController from "sdr_view_components/tab_nav_controller"
+
+application.register("sdr-tab-error", TabErrorController)
+application.register("sdr-tab-link", TabLinkController)
+application.register("sdr-tab-nav", TabNavController)
+```
+
+`SdrViewComponents::Elements::Tabs::TabListComponent`'s `collapse_below` option (see [General usage](#general-usage) below) ships `sdr_view_components/tab_select_controller`, registered as `sdr-tab-select`:
+
+```ruby
+pin "sdr_view_components/tab_select_controller", to: "sdr_view_components/tab_select_controller.js"
+```
+
+```javascript
+import { application } from "controllers/application"
+import TabSelectController from "sdr_view_components/tab_select_controller"
+
+application.register("sdr-tab-select", TabSelectController)
+```
+
 ## Usage
 
 ### Form components
@@ -93,8 +125,62 @@ Each of the supported components above uses the provided "basic" components:
 
 At a minimum, each of these components must be provided wih the `form:` and `field_name:` parameters. Additionally, you can provide additional parameters that will be passed to the standard ActionView::Helpers::Tag.
 
+### Tab form components
+
+SdrViewComponents provides components for rendering a tabbed form, where a form's fields are split across tabs rather than shown all at once:
+
+- `SdrViewComponents::TabForm::TabListComponent` -- renders the tab navigation and tab panes. It doesn't render a `<form>` tag itself.
+- `SdrViewComponents::TabForm::TabComponent` -- a single tab, rendered via `TabListComponent#with_tab`.
+- `SdrViewComponents::TabForm::HiddenFieldsFormComponent` -- renders the one real `<form>` tag backing the tabbed form. It only contains hidden fields; the visible fields (rendered inside `TabListComponent`'s panes) associate with this form via the HTML `form` attribute rather than DOM nesting, since panes aren't necessarily inside the `<form>`.
+- `SdrViewComponents::TabForm::TabbedFormBuilder` -- a `FormBuilder` that automatically sets the `form` attribute (pointing at the `HiddenFieldsFormComponent`'s form id) on every field it builds.
+- `SdrViewComponents::TabForm::PaneComponent` -- generic tab-pane chrome (optional header/help/footer, Bootstrap `tab-pane` classes, and the target wiring the `sdr-tab-error` controller needs). Wrap it in an app-specific component if you need pane-level buttons or layout beyond what it provides.
+
+Panes passed to `TabListComponent#with_pane` can be any renderable object (a `ViewComponent`, a block, etc.) -- the caller supplies its own pane component, whether that's `PaneComponent` directly or a wrapper around it. If the pane responds to `active_tab_name=`, `TabListComponent` sets it centrally, so panes don't need `active_tab_name` passed to them individually.
+
+`TabListComponent` requires JavaScript to mark tabs containing invalid fields -- see the `sdr-tab-error` controller under [JavaScript](#javascript) above.
+
+A minimal example:
+
+```erb
+<%= render SdrViewComponents::TabForm::HiddenFieldsFormComponent.new(model: @work_form, id: 'tabbed_form', hidden_fields: %i[lock version]) %>
+
+<%= render SdrViewComponents::TabForm::TabListComponent.new(id: 'tabbed_form', active_tab_name: :details) do |tab_list| %>
+  <% tab_list.with_tab(label: 'Details', tab_name: :details, mark_required: true) %>
+  <% tab_list.with_tab(label: 'Notes', tab_name: :notes) %>
+
+  <% form_with(model: @work_form, html: { id: 'tabbed_form' }, builder: SdrViewComponents::TabForm::TabbedFormBuilder) do |form| %>
+    <% tab_list.with_pane(SdrViewComponents::TabForm::PaneComponent.new(tab_name: :details, label: 'Details')) do %>
+      <%= render SdrViewComponents::Forms::TextFieldComponent.new(form:, field_name: :title) %>
+    <% end %>
+
+    <% tab_list.with_pane(SdrViewComponents::TabForm::PaneComponent.new(tab_name: :notes, label: 'Notes')) do %>
+      <%= render SdrViewComponents::Forms::TextAreaComponent.new(form:, field_name: :notes) %>
+    <% end %>
+  <% end %>
+<% end %>
+```
+
+See the Lookbook preview for `SdrViewComponents::TabForm::TabListComponent` for a runnable example.
+
 ### General usage:
 
+`SdrViewComponents::Elements::Tabs::TabListComponent` accepts a `collapse_below:` option (one of `:sm`, `:md`, `:lg`, `:xl`, `:xxl`). When given, the tabs are replaced with a `<select>` below that Bootstrap breakpoint instead of wrapping or scrolling -- the `<select>` drives the same Bootstrap tab JavaScript as the tabs, so panes switch the same way regardless of which control is visible. Leave it unset (the default) to always render the tabs. This requires the `sdr-tab-select` controller -- see [JavaScript](#javascript) above.
+
+```erb
+<%= render SdrViewComponents::Elements::Tabs::TabListComponent.new(variant: :underline, collapse_below: :xl) do |tab_list| %>
+  <% tab_list.with_tab(label: 'Details', id: 'details-tab', pane_id: 'details-pane', active: true) %>
+  <% tab_list.with_tab(label: 'History', id: 'history-tab', pane_id: 'history-pane') %>
+
+  <% tab_list.with_pane(id: 'details-pane', tab_id: 'details-tab', active: true) do %>
+    <p>Details pane content.</p>
+  <% end %>
+
+  <% tab_list.with_pane(id: 'history-pane', tab_id: 'history-tab') do %>
+    <p>History pane content.</p>
+  <% end %>
+<% end %>
+```
+
 ```
 <% render SdrViewComponent::....>
 ```

data/app/assets/sdr_view_components.css

@@ -76,6 +76,90 @@
   font-weight: bold;
 }
 
+/* Tab form */
+.tab-form .nav-pills {
+  background-color: var(--stanford-10-black);
+}
+
+.tab-form .nav-pills .nav-link {
+  --bs-nav-link-padding-x: 0.5rem;
+
+  border-radius: unset;
+  display: block flex;
+  text-align: left;
+}
+
+.tab-form .nav-pills .nav-link:not(:first-child) {
+  border-top: var(--bs-border-width) var(--bs-border-style) rgb(var(--bs-white-rgb), 1);
+}
+
+.tab-form .nav-pills .nav-link:first-child {
+  border-top-left-radius: var(--bs-border-radius);
+  border-top-right-radius: var(--bs-border-radius);
+}
+
+.tab-form .nav-pills .nav-link:last-child {
+  border-bottom-left-radius: var(--bs-border-radius);
+  border-bottom-right-radius: var(--bs-border-radius);
+}
+
+.tab-form .nav-pills .nav-link:not(.active) {
+  color: var(--stanford-black);
+  padding-left: 1.7rem; /* Align the text of inactive nav items with the active one, roughly */
+}
+
+.tab-form .nav-pills .nav-link:not(.active):hover {
+  text-decoration: underline;
+}
+
+.tab-form .nav-pills .nav-link.active {
+  background-color: var(--stanford-black);
+  color: var(--bs-white);
+  font-weight: 700;
+}
+
+.tab-form .nav-pills .nav-link.active .required {
+  color: var(--bs-white);
+}
+
+.tab-form .nav-pills .nav-link.active::before {
+  display: inline-block;
+  margin-right: 2px;
+  font-family: bootstrap-icons;
+  vertical-align: -15%;
+  content: "\F138"; /* right arrow */
+}
+
+.tab-form .nav-pills .nav-link.is-invalid {
+  color: var(--bs-danger-text-emphasis);
+}
+
+.tab-form .nav-pills .nav-link.is-invalid.active {
+  background-color: white;
+  border: 2px solid var(--stanford-black);
+}
+
+.tab-form .nav-pills .nav-link.is-invalid::after {
+  margin-left: 10px;
+  display: inline-block;
+  font-family: bootstrap-icons;
+  font-weight: normal;
+  vertical-align: -15%;
+  content: "\F33A"; /* exclamation triangle fill */
+}
+
+.tab-form .pane-header {
+  padding-bottom: 40px;
+}
+
+.tab-form .pane-section {
+  padding-bottom: 40px;
+}
+
+.tab-form .pane-section:last-child {
+  padding-bottom: 80px;
+}
+
 /* Tables */
 table.table-h3 caption {
   padding: .25rem;

data/app/components/base_component.rb

@@ -28,4 +28,18 @@ class BaseComponent < ViewComponent::Base
       h[key.to_s.delete_prefix(prefix).to_sym] = value if key.to_s.start_with?(prefix)
     end
   end
+
+  # Append a required-field marker to a label.
+  #
+  # @param label [String] The label text.
+  # @param mark_required [Boolean] Whether to append the marker.
+  # @param hidden_label [String] The screen-reader-only text describing why the marker is present.
+  # @return [String] The label, marked as required if requested.
+  def mark_label_required(label:, mark_required: false, hidden_label: 'required')
+    label.to_s.dup.tap do |label_text|
+      if mark_required
+        label_text << "&nbsp;<span class=\"required\">*</span><span class=\"visually-hidden\"> (#{hidden_label})</span>".html_safe # rubocop:disable Rails/OutputSafety, Layout/LineLength
+      end
+    end.html_safe # rubocop:disable Rails/OutputSafety
+  end
 end

data/app/components/sdr_view_components/elements/heading_component.rb

@@ -4,13 +4,14 @@ module SdrViewComponents
   module Elements
     # Applies an h# component with the expected styling.
     class HeadingComponent < BaseComponent
-      def initialize(level:, text: nil, variant: nil, classes: [])
+      def initialize(level:, text: nil, variant: nil, classes: [], **options)
         raise ArgumentError, 'Invalid level' unless %i[h1 h2 h3 h4 h5 h6].include?(level.to_sym)
 
         @level = level
         @variant = variant
         @classes = classes
         @text = text # Provide text or content
+        @options = options
         super()
       end
 
@@ -22,7 +23,7 @@ module SdrViewComponents
       def call
         return unless tag.respond_to?(@level)
 
-        tag.public_send(@level, class: classes) do
+        tag.public_send(@level, class: classes, **@options) do
           @text || content
         end
       end

data/app/components/sdr_view_components/elements/tabs/tab_list_component.html.erb

@@ -1,9 +1,21 @@
-<%= tag.ul class: classes, role: 'tablist' do %>
-  <% tabs.each do |tab| %><%= tab %><% end %>
+<% if collapse_below? %>
+  <div data-controller="sdr-tab-select" data-action="shown.bs.tab->sdr-tab-select#sync">
+    <%= tag.select class: select_classes, 'aria-label': 'Select a tab', data: { sdr_tab_select_target: 'select', action: 'sdr-tab-select#change' } do %>
+      <% tabs.each do |tab| %><%= tag.option(tab.label, value: tab.id, selected: tab.active?) %><% end %>
+    <% end %>
+
+    <%= tag.ul class: classes, role: 'tablist' do %>
+      <% tabs.each do |tab| %><%= tab %><% end %>
+    <% end %>
+  </div>
+<% else %>
+  <%= tag.ul class: classes, role: 'tablist' do %>
+    <% tabs.each do |tab| %><%= tab %><% end %>
+  <% end %>
 <% end %>
 
 <%= header %>
 
-<div class="tab-content">
+<%= tag.div class: content_classes do %>
   <% panes.each do |pane| %><%= pane %><% end %>
-</div>
+<% end %>

data/app/components/sdr_view_components/elements/tabs/tab_list_component.rb

@@ -5,21 +5,48 @@ module SdrViewComponents
     module Tabs
       # Component for rendering a list of tabs in a tabbed interface.
       class TabListComponent < BaseComponent
+        BREAKPOINTS = %i[sm md lg xl xxl].freeze
+
         renders_one :header # optional
         renders_many :tabs, Elements::Tabs::TabComponent
         renders_many :panes, Elements::Tabs::PaneComponent
 
-        def initialize(classes: [], variant: :default)
+        # @param classes [Array<String>, String] additional classes for the tab list.
+        # @param content_classes [Array<String>, String] additional classes for the tab content container.
+        # @param variant [Symbol] the visual style of the tabs (:default or :underline).
+        # @param collapse_below [Symbol, nil] if given, the tabs are replaced with a `<select>`
+        #   below this Bootstrap breakpoint (one of :sm, :md, :lg, :xl, :xxl). The tabs remain
+        #   fully functional (the `<select>` drives the same Bootstrap tab JavaScript) -- this
+        #   only changes how they're presented at narrow viewports. Leave nil (the default) to
+        #   always render the tabs.
+        def initialize(classes: [], content_classes: [], variant: :default, collapse_below: nil)
           @classes = classes
+          @content_classes = content_classes
           @variant = variant
+          @collapse_below = collapse_below
 
           raise ArgumentError, "Invalid variant: #{variant}" unless %i[underline default].include?(variant)
+          if collapse_below && BREAKPOINTS.exclude?(collapse_below)
+            raise ArgumentError, "Invalid collapse_below: #{collapse_below}"
+          end
 
           super()
         end
 
+        def collapse_below?
+          @collapse_below.present?
+        end
+
         def classes
-          merge_classes('nav', @classes, variant_classes)
+          merge_classes('nav', @classes, variant_classes, collapse_below? ? ['d-none', "d-#{@collapse_below}-flex"] : nil)
+        end
+
+        def select_classes
+          merge_classes('form-select', "d-#{@collapse_below}-none", @classes)
+        end
+
+        def content_classes
+          merge_classes('tab-content', @content_classes)
         end
 
         private

data/app/components/sdr_view_components/forms/label_component.rb

@@ -5,7 +5,7 @@ module SdrViewComponents
     # Component for rendering a form label.
     class LabelComponent < BaseComponent
       def initialize(form:, field_name:, text: nil, default_class: 'form-label', hidden: false, # rubocop:disable Metrics/ParameterLists
-                     classes: [], tooltip: nil, caption: nil)
+                     classes: [], tooltip: nil, caption: nil, mark_required: false)
         @form = form
         @text = text
         @field_name = field_name
@@ -14,15 +14,14 @@ module SdrViewComponents
         @classes = classes
         @tooltip = tooltip
         @caption = caption
+        @mark_required = mark_required
         super()
       end
 
-      attr_reader :field_name, :form, :tooltip, :caption
+      attr_reader :field_name, :form, :tooltip, :caption, :mark_required
 
       def text
-        return field_name if @text.blank?
-
-        @text
+        mark_label_required(label: @text.presence || field_name, mark_required:)
       end
 
       def classes

data/app/components/sdr_view_components/tab_form/hidden_fields_form_component.html.erb

@@ -0,0 +1,5 @@
+<%= form_with(model:, id:, url:, html: { novalidate: true }) do |form| %>
+  <% hidden_fields.each do |field| %>
+    <%= form.hidden_field field %>
+  <% end %>
+<% end %>

data/app/components/sdr_view_components/tab_form/hidden_fields_form_component.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module SdrViewComponents
+  module TabForm
+    # Renders the one real <form> tag backing a TabListComponent-based tabbed form.
+    # Contains only hidden fields -- the tabbed form's visible fields associate with this
+    # form via the `form` HTML attribute (see TabbedFormBuilder), not DOM nesting.
+    #
+    # `url:` is optional and only needed when the model can't derive its own submission url
+    # (e.g. it has no resourceful routes).
+    class HiddenFieldsFormComponent < BaseComponent
+      def initialize(model:, id:, hidden_fields: [], url: nil)
+        @model = model
+        @id = id
+        @hidden_fields = hidden_fields
+        @url = url
+        super()
+      end
+
+      attr_reader :model, :id, :hidden_fields, :url
+    end
+  end
+end

data/app/components/sdr_view_components/tab_form/pane_component.html.erb

@@ -0,0 +1,16 @@
+<%= tag.div(id:, class: classes, role: 'tabpanel', 'aria-labelledby': tab_id, tabindex: '0', data: { sdr_tab_error_target: 'pane' }) do %>
+  <div class="d-flex flex-column justify-content-between h-100">
+    <div>
+      <% if label || help_text || help? %>
+        <%= tag.div(class: pane_header_class) do %>
+          <% if label %><h2 class="tooltip-header"><%= label %></h2><% end %>
+          <%= render SdrViewComponents::Elements::TooltipComponent.new(target_label: label, tooltip:) %>
+          <% if help_text %><p class="mb-0"><%= help_text || help %></p><% end %>
+          <%= help if help? %>
+        <% end %>
+      <% end %>
+      <%= content %>
+    </div>
+    <%= footer %>
+  </div>
+<% end %>

data/app/components/sdr_view_components/tab_form/pane_component.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module SdrViewComponents
+  module TabForm
+    # Component for a tab pane in a SdrViewComponents::TabForm::TabListComponent.
+    # Based on https://getbootstrap.com/docs/5.3/components/navs-tabs/#javascript-behavior
+    class PaneComponent < BaseComponent
+      renders_one :footer
+      renders_one :help
+
+      attr_accessor :active_tab_name
+
+      def initialize(tab_name:, label: nil, help_text: nil, tooltip: nil, pane_header_class: 'pane-header', # rubocop:disable Metrics/ParameterLists
+                     mark_required: false)
+        @tab_name = tab_name
+        @label = label
+        @help_text = help_text
+        @tooltip = tooltip
+        @pane_header_class = pane_header_class
+        @mark_required = mark_required
+        super()
+      end
+
+      attr_reader :tab_name, :help_text, :tooltip, :pane_header_class
+
+      def selected?
+        tab_name == active_tab_name
+      end
+
+      def mark_required?
+        @mark_required
+      end
+
+      def label
+        return unless @label
+
+        mark_label_required(label: @label, mark_required: mark_required?)
+      end
+
+      def classes
+        merge_classes(%w[tab-pane fade h-100], selected? ? 'show active' : nil)
+      end
+
+      def id
+        "#{tab_name}-pane"
+      end
+
+      def tab_id
+        "#{tab_name}-tab"
+      end
+    end
+  end
+end

data/app/components/sdr_view_components/tab_form/tab_component.html.erb

@@ -0,0 +1,14 @@
+<%= tag.button(
+      class: classes,
+      id:,
+      data:,
+      type: 'button',
+      'aria-controls': pane_id,
+      'aria-selected': selected?,
+      'aria-labelledby': id,
+      'aria-role': 'tab',
+      tabindex: '0',
+      role: 'tab'
+    ) do %>
+  <%= tag.span(label) %>
+<% end %>

data/app/components/sdr_view_components/tab_form/tab_component.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module SdrViewComponents
+  module TabForm
+    # Component for a tab in a SdrViewComponents::TabForm::TabListComponent.
+    class TabComponent < BaseComponent
+      attr_accessor :active_tab_name
+
+      def initialize(label:, tab_name:, mark_required: false, data: {})
+        @label = label
+        @tab_name = tab_name
+        @mark_required = mark_required
+        @data = data
+        super()
+      end
+
+      attr_reader :tab_name
+
+      def selected?
+        tab_name == active_tab_name
+      end
+
+      def classes
+        merge_classes('nav-link w-100', selected? ? 'active' : nil)
+      end
+
+      def id
+        "#{tab_name}-tab"
+      end
+
+      def pane_id
+        "#{tab_name}-pane"
+      end
+
+      def mark_required?
+        @mark_required
+      end
+
+      def label
+        mark_label_required(label: @label, mark_required: mark_required?, hidden_label: 'contains required fields')
+      end
+
+      # Callers can pass their own `data:` (e.g. an `action:` to wire up other Stimulus controllers);
+      # it's merged with the data this component needs to function as a Bootstrap tab wired to
+      # TabListComponent's sdr-tab-error controller.
+      def data
+        { bs_toggle: 'tab', bs_target: "##{pane_id}", sdr_tab_error_target: 'tab' }.merge(@data)
+      end
+    end
+  end
+end

data/app/components/sdr_view_components/tab_form/tab_list_component.html.erb

@@ -0,0 +1,20 @@
+<%= tag.div class: classes, data: do %>
+  <div class="col-md-3">
+    <%= tag.div class: 'nav nav-pills d-flex flex-column rounded-top rounded-bottom', role: 'tablist navigation', 'aria-orientation': 'vertical', tabindex: '0' do %>
+      <% tabs.each do |tab| %>
+        <% tab.active_tab_name = active_tab_name %>
+        <%= tab %>
+      <% end %>
+    <% end %>
+    <span class="required mt-2">* Required</span>
+  </div>
+  <div class="col-md-9">
+    <div class="tab-content h-100">
+      <% panes.each do |pane| %>
+        <% pane.active_tab_name = active_tab_name if pane.respond_to?(:active_tab_name=) %>
+        <%= pane %>
+      <% end %>
+    </div>
+  </div>
+  <span id="<%= invalid_description_id %>" class="visually-hidden" data-sdr-tab-error-target="invalidDescription">Error: required fields missing</span>
+<% end %>

data/app/components/sdr_view_components/tab_form/tab_list_component.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module SdrViewComponents
+  module TabForm
+    # Component for rendering tabbed navigation for a form.
+    #
+    # TabListComponent doesn't render a <form> tag itself -- the real <form> is rendered
+    # separately (see HiddenFieldsFormComponent), and the panes' fields are associated with it
+    # via the HTML `form` attribute (see TabbedFormBuilder) rather than DOM nesting, since panes
+    # aren't necessarily inside the <form>.
+    #
+    # Panes can be any renderable object; if it responds to `active_tab_name=`, that's set for you
+    # before rendering, so panes don't have to be passed `active_tab_name` at construction.
+    class TabListComponent < BaseComponent
+      renders_many :tabs, SdrViewComponents::TabForm::TabComponent
+      renders_many :panes, ->(pane) { pane }
+
+      def initialize(id:, active_tab_name:, classes: [], data: {})
+        @id = id
+        @active_tab_name = active_tab_name
+        @classes = classes
+        @data = data
+        super()
+      end
+
+      attr_reader :id, :active_tab_name
+
+      def classes
+        # Provides tab-error, tab-form as the static default classes
+        # merged with any additional classes passed in.
+        merge_classes(%w[tab-error row tab-form gx-4 gy-4 mb-5], @classes)
+      end
+
+      # `change` events fired by fields anywhere in the panes bubble up to this
+      # component's root element (fields are associated with the real form via the
+      # `form` attribute, not DOM nesting, so actions can't live on the `<form>` tag itself).
+      def data
+        @data.merge(controller: 'sdr-tab-error')
+      end
+
+      def invalid_description_id
+        "#{id}-invalid-description"
+      end
+    end
+  end
+end

data/app/components/sdr_view_components/tab_form/tabbed_form_builder.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module SdrViewComponents
+  module TabForm
+    # A FormBuilder for use with SdrViewComponents::TabForm::TabListComponent-based forms.
+    #
+    # TabListComponent doesn't render a <form> tag itself -- the real <form> is rendered
+    # separately by the caller (see HiddenFieldsFormComponent), and fields are associated with it
+    # via the HTML `form` attribute rather than DOM nesting (since panes aren't necessarily inside
+    # the <form>). This builder automatically sets that `form` attribute on every field it builds,
+    # so callers don't need to pass `form: form_id` explicitly at every call site.
+    #
+    # It also makes `id` (used above to derive the `form` attribute) available on builders
+    # created via `fields_for`, by falling back to the parent builder's `id`. Rails' `fields_for`
+    # doesn't otherwise propagate the `html: { id: }` option to nested builders.
+    class TabbedFormBuilder < ActionView::Helpers::FormBuilder
+      FIELD_METHODS = %i[text_field email_field textarea text_area hidden_field file_field radio_button checkbox
+                         date_field].freeze
+
+      FIELD_METHODS.each do |field_method|
+        define_method(field_method) do |*args, &block|
+          # These methods take a plain trailing options Hash (not real keyword arguments), and
+          # callers pass it either as `key: value` pairs or as a literal Hash -- both arrive here
+          # as a positional Hash, so it has to be merged in place rather than via **kwargs.
+          args << {} unless args.last.is_a?(Hash)
+          args[-1] = { form: id }.merge(args.last)
+          super(*args, &block)
+        end
+      end
+
+      def select(method, choices = nil, options = {}, html_options = {}, &)
+        html_options[:form] ||= id
+        super
+      end
+
+      def id
+        super || options[:parent_builder]&.id
+      end
+    end
+  end
+end

data/app/javascript/sdr_view_components/tab_error_controller.js

@@ -0,0 +1,81 @@
+import { Controller } from '@hotwired/stimulus'
+import * as bootstrap from 'bootstrap'
+
+export default class extends Controller {
+  static targets = ['tab', 'pane', 'invalidDescription']
+
+  connect () {
+    // For each tab / pane pair, check if the pane contains an invalid input.
+    // If it does, add the is-invalid class to the tab and modify the tab's
+    // accessible label to include the error message.
+    this.tabTargets.forEach((tabEl, index) => {
+      const paneElement = this.paneTargets[index]
+      const invalidElements = paneElement.querySelectorAll('.is-invalid')
+      if (invalidElements.length > 0) {
+        tabEl.classList.add('is-invalid')
+        const currentLabelledBy = tabEl.getAttribute('aria-labelledby')
+        const newLabelledBy = `${currentLabelledBy} ${this.invalidDescriptionTarget.id}`
+        tabEl.setAttribute('aria-labelledby', newLabelledBy)
+      }
+    })
+
+    // Show the first tab that has an invalid input.
+    const firstErrorTabEl = this.tabTargets.find(tabEl => tabEl.classList.contains('is-invalid'))
+    if (firstErrorTabEl) {
+      bootstrap.Tab.getOrCreateInstance(firstErrorTabEl).show() // eslint-disable-line no-undef
+    }
+  }
+
+  changed (event) {
+    const target = event.target
+    if (!target.classList.contains('is-invalid')) return
+    const paneElement = target.closest('.tab-pane')
+    // Mark the invalid target that was changed as no longer invalid, *and* mark any other invalid field
+    // with the same ID as no longer invalid. We think this is both harmless and it marks as valid the
+    // first name and last name fields in the contributor form, which are duplicated due to their being
+    // names in both the ORCID section and the non-ORCID section.
+    const invalidFieldElements = paneElement.querySelectorAll(`#${target.id}`)
+    if (invalidFieldElements) invalidFieldElements.forEach(element => element.classList.remove('is-invalid'))
+
+    // Remove the invalid feedback divs corresponding to invalid fields that are changed.
+    const invalidFeedbackElements = paneElement.querySelectorAll(`#${target.id}_error`)
+    if (invalidFeedbackElements) invalidFeedbackElements.forEach(element => element.remove())
+
+    // If the current pane no longer has fields marked as invalid, mark the tab as no longer
+    // being invalid.
+    const tabEl = this.tabElementFromId(paneElement.id.replace('-pane', ''))
+    if (!paneElement.querySelector('.is-invalid')) tabEl.classList.remove('is-invalid')
+  }
+
+  // Clear all invalid feedbacks on a pane and removes invalid from the tab.
+  clearInvalidStatus (paneAndTabId) {
+    const tabElement = this.tabElementFromId(paneAndTabId)
+    const paneElement = this.paneElementFromId(paneAndTabId)
+    const invalidElements = paneElement.querySelectorAll('.is-invalid')
+    if (invalidElements.length > 0) {
+      invalidElements.forEach(invalidElement => {
+        if (invalidElement.tagName === 'DIV') {
+          invalidElement.remove()
+        } else {
+          invalidElement.classList.remove('is-invalid')
+        }
+      })
+      tabElement.classList.remove('is-invalid')
+    }
+  }
+
+  updateTabInvalidStatus (paneAndTabId) {
+    const tabElement = this.tabElementFromId(paneAndTabId)
+    const paneElement = this.paneElementFromId(paneAndTabId)
+
+    if (!paneElement.querySelector('.is-invalid')) tabElement.classList.remove('is-invalid')
+  }
+
+  tabElementFromId (paneAndTabId) {
+    return this.tabTargets.find(tab => tab.id === `${paneAndTabId}-tab`)
+  }
+
+  paneElementFromId (paneAndTabId) {
+    return this.paneTargets.find(pane => pane.id === `${paneAndTabId}-pane`)
+  }
+}

data/app/javascript/sdr_view_components/tab_link_controller.js

@@ -0,0 +1,13 @@
+import { Controller } from '@hotwired/stimulus'
+import * as bootstrap from 'bootstrap'
+
+// Switches to a tab when the link is clicked.
+// Provide the #id of the tab to switch to in the href attribute of the link.
+export default class extends Controller {
+  show (event) {
+    event.preventDefault()
+
+    const tabAnchor = this.element.getAttribute('href')
+    bootstrap.Tab.getOrCreateInstance(tabAnchor).show() // eslint-disable-line no-undef
+  }
+}

data/app/javascript/sdr_view_components/tab_nav_controller.js

@@ -0,0 +1,24 @@
+import { Controller } from '@hotwired/stimulus'
+import * as bootstrap from 'bootstrap'
+
+export default class extends Controller {
+  static values = { tabId: String }
+
+  showNext (event) {
+    event.preventDefault()
+
+    const nextTab = this.currentTab.nextElementSibling
+    bootstrap.Tab.getOrCreateInstance(nextTab).show()
+  }
+
+  showPrevious (event) {
+    event.preventDefault()
+
+    const previousTab = this.currentTab.previousElementSibling
+    bootstrap.Tab.getOrCreateInstance(previousTab).show()
+  }
+
+  get currentTab () {
+    return document.querySelector(`#${this.tabIdValue}`)
+  }
+}

data/app/javascript/sdr_view_components/tab_select_controller.js

@@ -0,0 +1,22 @@
+import { Controller } from '@hotwired/stimulus'
+
+// Drives a <select> that stands in for a tab list on narrow viewports (see
+// TabListComponent's `collapse_below` option). Selecting an option shows the
+// corresponding tab; activating a tab some other way (e.g. clicking the tab
+// list above the collapse breakpoint) keeps the select's value in sync.
+//
+// Uses window.bootstrap rather than `import * as bootstrap from 'bootstrap'`:
+// the UMD bootstrap.bundle.min.js has no ES module exports, so an ESM import
+// of it resolves to an empty namespace object even though the script itself
+// still assigns the real API to window.bootstrap as a side effect.
+export default class extends Controller {
+  static targets = ['select']
+
+  change (event) {
+    window.bootstrap.Tab.getOrCreateInstance(document.getElementById(event.target.value)).show()
+  }
+
+  sync (event) {
+    this.selectTarget.value = event.target.id
+  }
+}

data/lib/sdr_view_components/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SdrViewComponents
-  VERSION = '0.4.2'
+  VERSION = '0.6.0'
 end

data/spec/components/previews/sdr_view_components/elements/button_link_component_preview.rb

@@ -33,6 +33,12 @@ module SdrViewComponents
         render SdrViewComponents::Elements::ButtonLinkComponent.new(link: '/example', label: 'Info Link Button',
                                                                     variant: :info)
       end
+
+      def nil
+        render SdrViewComponents::Elements::ButtonLinkComponent.new(link: '/example', label: 'Nil Variant Link Button',
+                                                                    variant: nil)
+      end
+
       # @!endgroup
 
       # @!group Button Sizes

data/spec/components/previews/sdr_view_components/elements/tabs/tab_list_component_preview/collapsible.html.erb

@@ -0,0 +1,14 @@
+<%# Resize the preview frame below the sm breakpoint to see the tabs collapse into a select. %>
+<%# The sdr-tab-select controller isn't registered in this dummy app, so the select won't switch panes here -- see the consuming app for a working example. %>
+<%= render SdrViewComponents::Elements::Tabs::TabListComponent.new(variant: :underline, collapse_below: :sm) do |tab_list| %>
+  <% tab_list.with_tab(label: 'Details', id: 'details-tab', pane_id: 'details-pane', active: true) %>
+  <% tab_list.with_tab(label: 'History', id: 'history-tab', pane_id: 'history-pane') %>
+
+  <% tab_list.with_pane(id: 'details-pane', tab_id: 'details-tab', active: true) do %>
+    <p>Details pane content.</p>
+  <% end %>
+
+  <% tab_list.with_pane(id: 'history-pane', tab_id: 'history-tab') do %>
+    <p>History pane content.</p>
+  <% end %>
+<% end %>

data/spec/components/previews/sdr_view_components/elements/tabs/tab_list_component_preview.rb

@@ -10,6 +10,8 @@ module SdrViewComponents
         # @!endgroup
 
         def with_header; end
+
+        def collapsible; end
       end
     end
   end

data/spec/components/previews/sdr_view_components/forms/label_component_preview/mark_required.html.erb

@@ -0,0 +1,8 @@
+<%= form_with(url: '/example', scope: :item) do |form| %>
+  <%= render SdrViewComponents::Forms::LabelComponent.new(
+        form: form,
+        field_name: :title,
+        text: 'Collection title',
+        mark_required: true
+      ) %>
+<% end %>

data/spec/components/previews/sdr_view_components/forms/label_component_preview.rb

@@ -11,6 +11,8 @@ module SdrViewComponents
       def with_tooltip; end
 
       def with_caption; end
+
+      def mark_required; end
       # @!endgroup
     end
   end

data/spec/components/previews/sdr_view_components/tab_form/tab_list_component_preview/default.html.erb

@@ -0,0 +1,25 @@
+<% model = SdrViewComponents::TabForm::TabListComponentPreview::TabFormPreviewModel.new(title: 'Project overview') %>
+
+<%# The real <form> -- only holds hidden fields. Visible fields below associate with it via %>
+<%# the `form` HTML attribute (see TabbedFormBuilder), not DOM nesting. %>
+<%= render SdrViewComponents::TabForm::HiddenFieldsFormComponent.new(model:, id: 'preview-tabbed-form', url: '/example') %>
+
+<%= render SdrViewComponents::TabForm::TabListComponent.new(id: 'preview-tabbed-form', active_tab_name: :details) do |tab_list| %>
+  <% tab_list.with_tab(label: 'Details', tab_name: :details, mark_required: true) %>
+  <% tab_list.with_tab(label: 'Notes', tab_name: :notes) %>
+
+  <%# This builder is used only to render pane content; TabListComponent won't render this as a %>
+  <%# form. TabbedFormBuilder sets the `form` attribute on the fields it builds to the real %>
+  <%# form's id, so they submit correctly even though they aren't nested inside it. %>
+  <% form_with(model:, html: { id: 'preview-tabbed-form' }, url: '/example', builder: SdrViewComponents::TabForm::TabbedFormBuilder) do |form| %>
+    <% details_pane = SdrViewComponents::TabForm::PaneComponent.new(tab_name: :details, label: 'Details', help_text: 'The essentials.') %>
+    <% tab_list.with_pane(details_pane) do %>
+      <%= render SdrViewComponents::Forms::TextFieldComponent.new(form:, field_name: :title) %>
+    <% end %>
+
+    <% notes_pane = SdrViewComponents::TabForm::PaneComponent.new(tab_name: :notes, label: 'Notes') %>
+    <% tab_list.with_pane(notes_pane) do %>
+      <%= render SdrViewComponents::Forms::TextAreaComponent.new(form:, field_name: :notes) %>
+    <% end %>
+  <% end %>
+<% end %>

data/spec/components/previews/sdr_view_components/tab_form/tab_list_component_preview.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module SdrViewComponents
+  module TabForm
+    class TabListComponentPreview < ViewComponent::Preview
+      def default; end
+
+      class TabFormPreviewModel
+        include ActiveModel::Model
+        include ActiveModel::Attributes
+
+        attribute :title, :string, default: nil
+        attribute :notes, :string, default: nil
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: sdr_view_components
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.6.0
 platform: ruby
 authors:
 - Aaron Collier
@@ -146,6 +146,15 @@ files:
 - app/components/sdr_view_components/structure/style_override_dark_component.rb
 - app/components/sdr_view_components/structure/style_override_light_component.html.erb
 - app/components/sdr_view_components/structure/style_override_light_component.rb
+- app/components/sdr_view_components/tab_form/hidden_fields_form_component.html.erb
+- app/components/sdr_view_components/tab_form/hidden_fields_form_component.rb
+- app/components/sdr_view_components/tab_form/pane_component.html.erb
+- app/components/sdr_view_components/tab_form/pane_component.rb
+- app/components/sdr_view_components/tab_form/tab_component.html.erb
+- app/components/sdr_view_components/tab_form/tab_component.rb
+- app/components/sdr_view_components/tab_form/tab_list_component.html.erb
+- app/components/sdr_view_components/tab_form/tab_list_component.rb
+- app/components/sdr_view_components/tab_form/tabbed_form_builder.rb
 - app/components/sdr_view_components/tables/base_table_component.html.erb
 - app/components/sdr_view_components/tables/base_table_component.rb
 - app/components/sdr_view_components/tables/cell_component.html.erb
@@ -158,6 +167,10 @@ files:
 - app/components/sdr_view_components/tables/row_component.html.erb
 - app/components/sdr_view_components/tables/row_component.rb
 - app/components/sdr_view_components/tables/table_component.rb
+- app/javascript/sdr_view_components/tab_error_controller.js
+- app/javascript/sdr_view_components/tab_link_controller.js
+- app/javascript/sdr_view_components/tab_nav_controller.js
+- app/javascript/sdr_view_components/tab_select_controller.js
 - app/javascript/sdr_view_components/toast_controller.js
 - app/views/layouts/lookbook.html.erb
 - config/routes.rb
@@ -187,6 +200,7 @@ files:
 - spec/components/previews/sdr_view_components/elements/progress_bar_component_preview.rb
 - spec/components/previews/sdr_view_components/elements/spinner_component_preview.rb
 - spec/components/previews/sdr_view_components/elements/tabs/tab_list_component_preview.rb
+- spec/components/previews/sdr_view_components/elements/tabs/tab_list_component_preview/collapsible.html.erb
 - spec/components/previews/sdr_view_components/elements/tabs/tab_list_component_preview/default_variant.html.erb
 - spec/components/previews/sdr_view_components/elements/tabs/tab_list_component_preview/underline_variant.html.erb
 - spec/components/previews/sdr_view_components/elements/tabs/tab_list_component_preview/with_header.html.erb
@@ -242,6 +256,7 @@ files:
 - spec/components/previews/sdr_view_components/forms/label_component_preview.rb
 - spec/components/previews/sdr_view_components/forms/label_component_preview/default.html.erb
 - spec/components/previews/sdr_view_components/forms/label_component_preview/hidden_label.html.erb
+- spec/components/previews/sdr_view_components/forms/label_component_preview/mark_required.html.erb
 - spec/components/previews/sdr_view_components/forms/label_component_preview/with_caption.html.erb
 - spec/components/previews/sdr_view_components/forms/label_component_preview/with_tooltip.html.erb
 - spec/components/previews/sdr_view_components/forms/radio_button_component_preview.rb
@@ -298,6 +313,8 @@ files:
 - spec/components/previews/sdr_view_components/structure/header_component_preview/light_variant.html.erb
 - spec/components/previews/sdr_view_components/structure/header_component_preview/no_rosette.html.erb
 - spec/components/previews/sdr_view_components/structure/header_component_preview/white_variant.html.erb
+- spec/components/previews/sdr_view_components/tab_form/tab_list_component_preview.rb
+- spec/components/previews/sdr_view_components/tab_form/tab_list_component_preview/default.html.erb
 - spec/components/previews/sdr_view_components/tables/cell_component_preview.rb
 - spec/components/previews/sdr_view_components/tables/cell_component_preview/default.html.erb
 - spec/components/previews/sdr_view_components/tables/cell_component_preview/with_colspan.html.erb