recourse 5.3.0 → 5.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0c224b5ff48a88afa37e70da5d2157d9b5229eccdc02d7d9f8ce1b85e4df31d8
-  data.tar.gz: 50da170bddd967baba9c46c276e61f750694465a2c2e11c5fe09c5e59cc84eff
+  metadata.gz: fcfda63efd2c2320ea4e97b5805d1ba4aadeb0686b78d613c2b2c4ad71b9fc17
+  data.tar.gz: ffaa33863a46cdf213c5ab2fab3266b7266bf4e73073e88be42928e72838471f
 SHA512:
-  metadata.gz: 91bc98cadd2186f29b342da8804c0926f523656aec2149e8025393c4c3ba3ec034e1ae359732cb81368192ac00b70f484731640227692c18b4c5d1ed09adac1f
-  data.tar.gz: a0565fb334f552e1a403af4db94f8d878f25ae5473e6af167304785fc017d42e392e9276ece5b2fcd4475fe48511cac8216a670adc23f8269f9ee8b931573c4f
+  metadata.gz: 45bfd3ce50837e3a0d28a02f226f0eca777ebb2b25e880059db61052313a67ebd311b8c2404f0281b147713fa346d8cf3653effb9f180ba0743d998acba12a10
+  data.tar.gz: 20f922caf3230244b441b47dcfd3fa4ca7fe7abd5045c1f765f47cad8ce54d737be6aabf22dce13c0d81720e15c1cc7803b9b8077df9fcbfda90ac5a9a4fd311

data/CHANGELOG.md

@@ -7,6 +7,24 @@ For more information about changelogs, check [Keep a Changelog](http://keepachan
 
 ## [Unreleased]
 
+## 5.4.0 - 2026-09-17
+
+* [Feature] A table of events can be read as a week
+
+  The second shape a page of rows can take, beside the map: a model keeping a `starts_at`
+  and an `ends_at` offers `Display as calendar` in its footer, and `/shifts.cal` draws
+  them as a week — a column a day from Sunday, the hours that week's own rows cover down
+  the side, and each row placed by the share of the day it takes, in a lane of its own
+  where a day's rows overlap, saying what it is, whoever it points at and the hours
+  themselves. The grid is as tall as a table's own first page, so the two shapes carry
+  their footers at one height. A week rather than a page is the unit, so `?week=` moves it
+  and `<<`, `<`, `>` and `>>` stand where a table's pages stand — a week either side and
+  four weeks beyond each — with the week named between them;
+  the search, the filters and the reader's own time zone all travel with it. A search or
+  a filter now answers in the shape it was picked in rather than falling back to the
+  table, and `Display as map` and `Display as table` are drawn by one helper, so a model
+  earning both shapes offers both.
+
 ## 5.3.0 - 2026-09-16
 
 * [Feature] A record's files are a field, a value and a page

data/README.md

@@ -208,6 +208,37 @@ Security Policy allows `maps.googleapis.com` for scripts and connections, and Go
 tile hosts for images.
 
 
+### Calendars
+
+A table whose model keeps a `starts_at` and an `ends_at` can be read as a week of the same
+rows: the footer offers `Display as calendar`, and `/shifts.cal` draws a column a day with
+each row placed by the hours it runs between — rows that overlap in lanes of their own.
+A row says what it is, whoever it points at, and the hours themselves, each led to its own
+page where the routes drew one.
+
+```ruby
+recourses :shifts
+```
+
+A week rather than a page is what a calendar shows, so there is nothing to paginate:
+`?week=2026-09-13` moves to the week holding that day, and `<<`, `<`, `>` and `>>` stand
+where the pages stand under a table — a week either side and four weeks beyond each —
+with the week named between them. The search and the
+filters travel with it — and answer in the shape they were picked in — so a calendar
+narrowed to one person stays a narrowed calendar as the weeks move.
+
+The grid stands as tall as a table's own first page, so the weeks under a calendar sit
+where the pages under a table do. The week opens on Sunday and the hours are the reader's
+own — the same cookie every other
+time on these pages is drawn against — and the scale runs only over the hours that week's
+rows cover, or a working day where it holds none. A row running past midnight is drawn on
+the day it opens, down to the foot of its column.
+
+Both columns have to be datetimes, asked through `type_for_attribute`, so an
+`attribute :starts_at, :datetime` override counts and a column of another kind named
+`starts_at` earns nothing.
+
+
 ## Development
 
 ```bash

data/app/controllers/concerns/recourse/weeks.rb

@@ -0,0 +1,40 @@
+module Recourse
+  # Which week a calendar draws, and the rows that fall inside it.
+  module Weeks
+    # How a week is written into an address: `?week=2026-09-13`, any day of the one
+    # meant, since a reader following a link never types one.
+    WEEK_FORMAT = '%Y-%m-%d'
+
+  private
+
+    # The Sunday the calendar opens on: the week the address names, or the reader's
+    # own. An address is a stranger's to write, so a day nothing can be made of is
+    # this week rather than a 500.
+    def recourse_week
+      Recourse.week_of Date.strptime(params[:week].to_s, WEEK_FORMAT)
+    rescue Date::Error
+      Recourse.week_of Time.zone.today
+    end
+
+    # What the index lists, as the pair it assigns: one week where the calendar was
+    # asked for, and one page everywhere else. A calendar has no pages to take and a
+    # table has no week, so neither shape carries the other's.
+    def week_or_page(scope)
+      return pagy scope, limit: recourse_limit unless request.format.cal?
+
+      [nil, week_resources(scope)]
+    end
+
+    # The week's rows, earliest first and all of them: a week is how much a calendar
+    # shows, so the sort a heading asked for is not what a grid reads by. Against the
+    # reader's own clock, which `Zoning` has already put in `Time.zone` — the same
+    # midnight the grid draws from.
+    def week_resources(scope)
+      @recourse_week = recourse_week
+      opening = @recourse_week.in_time_zone
+
+      scope.reorder(Recourse::START_COLUMN => :asc)
+           .where Recourse::START_COLUMN => opening...(opening + 1.week)
+    end
+  end
+end

data/app/controllers/recourse/base_controller.rb

@@ -6,7 +6,7 @@ module Recourse
     include Pagy::Method, AttachmentResolution, AttachmentWriting,
             Landing, Paging, ListResolution, ParentNaming,
             ParentResolution, ReferenceResolution, ResourceResolution,
-            Zoning
+            Weeks, Zoning
 
     helper Helpers
 
@@ -19,13 +19,17 @@ module Recourse
     # The model broadcasts refreshes for its index, before `create` commits its own.
     before_action :broadcast_resource_changes
 
-    # Lists one page of the model the route is named after. `@q` is Ransack's own name.
+    # Lists one page of the model the route is named after, or one week of it where the
+    # calendar was asked for — a week is how much that shape shows. `@q` is Ransack's own.
     def index
       search = Search.new recourse_relation, params[:q]
       @q = search.query
-      @pagy, @resources = pagy search.scope, limit: recourse_limit
-      # A map is the same page in another shape, so the HTML templates draw it.
-      render :index, formats: :html if request.format.map?
+
+      @pagy, @resources = week_or_page search.scope
+
+      # A map and a calendar are the same page in another shape: the HTML templates draw
+      # both.
+      render :index, formats: :html if SHAPES.include? request.format.symbol
     end
 
     # Builds a blank record under the name Rails would use: @contact for contacts, with

data/app/views/layouts/recourses.html.erb

@@ -17,15 +17,16 @@
     <%= yield :head %>
 
     <%# Everything the page is styled by, from the one place every HouseAccount app draws
-        on: Bootstrap 6, its icons and the house's own rules for this gem's markup. Pinned
-        to a version, so a change there reaches these pages when somebody moves the pin
-        here and not before; the same version stands in the script below and in
-        `Recourse::THEMES_PATH`. Two connections opened before the parser finds either tag:
-        the stylesheet's plain one and the CORS one a module script and a font are fetched
-        over. -%>
-    <link rel='preconnect' href='https://design.houseaccount.com'>
-    <link rel='preconnect' href='https://design.houseaccount.com' crossorigin>
-    <link rel='stylesheet' href='https://design.houseaccount.com/v0.5.0/css/houseaccount.css'>
+        on: Bootstrap 6, its icons and the house's own rules for this gem's markup. Served
+        from the `houseaccount` package on a CDN, pinned to a version, so a change there
+        reaches these pages when somebody moves the pin here and not before; the same
+        version stands in the script below and in `Recourse::THEMES_PATH`. A published
+        version is never written again, so the bytes behind that URL cannot move under us.
+        Two connections opened before the parser finds either tag: the stylesheet's plain
+        one and the CORS one a module script and a font are fetched over. -%>
+    <link rel='preconnect' href='https://cdn.jsdelivr.net'>
+    <link rel='preconnect' href='https://cdn.jsdelivr.net' crossorigin>
+    <link rel='stylesheet' href='https://cdn.jsdelivr.net/npm/houseaccount@0.11.0/public/css/houseaccount.css'>
     <%# The one thing these screens set that the house's stylesheet does not: system faces
         at a compact size, for pages dense with figures. 14px as rem, so a browser's own
         text-size setting still scales it. After the stylesheet, since both are `:root`. -%>
@@ -49,7 +50,7 @@
     <%# Turbo, Bootstrap and a Stimulus application with every controller this markup
         names, started once under `window.Stimulus`. In the head, so a controller exists
         before the body's first `data-controller`. -%>
-    <script type='module' src='https://design.houseaccount.com/v0.5.0/js/houseaccount.js'></script>
+    <script type='module' src='https://cdn.jsdelivr.net/npm/houseaccount@0.11.0/public/js/houseaccount.js'></script>
   </head>
 
   <%# The reader's zone is told to the server here rather than from a page of its

data/app/views/recourses/_calendar.html.erb

@@ -0,0 +1,40 @@
+<%# locals: (recourses:, week:) %>
+<div class='card overflow-hidden mb-3'>
+  <div class='overflow-x-auto'>
+    <%# One grid rather than a row of columns: the days have to line up under their own
+        headings, and a column whose width is what it happens to hold does not. The
+        gutter is as wide as `12am` reads, and the seven take equal shares of the rest.
+        A minimum width so a phone scrolls the week rather than crushing it. -%>
+    <div class='d-grid' style='grid-template-columns: 4rem repeat(7, 1fr); min-width: 48rem'>
+      <div class='border-bottom'></div>
+
+      <% calendar_days(week).each do |day| %>
+        <div class='border-bottom border-start text-center py-2'><%= calendar_day_title day %></div>
+      <% end %>
+
+      <%# Every column is the same height whatever hours it draws — a table's own first
+          page — and the bands share it out, so the week nav under the grid stands where
+          a table's pages stand. -%>
+      <div class='d-flex flex-column' style='<%= calendar_grid_style %>'>
+        <% calendar_hours(recourses).each do |hour| %>
+          <div class='small fg-2 text-end pe-2 flex-fill'><%= calendar_hour_title hour %></div>
+        <% end %>
+      </div>
+
+      <%# Each day is those same bands with its own rows laid over them, which is what
+          `position-relative` is here for: a row is placed by the share of the grid it
+          takes rather than by anything the flow could work out. -%>
+      <% calendar_days(week).each do |day| %>
+        <div class='d-flex flex-column border-start position-relative' style='<%= calendar_grid_style %>'>
+          <% calendar_hours(recourses).each do %>
+            <div class='border-top flex-fill'></div>
+          <% end %>
+
+          <%= calendar_events recourses, day, calendar_hours(recourses) %>
+        </div>
+      <% end %>
+    </div>
+  </div>
+</div>
+
+<%= render 'week', recourses: recourses, week: week %>

data/app/views/recourses/_footer.html.erb

@@ -18,11 +18,12 @@
       <% else %>
         <%= t 'recourse.displaying', count: pagy.count %>
       <% end %>
-      <%# And the other shape the same rows can take, where the model keeps a place or
-          a point: a table becomes a map of this page's rows, and a map a table again. -%>
-      <% if (other = view_link) %>
+      <%# And every other shape the same rows can take, where the model's own columns
+          earn one: a place or a point makes a map of this page's rows, the two ends of
+          an event make a week of them, and either leads back to the table. -%>
+      <% view_links.each do |link| %>
         <span class='fg-2'>&middot;</span>
-        <%= other %>
+        <%= link %>
       <% end %>
     </div>
     <%# Centered on the row of their own a phone gives them, and at the end of the shared row from `sm` up. -%>

data/app/views/recourses/_results.html.erb

@@ -1,8 +1,12 @@
-<%# locals: (resources:, pagy:) %>
+<%# locals: (resources:, pagy:, week:) %>
 <%# Both branches, so a search that matches nothing still answers with the frame
-    it was asked for. `advance` puts the query in the address bar. -%>
+    it was asked for. `advance` puts the query in the address bar. A calendar is the
+    exception to the empty one: a week with nothing in it is still a week to draw, or
+    there would be nothing to reach the weeks either side by. -%>
 <turbo-frame id='results' data-turbo-action='advance'>
-  <% if resources.blank? %>
+  <% if calendar_view? %>
+    <%= render 'calendar', recourses: resources, week: week %>
+  <% elsif resources.blank? %>
     <%= render 'none' %>
   <% else %>
     <%= render map_view? ? 'map' : 'table', recourses: resources, pagy: pagy %>

data/app/views/recourses/_week.html.erb

@@ -0,0 +1,19 @@
+<%# locals: (recourses:, week:) %>
+<%# What the footer is to a table: how much is showing, the other shapes the same rows
+    take after it, and at the end of the row — where a table's pages stand, and drawn as
+    they are — the weeks either side with this one named between them. A week is how much
+    a calendar shows, so there is no page size to offer. -%>
+<div class='d-flex flex-column sm:flex-row sm:align-items-center'>
+  <div class='ps-2 flex-grow-1 text-center sm:text-start'>
+    <%= t 'recourse.displaying', count: recourses.size %>
+
+    <% view_links.each do |link| %>
+      <span class='fg-2'>&middot;</span>
+      <%= link %>
+    <% end %>
+  </div>
+
+  <div class='px-2 mt-2 sm:mt-0 d-flex justify-content-center sm:justify-content-end'>
+    <ul class='pagination mb-0'><%= week_links week %></ul>
+  </div>
+</div>

data/app/views/recourses/index.html.erb

@@ -26,8 +26,8 @@
     card, beside the record's other pages — its tab, the count, the current one. -%>
 <% if resource_parent %>
   <%= render layout: 'card', locals: { record: resource_parent } do %>
-    <%= render 'results', resources: @resources, pagy: @pagy %>
+    <%= render 'results', resources: @resources, pagy: @pagy, week: @recourse_week %>
   <% end %>
 <% else %>
-  <%= render 'results', resources: @resources, pagy: @pagy %>
+  <%= render 'results', resources: @resources, pagy: @pagy, week: @recourse_week %>
 <% end %>

data/config/locales/recourse.en.yml

@@ -3,14 +3,22 @@ en:
   date:
     formats:
       recourse: "%b %-d, %Y"
+      # A calendar's own two: the day over one of its columns, `Sun, Aug 30`, and the
+      # month a week is named by, whose day is an ordinal Ruby writes, not a format.
+      recourse_day: "%a, %b %-d"
+      recourse_month: "%B"
   time:
     formats:
       recourse: "%b %-d at %I:%M%P %Z"
+      # The scale down a calendar, `9am`, and the hours one row runs between, `9:30am`.
+      recourse_hour: "%-I%P"
+      recourse_time: "%-I:%M%P"
   recourse:
     add: Add %{model}
     ago: "%{distance} ago"
     all: All %{models}
     all_values: All
+    as_calendar: Display as calendar
     as_map: Display as map
     as_table: Display as table
     # One message in four spellings: what a record is holding, under the field that
@@ -58,11 +66,15 @@ en:
     more: "%{first} + %{count} more"
     new: New %{model}
     new_tab: Open in a new tab
+    next_week: Next week
+    next_weeks: Next four weeks
     no_results: No results found
     none: "No %{models}."
     optional: Optional
     per_page: "%{limit} per page"
     preview: Preview
+    previous_week: Previous week
+    previous_weeks: Previous four weeks
     ambiguous: "matches more than one record, so it does not say which: %{label}"
     reference: "%{model} %{attribute}"
     reveal: Show
@@ -79,6 +91,8 @@ en:
     updated: "%{record} was updated."
     updated_error: "%{model} could not be updated."
     unset: None
+    # The two days a calendar's week runs between, and the year both are in.
+    week: "%{from} – %{to}, %{year}"
     deletion:
       delete: Delete
       title: Delete %{record}?

data/lib/recourse/calendars.rb

@@ -0,0 +1,27 @@
+# Reopened for the calendar a table of events can be read as.
+module Recourse
+  # The column an event opens at, which is the day and the hour a calendar draws it on.
+  START_COLUMN = 'starts_at'
+
+  # And the one it closes at, which is how far down the day it reaches.
+  FINISH_COLUMN = 'ends_at'
+
+  # The two together, which is what a model is asked for its rows to be a week's events.
+  EVENT_COLUMNS = [START_COLUMN, FINISH_COLUMN].freeze
+
+  # The day a week opens on. Sunday, which is the column a calendar leads with wherever
+  # these pages are read — `Date.beginning_of_week` is the host's own setting, and a
+  # grid of seven is not a thing to draw two ways.
+  WEEK_START = :sunday
+
+  # Whether a model's rows can be drawn on a calendar: both ends of an event, and both
+  # an instant rather than a day — a date has no hour for a week to place it by. Asked
+  # of the type the model reports, so an `attribute` override counts and a column of
+  # another kind named `starts_at` earns nothing.
+  def self.calendarable?(model)
+    EVENT_COLUMNS.all? { |column| model.type_for_attribute(column).type == :datetime }
+  end
+
+  # The Sunday a day belongs to, which is the week a calendar of it opens on.
+  def self.week_of(day) = day.beginning_of_week WEEK_START
+end

data/lib/recourse/engine.rb

@@ -15,10 +15,11 @@ module Recourse
       ActionDispatch::Routing::Mapper.include Scopes, Routes
     end
 
-    # `/counties.map` is the same page in another shape, so the format is a name for
-    # HTML: without it Rails has no type for the extension and answers 406.
+    # `/counties.map` and `/shifts.cal` are the same page in another shape, so each
+    # format is a name for HTML: without one Rails has no type for the extension and
+    # answers 406.
     initializer 'recourse.formats' do
-      Mime::Type.register_alias 'text/html', :map
+      SHAPES.each { |shape| Mime::Type.register_alias 'text/html', shape }
     end
   end
 end

data/lib/recourse/helpers/calendars.rb

@@ -0,0 +1,55 @@
+module Recourse
+  module Helpers
+    # The grid a table of events is read as: the seven days across it, the hours down
+    # it, and how tall the whole of it stands. What the week is called is `Weeks`.
+    module Calendars
+      # The hours a week with nothing in it draws: a working day, which is what a
+      # reader moving through empty weeks has to place the next one's rows against.
+      DEFAULT_HOURS = (8...18)
+
+    private
+
+      # The seven days the grid draws, Sunday first.
+      def calendar_days(week) = week..(week + 6)
+
+      # A day's heading, `Sun, Aug 30`, and today's said louder — the one column a reader
+      # is looking for before they read a single row.
+      def calendar_day_title(day)
+        tag.span l(day, format: :recourse_day),
+                 class: day == Time.zone.today ? 'fw-semibold' : 'fg-2'
+      end
+
+      # How tall the grid stands, whatever hours it draws, and why the figure is stated
+      # here: a table's own first page is `LIMITS.first` rows, so a grid that height
+      # leaves the weeks under a calendar where the pages under a table already are. A
+      # row is its line box, the two paddings a cell keeps — Bootstrap's
+      # `--bs-table-cell-padding-y`, which is declared inside a table and nowhere a
+      # calendar could read it — and the rule under it.
+      def calendar_grid_style
+        "height: calc(#{Recourse::LIMITS.first} * (1em * var(--bs-body-line-height) + " \
+          '1rem + var(--bs-border-width)))'
+      end
+
+      # The hours the grid runs between, one band of that height each. Remembered per
+      # render: every one of the eight columns asks, and a page draws one grid.
+      def calendar_hours(recourses)
+        @recourse_hours ||= hours_of recourses
+      end
+
+      # From the hour the week's earliest row opens in to the one its latest closes
+      # in, so a week of evenings is a grid of evenings rather than a day of empty
+      # bands. `blank?` and not `empty?`: the rows are about to be drawn either way.
+      def hours_of(recourses)
+        return DEFAULT_HOURS if recourses.blank?
+
+        minutes = recourses.map { |one| event_minutes one }
+
+        (minutes.map(&:first).min / 60)...(minutes.map(&:last).max / 60.0).ceil
+      end
+
+      # An hour of the scale, `9am`, read off a clock rather than named in Ruby: which
+      # words those are is a locale's to say, like every other time on the page.
+      def calendar_hour_title(hour) = l(Time.zone.now.change(hour:), format: :recourse_hour)
+    end
+  end
+end

data/lib/recourse/helpers/events.rb

@@ -0,0 +1,79 @@
+module Recourse
+  module Helpers
+    # What a calendar draws of one row: the lane it is given where a day's rows overlap,
+    # and what it says once it has one. Where it is placed is `Spans`.
+    module Events
+    private
+
+      # One day's rows, in the lanes that day needed: a row takes the first lane whose
+      # last row has closed, so rows that overlap stand side by side. The lanes are
+      # counted over the whole day rather than over each run of overlaps — a column is
+      # a day, and two days are read against each other.
+      def calendar_events(recourses, day, hours)
+        lanes = []
+        placed = recourses.select { |one| opens_on? one, day }
+                          .map { |one| [one, take_lane(one, lanes)] }
+
+        safe_join(placed.map { |one, lane| event_chip one, hours, lane, lanes.size })
+      end
+
+      def opens_on?(recourse, day) = recourse.attributes[Recourse::START_COLUMN].to_date == day
+
+      # The first lane free by the time this row opens, or one of its own, with the
+      # minute it closes at left in it for whatever comes next.
+      def take_lane(recourse, lanes)
+        opening, closing = event_minutes recourse
+        lane = lanes.index { |taken| taken <= opening } || lanes.size
+        lanes[lane] = closing
+
+        lane
+      end
+
+      # One row, placed by the hours it runs between and saying what it is.
+      def event_chip(recourse, hours, lane, lanes)
+        tag.div event_words(recourse),
+                class: 'position-absolute overflow-hidden small rounded border bg-1 px-1',
+                style: event_style(recourse, hours, lane, lanes)
+      end
+
+      # What it says, a line each: its own label, whoever it is for, and the hours. In
+      # that order because a chip is as tall as the row is long — an hour at the foot of
+      # a full week is two lines — so what is clipped first is what the grid itself has
+      # already said.
+      def event_words(recourse)
+        label = led Recourse.record_title(recourse), resource_model.name, recourse.id
+        named = event_references recourse
+
+        safe_join [
+          tag.div(label, class: 'text-truncate'),
+          named && tag.div(named, class: 'fg-2 text-truncate'),
+          tag.div(event_times(recourse), class: 'fg-2 text-truncate'),
+        ].compact
+      end
+
+      # Whoever the row points at, each led to its own page: a shift is read as whose
+      # it is after it is read as what it is. Every `belongs_to` the model can follow,
+      # and the same label a table's own cell would draw for it — already loaded, since
+      # the index eager-loads every one of them.
+      def event_references(recourse)
+        named = resource_model.recourse_references.filter_map do |association|
+          named_cell recourse, association
+        end
+
+        safe_join named, ' · ' if named.any?
+      end
+
+      # The two ends of a row, each carrying what a machine reads, like every other
+      # time on these pages.
+      def event_times(recourse)
+        ends = Recourse::EVENT_COLUMNS.filter_map do |column|
+          value = recourse.attributes[column]
+
+          time_tag value, l(value, format: :recourse_time) if value
+        end
+
+        safe_join ends, '–'
+      end
+    end
+  end
+end

data/lib/recourse/helpers/maps.rb

@@ -1,25 +1,10 @@
 module Recourse
   module Helpers
-    # The map a table of places is read as, and the link under either that leads to
-    # the other.
+    # The map a table of places is read as. Which shapes a page has and the links
+    # between them are `Shapes`, since a map is only one of them.
     module Maps
     private
 
-      # Whether this page is the map rather than the table.
-      def map_view? = request.format.map?
-
-      # The link under the rows to the other shape of the page, or nothing where the
-      # model keeps neither a place nor a point to draw one by. The query goes with it —
-      # the search, the sort and the page — so the map shows the rows the table did.
-      def view_link
-        return unless Recourse.mappable? resource_model
-
-        params = request.query_parameters
-        return link_to t('recourse.as_table'), url_for(params.merge(format: nil)) if map_view?
-
-        link_to t('recourse.as_map'), url_for(params.merge(format: :map))
-      end
-
       # What the map controller needs: the key and the map from the host's credentials,
       # and this page's rows as the places or the points they keep.
       def map_data(recourses)

data/lib/recourse/helpers/searches.rb

@@ -24,11 +24,20 @@ module Recourse
         filters = resource_filter_fields
         return if field.blank? && filters.empty?
 
-        render 'recourses/search', query: resource_search, url: url_for(action: :index),
+        render 'recourses/search', query: resource_search, url: search_url,
                                    field: field, prompt: resource_search_prompt,
                                    filters: filters, sort: sort_param
       end
 
+      # Where the form submits: this page's own shape, so a filter picked on the map or
+      # on the calendar answers with the map or the calendar. Only a shape's format goes
+      # into the address — the table is the page at its own, with no extension at all.
+      def search_url
+        format = request.format.symbol
+
+        url_for action: :index, format: (format if Recourse::SHAPES.include? format)
+      end
+
       # The model's search field, less the reach-through a nested route already
       # answered: a page pinned to one provider offers no box to search them all.
       def resource_search_field

data/lib/recourse/helpers/shapes.rb

@@ -0,0 +1,42 @@
+module Recourse
+  module Helpers
+    # The shapes one page of rows can be read in — a table, a map of where they are, a
+    # calendar of when they are — and the links from the one showing to the others.
+    module Shapes
+    private
+
+      # Whether this page is the map rather than the table.
+      def map_view? = request.format.map?
+
+      # Whether this page is the calendar rather than the table.
+      def calendar_view? = request.format.cal?
+
+      # What this page can be, by the format each shape is addressed as and the word
+      # the link to it reads: the table every model has, and whichever of the other
+      # two the model's own columns earn.
+      def view_shapes
+        model = resource_model
+        shapes = { html: 'recourse.as_table' }
+        shapes[:map] = 'recourse.as_map' if Recourse.mappable? model
+        shapes[:cal] = 'recourse.as_calendar' if Recourse.calendarable? model
+
+        shapes
+      end
+
+      # A link to each shape the page is not in, carrying the query it was asked with —
+      # the search, the sort and the page — so another shape shows the rows the table
+      # did. The week stays behind: only a calendar has one, and a calendar reached
+      # from the table opens on this week.
+      def view_links
+        shapes = view_shapes
+        query = request.query_parameters.except 'week'
+
+        # The table is the page at its own address, which is the one shape asked for by
+        # carrying no extension at all.
+        shapes.except(request.format.symbol).map do |shape, key|
+          link_to t(key), url_for(query.merge(format: (shape unless shape == :html)))
+        end
+      end
+    end
+  end
+end

data/lib/recourse/helpers/spans.rb

@@ -0,0 +1,59 @@
+module Recourse
+  module Helpers
+    # How much of a day one row takes, and where in the grid that puts it. Every figure
+    # here is minutes on the way in and a share of the grid on the way out, so a row and
+    # the hours behind it agree however tall an hour is drawn.
+    module Spans
+      # Minutes in a day, which is where a row running into the next one stops: a
+      # calendar draws a row on the day it opens, and a block past the foot of its
+      # column would be drawn over the week.
+      DAY_MINUTES = 1440
+
+      # And the least a row may be drawn as, so one nobody gave a length to is still
+      # something to read and to click rather than a line.
+      LEAST_MINUTES = 15
+
+    private
+
+      # Where the row sits: how far down the grid it opens, how much of the grid it
+      # takes, and which lane of its day it was given.
+      def event_style(recourse, hours, lane, lanes)
+        width = 100.0 / lanes
+        shares = event_shares(recourse, hours).merge left: lane * width, width: width
+
+        shares.map { |side, share| "#{side}: #{share.round 2}%" }.join '; '
+      end
+
+      # The two the hours decide: everything above the row, and the row itself.
+      def event_shares(recourse, hours)
+        opening, closing = event_minutes recourse
+        minutes = hours.count * 60.0
+
+        {
+          top: (opening - (hours.first * 60)) * 100 / minutes,
+          height: (closing - opening) * 100 / minutes,
+        }
+      end
+
+      # When a row opens and closes, as minutes from the midnight of the day it opens
+      # on — the two figures every measurement above is made from.
+      def event_minutes(recourse)
+        opening = recourse.attributes[Recourse::START_COLUMN]
+        opened = minute_of opening
+
+        [opened, [closing_minute(opening, recourse), opened + LEAST_MINUTES].max]
+      end
+
+      # Midnight for a row that runs into the next day, and for one nothing has closed
+      # yet — an end nobody has written is a row still open rather than one over at once.
+      def closing_minute(opening, recourse)
+        closing = recourse.attributes[Recourse::FINISH_COLUMN]
+        return DAY_MINUTES if closing.nil? || closing.to_date != opening.to_date
+
+        minute_of closing
+      end
+
+      def minute_of(value) = (value.hour * 60) + value.min
+    end
+  end
+end

data/lib/recourse/helpers/weeks.rb

@@ -0,0 +1,53 @@
+module Recourse
+  module Helpers
+    # What a week is called, and the ways out of one into the next.
+    module Weeks
+      # The four ways out of a week, in the order they stand, each as the weeks it moves
+      # and the arrow it is drawn as. The outer pair jump four weeks, which is a month as
+      # near as a grid drawn in weeks can hold one.
+      WEEK_STEPS = {
+        previous_weeks: [-4, '<<'], previous_week: [-1, '<'],
+        next_week: [1, '>'], next_weeks: [4, '>>'],
+      }.freeze
+
+    private
+
+      # The week the grid draws, named as the two days it runs between: `September 13th
+      # – September 19th, 2026`. The year is said once, at the end, being the one thing
+      # the two ends of a week almost always agree about.
+      def week_title(week)
+        finish = week + 6
+
+        t 'recourse.week', from: week_day(week), to: week_day(finish), year: finish.year
+      end
+
+      def week_day(day) = "#{l day, format: :recourse_month} #{day.day.ordinalize}"
+
+      # The ways out of a week, drawn as a table's pages are drawn — pagy's own markup,
+      # down to the arrows and to the item it leaves unlinked — with the week showing
+      # named in the middle, where pagy names the page.
+      def week_links(week)
+        shown = tag.a week_title(week), role: :link, class: 'page-link',
+                                        aria: { current: :page, disabled: true }
+
+        safe_join [
+          week_step(week, :previous_weeks), week_step(week, :previous_week),
+          tag.li(shown, class: 'page-item active'),
+          week_step(week, :next_week), week_step(week, :next_weeks),
+        ]
+      end
+
+      # One step: its own arrow, and the words behind it for a reader who is hearing
+      # the page rather than seeing it. The query goes with the week, so a search or a
+      # filter stands while the weeks move under it.
+      def week_step(week, key)
+        weeks, arrow = WEEK_STEPS[key]
+        query = request.query_parameters.merge week: (week + weeks.weeks).to_s
+        step = link_to arrow, url_for(query.merge(format: :cal)),
+                       class: 'page-link', aria: { label: t("recourse.#{key}") }
+
+        tag.li step, class: "page-item #{weeks.negative? ? 'previous' : 'next'}"
+      end
+    end
+  end
+end

data/lib/recourse/helpers.rb

@@ -3,6 +3,7 @@ require_relative 'helpers/attachments'
 require_relative 'helpers/blobs'
 require_relative 'helpers/bookmarks'
 require_relative 'helpers/buttons'
+require_relative 'helpers/calendars'
 require_relative 'helpers/cards'
 require_relative 'helpers/cells'
 require_relative 'helpers/choices'
@@ -13,6 +14,7 @@ require_relative 'helpers/counters'
 require_relative 'helpers/deletions'
 require_relative 'helpers/densities'
 require_relative 'helpers/details'
+require_relative 'helpers/events'
 require_relative 'helpers/examples'
 require_relative 'helpers/fields'
 require_relative 'helpers/filters'
@@ -34,25 +36,28 @@ require_relative 'helpers/routing'
 require_relative 'helpers/rows'
 require_relative 'helpers/themes'
 require_relative 'helpers/searches'
+require_relative 'helpers/shapes'
 require_relative 'helpers/shortcuts'
 require_relative 'helpers/sidebars'
 require_relative 'helpers/sorts'
+require_relative 'helpers/spans'
 require_relative 'helpers/tabs'
 require_relative 'helpers/times'
 require_relative 'helpers/values'
+require_relative 'helpers/weeks'
 require_relative 'helpers/zones'
 
 module Recourse
   # View helpers for the pages the gem renders, and what the parts share.
   module Helpers
-    include Actions, Attachments, Blobs, Bookmarks, Buttons, Cards,
+    include Actions, Attachments, Blobs, Bookmarks, Buttons, Calendars, Cards,
             Cells, Choices, Colors, Comboboxes, Constraints, Counters, Deletions, Densities,
             Details,
-            Examples, Fields, Filters, Flashes, Formats, Inputs, Kinds, Limits, Maps,
+            Events, Examples, Fields, Filters, Flashes, Formats, Inputs, Kinds, Limits, Maps,
             Names, Navigation, Parents, Pictures, Previews, References, Refreshes,
             Routing,
-            Resources, Rows, Searches, Shortcuts, Sidebars, Sorts, Tabs, Themes,
-            Times, Values, Zones
+            Resources, Rows, Searches, Shapes, Shortcuts, Sidebars, Sorts, Spans, Tabs,
+            Themes, Times, Values, Weeks, Zones
 
     # The grid a record's own two pages lay an attribute out in: two columns on a large
     # viewport, and the same padding on both, so a value and the field that edits it sit

data/lib/recourse/themes.rb

@@ -25,7 +25,7 @@ module Recourse
   # Where the palettes are served from, named once: the layout links one, the layout's
   # own script puts back the one a reader chose, and the sidebar's controller swaps it.
   # The version is the one the layout links its stylesheet and script at.
-  THEMES_PATH = 'https://design.houseaccount.com/v0.5.0/theme'
+  THEMES_PATH = 'https://cdn.jsdelivr.net/npm/houseaccount@0.11.0/public/theme'
 
   # Where a reader's chosen palette and mode are kept in their browser. Named once for
   # the same reason: the sidebar's controller writes it and the layout reads it back.

data/lib/recourse/version.rb

@@ -1,4 +1,4 @@
 module Recourse
   # Version of the gem, read by the gemspec and by hosts checking compatibility.
-  VERSION = '5.3.0'
+  VERSION = '5.4.0'
 end

data/lib/recourse.rb

@@ -7,6 +7,7 @@ require_relative 'recourse/version'
 require_relative 'recourse/attachments'
 require_relative 'recourse/blobs'
 require_relative 'recourse/bookmarks'
+require_relative 'recourse/calendars'
 require_relative 'recourse/colors'
 require_relative 'recourse/columns'
 require_relative 'recourse/themes'
@@ -35,6 +36,11 @@ module Recourse
   # them. Named once: three places ask which columns these are.
   TIMESTAMPS = %w[created_at updated_at].freeze
 
+  # The shapes a page of rows takes besides the table, by the format each is asked
+  # for. Every one of them is the same HTML drawn another way, which is why none has
+  # a template of its own and all three answer to one controller action.
+  SHAPES = %i[map cal].freeze
+
   class << self
     # Resources `recourses` has drawn, in the order config/routes.rb lists them.
     attr_reader :declared

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: recourse
 version: !ruby/object:Gem::Version
-  version: 5.3.0
+  version: 5.4.0
 platform: ruby
 authors:
 - claudiob
@@ -130,12 +130,14 @@ files:
 - app/controllers/concerns/recourse/parent_resolution.rb
 - app/controllers/concerns/recourse/reference_resolution.rb
 - app/controllers/concerns/recourse/resource_resolution.rb
+- app/controllers/concerns/recourse/weeks.rb
 - app/controllers/concerns/recourse/zoning.rb
 - app/controllers/recourse/base_controller.rb
 - app/controllers/recourse/bookmarks_controller.rb
 - app/controllers/recourses_controller.rb
 - app/views/layouts/recourses.html.erb
 - app/views/recourses/_breadcrumb.html.erb
+- app/views/recourses/_calendar.html.erb
 - app/views/recourses/_card.html.erb
 - app/views/recourses/_color.html.erb
 - app/views/recourses/_combobox.html.erb
@@ -152,6 +154,7 @@ files:
 - app/views/recourses/_sidebar.html.erb
 - app/views/recourses/_table.html.erb
 - app/views/recourses/_values.html.erb
+- app/views/recourses/_week.html.erb
 - app/views/recourses/edit.html.erb
 - app/views/recourses/index.html.erb
 - app/views/recourses/new.html.erb
@@ -162,6 +165,7 @@ files:
 - lib/recourse/blobs.rb
 - lib/recourse/bookmarks.rb
 - lib/recourse/broadcasting.rb
+- lib/recourse/calendars.rb
 - lib/recourse/colors.rb
 - lib/recourse/columns.rb
 - lib/recourse/controllers.rb
@@ -173,6 +177,7 @@ files:
 - lib/recourse/helpers/blobs.rb
 - lib/recourse/helpers/bookmarks.rb
 - lib/recourse/helpers/buttons.rb
+- lib/recourse/helpers/calendars.rb
 - lib/recourse/helpers/cards.rb
 - lib/recourse/helpers/cells.rb
 - lib/recourse/helpers/choices.rb
@@ -183,6 +188,7 @@ files:
 - lib/recourse/helpers/deletions.rb
 - lib/recourse/helpers/densities.rb
 - lib/recourse/helpers/details.rb
+- lib/recourse/helpers/events.rb
 - lib/recourse/helpers/examples.rb
 - lib/recourse/helpers/fields.rb
 - lib/recourse/helpers/filters.rb
@@ -203,13 +209,16 @@ files:
 - lib/recourse/helpers/routing.rb
 - lib/recourse/helpers/rows.rb
 - lib/recourse/helpers/searches.rb
+- lib/recourse/helpers/shapes.rb
 - lib/recourse/helpers/shortcuts.rb
 - lib/recourse/helpers/sidebars.rb
 - lib/recourse/helpers/sorts.rb
+- lib/recourse/helpers/spans.rb
 - lib/recourse/helpers/tabs.rb
 - lib/recourse/helpers/themes.rb
 - lib/recourse/helpers/times.rb
 - lib/recourse/helpers/values.rb
+- lib/recourse/helpers/weeks.rb
 - lib/recourse/helpers/zones.rb
 - lib/recourse/icons.rb
 - lib/recourse/limits.rb