atomic_view 0.1.18 → 0.2.0

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

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module AtomicView
+  module Components
+    class GanttComponent
+      # A single resource row within a `GanttComponent` -- a label (e.g. a
+      # site code) plus a horizontally-scrolling track that its `ItemComponent`
+      # bars position themselves within. Rendered via `GanttComponent#with_row`
+      # -- see that class's docs for the full picture, including what
+      # `origin:` means and why it has to stay consistent across requests.
+      #
+      # `track_id` is the id a `next_dates_path`/`prev_dates_path` Turbo
+      # Stream response `append`s/`prepend`s new bars to once more date
+      # columns load -- this row's own markup doesn't otherwise get
+      # re-rendered when that happens.
+      class RowComponent < AtomicView::Component
+        renders_many :items, "AtomicView::Components::GanttComponent::ItemComponent"
+
+        attr_reader :id, :label, :sublabel, :href, :origin, :cell_width, :label_width, :lanes, :today
+
+        # @param id [String] unique DOM id for this row.
+        # @param label [String] primary label (e.g. a site code).
+        # @param sublabel [String, nil] secondary label under it (e.g. a park name).
+        # @param href [String, nil] wraps the label in a link when given.
+        # @param origin [Date] must match the `origin:` given to every
+        #   `ItemComponent` in this row (and every other row in this grid) --
+        #   used here only for the optional `today:` highlight strip.
+        # @param cell_width [Integer] must match the parent `GanttComponent`'s.
+        # @param label_width [Integer] must match the parent `GanttComponent`'s.
+        # @param lanes [Integer] how many horizontal lanes of overlapping
+        #   items this row's track should reserve height for -- `1` (the
+        #   default) fits a row with no overlaps. See
+        #   `ItemComponent#lane`/`GanttComponent.pack_lanes`.
+        # @param today [Date, nil] renders a highlighted strip at this date's
+        #   column, when given (typically threaded through from the parent
+        #   `GanttComponent#today`).
+        def initialize(
+          id:,
+          label:,
+          origin:,
+          sublabel: nil,
+          href: nil,
+          cell_width: GanttComponent::DEFAULT_CELL_WIDTH,
+          label_width: GanttComponent::DEFAULT_LABEL_WIDTH,
+          lanes: 1,
+          today: nil,
+          **options
+        )
+          super()
+          @id = id
+          @label = label
+          @sublabel = sublabel
+          @href = href
+          @origin = origin
+          @cell_width = cell_width
+          @label_width = label_width
+          @lanes = lanes
+          @today = today
+          @options = options
+        end
+
+        def track_id = "#{id}_track"
+
+        def html_options
+          @options.except(:class)
+        end
+
+        def html_class
+          class_names("flex", @options[:class])
+        end
+
+        def track_style
+          min_height = GanttComponent::LANE_TOP_PADDING * 2 + (lanes * GanttComponent::LANE_HEIGHT)
+          "background-image: repeating-linear-gradient(to right, var(--color-border) 0, var(--color-border) 1px, transparent 1px, transparent #{cell_width}px); min-height: #{min_height}px"
+        end
+
+        def today_offset_px
+          return nil unless today
+          GanttComponent.offset_px(today, origin: origin, cell_width: cell_width)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,76 @@
+<%= tag.div(id: id, **html_options, class: html_class, data: data_attributes) do %>
+  <% if paginated_dates_backward? %>
+    <div class="flex items-center border-b border-border px-3 py-1.5">
+      <button
+        type="button"
+        id="<%= date_start_trigger_id %>"
+        class="flex items-center gap-1.5 rounded-btn px-2 py-1 text-xs font-semibold text-muted-foreground transition-colors hover:bg-muted/60 hover:text-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring"
+        data-atomic-view--gantt-target="dateStartTrigger"
+        data-action="click->atomic-view--gantt#loadEarlierDates"
+        data-prev-page="<%= prev_dates_path %>"
+      >
+        <span id="<%= date_start_loader_id %>" class="size-3.5 flex-none animate-spin rounded-full border-2 border-border border-t-foreground motion-reduce:animate-none" data-atomic-view--gantt-target="dateStartLoader" hidden aria-hidden="true"></span>
+        Load earlier days
+      </button>
+    </div>
+  <% end %>
+
+  <div id="<%= scroller_id %>" class="overflow-x-auto" data-atomic-view--gantt-target="scroller">
+    <div class="w-max min-w-full">
+      <div class="flex">
+        <div class="sticky left-0 top-0 z-30 flex-none border-b border-r border-border bg-surface" style="width: <%= label_width %>px"></div>
+
+        <div class="flex flex-col">
+          <div id="<%= month_band_id %>" class="grid h-5 flex-none grid-flow-col border-b border-border/60 bg-surface" style="<%= column_grid_style %>">
+            <% month_segments.each do |segment| %>
+              <%= render(AtomicView::Components::GanttComponent::MonthBandComponent.new(
+                    id: "#{month_band_id}_#{segment[:month_start].strftime("%Y-%m")}",
+                    label: segment[:month_start].strftime("%B %Y"),
+                    span: segment[:count]
+                  )) %>
+            <% end %>
+          </div>
+
+          <div id="<%= dates_id %>" class="grid grid-flow-col" style="<%= column_grid_style %>" data-atomic-view--gantt-target="dates">
+            <% dates.each do |date| %>
+              <%= render(AtomicView::Components::GanttComponent::DateHeaderComponent.new(date: date, today: today)) %>
+            <% end %>
+          </div>
+        </div>
+
+        <div id="<%= date_loader_id %>" class="flex flex-none items-center justify-center px-3" data-atomic-view--gantt-target="dateLoader" hidden>
+          <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 days…</span>
+        </div>
+
+        <% if paginated_dates_forward? %>
+          <div
+            id="<%= date_sentinel_id %>"
+            class="w-px flex-none self-stretch"
+            data-atomic-view--gantt-target="dateSentinel"
+            data-next-page="<%= next_dates_path %>"
+          ></div>
+        <% end %>
+      </div>
+
+      <div id="<%= rows_id %>" class="flex flex-col">
+        <% rows.each do |row| %>
+          <%= row %>
+        <% end %>
+      </div>
+
+      <% if empty? %>
+        <p class="px-4 py-6 text-center text-sm text-muted-foreground"><%= empty_message %></p>
+      <% end %>
+    </div>
+  </div>
+
+  <% if paginated_rows? %>
+    <%= tag.turbo_frame(id: row_pagination_id, src: next_rows_path, loading: :lazy, class: "flex items-center justify-center gap-2 border-t border-border 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 rows…</span>
+    <% end %>
+  <% else %>
+    <%= tag.turbo_frame(id: row_pagination_id) %>
+  <% end %>
+<% end %>

data/lib/atomic_view/components/gantt_component.rb

@@ -0,0 +1,486 @@
+# frozen_string_literal: true
+
+module AtomicView
+  module Components
+    # Gantt
+    #
+    # A resource-scheduling grid -- rows are resources (sites, rooms, staff),
+    # columns are days, and each row's bookings render as bars positioned by
+    # real date math. Both axes load more data independently via Turbo, no
+    # full page reload:
+    #
+    #   render(GanttComponent.new(
+    #     id: "site-schedule",
+    #     dates: @dates,                    # Array<Date> currently loaded/visible
+    #     next_rows_path: @next_rows_path,  # more sites (down)
+    #     next_dates_path: @next_dates_path # more days (right)
+    #   )) do |gantt|
+    #     @sites.each do |site|
+    #       gantt.with_row(id: dom_id(site, :row), label: site.code, sublabel: site.park.name, origin: @origin) do |row|
+    #         site.bookings.each do |booking|
+    #           row.with_item(starts_on: booking.starts_on, ends_on: booking.ends_on, label: booking.camper_name, origin: @origin, variant: :success, href: booking_path(booking))
+    #         end
+    #       end
+    #     end
+    #   end
+    #
+    # Unlike `TimelineComponent` (a vertical activity feed, unrelated to this
+    # component despite the shared "timeline" vocabulary in casual use), a
+    # Gantt's date columns must line up across every row -- that's the whole
+    # point of the chart. So horizontal pagination here is *grid-wide*: one
+    # trigger loads more days for every row at once, rather than each row
+    # scrolling its own independent strip of items. See `RowComponent` and
+    # `ItemComponent` for the per-row/per-bar API.
+    #
+    # == How the grid is laid out
+    #
+    # The label column is `sticky left-0`; each row is a flex box of (label,
+    # track). Every row's track is `width: 100%` of a `width: max-content`
+    # inner wrapper shared with the date header -- so as the header grows
+    # (more date cells appended), every row's track grows with it
+    # automatically, via ordinary CSS reflow.
+    #
+    # The date header and month band are each a CSS Grid (`grid-auto-flow:
+    # column`, `grid-auto-columns: <cell_width>`) -- one declaration on the
+    # container sizes every column, so a `DateHeaderComponent` cell carries no
+    # width of its own, and a `MonthBandComponent` segment just declares
+    # `grid-column: span <day count>` rather than a computed pixel width. This
+    # is deliberately plain flow/grid layout, not client-side column
+    # bookkeeping: appending or prepending a cell is nothing more than
+    # inserting a DOM node, and the grid places it.
+    #
+    # Bars are the one thing that *can't* live on that grid -- a booking
+    # starting or ending mid-render isn't a concept here (every date is a
+    # whole day, and a bar always starts/ends on one), but a bar can still
+    # begin before the currently-loaded window, and grid line numbers aren't
+    # stable across a `prepend` the way real calendar dates are (see
+    # "`origin:` has to round-trip through every request" below). So bars
+    # stay `position: absolute` with inline `left`/`width` in pixels, computed
+    # from real dates (see `.offset_px`/`.span_px`) rather than a column
+    # index or grid line.
+    #
+    # == `origin:` has to round-trip through every request
+    #
+    # `RowComponent` and `ItemComponent` both take `origin:` -- the `Date`
+    # that renders at pixel 0 (the leftmost edge of the whole grid, not just
+    # the currently-loaded page of dates), and should be the same value as
+    # `dates.first` from the very first render. Every bar's position is
+    # computed relative to it. Pick it once and pass the *same* value on
+    # every request for this grid -- the initial render, every
+    # `next_rows_path` response, and every `next_dates_path` response --
+    # typically by round-tripping it through the pagination URLs as a param
+    # (see the worked example below). Getting this wrong doesn't break any
+    # single response in isolation; it just misaligns bars appended later
+    # against columns rendered earlier.
+    #
+    # A `prev_dates_path` response prepending earlier days shifts the date
+    # header's own grid (new columns land at its start, pushing the rest
+    # right) without moving any bar already positioned in pixels against the
+    # fixed `origin:` -- the `atomic-view--gantt` Stimulus controller
+    # compensates by nudging every already-rendered bar (and the today strip)
+    # right by however much width the header just grew by; see that
+    # controller's docs.
+    #
+    # == Wiring this up with real data (Pagy keyset + Turbo Streams)
+    #
+    # Rows don't need any special interface -- `with_row`/`with_item` just
+    # want plain values (a label, dates, a variant), so mapping from
+    # ActiveRecord is nothing more than the block above: call whatever
+    # reads naturally off your models. The only real design decision is
+    # pagination, and the two axes are different enough to solve
+    # differently:
+    #
+    # *Rows* are a normal, orderable AR relation -- exactly what Pagy's
+    # keyset extra is for (see `Pagy::Method`/`pagy(:keyset, ...)`). A
+    # worked example, keyset-paginating `Site`, following the same
+    # controller shape as an index action anywhere else in the app:
+    #
+    #   class RentalsController < ApplicationController
+    #     def index
+    #       @origin = parse_date(params[:origin]) || Date.current.beginning_of_month
+    #       @dates = (@origin...(@origin + 30)).to_a
+    #       @pagy, @sites = pagy(:keyset, Site.order(:prefix, :name, :id))
+    #
+    #       respond_to do |format|
+    #         format.html
+    #         format.turbo_stream # only reached by the row_pagination frame below
+    #       end
+    #     end
+    #   end
+    #
+    #   # index.html.erb
+    #   <%= render(AtomicView::Components::GanttComponent.new(
+    #         id: "site-schedule",
+    #         dates: @dates,
+    #         next_rows_path: (@pagy.next && rentals_path(page: @pagy.next, origin: @origin, format: :turbo_stream)),
+    #         next_dates_path: more_dates_path(origin: @origin, after: @dates.last)
+    #       )) do |gantt|
+    #     @sites.each { |site| render_site_row(gantt, site, @origin, @dates) }
+    #   end %>
+    #
+    #   # index.turbo_stream.erb -- reached when the row_pagination frame's
+    #   # lazily-loaded `src` fires (see "Loading more rows" below)
+    #   <%= turbo_stream.append("site-schedule_rows") do %>
+    #     <% @sites.each { |site| render_site_row(gantt, site, @origin, @dates) } %>
+    #   <% end %>
+    #   <%= turbo_stream.replace("site-schedule_row_pagination") do %>
+    #     <%= tag.turbo_frame(
+    #           id: "site-schedule_row_pagination",
+    #           src: (@pagy.next && rentals_path(page: @pagy.next, origin: @origin, format: :turbo_stream)),
+    #           loading: :lazy
+    #         ) %>
+    #   <% end %>
+    #
+    # `render_site_row` also has to decide *which* bookings to pass to
+    # `with_item` -- not every booking a site has, just the ones that fall
+    # anywhere within `@dates` (see "New rows outside the currently-loaded
+    # date window" below for why):
+    #
+    #   def render_site_row(gantt, site, origin, dates)
+    #     bookings = site.bookings.select { |b| GanttComponent.overlaps_range?(b.starts_on, b.ends_on, dates.first, dates.last) }
+    #     gantt.with_row(id: dom_id(site, :row), label: site.code, sublabel: site.park.name, origin: origin) do |row|
+    #       bookings.each { |b| row.with_item(starts_on: b.starts_on, ends_on: b.ends_on, label: b.camper_name, origin: origin, variant: :success, href: booking_path(b)) }
+    #     end
+    #   end
+    #
+    # *Dates* aren't an AR relation at all -- "the next 30 days" is just date
+    # arithmetic, so `next_dates_path` is simpler custom logic rather than
+    # Pagy: a `MoreDatesController` (or an action alongside the one above)
+    # that takes `after:` (the last date currently loaded) and `origin:`,
+    # computes the next batch of `Date`s, and returns a stream that appends
+    # both new date header cells *and* any new bars those dates bring into
+    # range -- neither one is optional, and this is genuinely two separate
+    # append operations, since the header cells and the bars live in
+    # different DOM containers (`#{id}_dates` vs. each row's own `track_id`):
+    #
+    #   class MoreDatesController < ApplicationController
+    #     def show
+    #       origin = parse_date(params[:origin])
+    #       after = parse_date(params[:after])
+    #       new_dates = next_batch_of_dates(after: after) # your own date-arithmetic helper
+    #       @sites = authorized(Site.all).order(:prefix, :name, :id) # the same rows currently on the page -- see below
+    #     end
+    #   end
+    #
+    #   # show.turbo_stream.erb
+    #   <% new_dates.each do |date| %>
+    #     <%= turbo_stream.append("site-schedule_dates") do %>
+    #       <%= render(AtomicView::Components::GanttComponent::DateHeaderComponent.new(date: date, today: Date.current)) %>
+    #     <% end %>
+    #   <% end %>
+    #
+    #   <% @sites.each do |site| %>
+    #     <% bookings = site.bookings.select { |b| AtomicView::Components::GanttComponent.overlaps_range?(b.starts_on, b.ends_on, new_dates.first, new_dates.last) } %>
+    #     <% bookings.each do |b| %>
+    #       <%= turbo_stream.append(dom_id(site, :row) + "_track") do %>
+    #         <%= render(AtomicView::Components::GanttComponent::ItemComponent.new(starts_on: b.starts_on, ends_on: b.ends_on, origin: origin, label: b.camper_name, variant: :success, href: booking_path(b))) %>
+    #       <% end %>
+    #     <% end %>
+    #   <% end %>
+    #
+    #   <%= turbo_stream.replace("site-schedule_date_sentinel") do %>
+    #     <div id="site-schedule_date_sentinel" data-atomic-view--gantt-target="dateSentinel" data-next-page="<%= more_dates_path(origin: origin, after: new_dates.last) %>"></div>
+    #   <% end %>
+    #
+    # That response needs to know which rows are currently rendered (to
+    # backfill *their* new bars, not just draw the header) -- either
+    # re-derive the same page of rows from `params[:page]`/keyset params
+    # round-tripped alongside `after:`, or (simpler, if the row page is
+    # small) have the client send the visible row ids and scope the query to
+    # just those. `prev_dates_path`'s response is the same shape with every
+    # `append` swapped for `prepend`, targeting `#{id}_date_start_trigger`
+    # instead.
+    #
+    # == New rows outside the currently-loaded date window
+    #
+    # A booking's bar always renders at its real, correctly-computed pixel
+    # position -- it is never clipped or hidden by this component. So a site
+    # loaded later (via `next_rows_path`) whose booking starts on day 90,
+    # when only 30 days are loaded, renders that bar 90 columns from
+    # `origin` regardless -- past the last date header cell, in the blank
+    # area where the track's gridline background stops (that background,
+    # like the header, only ever covers `dates`; it doesn't extend to meet
+    # an overflowing bar). It isn't lost: the browser's scroll region grows
+    # to include it (out-of-flow descendants still count toward their
+    # scrolling ancestor's scrollable area), so scrolling right reveals it
+    # sitting in that gap, and it "snaps" into a normal, gridded column the
+    # moment `next_dates_path` loads that far.
+    #
+    # That's a legitimate transient state, not a bug -- but there's rarely a
+    # reason to let it happen at all. Scope every row's bookings to ones
+    # that actually intersect `dates` (see `render_site_row` above,
+    # `.overlaps_range?`) before calling `with_item`, the same way you'd
+    # already scope any other index view's records to what's on the current
+    # page. A booking that starts beyond the loaded window simply isn't
+    # rendered yet; it appears exactly when `next_dates_path` reaches it,
+    # via that response's own "backfill every row's new bars" step (see
+    # "Loading more days" below) -- which is the same step responsible for
+    # backfilling it into *this* row once it exists, no special-casing
+    # needed for "a row that was loaded after the date window had already
+    # moved."
+    #
+    # A booking that starts *before* `origin` is the mirror case (e.g. an
+    # already-in-progress booking on the very first render) -- its bar's
+    # `left` is negative from the start, extending into scroll space that
+    # hasn't been unlocked by any `prev_dates_path` prepend yet. That's why
+    # `ItemComponent`'s label is `position: sticky` rather than flowing at
+    # the bar's own true start: without it, the label would sit somewhere
+    # the user can't scroll to (yet), rendering the bar with no visible text
+    # at all until they've scrolled back far enough to reach it.
+    #
+    # == Turbo Stream contract
+    #
+    # === Loading more rows
+    #
+    # `next_rows_path` is rendered as a lazily-loaded `<turbo-frame
+    # loading="lazy">` (`#{id}_row_pagination`, see `row_pagination_id`) --
+    # the same "infinite frame" pattern as any other keyset-paginated index
+    # page in a Turbo app: no custom JS, the frame's own `loading="lazy"`
+    # fetches `src` once it scrolls into the *page* viewport. That fetch's
+    # response is a turbo_stream (the frame's `src` should carry
+    # `format: :turbo_stream`, same as the example above) that:
+    #   1. `append`s new `RowComponent`s to `#{id}_rows`
+    #   2. `replace`s `#{id}_row_pagination` with an updated frame (new
+    #      `src`) to continue the chain, or an empty one (no `src`) when
+    #      there are no more rows
+    #
+    # === Loading more days, in either direction
+    #
+    # Both directions are handled by a small Stimulus controller
+    # (`atomic-view--gantt`), but deliberately *not* the same way:
+    #
+    #   - `next_dates_path` (scrolling right) is watched by a trailing
+    #     sentinel (`#{id}_date_sentinel`) via IntersectionObserver, rooted
+    #     at the grid's own horizontally-scrolling container rather than the
+    #     page viewport (a plain `loading="lazy"` frame can't do that -- it
+    #     only ever watches the page viewport).
+    #   - `prev_dates_path` (scrolling left) is loaded by a plain button the
+    #     user clicks (`#{id}_date_start_trigger`), not auto-loaded on
+    #     scroll -- see the Stimulus controller's own docs for why an
+    #     IntersectionObserver-driven sentinel doesn't work well for this
+    #     direction (in short: it sits right where the grid is already
+    #     scrolled to on a normal page load, so there's no clean way to tell
+    #     "the user scrolled here" apart from "this is just where it starts").
+    #
+    # Both fetch the same way, with `Accept: text/vnd.turbo-stream.html`.
+    #
+    # A `next_dates_path` response must:
+    #   1. `append`s new `DateHeaderComponent` cells to `#{id}_dates`
+    #   2. for every row *currently on the page*, `append`s any new
+    #      `ItemComponent` bars that fall in the newly-loaded date range to
+    #      that row's `RowComponent#track_id`
+    #   3. `replace`s `#{id}_date_sentinel` with an updated one, or `remove`s
+    #      it when there are no more days ahead
+    #   4. `append`s one or more `MonthBandComponent` segments to
+    #      `#{id}_month_band`, covering the same newly-loaded dates -- see
+    #      that class's docs, "Loading more days"
+    #
+    # A `prev_dates_path` response is the mirror image -- `prepend` instead
+    # of `append` to `#{id}_dates`/`#{id}_month_band` and each row's track
+    # (bars are absolutely positioned, so prepend vs. append only matters for
+    # the date header cells' visual order), and it `replace`s
+    # `#{id}_date_start_trigger` with an updated one (new `data-prev-page`),
+    # or `remove`s it when there are no earlier days behind. After that
+    # stream renders, the controller adds the newly-prepended width to the
+    # scroller's `scrollLeft` so the content the user was already looking at
+    # doesn't visually jump -- the same scroll-anchor correction any "load
+    # older messages above" infinite-scroll UI needs -- and rebases every
+    # bar/today strip already on the page by that same amount (see
+    # "`origin:` has to round-trip through every request" above).
+    #
+    # See "New rows outside the currently-loaded date window" above for what
+    # happens when a bar's dates fall outside what `next_dates_path`/
+    # `prev_dates_path` have loaded so far -- a real, if usually avoidable,
+    # possibility on this axis too (a newly-appended row's bookings, or a
+    # newly-appended bar from a horizontal-load response, same idea either
+    # way).
+    #
+    # Rows themselves only paginate forward (down) -- `next_rows_path` has
+    # no `prev_rows_path` counterpart. Add one yourself (a second lazily-
+    # loaded frame above `#{id}_rows`, prepending instead of appending) if
+    # you need it; nothing here assumes rows can't also load backward, there
+    # just isn't a use case yet that needs it.
+    class GanttComponent < AtomicView::Component
+      DEFAULT_CELL_WIDTH = 42
+      DEFAULT_LABEL_WIDTH = 176
+
+      # Bar height, the gap below it before the next lane, and the gap above
+      # the first lane -- see `ItemComponent#lane`/`RowComponent#lanes` and
+      # `.pack_lanes` for the overlap-handling these size.
+      BAR_HEIGHT = 28
+      LANE_GAP = 8
+      LANE_TOP_PADDING = 8
+      LANE_HEIGHT = BAR_HEIGHT + LANE_GAP
+
+      renders_many :rows, "AtomicView::Components::GanttComponent::RowComponent"
+
+      attr_reader :id, :dates, :next_rows_path, :next_dates_path, :prev_dates_path, :cell_width, :label_width,
+        :today, :date_root_margin, :empty_message
+
+      # @param id [String] unique DOM id for this grid; every other id
+      #   (rows/dates containers, sentinels, frames) is derived from it.
+      # @param dates [Array<Date>] the date columns to render *this call* --
+      #   for the initial render, the first page of the visible range; a
+      #   `next_dates_path`/`prev_dates_path` response renders only the
+      #   newly-appended/prepended dates.
+      # @param next_rows_path [String, nil] URL for the next page of rows,
+      #   rendered as a lazily-loaded turbo-frame. Omit (nil) when there are
+      #   no more rows to load.
+      # @param next_dates_path [String, nil] URL for the next page of date
+      #   columns, loaded when the grid scrolls right. Omit when there are no
+      #   more days ahead to load.
+      # @param prev_dates_path [String, nil] URL for the previous page of
+      #   date columns, loaded when the grid scrolls left. Omit when there
+      #   are no earlier days to load.
+      # @param cell_width [Integer] pixel width of one day column. Must match
+      #   whatever `RowComponent`/`ItemComponent` instances use for this same
+      #   grid (they default to the same constant, so leave this alone unless
+      #   you're overriding it everywhere).
+      # @param label_width [Integer] pixel width of the sticky label column.
+      # @param today [Date, nil] highlights the column `today` falls within.
+      # @param date_root_margin [String] IntersectionObserver rootMargin for
+      #   the trailing (right/`next_dates_path`) date sentinel, rooted at the
+      #   grid's own scroll container rather than the viewport. Only the
+      #   forward direction uses an observer -- see "Loading more days, in
+      #   either direction" above for why the backward one is a plain button
+      #   instead.
+      # @param empty_message [String] shown when there are no rows at all.
+      def initialize(
+        id:,
+        dates:,
+        next_rows_path: nil,
+        next_dates_path: nil,
+        prev_dates_path: nil,
+        cell_width: DEFAULT_CELL_WIDTH,
+        label_width: DEFAULT_LABEL_WIDTH,
+        today: nil,
+        date_root_margin: "0px 400px 0px 0px",
+        empty_message: "Nothing scheduled.",
+        **options
+      )
+        super()
+        @id = id
+        @dates = dates
+        @next_rows_path = next_rows_path
+        @next_dates_path = next_dates_path
+        @prev_dates_path = prev_dates_path
+        @cell_width = cell_width
+        @label_width = label_width
+        @today = today
+        @date_root_margin = date_root_margin
+        @empty_message = empty_message
+        @options = options
+      end
+
+      # Absolute position of `date`, in days. Epoch-independent (only ever
+      # used as a difference between two calls, in `.offset_px`/`.span_px`
+      # below).
+      def self.position(date)
+        date.to_date.jd
+      end
+
+      # Whether `starts_on`..`ends_on` shares any inclusive day with
+      # `range_starts_on`..`range_ends_on`. Meant for scoping which bookings
+      # to render at all -- e.g. `site.bookings.select { |b|
+      # GanttComponent.overlaps_range?(b.starts_on, b.ends_on, dates.first,
+      # dates.last) }` before calling `with_item` -- so a row never carries
+      # bars far outside what's currently loaded; see "New rows outside the
+      # currently-loaded date window" above.
+      def self.overlaps_range?(starts_on, ends_on, range_starts_on, range_ends_on)
+        starts_on.to_date <= range_ends_on.to_date && ends_on.to_date >= range_starts_on.to_date
+      end
+
+      # Pixel offset of `date` from `origin` -- the left edge of a bar/strip
+      # starting on `date`. Negative when `date` is before `origin` (a bar
+      # that started before the currently-loaded window); callers don't need
+      # to clip this themselves, it just renders (partially) off the
+      # scroller's left edge.
+      def self.offset_px(date, origin:, cell_width: DEFAULT_CELL_WIDTH)
+        (position(date) - position(origin)) * cell_width
+      end
+
+      # Pixel width of a bar spanning `starts_on`..`ends_on`, inclusive of
+      # both end dates.
+      def self.span_px(starts_on, ends_on, cell_width: DEFAULT_CELL_WIDTH)
+        (position(ends_on.to_date + 1) - position(starts_on)) * cell_width
+      end
+
+      # Greedily assigns each `[starts_on, ends_on]` pair in `ranges` to the
+      # lowest-numbered lane that doesn't overlap anything already placed
+      # there, returning the lanes as an `Array<Integer>` in the same order
+      # as `ranges` (not sort order -- `ranges` doesn't need to be
+      # pre-sorted). Two ranges "overlap" if they share any inclusive day;
+      # adjacent ranges (one ending the day before the next starts) can share
+      # a lane. See `ItemComponent#lane`/`RowComponent#lanes` for how to use
+      # the result.
+      #
+      #   GanttComponent.pack_lanes([[Date.new(2026, 9, 1), Date.new(2026, 9, 5)], [Date.new(2026, 9, 3), Date.new(2026, 9, 8)], [Date.new(2026, 9, 10), Date.new(2026, 9, 12)]])
+      #   # => [0, 1, 0] -- the first two overlap (Sep 3-5) so need separate lanes;
+      #   #    the third starts after the first one ends, so reuses lane 0.
+      def self.pack_lanes(ranges)
+        lane_ends = []
+        lanes = Array.new(ranges.size)
+
+        ranges.each_with_index.sort_by { |(starts_on, _ends_on), _index| starts_on.to_date }.each do |(starts_on, ends_on), index|
+          starts_on = starts_on.to_date
+          ends_on = ends_on.to_date
+          lane = lane_ends.index { |lane_end| starts_on > lane_end } || lane_ends.length
+          lane_ends[lane] = ends_on
+          lanes[index] = lane
+        end
+
+        lanes
+      end
+
+      # One entry per distinct calendar month present in `dates`, clipped to
+      # whatever's currently loaded -- e.g. `dates` starting mid-September
+      # yields a first segment covering just `dates.first`..(Sep 30), not the
+      # 1st..30th (`count` is the number of *loaded* days, not the month's
+      # real length). `count` is exactly what `MonthBandComponent#span`
+      # wants.
+      def month_segments
+        dates.chunk { |date| date.beginning_of_month }.map do |month_start, days|
+          {month_start: month_start, count: days.size}
+        end
+      end
+
+      def scroller_id = "#{id}_scroller"
+      def month_band_id = "#{id}_month_band"
+      def dates_id = "#{id}_dates"
+      def rows_id = "#{id}_rows"
+      def row_pagination_id = "#{id}_row_pagination"
+      def date_sentinel_id = "#{id}_date_sentinel"
+      def date_loader_id = "#{id}_date_loader"
+      def date_start_trigger_id = "#{id}_date_start_trigger"
+      def date_start_loader_id = "#{id}_date_start_loader"
+
+      def paginated_rows? = next_rows_path.present?
+      def paginated_dates_forward? = next_dates_path.present?
+      def paginated_dates_backward? = prev_dates_path.present?
+      def empty? = rows.empty?
+
+      # Shared by the date header and month band containers -- both are a
+      # single-row CSS Grid (`grid-auto-flow: column`) so their children
+      # (`DateHeaderComponent` cells, `MonthBandComponent` segments) never
+      # need a pixel width of their own. See "How the grid is laid out"
+      # above.
+      def column_grid_style = "grid-auto-columns: #{cell_width}px"
+
+      def html_options
+        @options.except(:class, :data)
+      end
+
+      def html_class
+        class_names("rounded-card border border-border bg-surface", @options[:class])
+      end
+
+      def data_attributes
+        controllers = ["atomic-view--gantt", @options.dig(:data, :controller)].compact.join(" ")
+        (@options[:data] || {}).except(:controller).merge(
+          "controller" => controllers,
+          "atomic-view--gantt-date-root-margin-value" => date_root_margin
+        )
+      end
+    end
+  end
+end

data/lib/atomic_view/version.rb

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