atomic_view 0.1.17 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60e24ea14905c39463895bf65986134967d2d43ca813e0bf2694ac2624675bb7
-  data.tar.gz: 4776e9b26a08dcc0ef789bc94e1a1ee7067226bce0a02674516b1bfb9f3e8a73
+  metadata.gz: 8f8b65a708eb61c363c49739577ef43d71266873a2ec2f64aea3d5d1e376b626
+  data.tar.gz: 167cbbac4465b3bc599c0f86f13f2a9f19f7771ca5e545d7cda0372f298a5755
 SHA512:
-  metadata.gz: a8c0c0b283c93b31c668e5c5354940031caf143e017486cb4634b4d7dc458dfec76cd3721ecf1ba8dd389f3dbad7dde6f8c557acd5f879b5a254bfc130f8bf06
-  data.tar.gz: dfefa8a1cda45ae904771d27c02cb9d106323cdd5a9db8aab3876e8d4fd684d070f473fe39a27a2aa9c9238cd663298cf46af2bbe47d23b23b41c028e1e78331
+  metadata.gz: 3e5ca41fad05a869f0307bd23f1fe8a8c180370accfdff2f3ca5ddc66c84dd77133d60e85d3f1acdc5f2d8b978a2f27aea9eb6755ff362c351e2c23002e3ebd0
+  data.tar.gz: 35197eb341f652950d8718dc154eed20900f222eb9e4de4187b2fc2ab33b370d28f24cd2990296162f9cad9dc45b36196aff6bfb91cd3145aea6b3c4ef679b54

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/app/assets/javascripts/atomic_view/controllers/hotkey_controller.js

@@ -0,0 +1,32 @@
+import { Controller } from "@hotwired/stimulus"
+
+// A key (or chord) bound elsewhere via Stimulus's keyboard event filters,
+// e.g. `data-action="keydown.n@window->hotkey#click"`, activates this
+// element instead of every shortcut needing its own handler. Ignored while
+// the user is typing (an input/textarea/Trix editor has focus) or when the
+// element itself isn't interactable right now (hidden, disabled via
+// pointer-events: none, ...).
+export default class extends Controller {
+  click(event) {
+    if (this.isClickable && !this.shouldIgnore(event)) {
+      event.preventDefault()
+      this.element.click()
+    }
+  }
+
+  focus(event) {
+    if (this.isClickable && !this.shouldIgnore(event)) {
+      event.preventDefault()
+      this.element.focus()
+    }
+  }
+
+  shouldIgnore(event) {
+    const target = event.target
+    return event.defaultPrevented || !!target?.closest("input, textarea, trix-editor, [contenteditable]")
+  }
+
+  get isClickable() {
+    return getComputedStyle(this.element).pointerEvents !== "none"
+  }
+}

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 %>