keystone_ui 0.34.0 → 0.36.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac460729f806dac1343306018aab4560b2c75f39ad05ec5a775886c24f5084fb
-  data.tar.gz: 89e7107f63d2d0b6f4b2b27907c464b09cc44375d12fc59e7958bae8e99efbb7
+  metadata.gz: d7a0b5685fe1dc1107e8e75d274e80401826ed52616ae95c20d6a288fdc5c647
+  data.tar.gz: 8220957d8d617f0c32c71b264c84c5bf8b992a3cc2e3bb512f3f4e0a1cbf8bb0
 SHA512:
-  metadata.gz: '097bdb96a57af1b3b1f886b522fa4bd3a5be40f89b433be36df0c5c74ae895ba4c5dda568a6bbea8c5e32743ee6d072cd61ba553ee9d381fc90c8917399b768f'
-  data.tar.gz: e0b238491fc14b93e2cb32e67871290bb8a5a0d606f3663c3c839a62964ce2c8a954d1f6242a158da01713eb7e1b3565f2b3371b46c7e54607cc9e4aae77967a
+  metadata.gz: 58889e18335df436f8b13caad57648caf6ed3e13e17b50dc5d6011ae0f8fa85ceb98a9e9fd682f90cd10729ed3d3f20603ed34e438afb09a33090ec4d7493c95
+  data.tar.gz: c79c624b0a0a09e83b1f6fcee1566df17c7adf96f8141a20c8ee3ed20b361ab7faa1135be33bcf41f780e68e663e78d9ba833d27af09e72c782d4763a09463da

data/app/assets/javascripts/keystone_ui/column_picker_controller.js

@@ -15,33 +15,62 @@ export default class extends Controller {
 
   toggle(event) {
     event.stopPropagation()
-    this.menuTarget.classList.toggle("hidden")
+    if (this.menuTarget.classList.contains("hidden")) {
+      this.menuTarget.classList.remove("hidden")
+    } else {
+      this.hideMenu()
+    }
   }
 
   close(event) {
     if (!this.element.contains(event.target)) {
-      this.menuTarget.classList.add("hidden")
+      this.hideMenu()
     }
   }
 
-  save() {
-    this.send(this.columnOrder())
+  hideMenu() {
+    this.menuTarget.classList.add("hidden")
+    if (!this.changed) return
+
+    this.changed = false
+    this.send()
+  }
+
+  mark(event) {
+    const option = this.optionFor(event)
+    option.querySelector("label").classList.toggle("ks-menu-option-hidden", !this.checkboxIn(option).checked)
+    this.changed = true
+  }
+
+  optionFor(event) {
+    return event.currentTarget.closest('[data-column-picker-target="option"]')
   }
 
   moveUp(event) {
-    this.move(event, -1)
+    const option = this.optionFor(event)
+    const previous = option.previousElementSibling
+    if (!previous) return
+
+    option.parentNode.insertBefore(option, previous)
+    this.moved()
   }
 
   moveDown(event) {
-    this.move(event, 1)
+    const option = this.optionFor(event)
+    const next = option.nextElementSibling
+    if (!next) return
+
+    option.parentNode.insertBefore(next, option)
+    this.moved()
   }
 
-  move(event, step) {
-    const order = this.columnOrder()
-    const index = this.optionTargets.indexOf(event.currentTarget.closest('[data-column-picker-target="option"]'))
-    const [key] = order.splice(index, 1)
-    order.splice(index + step, 0, key)
-    this.send(order)
+  moved() {
+    this.changed = true
+    const options = this.optionTargets
+    options.forEach((option, index) => {
+      option.querySelector('[data-action="click->column-picker#moveUp"]').disabled = index === 0
+      option.querySelector('[data-action="click->column-picker#moveDown"]').disabled = index === options.length - 1
+    })
   }
 
   columnOrder() {
@@ -59,7 +88,7 @@ export default class extends Controller {
     return option.querySelector("input[type=checkbox]")
   }
 
-  send(columnOrder) {
+  send() {
     if (!this.hasSaveUrlValue) return
 
     const token = document.querySelector('meta[name="csrf-token"]')?.content
@@ -69,7 +98,7 @@ export default class extends Controller {
         "Content-Type": "application/json",
         "X-CSRF-Token": token
       },
-      body: JSON.stringify({ hidden_columns: this.hiddenColumns(), column_order: columnOrder })
+      body: JSON.stringify({ hidden_columns: this.hiddenColumns(), column_order: this.columnOrder() })
     }).then(() => {
       Turbo.visit(window.location.href, { action: "replace" })
     })

data/app/components/keystone/ui/breadcrumbs_component.rb

@@ -3,7 +3,7 @@
 module Keystone
   module Ui
     class BreadcrumbsComponent < ViewComponent::Base
-      CLASSES = "ks-mobile-header-back hidden lg:block text-sm"
+      CLASSES = "ks-mobile-header-back ks-breadcrumbs hidden lg:block text-sm"
       SEPARATOR = "›"
 
       def initialize(trail:, current: nil)

data/app/components/keystone/ui/column.rb

@@ -5,17 +5,19 @@ module Keystone
     class Column
       attr_reader :key, :header_text
 
-      def initialize(key, header_text, mobile_hidden: false, sortable: false, hideable: false)
+      def initialize(key, header_text, mobile_hidden: false, sortable: false, hideable: false, locked: false)
         @key = key
         @header_text = header_text
         @mobile_hidden = mobile_hidden
         @sortable = sortable
         @hideable = hideable
+        @locked = locked
       end
 
       def mobile_hidden? = @mobile_hidden
       def sortable? = @sortable
-      def hideable? = @hideable
+      def hideable? = @hideable && !@locked
+      def locked? = @locked
     end
   end
 end

data/app/components/keystone/ui/column_picker_component.html.erb

@@ -8,11 +8,11 @@
   <div data-column-picker-target="menu" class="<%= MENU_CLASSES %>">
     <% hideable_columns.each_with_index do |col, index| %>
       <div class="<%= OPTION_ROW_CLASSES %>" data-column-picker-target="option">
-        <label class="<%= OPTION_CLASSES %>">
+        <label class="<%= option_classes(col.key) %>">
           <input type="checkbox"
                  value="<%= col.key %>"
                  <%= "checked" unless hidden?(col.key) %>
-                 data-action="change->column-picker#save"
+                 data-action="change->column-picker#mark"
                  class="<%= CHECKBOX_CLASSES %>">
           <%= col.header_text %>
         </label>

data/app/components/keystone/ui/column_picker_component.rb

@@ -8,6 +8,7 @@ module Keystone
       MENU_CLASSES = "ks-menu absolute right-0 z-10 w-56 hidden"
       OPTION_CLASSES = "ks-menu-option flex items-center text-sm cursor-pointer"
       CHECKBOX_CLASSES = "ks-menu-checkbox"
+      OPTION_HIDDEN_CLASSES = "ks-menu-option-hidden"
       OPTION_ROW_CLASSES = "flex items-center"
       MOVE_BUTTON_CLASSES = "ks-menu-move text-sm"
 
@@ -32,6 +33,10 @@ module Keystone
       def hidden?(key)
         @hidden_keys.include?(key.to_sym)
       end
+
+      def option_classes(key)
+        hidden?(key) ? "#{OPTION_CLASSES} #{OPTION_HIDDEN_CLASSES}" : OPTION_CLASSES
+      end
     end
   end
 end

data/app/components/keystone/ui/data_table_component.html.erb

@@ -1,5 +1,7 @@
 <% if column_picker %>
-  <%= render column_picker %>
+  <div class="<%= Keystone::Ui::DataTableComponent::TOOLBAR_CLASSES %>">
+    <%= render column_picker %>
+  </div>
 <% end %>
 <div class="<%= Keystone::Ui::DataTableComponent::WRAPPER_CLASSES %>">
   <table class="relative min-w-full divide-y divide-gray-300 dark:divide-white/15">

data/app/components/keystone/ui/data_table_component.rb

@@ -7,6 +7,7 @@ module Keystone
       BODY_CLASSES = "ks-table-body"
       HEAD_CLASSES = "ks-table-head"
       WRAPPER_CLASSES = "ks-table overflow-x-auto"
+      TOOLBAR_CLASSES = "ks-table-toolbar flex justify-end"
       HEADER_CLASSES_FIRST = "ks-table-header ks-table-header-first text-left text-sm"
       HEADER_CLASSES_MIDDLE = "ks-table-header ks-table-header-middle text-left text-sm"
       HEADER_CLASSES_LAST = "ks-table-header ks-table-header-last text-right text-sm"
@@ -16,6 +17,8 @@ module Keystone
       ROW_CLASSES_LAST = "ks-table-cell-last text-right text-sm whitespace-nowrap"
 
       MOBILE_HIDDEN_CLASSES = "hidden sm:table-cell"
+      HEADER_LOCKED_CLASSES = "ks-table-header-locked sticky left-0"
+      CELL_LOCKED_CLASSES = "ks-table-cell-locked sticky left-0"
 
       SORT_LINK_CLASSES = "ks-table-sort-link group inline-flex items-center"
       SORT_ICON_CLASSES = "h-4 w-4 flex-shrink-0"
@@ -75,6 +78,7 @@ module Keystone
         cells = @columns.map.with_index do |column, index|
           tokens = [ header_classes_for(index) ]
           tokens << MOBILE_HIDDEN_CLASSES if column.mobile_hidden?
+          tokens << HEADER_LOCKED_CLASSES if index.zero? && column.locked?
 
           cell = {
             label: column.header_text,
@@ -118,6 +122,7 @@ module Keystone
           @columns.map.with_index do |column, index|
             tokens = [ row_classes_for(index) ]
             tokens << MOBILE_HIDDEN_CLASSES if column.mobile_hidden?
+            tokens << CELL_LOCKED_CLASSES if index.zero? && column.locked?
 
             cell = {
               value: resolve_value(item, column.key),

data/app/components/keystone/ui/desktop_back_link_component.rb

@@ -3,7 +3,7 @@
 module Keystone
   module Ui
     class DesktopBackLinkComponent < ViewComponent::Base
-      CLASSES = "ks-mobile-header-back hidden lg:inline-flex items-center"
+      CLASSES = "ks-mobile-header-back ks-page-back hidden lg:inline-flex items-center"
       LABEL = "Back"
 
       def initialize(url:)

data/app/components/keystone/ui/form_page_component.html.erb

@@ -2,11 +2,12 @@
 <% content_for :form_page_title, @title %>
 <% content_for :form_page_back_url, @back_url %>
 
-<% if @trail %>
-  <% content_for :keystone_page_header, render(Keystone::Ui::BreadcrumbsComponent.new(trail: @trail, current: @title)) %>
-<% else %>
+<% unless top_level? %>
   <% content_for :keystone_page_header, render(Keystone::Ui::DesktopBackLinkComponent.new(url: @back_url)) %>
 <% end %>
+<% if @trail&.any? %>
+  <% content_for :keystone_page_header, render(Keystone::Ui::BreadcrumbsComponent.new(trail: @trail, current: @title)) %>
+<% end %>
 
 <% content_for :keystone_page_header do %>
   <div class="<%= DESKTOP_WRAPPER_CLASSES %>">

data/app/components/keystone/ui/form_page_component.rb

@@ -17,10 +17,14 @@ module Keystone
       def before_render
         @trail ||= KeystoneUi.configuration.supplied_trail(helpers)
         @back_url ||= @trail&.last&.last
-        raise KeystoneUi::MissingBackLink, @title unless @back_url
+        raise KeystoneUi::MissingBackLink, @title unless @back_url || top_level?
         raise KeystoneUi::IncompleteTrail, @title if @trail&.any? { |label, href| label.blank? || href.blank? }
       end
 
+      def top_level?
+        @trail == []
+      end
+
       def subtitle?
         !@subtitle.nil?
       end

data/app/components/keystone/ui/mobile_header_component.html.erb

@@ -1,6 +1,8 @@
 <div class="<%= WRAPPER_CLASSES %>">
-  <%= link_to @back_url, class: BACK_LINK_CLASSES, aria: { label: "Back" } do %>
-    <%= BACK_ICON.html_safe %>
+  <% if @back_url %>
+    <%= link_to @back_url, class: BACK_LINK_CLASSES, aria: { label: "Back" } do %>
+      <%= BACK_ICON.html_safe %>
+    <% end %>
   <% end %>
 </div>
 <span class="<%= TITLE_CLASSES %>">

data/app/components/keystone/ui/show_page_component.html.erb

@@ -3,8 +3,9 @@
 <% content_for :show_page_back_url, @back_url %>
 <% content_for :show_page_subtitle, @subtitle if @subtitle.present? %>
 
-<% if @trail %>
-  <% content_for :keystone_page_header, render(Keystone::Ui::BreadcrumbsComponent.new(trail: @trail, current: @title)) %>
-<% else %>
+<% unless top_level? %>
   <% content_for :keystone_page_header, render(Keystone::Ui::DesktopBackLinkComponent.new(url: @back_url)) %>
 <% end %>
+<% if @trail&.any? %>
+  <% content_for :keystone_page_header, render(Keystone::Ui::BreadcrumbsComponent.new(trail: @trail, current: @title)) %>
+<% end %>

data/app/components/keystone/ui/show_page_component.rb

@@ -17,10 +17,14 @@ module Keystone
       def before_render
         @trail ||= KeystoneUi.configuration.supplied_trail(helpers)
         @back_url ||= @trail&.last&.last
-        raise KeystoneUi::MissingBackLink, @title unless @back_url
+        raise KeystoneUi::MissingBackLink, @title unless @back_url || top_level?
         raise KeystoneUi::IncompleteTrail, @title if @trail&.any? { |label, href| label.blank? || href.blank? }
       end
 
+      def top_level?
+        @trail == []
+      end
+
       def subtitle?
         !@subtitle.nil?
       end

data/lib/keystone_ui/missing_back_link.rb

@@ -3,7 +3,7 @@
 module KeystoneUi
   class MissingBackLink < StandardError
     def initialize(title)
-      super(%(The page "#{title}" has no Back link. Pass back_url: or trail:, or supply a trail for it through config.trail_supplier.))
+      super(%(The page "#{title}" has no Back link. Pass back_url: or trail:, or supply a trail for it through config.trail_supplier. A nav tab's own page passes trail: [].))
     end
   end
 end

data/lib/keystone_ui/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module KeystoneUi
-  VERSION = "0.34.0"
+  VERSION = "0.36.0"
 end

data/the_local/agents/keystone_ui-develop.md

@@ -43,8 +43,9 @@ outer element. See Conventions before using it.
   takes a block. The outer wrapper for a screen. `max_width:` `:sm` `:md` `:lg`
   `:xl` `:full`; `padding:` `:standard` or `:none`; `top_offset:` `:sm` `:md`
   `:lg` `:xl` to clear a fixed navbar. When `ui_form_page` or `ui_show_page` was
-  called earlier on the same screen, `ui_page` renders their back link or
-  breadcrumbs, and the form page's title, at its top, above the block.
+  called earlier on the same screen, `ui_page` renders their "Back" link, their
+  breadcrumbs, and the form page's title, in that order, at its top, above the
+  block.
 - `ui_section(title: nil, subtitle: nil, action: nil, menu: [], spacing: :md, class: nil)`
   — takes a block. A titled block of content with an optional right-aligned
   link. `action:` is `{ label:, href: }`; `spacing:` `:sm` `:md` `:lg`.
@@ -73,25 +74,29 @@ outer element. See Conventions before using it.
   the title and back URL so the navbar can render mobile header context, and
   hands `ui_page` a "Back" link to `back_url` shown from `lg:` up, then the
   title and subtitle shown from `md:` up. Call it before `ui_page`, outside
-  `ui_page`'s block, or none of that appears. Passing `trail:` replaces the
-  "Back" link with breadcrumbs: the trail's links followed by `title` unlinked,
-  as `ui_breadcrumbs` renders them. With no `trail:`, it uses the trail the app
-  supplies for the current request, if the app supplies one. With no
-  `back_url:`, the back URL is the `href` of the trail's last link. A `trail:`
-  or `back_url:` passed here always wins over the supplied ones. With no
-  `back_url:` and no trail from either place, or a trail that is empty or whose
-  last link has no `href`, rendering raises `KeystoneUi::MissingBackLink`, naming
-  the page's title. A trail with any link whose label or `href` is `nil` or
-  blank raises `KeystoneUi::IncompleteTrail`, naming the page's title, even when
-  `back_url:` is passed.
+  `ui_page`'s block, or none of that appears. Passing a non-empty `trail:` adds
+  breadcrumbs under the "Back" link: the trail's links followed by `title`
+  unlinked, as `ui_breadcrumbs` renders them, shown from `lg:` up. With no
+  `trail:`, it uses the trail the app supplies for the current request, if the
+  app supplies one. With no `back_url:`, the back URL is the `href` of the
+  trail's last link. A `trail:` or `back_url:` passed here always wins over the
+  supplied ones. `trail: []` marks the page a navigation tab opens directly: it
+  shows no "Back" link and no breadcrumbs, publishes no back URL when no
+  `back_url:` is passed, so the mobile header shows no back arrow, and raises
+  nothing. With no `back_url:` and no trail from either place, or a trail whose
+  last link has no `href`, rendering raises `KeystoneUi::MissingBackLink`,
+  naming the page's title. A trail with any link whose label or `href` is `nil`
+  or blank raises `KeystoneUi::IncompleteTrail`, naming the page's title, even
+  when `back_url:` is passed.
 - `ui_show_page(title:, back_url: nil, subtitle: nil, trail: nil)` — the shell
   marker for a detail screen. It renders nothing where it is called. It
   publishes the title, subtitle, and back URL for the navbar, and hands
   `ui_page` a "Back" link to `back_url` shown from `lg:` up. Call it before
   `ui_page`, outside `ui_page`'s block. It shows no title, so put
   `ui_page_header` inside the `ui_page` block for the desktop title. `trail:`
-  and `back_url:` work as they do on `ui_form_page`, including the supplied
-  trail, the fallback to the trail's last link, and the
+  and `back_url:` work as they do on `ui_form_page`, including the breadcrumbs
+  under the "Back" link, the supplied trail, the fallback to the trail's last
+  link, `trail: []` for a navigation tab's own page, and the
   `KeystoneUi::MissingBackLink` and `KeystoneUi::IncompleteTrail` errors, and
   the breadcrumbs end with `title` unlinked.
 - `ui_breadcrumbs(trail:, current: nil)` — a line of links shown only from `lg:`
@@ -116,7 +121,8 @@ outer element. See Conventions before using it.
   `icon:` is a raw SVG string.
 - `ui_mobile_header(title:, back_url:, subtitle: nil)` — a back chevron plus
   centered title for mobile; hidden above `lg:`. Place it in the navbar's
-  `mobile_left` slot.
+  `mobile_left` slot. `back_url:` must be passed, and `nil` renders the title
+  with no back chevron.
 - `ui_action_menu` — no keywords, takes a block. An ellipsis (⋯) button that
   opens a dropdown of actions, shown at every screen size. Fill the block with
   `ui_action_menu_item` calls.
@@ -233,27 +239,36 @@ outer element. See Conventions before using it.
   they were declared. Columns that are not hideable keep their declared place,
   and the hideable ones fill the remaining places. With no `"column_order"` the
   columns keep their declared order. Whenever the supplier
-  returns a save address, the table renders a "Columns" menu above itself that
-  saves to it, including for a person with nothing saved yet. When the
+  returns a save address, the table renders a "Columns" menu in a row above
+  itself, aligned right, that saves to it as `ui_column_picker` does, including
+  for a person with nothing saved yet. When the
   supplier returns nothing, when no supplier is set, or when no `key:` is
   passed, the table renders from `hidden_columns:` with no Columns menu. In
   every case `hidden_columns:` is the table's default layout.
-- `Keystone::Ui::Column.new(key, header_text, mobile_hidden: false, sortable: false, hideable: false)`
+- `Keystone::Ui::Column.new(key, header_text, mobile_hidden: false, sortable: false, hideable: false, locked: false)`
   — a column with per-column options, for when a `{ key: "Label" }` hash is not
   enough. `mobile_hidden:` hides the column below `sm:`; `sortable:` opts it into
   sort headers; `hideable:` lets the Columns menu hide it and move it, and a
-  saved `"column_order"` place it.
+  saved `"column_order"` place it. `locked: true` on the table's first column
+  keeps its header and cells in view while the rest of the table scrolls
+  sideways. A locked column that is not first renders as an ordinary column. A
+  locked column is never hideable, even with `hideable: true`: it is left out of
+  the Columns menu, `hidden_columns:` and a saved layout cannot hide it, and a
+  saved `"column_order"` cannot move it.
 - `ui_column_picker(columns:, hidden_columns: [], save_url: nil)` — a "Columns"
   dropdown with one row per `hideable` column, in the order `columns:` lists
   them. Each row has a checkbox and an up and a down button that move the
   column one place; the first row's up button and the last row's down button
-  are disabled. Pass it the same columns, in the order the table shows them,
-  and the same hidden keys as the table. On a checkbox change or a move it
-  sends `PATCH save_url` with JSON
-  `{ "hidden_columns": ["key", ...], "column_order": ["key", ...] }` and a
-  `X-CSRF-Token` header, then reloads the page. `column_order` lists every
-  hideable column's key in the menu's order after the move. With no
-  `save_url:` it sends nothing. The app must provide that endpoint and persist
+  are disabled, and after a move the disabled buttons follow the new first and
+  last rows. A hidden column's name renders greyed, and unticking a box greys
+  its name at once. Pass it the same columns, in the order the table shows
+  them, and the same hidden keys as the table. Ticking, unticking and moving
+  change only the open menu and send nothing. When the menu closes, by its
+  Columns button or by a click outside it, it sends one `PATCH save_url` with
+  JSON `{ "hidden_columns": ["key", ...], "column_order": ["key", ...] }` and a
+  `X-CSRF-Token` header, then reloads the page. A menu closed with nothing
+  changed sends nothing. `column_order` lists every hideable column's key in
+  the menu's order when it closes. With no `save_url:` it sends nothing. The app must provide that endpoint and persist
   both lists. The picker does not reorder the table: beside a table without
   `key:`, the app must pass the table and the picker its columns in the saved
   order itself. A table
@@ -454,8 +469,11 @@ outer element. See Conventions before using it.
    detail screen without `ui_page` shows no desktop "Back" link or form title.
    Those shells supply the desktop "Back" link themselves, so never add a
    second back link or button to those screens. Whether a screen
-   shows that "Back" link or breadcrumbs, and which parent screens the trail
-   names, is the developer's choice, so ask before passing `trail:`. Check
+   shows breadcrumbs under its "Back" link, and which parent screens the trail
+   names, is the developer's choice, so ask before passing `trail:`. A screen
+   a navigation tab opens directly, such as a bottom tab's own page, passes
+   `trail: []` and no `back_url:`, so it shows no "Back" link and no back
+   arrow; which screens those are is the developer's choice, so ask. Check
    first whether the app's Keystone UI initializer sets a `trail_supplier`,
    which supplies a trail for every request: if it
    does, a screen whose supplied trail is right passes neither `trail:` nor
@@ -527,8 +545,16 @@ outer element. See Conventions before using it.
 
 6. For a table, decide how columns are declared. Use `{ key: "Label" }` hashes
    when every column is plain. Switch the whole set to `Keystone::Ui::Column`
-   objects as soon as one column needs `mobile_hidden:`, `sortable:`, or
-   `hideable:`.
+   objects as soon as one column needs `mobile_hidden:`, `sortable:`,
+   `hideable:`, or `locked:`.
+
+   To keep a wide table's first column, such as a name, in view while the rest
+   scrolls sideways, declare it first with `locked: true`. Whether a table locks
+   its first column is the developer's choice, so ask rather than pick. If the
+   locked column stays in place but the scrolled columns show through its
+   cells, the app's keystone_ui-styles version does not define the
+   `ks-table-header-locked` and `ks-table-cell-locked` classes, so stop and hand
+   that part to `keystone_ui-install`, and add no classes to fix it.
 
    For a table whose hideable columns a user should be able to choose and keep,
    check whether the app's Keystone UI initializer sets a
@@ -539,7 +565,10 @@ outer element. See Conventions before using it.
    names the table, which columns are hideable, and which it hides by default
    are the developer's choice, so ask rather than pick. If the app sets no supplier, either use `ui_column_picker`
    with an endpoint the app owns, as in step 7, or hand setting up a supplier to
-   `keystone_ui-install`, and ask the developer which.
+   `keystone_ui-install`, and ask the developer which. If a Columns menu shows
+   no greyed name for a hidden column, the app's keystone_ui-styles version is
+   older than 0.11.0, so stop and hand that part to `keystone_ui-install`, and
+   add no classes to fix it.
 
 7. Wire up anything that posts back. Several helpers render controls whose
    endpoints the app must own — the column picker's save URL, the pipeline's box

data/the_local/agents/keystone_ui-info.md

@@ -26,21 +26,24 @@ component updates every page that uses it. It is mobile-first — components shi
 separate mobile and desktop treatments (a bottom tab bar and mobile header on
 small screens, a full navigation bar from the `lg:` breakpoint up), because
 these apps are often viewed in a native webview. The form and show page shells
-follow the same split for going back: the mobile header carries the back link on
+follow the same split for going back: the mobile header carries the back arrow on
 small screens, and from `lg:` up the shell shows a "Back" link. Given a trail of
-earlier pages instead, the shell shows breadcrumbs in place of that link, ending
-with the page's own title. A page that passes no trail gets the one the app or
+earlier pages, the shell shows breadcrumbs under that "Back" link, ending with
+the page's own title. A page that passes no trail gets the one the app or
 another gem supplies for the request, if any, and a page that passes no back
 link goes back to that trail's last link. A trail or back link the page passes
 itself always wins. Supplying a trail is set up through the install local.
 
-Every form and show page must end up with a Back link. A page with no back
-link, no trail and no supplied trail raises `KeystoneUi::MissingBackLink` when it
-renders, and the message names the page's title. A trail with a link missing
-its label or its address raises `KeystoneUi::IncompleteTrail`, also naming the
-page. That link or those breadcrumbs, and the form page's title, appear at the
-top of the page container, inside its width and padding, so a page using either
-shell also uses the page container.
+A nav tab's own page has nowhere to go back to, and it says so by passing an
+empty trail. Such a page shows no "Back" link and no breadcrumbs, and its mobile
+header shows no back arrow. Every other form and show page must end up with a
+Back link. A page with no back link, no trail and no supplied trail raises
+`KeystoneUi::MissingBackLink` when it renders, and the message names the page's
+title and says an empty trail marks a nav tab's page. A trail with a link
+missing its label or its address raises `KeystoneUi::IncompleteTrail`, also
+naming the page. The "Back" link, the breadcrumbs and the form page's title
+appear at the top of the page container, inside its width and padding, so a
+page using either shell also uses the page container.
 
 ## Interface
 
@@ -124,6 +127,13 @@ holds the catalog.
 - **The last table column is right-aligned.** In a data table with no actions
   column, the last column's header is right-aligned like the cells beneath it,
   so a figure or total placed in that header lines up with the figures below.
+- **A locked first column.** A table column can be marked locked. When it is
+  the table's first column, its header and cells stay in view while the rest
+  of the table scrolls sideways, styled by keystone_ui-styles' locked header
+  and cell classes. A locked column anywhere else renders as an ordinary
+  column. A locked column cannot be hidden or moved, so it never appears in the
+  "Columns" menu and a saved layout leaves it where it is, even when it is also
+  marked hideable.
 - **Saved table layouts.** A data table can be given a key naming it. A table
   with a key asks the app, or another gem such as keystone_ui-preferences, for
   the layout saved under that key for the request. A saved layout lists the
@@ -137,11 +147,14 @@ holds the catalog.
   out follow the ones it names. Every other column keeps its place, and a
   layout with no order keeps the order the columns were declared in. When the
   supplier gives an address to save to, a "Columns" menu appears above the
-  table and saves the user's choice there, even before anything has been
-  saved. The menu lists the hideable columns in the order the table shows
-  them, each with a box to show or hide it and buttons to move it up or down.
-  Ticking a box or moving a column saves the hidden columns and the order
-  together, then reloads the page.
+  table, at its right, and saves the user's choice there, even before anything
+  has been saved. The menu lists the hideable columns in the order the table
+  shows them, each with a box to show or hide it and buttons to move it up or
+  down. An unticked column's name is greyed at once. Ticking boxes and moving
+  columns sends nothing while the menu is open. Closing the menu, with its
+  Columns button or by clicking anywhere outside it, saves the hidden columns
+  and the order together once, then reloads the page. Closing it with nothing
+  changed saves nothing.
   A table with no key, or an app with no supplier, renders from its own call
   alone. Setting up the supplier belongs to the install local.
 - **Suggestions.** A form field can carry a list of suggested values. The

data/the_local/agents/keystone_ui-install.md

@@ -43,7 +43,7 @@ built on ViewComponent; hook it in before building any screen with those helpers
 ## How to use it
 
 1. Confirm the prerequisites: Ruby >= 3.2 and **tailwindcss-rails v4+** in the
-   host app. The gem brings ViewComponent and keystone_ui-styles 0.10.0 or later with it.
+   host app. The gem brings ViewComponent and keystone_ui-styles 0.12.0 or later with it.
    Tailwind does not have to be initialized first, because the generator creates
    the stylesheet if it is missing.
 
@@ -213,26 +213,31 @@ built on ViewComponent; hook it in before building any screen with those helpers
      name for the request. A name that is not registered, or `nil`, leaves the
      page on the default look.
    - `trail_supplier` — a callable that receives the view and returns the
-     breadcrumb trail as an array of `[label, href]` pairs, or `nil`. A form or
-     show page that passes no trail of its own shows the supplied one on `lg:`
-     screens, ending with the page's title, in place of the desktop "Back" link.
-     A page that passes no Back link goes back to the trail's last link. A page
-     that passes its own trail or Back link keeps it. With no supplier, or a
-     `nil` return, the page shows its Back link. Return `nil`, not an empty
-     array, for a page with no trail. An empty array replaces the page's Back
-     link with breadcrumbs holding only its title, and on a page that passes
-     no Back link it raises `KeystoneUi::MissingBackLink`.
-   - Every form and show page must end up with a Back link. A page that passes
-     no Back link and no trail, and gets no trail from the supplier, raises
-     `KeystoneUi::MissingBackLink` naming the page's title when it renders.
-     So does a page whose trail's last link has no address.
-   - Every link the supplier returns needs both a label and an address. A trail
-     with a blank label or address raises `KeystoneUi::IncompleteTrail` naming
-     the page's title.
-   - Ask the developer which code in the app knows each page's trail before
-     writing the callable. If some form or show pages pass no `back_url:`, ask
-     where their Back link should come from before enabling the supplier or
-     leaving it out.
+     breadcrumb trail as an array of `[label, href]` pairs, an empty array, or
+     `nil`. It is asked only by a form or show page that passes no `trail:`.
+     A page that passes its own trail, including an empty one, keeps it.
+   - On `lg:` screens a form or show page shows a "Back" link, and under it the
+     breadcrumbs ending with the page's title when the trail has any links. A
+     page that passes no `back_url:` goes back to the trail's last link. With
+     no supplier, or a `nil` return, the page shows only its Back link.
+   - An empty trail marks a nav tab's own page, which has nowhere to go back
+     to. The page shows no Back link and no breadcrumbs, and raises nothing.
+     Return `[]` from the supplier for those
+     pages, and `nil` for a page whose Back link comes from its own
+     `back_url:`.
+   - Every other form and show page must end up with a Back link. A page that
+     passes no `back_url:`, and has no trail or a trail whose last link has no
+     address, raises `KeystoneUi::MissingBackLink` naming the page's title when
+     it renders. The message tells the developer to pass `back_url:` or
+     `trail:`, to supply a trail through `trail_supplier`, or to pass
+     `trail: []` on a nav tab's own page.
+   - Every link in a trail needs both a label and an address. A trail with a
+     blank label or address raises `KeystoneUi::IncompleteTrail` naming the
+     page's title.
+   - Ask the developer which code in the app knows each page's trail, and which
+     pages are nav tabs' own pages, before writing the callable. If some form
+     or show pages pass no `back_url:`, ask where their Back link should come
+     from before enabling the supplier or leaving it out.
    - `preference_supplier` — a callable that receives the view and a data
      table's key and returns `{ value:, save_url: }`, or `nil` when the person
      can neither see nor save a layout for that key. It is asked only for
@@ -243,6 +248,9 @@ built on ViewComponent; hook it in before building any screen with those helpers
      `"hidden_columns"`, such as `{ "hidden_columns" => ["sku"] }`. That list
      replaces the hidden columns the table's own call passes, and an empty list
      shows every column. Only columns marked hideable are hidden.
+   - A column marked locked is never hideable, even when it is also marked
+     hideable. A saved layout cannot hide it or move it, and the Columns menu
+     does not list it.
    - When `value` is `nil`, or has no `"hidden_columns"` string key, the table
      keeps the hidden columns its own call passes. A symbol key is not read, so
      `{ hidden_columns: [...] }` also keeps them.
@@ -257,13 +265,18 @@ built on ViewComponent; hook it in before building any screen with those helpers
    - When nothing is saved yet for a person who may save a layout, return
      `{ value: nil, save_url: }`. The table then shows its own default layout
      with the Columns menu, so the person can save a first layout.
-   - When `save_url` is present, the table shows a Columns menu above itself.
-     It lists the hideable columns in the order the table shows them, with the
-     currently hidden columns unchecked, and gives each column an up and a down
-     button. Ticking or unticking a column, or moving one, sends a `PATCH` to
-     `save_url` with the page's CSRF token and the JSON body
-     `{"hidden_columns": [...], "column_order": [...]}`, then reloads the page.
-     `column_order` lists every hideable column's name in the menu's order.
+   - When `save_url` is present, the table shows a Columns button above its
+     right edge. The button opens a menu listing the hideable columns in the
+     order the table shows them, with the currently hidden columns unchecked,
+     and gives each column an up and a down button.
+   - Ticking, unticking and moving columns change only the menu while it is
+     open. When the menu is closed, by its Columns button or by a click
+     outside it, it sends one `PATCH` to `save_url` if anything was changed
+     while it was open, then reloads the page. A menu closed with no change
+     sends nothing.
+   - The `PATCH` carries the page's CSRF token and the JSON body
+     `{"hidden_columns": [...], "column_order": [...]}`. `column_order` lists
+     every hideable column's name in the menu's order.
    - The host must have a route and action at `save_url` that store both lists
      for that key. The supplier must return them in `value` under the same
      string keys, `"hidden_columns"` and `"column_order"`, or the saved order

data/the_local/interface.yml

@@ -125,6 +125,7 @@ sources:
   - app/components/keystone/ui/action_menu_component.rb
   - app/components/keystone/ui/action_menu_item_component.rb
   - app/components/keystone/ui/mobile_header_component.rb
+  - app/components/keystone/ui/mobile_header_component.html.erb
   - app/components/keystone/ui/modal_component.rb
   - app/components/keystone/ui/multi_select_component.rb
   - app/components/keystone/ui/nav_dropdown_component.rb

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keystone_ui
 version: !ruby/object:Gem::Version
-  version: 0.34.0
+  version: 0.36.0
 platform: ruby
 authors:
 - Tyler Schneider
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.10.0
+        version: 0.12.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.10.0
+        version: 0.12.0
 - !ruby/object:Gem::Dependency
   name: view_component
   requirement: !ruby/object:Gem::Requirement