atomic_view 0.1.18 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bf51382f0171a3bef2e79ae3229c2de7838e4b69d01fa8ea7ec8cc3ba0d0cde6
-  data.tar.gz: 0a990c04df1c8cfc688b66c0c4d2805c54e5af984ca4e81942f1225952c15841
+  metadata.gz: 2cfa124ea9d90829cb7c8879e99d63b4c0e5587f4ee294ca19557f9dc0b92699
+  data.tar.gz: 972a88497711cd0d4c1f9e323346886b9eed136c350120ab0e6adfbb62764f25
 SHA512:
-  metadata.gz: d5f777b44351f97e414c6f157389fd3fc00e360e08dbb40dff71e3f4251d60341e4ed0c6ad5479d38a207bc861261572ba0e53460239393ce707b238e5f762a2
-  data.tar.gz: 791368e6d9ee177cd2ee840697158a876062af1e44881ae505606c51c0b09286b04e627c980c5b7ef047ed9f76af7226c6b5636cc86c7c41a5358af08a608b23
+  metadata.gz: 3696f874e0d5e627a572be114d091a18d451427f9e980e79b8b9304a3965b0d5a11060d44b0f7a7711364553199127778dc86ffc8d86d45851a65184250861fb
+  data.tar.gz: db66b0814f6c2b03969d1d4f0b422f1494768d24699d308e522deefcd5a629e77bf4382263a573765188ead91c986e0618b52700c8ff897852852ae823578049

data/Rakefile

@@ -6,3 +6,5 @@ APP_RAKEFILE = File.expand_path('test/dummy/Rakefile', __dir__)
 load 'rails/tasks/engine.rake'
 
 require 'bundler/gem_tasks'
+
+task default: "app:test"

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

@@ -0,0 +1,199 @@
+import { Controller } from "@hotwired/stimulus"
+// `@hotwired/turbo-rails`'s own module re-exports the real Turbo namespace
+// under a *named* `Turbo` export (`export { Turbo }`, itself `* as Turbo
+// from "@hotwired/turbo"`) rather than being that namespace directly --
+// `import * as Turbo from "@hotwired/turbo-rails"` looks right but actually
+// gives back `{ Turbo: {...}, cable: {...} }`, one level too shallow.
+import { Turbo } from "@hotwired/turbo-rails"
+
+// Connects to data-controller="atomic-view--gantt"
+//
+// Handles the grid's horizontal (date) pagination:
+//
+//   - forward (scrolling right, more days ahead): an IntersectionObserver
+//     watches a trailing sentinel, rooted at this grid's own `scroller`
+//     target rather than the page viewport (a `loading="lazy"` frame only
+//     ever watches the page viewport, which is why the row axis --
+//     `GanttComponent#row_pagination_id` -- can use one but this can't).
+//   - backward (earlier days): a plain button the user clicks --
+//     `dateStartTrigger` -- not auto-loaded on scroll. An
+//     IntersectionObserver-driven backward sentinel sitting right at the
+//     scroll container's start is already within its own rootMargin the
+//     instant it's observed, before the user has done anything, and
+//     "wait for a gesture first" guards around that both have real gaps
+//     (a plain `scroll` listener never fires if the very first gesture
+//     *is* trying to scroll left from `scrollLeft: 0`, since the browser
+//     doesn't dispatch one when the position can't change; and gating the
+//     observer's own callback doesn't work either, since
+//     IntersectionObserver only calls back on a *change* in intersection
+//     state, so the one notification for an already-in-view target fires
+//     and gets dropped while gated, then never re-fires once ungated,
+//     since nothing about its geometry changed in between). A real click
+//     sidesteps all of that -- see `loadEarlierDates` below.
+//
+// Both directions share the same fetch/prepend-or-append/rebase mechanics;
+// see `GanttComponent`'s class docs for what each direction's stream
+// response is expected to contain.
+//
+// The forward sentinel and the backward trigger both carry their page URL
+// as a `data-*` attribute on themselves (rather than a Stimulus Value on
+// this controller's root) so a `turbo_stream.replace` of just that element
+// is enough to advance the cursor. `dateSentinelTargetConnected` re-observes
+// automatically whenever Turbo swaps the forward sentinel out for its
+// replacement -- no manual re-wiring needed after each page loads; the
+// backward trigger needs no such wiring at all, since its `data-action`
+// attribute is enough for Stimulus to bind the click handler to whatever
+// element currently has it, including a freshly-swapped-in replacement.
+export default class extends Controller {
+  static targets = ["scroller", "dates", "dateSentinel", "dateLoader", "dateStartTrigger", "dateStartLoader", "originAnchored"]
+  static values = {
+    dateRootMargin: { type: String, default: "0px 400px 0px 0px" },
+  }
+
+  // Target-connected callbacks (below) can fire for targets already present
+  // in the initial DOM *before* `connect()` runs -- Stimulus wires up
+  // existing targets as part of connecting the controller itself, and that
+  // includes invoking their connected callbacks, ahead of calling
+  // `connect()`. So the observer `dateSentinelTargetConnected` reaches for
+  // has to exist by `initialize()` (guaranteed to run first, exactly once),
+  // not `connect()` -- creating it there worked by coincidence whenever a
+  // sentinel was added later via Turbo Stream, and threw on the very first
+  // (already-in-the-DOM) sentinel otherwise.
+  initialize() {
+    this.dateForwardLoading = false
+    this.dateBackwardLoading = false
+    // Running total of pixel width ever prepended to the date header so far
+    // -- see `rebaseOriginAnchored` below.
+    this.prependedWidth = 0
+
+    this.dateForwardObserver = new IntersectionObserver(this.handleDateForwardIntersect, {
+      root: this.hasScrollerTarget ? this.scrollerTarget : null,
+      rootMargin: this.dateRootMarginValue,
+      threshold: 0,
+    })
+  }
+
+  disconnect() {
+    this.dateForwardObserver.disconnect()
+  }
+
+  dateSentinelTargetConnected(element) {
+    this.dateForwardObserver.observe(element)
+  }
+
+  dateSentinelTargetDisconnected(element) {
+    this.dateForwardObserver.unobserve(element)
+  }
+
+  handleDateForwardIntersect = (entries) => {
+    for (const entry of entries) {
+      if (entry.isIntersecting) this.loadMoreDates(entry.target)
+    }
+  }
+
+  async loadMoreDates(sentinel) {
+    const url = sentinel.dataset.nextPage
+    if (!url || this.dateForwardLoading) return
+
+    this.dateForwardLoading = true
+    this.toggleLoader(this.hasDateLoaderTarget ? this.dateLoaderTarget : null, true)
+
+    try {
+      await this.renderStream(url, "date columns")
+    } finally {
+      this.dateForwardLoading = false
+      this.toggleLoader(this.hasDateLoaderTarget ? this.dateLoaderTarget : null, false)
+    }
+  }
+
+  // Bound via `data-action="click->atomic-view--gantt#loadEarlierDates"` on
+  // the `dateStartTrigger` button -- see this class's docs for why backward
+  // pagination is a click rather than a scroll-triggered sentinel.
+  async loadEarlierDates(event) {
+    const trigger = event.currentTarget
+    const url = trigger.dataset.prevPage
+    if (!url || this.dateBackwardLoading) return
+
+    this.dateBackwardLoading = true
+    trigger.disabled = true
+    this.toggleLoader(this.hasDateStartLoaderTarget ? this.dateStartLoaderTarget : null, true)
+
+    const widthBefore = this.hasDatesTarget ? this.datesTarget.scrollWidth : 0
+    const anchoredBeforeRender = new Set(this.originAnchoredTargets)
+
+    try {
+      await this.renderStream(url, "earlier date columns")
+
+      // The prepended cells pushed everything else to the right by however
+      // much width they added -- without this, the user's viewport would
+      // stay anchored to the same *scroll offset*, which now points at
+      // different (newly-loaded) content instead of what they were just
+      // looking at.
+      if (this.hasDatesTarget && this.hasScrollerTarget) {
+        const addedWidth = this.datesTarget.scrollWidth - widthBefore
+        if (addedWidth > 0) {
+          this.scrollerTarget.scrollLeft += addedWidth
+          this.rebaseOriginAnchored(anchoredBeforeRender, addedWidth)
+        }
+      }
+    } finally {
+      this.dateBackwardLoading = false
+      // `trigger` may have just been replaced by the stream response (a new
+      // page's worth of `data-prev-page`) -- re-read the current element
+      // via the target rather than re-enabling the stale reference.
+      if (this.hasDateStartTriggerTarget) this.dateStartTriggerTarget.disabled = false
+      this.toggleLoader(this.hasDateStartLoaderTarget ? this.dateStartLoaderTarget : null, false)
+    }
+  }
+
+  // Prepending date-header cells shifts the header's own flow-based
+  // coordinate system right by `addedWidth` -- see `GanttComponent`'s class
+  // docs, "How the grid is laid out" -- without moving anything positioned
+  // in pixels from a fixed `origin:` instead (item bars, the today strip;
+  // anything carrying `data-atomic-view--gantt-target="originAnchored"`).
+  // Elements already on the page before this response need nudging right by
+  // that same `addedWidth` to stay under the header cell they belong to.
+  // Ones this response just backfilled (new bars for the newly-loaded date
+  // range) were positioned by the server against the *original* origin with
+  // no knowledge of drift accumulated by earlier backward loads on this
+  // page, so they need the full running total instead.
+  //
+  // NOTE: this only rebases bars/the today strip backfilled by *this* date
+  // axis. A row loaded afterward via `next_rows_path`, or a bar backfilled
+  // by a *forward* `next_dates_path` response, is rendered fresh from the
+  // same unshifted origin math and would need this same treatment to stay
+  // aligned once `prependedWidth` is nonzero -- not wired up, since neither
+  // path currently has a hook to apply it from.
+  rebaseOriginAnchored(anchoredBeforeRender, addedWidth) {
+    for (const el of this.originAnchoredTargets) {
+      const delta = anchoredBeforeRender.has(el) ? addedWidth : this.prependedWidth + addedWidth
+      const left = Number.parseFloat(el.style.left) || 0
+      el.style.left = `${left + delta}px`
+    }
+    this.prependedWidth += addedWidth
+  }
+
+  async renderStream(url, description) {
+    this.element.setAttribute("aria-busy", "true")
+
+    try {
+      const response = await fetch(url, {
+        headers: { Accept: "text/vnd.turbo-stream.html" },
+      })
+
+      if (response.ok) {
+        Turbo.renderStreamMessage(await response.text())
+      } else {
+        console.error(`atomic-view--gantt: failed to load more ${description} from ${url} (${response.status})`)
+      }
+    } catch (error) {
+      console.error(`atomic-view--gantt: network error loading more ${description}`, error)
+    } finally {
+      this.element.removeAttribute("aria-busy")
+    }
+  }
+
+  toggleLoader(loader, visible) {
+    if (loader) loader.hidden = !visible
+  }
+}

data/lib/atomic_view/components/datetime_select_component.rb

@@ -8,6 +8,17 @@ module AtomicView
       end
 
       def call
+        # `ViewComponent::Form::DatetimeSelectComponent#call` builds
+        # `ActionView::Helpers::Tags::DatetimeSelect` straight from
+        # `object_name`/`method_name` without `options[:object]`, so it
+        # resolves the bound object by looking up an `@<object_name>` ivar
+        # on the view context instead of using `form.object` -- outside a
+        # real `form_for`-rendered view that ivar doesn't exist, so Rails'
+        # `DateTimeSelector` silently falls back to `Time.current` instead
+        # of the model's actual value. Set it explicitly so the rendered
+        # selection always reflects the object, not the clock.
+        options[:object] = object
+
         content_tag(:div, super, class: "flex gap-2")
       end
     end

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

@@ -1,6 +1,13 @@
 <%= tag.div(**html_options, class: html_class, data: data_attributes) do %>
   <%= tag.div(class: trigger_class, data: trigger_data_attributes) do %>
-    <%= trigger %>
+    <% if trigger? %>
+      <%= trigger %>
+    <% elsif default_trigger? %>
+      <%= tag.button(type: "button", class: default_trigger_class, aria: {haspopup: "menu"}) do %>
+        <%= label %>
+        <%= icon("chevron-down", variant: :mini, options: {class: "size-4 shrink-0 text-muted-foreground"}) %>
+      <% end %>
+    <% end %>
   <% end %>
 
   <% if menu? %>

data/lib/atomic_view/components/dropdown_component.rb

@@ -24,8 +24,11 @@ module AtomicView
       renders_one :trigger
       renders_one :menu
 
-      def initialize(**options)
+      attr_reader :label
+
+      def initialize(label: nil, **options)
         super()
+        @label = label
         @options = options
       end
 
@@ -33,6 +36,23 @@ module AtomicView
         @options.except(:class, :data, :trigger_class)
       end
 
+      # True when no `trigger` slot was given but `label:` was -- the
+      # template falls back to rendering a button with `default_trigger_class`,
+      # styled to match `FieldChrome` (the same ring-based border/focus
+      # treatment as text fields and selects), instead of every consumer
+      # hand-rolling a `border border-border` button that looks subtly
+      # different from the rest of the form chrome.
+      def default_trigger?
+        !trigger? && label.present?
+      end
+
+      def default_trigger_class
+        "inline-flex h-8 items-center gap-1.5 rounded-btn border-0 px-3 text-sm font-medium shadow-xs ring-1 " \
+          "bg-transparent dark:bg-white/5 text-foreground ring-ring/10 dark:ring-white/10 hover:bg-offset " \
+          "focus:ring-focus-ring focus:border-ring/20 dark:focus:ring-focus-ring " \
+          "disabled:cursor-not-allowed disabled:bg-disabled disabled:text-disabled-foreground disabled:ring-disabled-ring"
+      end
+
       def html_class
         class_names("relative inline-block", @options[:class])
       end

data/lib/atomic_view/components/gantt_component/date_header_component.html.erb

@@ -0,0 +1,4 @@
+<%= tag.div(**html_options, class: html_class) do %>
+  <span><%= primary_label %></span>
+  <span class="text-[10px] font-medium uppercase tracking-wide text-muted-foreground/80"><%= secondary_label %></span>
+<% end %>

data/lib/atomic_view/components/gantt_component/date_header_component.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module AtomicView
+  module Components
+    class GanttComponent
+      # A single day column header cell within a `GanttComponent`'s
+      # `#{id}_dates` grid. Carries no width of its own -- the parent grid's
+      # `grid-auto-columns` (see `GanttComponent#column_grid_style`) sizes
+      # every cell uniformly, so appending/prepending one is nothing more
+      # than inserting a plain DOM node. Standalone (like `ItemComponent`,
+      # unlike `RowComponent`/its items) for the same reason `ItemComponent`
+      # is -- a `next_dates_path`/`prev_dates_path` Turbo Stream response has
+      # to `append`/`prepend` *new* header cells into `#{id}_dates` alongside
+      # the new bars it backfills into existing rows (see `GanttComponent`'s
+      # class docs, "Loading more days"), and it needs something it can
+      # render for just those new dates without re-rendering the whole grid.
+      #
+      #   render(AtomicView::Components::GanttComponent::DateHeaderComponent.new(date: new_date, today: Date.current))
+      class DateHeaderComponent < AtomicView::Component
+        attr_reader :date, :today
+
+        # @param date [Date] the day this column represents.
+        # @param today [Date, nil] highlights this cell when given and equal
+        #   to `date`.
+        def initialize(date:, today: nil, **options)
+          super()
+          @date = date
+          @today = today
+          @options = options
+        end
+
+        def html_options
+          @options.except(:class)
+        end
+
+        def html_class
+          class_names(base_classes, {"text-primary" => today?}, @options[:class])
+        end
+
+        def today?
+          today.present? && date.to_date == today.to_date
+        end
+
+        def primary_label
+          date.day.to_s
+        end
+
+        def secondary_label
+          date.strftime("%a")
+        end
+
+        private
+
+        def base_classes
+          "sticky top-0 z-10 flex flex-col items-center justify-center gap-0.5 border-b border-border bg-surface py-2 text-xs font-semibold text-muted-foreground"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,7 @@
+<%= content_tag(tag_name, **html_options, id: id, href: href, style: position_style, class: html_class, data: data_attributes) do %>
+  <% if content.present? %>
+    <%= content %>
+  <% else %>
+    <span class="sticky truncate" style="<%= label_style %>"><%= label %></span>
+  <% end %>
+<% end %>

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

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module AtomicView
+  module Components
+    class GanttComponent
+      # A single bar within a `GanttComponent::RowComponent`'s track,
+      # positioned by real date math rather than a column index -- see
+      # `GanttComponent`'s class docs for why. Rendered via
+      # `RowComponent#with_item`, or standalone (e.g. from a
+      # `next_dates_path` Turbo Stream response `append`ing a newly-loaded
+      # bar into an existing row's `RowComponent#track_id`) since it carries
+      # everything it needs -- including `origin:` -- to position itself with
+      # no help from its parent row.
+      #
+      #   row.with_item(starts_on: booking.starts_on, ends_on: booking.ends_on, origin: @origin, label: booking.camper_name, variant: :success)
+      #
+      #   row.with_item(starts_on: booking.starts_on, ends_on: booking.ends_on, origin: @origin, variant: :outline) do
+      #     tag.span("Inquiry", class: "italic")
+      #   end
+      #
+      # `label:` renders as truncated text; pass a block instead for
+      # anything richer (an avatar, a badge) -- the block replaces `label:`
+      # entirely rather than appending to it.
+      #
+      # == Updating one bar in place
+      #
+      # Give it `id:` (e.g. `dom_id(booking, :bar)`) and it becomes a stable
+      # Turbo Stream target -- when a booking's status/dates/label change,
+      # `turbo_stream.replace(dom_id(booking, :bar), render(...))` swaps just
+      # that bar, no different from updating any other DOM-id'd partial. This
+      # is a plain, independent update -- no relation to the row/date
+      # pagination sentinels elsewhere in this component.
+      #
+      # == Overlapping bars in the same row
+      #
+      # Two items with overlapping `starts_on`..`ends_on` ranges need to
+      # render in separate horizontal "lanes" so they don't paint on top of
+      # each other -- `lane:` (a 0-based integer, default `0`) picks which
+      # one. Compute lane assignments for a row's items with
+      # `GanttComponent.pack_lanes`, then pass `lanes:` (the count) to the
+      # parent `RowComponent#with_row` so its track reserves enough height:
+      #
+      #   bookings = [overlapping_booking_a, overlapping_booking_b, later_booking]
+      #   lanes = AtomicView::Components::GanttComponent.pack_lanes(bookings.map { |b| [b.starts_on, b.ends_on] })
+      #
+      #   gantt.with_row(id: dom_id(site, :row), label: site.code, origin: @origin, lanes: lanes.max + 1) do |row|
+      #     bookings.zip(lanes).each { |booking, lane| row.with_item(starts_on: booking.starts_on, ends_on: booking.ends_on, origin: @origin, lane: lane, label: booking.camper_name) }
+      #   end
+      #
+      # Like `origin:`, a newly-appended bar (from a `next_dates_path`
+      # response) needs its `lane:` computed the same way, against every
+      # other item already in that row -- and if that pushes the row's lane
+      # count higher than what was initially rendered, the response should
+      # also `turbo_stream.replace` (or otherwise resize) the row's track to
+      # fit, since `RowComponent` only sizes itself once, from the `lanes:`
+      # it was given at render time.
+      class ItemComponent < AtomicView::Component
+        VARIANTS = %i[primary success warning destructive muted outline].freeze
+
+        attr_reader :id, :starts_on, :ends_on, :origin, :cell_width, :label_width, :lane, :label, :href, :variant
+
+        # @param id [String, nil] DOM id for this bar. Omit if you never need
+        #   to target it directly; give it one (e.g. `dom_id(booking, :bar)`)
+        #   to make it a stable Turbo Stream target for later in-place
+        #   updates -- see "Updating one bar in place" above.
+        # @param starts_on [Date] first day this bar covers.
+        # @param ends_on [Date] last day this bar covers (inclusive). Pass
+        #   the same value as `starts_on` for a single-day bar. There's no
+        #   "open-ended" concept here -- resolve an ongoing booking to a real
+        #   end date yourself (e.g. the last date currently loaded) before
+        #   calling this.
+        # @param origin [Date] must match the `origin:` every other row/item
+        #   in this grid uses -- the date that renders at pixel 0.
+        # @param cell_width [Integer] must match the parent `GanttComponent`'s.
+        # @param label_width [Integer] must match the parent `GanttComponent`'s
+        #   -- used only to keep the label clear of the sticky label column
+        #   when this bar's own true start is scrolled out of view (see
+        #   `label_style`).
+        # @param lane [Integer] which horizontal lane (0-based) this bar
+        #   renders in, for when it overlaps another item in the same row --
+        #   see "Overlapping bars in the same row" above. `0` (the default)
+        #   is fine for a row with no overlaps.
+        # @param label [String, nil] truncated text label; omit in favor of a
+        #   block for richer content.
+        # @param href [String, nil] wraps the bar in a link when given --
+        #   the whole bar becomes clickable, with a hover/focus treatment to
+        #   match.
+        # @param variant [Symbol] one of #{VARIANTS.join(", ")} -- maps onto
+        #   the gem's existing success/warning/destructive/muted tokens
+        #   rather than domain-specific statuses, so map your own status
+        #   values onto these however fits.
+        def initialize(starts_on:, ends_on:, origin:, id: nil, cell_width: GanttComponent::DEFAULT_CELL_WIDTH, label_width: GanttComponent::DEFAULT_LABEL_WIDTH, lane: 0, label: nil, href: nil, variant: :primary, **options)
+          super()
+          @id = id
+          @starts_on = starts_on
+          @ends_on = ends_on
+          @origin = origin
+          @cell_width = cell_width
+          @label_width = label_width
+          @lane = lane
+          @label = label
+          @href = href
+          @variant = variant.to_sym
+          @options = options
+        end
+
+        def html_options
+          @options.except(:class, :data)
+        end
+
+        # Marks this bar as a Turbo-target for the `atomic-view--gantt`
+        # Stimulus controller's backward-pagination rebasing -- see
+        # `GanttComponent`'s class docs, "How the grid is laid out": a bar's
+        # `left` is fixed in pixels against `origin:`, so unlike the flow-
+        # positioned date header cells above it, it needs nudging whenever a
+        # `prev_dates_path` response prepends earlier day columns ahead of
+        # it.
+        def data_attributes
+          (@options[:data] || {}).merge("atomic-view--gantt-target" => "originAnchored")
+        end
+
+        def position_style
+          left = GanttComponent.offset_px(starts_on, origin: origin, cell_width: cell_width)
+          width = GanttComponent.span_px(starts_on, ends_on, cell_width: cell_width)
+          top = GanttComponent::LANE_TOP_PADDING + (lane * GanttComponent::LANE_HEIGHT)
+          "left: #{left}px; width: #{width}px; top: #{top}px; height: #{GanttComponent::BAR_HEIGHT}px"
+        end
+
+        # `sticky`, so a bar starting well before the currently-loaded window
+        # -- rendered with a large negative `left` in `position_style` above,
+        # per "New rows outside the currently-loaded date window" in
+        # `GanttComponent`'s class docs -- keeps its label visible near
+        # whichever edge of the bar is currently on screen, instead of the
+        # label sitting at the bar's own (unreachably off-screen) true start.
+        # Offset past `label_width` so a stuck label never renders underneath
+        # the sticky row-label column.
+        #
+        # Only reachable in the plain `label:` path (see the template) --
+        # `position: sticky` computes relative to the *nearest* ancestor with
+        # non-visible `overflow`, so it only works here because that path
+        # skips `overflow_class` below; custom block content still gets
+        # wrapped in an `overflow-hidden` bar (needed to clip it to
+        # `rounded-btn`'s corners), which would silently break stickiness --
+        # its nearest non-visible-overflow ancestor would become the bar
+        # itself instead of the real scrolling container.
+        def label_style
+          "left: #{label_width + 8}px"
+        end
+
+        def html_class
+          class_names(base_classes, overflow_class, href.present? ? interactive_classes : nil, variant_classes, @options[:class])
+        end
+
+        def tag_name
+          href.present? ? :a : :div
+        end
+
+        private
+
+        # See `label_style` above for why this only applies when there's
+        # custom block content to clip -- the plain-label path needs to stay
+        # free of it for the sticky label to work.
+        def overflow_class
+          "overflow-hidden" if content.present?
+        end
+
+        def base_classes
+          "absolute z-[1] flex items-center rounded-btn px-2.5 text-xs font-semibold whitespace-nowrap"
+        end
+
+        def interactive_classes
+          "cursor-pointer transition-[filter] hover:brightness-95 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 focus-visible:ring-offset-surface"
+        end
+
+        def variant_classes
+          case variant
+          when :success
+            "bg-success text-success-foreground"
+          when :warning
+            "bg-warning text-warning-foreground"
+          when :destructive
+            "bg-destructive text-destructive-foreground line-through opacity-80"
+          when :muted
+            "bg-muted text-muted-foreground opacity-70"
+          when :outline
+            "border-2 border-dashed border-muted-foreground/40 bg-transparent text-muted-foreground"
+          else
+            "bg-primary text-primary-foreground"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/atomic_view/components/gantt_component/month_band_component.html.erb

@@ -0,0 +1,3 @@
+<%= tag.div(**html_options, id: id, style: style, class: html_class) do %>
+  <%= label %>
+<% end %>

data/lib/atomic_view/components/gantt_component/month_band_component.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module AtomicView
+  module Components
+    class GanttComponent
+      # One "September 2026"-style segment in the `GanttComponent`'s month
+      # band strip (see `GanttComponent#month_band_id`), above the
+      # day/weekday header row. `#{gantt_id}_month_band` is a single-row CSS
+      # Grid sharing the same `grid-auto-columns` as `#{gantt_id}_dates` (see
+      # `GanttComponent#column_grid_style`), so a segment carries no pixel
+      # width of its own -- just `grid-column: span #{span}`, `span` day-wide
+      # tracks stretched together automatically. That also means a segment
+      # never needs resizing once rendered: appending/prepending more days
+      # elsewhere in the same grid doesn't touch its track sizing, so it's
+      # exactly as correct after ten more `prepend`s as it was on the first
+      # render.
+      #
+      # `GanttComponent` renders one of these per distinct month present in
+      # `dates:` on the initial render (see `GanttComponent#month_segments`).
+      #
+      # == Loading more days
+      #
+      # A `next_dates_path`/`prev_dates_path` Turbo Stream response that
+      # `append`s/`prepend`s new `DateHeaderComponent` cells to
+      # `#{gantt_id}_dates` (see `GanttComponent`'s class docs) should do the
+      # same here, to `#{gantt_id}_month_band`. Simplest when each batch of
+      # newly-loaded dates is itself exactly one calendar month (see
+      # `RentalsController` in this gem's dummy app for a worked example) --
+      # then every response adds exactly one new segment, always with a real
+      # label, no chunking needed. A batch that can straddle a month
+      # boundary needs to chunk its own dates by month the same way
+      # `GanttComponent#month_segments` does, and skip the label (`label:
+      # nil`) on whichever chunk continues the month a previous segment
+      # already labeled.
+      #
+      # Order matters the same way it does for date cells: `append` new
+      # segments in chronological order; `prepend` them in *reverse*
+      # chronological order (latest chunk first), since each prepend pushes
+      # the previous one further right.
+      class MonthBandComponent < AtomicView::Component
+        attr_reader :id, :label, :span
+
+        # @param id [String, nil] DOM id for this segment.
+        # @param label [String, nil] the text to show, e.g. `"September 2026"`
+        #   -- `nil` renders a blank (unlabeled) segment, for a batch of
+        #   newly-loaded dates that continue a month whose label an earlier
+        #   segment already shows (see "Loading more days" above).
+        # @param span [Integer] how many day columns this segment covers --
+        #   becomes `grid-column: span #{span}`.
+        def initialize(span:, label: nil, id: nil, **options)
+          super()
+          @id = id
+          @label = label
+          @span = span
+          @options = options
+        end
+
+        def html_options
+          @options.except(:class)
+        end
+
+        def html_class
+          class_names(base_classes, @options[:class])
+        end
+
+        def style
+          "grid-column: span #{span}"
+        end
+
+        private
+
+        def base_classes
+          "flex items-center overflow-hidden whitespace-nowrap px-1.5 text-[10px] font-semibold uppercase tracking-wide text-muted-foreground"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,22 @@
+<%= tag.div(id: id, **html_options, class: html_class) do %>
+  <div class="sticky left-0 z-10 flex-none border-r border-b border-border bg-surface px-3 py-2" style="width: <%= label_width %>px">
+    <% if href.present? %>
+      <%= link_to label, href, class: "block truncate text-sm font-semibold text-foreground hover:underline" %>
+    <% else %>
+      <div class="truncate text-sm font-semibold text-foreground"><%= label %></div>
+    <% end %>
+    <% if sublabel.present? %>
+      <div class="truncate text-xs text-muted-foreground"><%= sublabel %></div>
+    <% end %>
+  </div>
+
+  <div id="<%= track_id %>" class="relative flex-1 border-b border-border" style="<%= track_style %>">
+    <% if today_offset_px %>
+      <div class="absolute inset-y-0 bg-primary/5" data-atomic-view--gantt-target="originAnchored" style="left: <%= today_offset_px %>px; width: <%= cell_width %>px"></div>
+    <% end %>
+
+    <% items.each do |item| %>
+      <%= item %>
+    <% end %>
+  </div>
+<% end %>