keystone_ui 0.33.1 → 0.35.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: af9ebb3caf69815bf6272cf2f67028d1f4e7a98b44f5e8fb0c70654a54b84303
-  data.tar.gz: a0465bf4038d273df4d29aca184443640f113a73260842c7590e12d040557a18
+  metadata.gz: c2f3f4d0784444fc8cf7acde02c493fa2829dbcca367d1af4a852338b6f42212
+  data.tar.gz: 366951b7d1e19d053229c9c509db6555a8de379442e7bf0d11dfb9637992e012
 SHA512:
-  metadata.gz: 986eb9e5c25dfafa87579cec226b9a7ec3511478a0a402158e2a5279f290311e3e6d513a2f082f331d01e5f2d0fd73463f7bf108a401276530963a2cecbec977
-  data.tar.gz: 1a0c99faa3fd4c3c03863adf0a467cd53de595367af6cf015c6ffe6afab5e2b31b7713110341b26aad4dd11b6ecd626146020a9aef9549b7c6e600886e383cfa
+  metadata.gz: 8f8064c88fc4ce2937ec84bff38ee5a60eab0fe03380995af9204fc2ccc58d82ec7c5cf89203ceb991088b0e0e06c6aa1b9d4106b251b099ea86e8303a686d85
+  data.tar.gz: d9453549349d298e249bab69ee78ea54d70a09c1cbf989c9aaba21c307c8525b985708f4645e3374bb99e72457954cf9c5d39c4a5f71ab7ecbe6c0e4f490f17b

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

@@ -1,7 +1,7 @@
 import { Controller } from "@hotwired/stimulus"
 
 export default class extends Controller {
-  static targets = ["menu"]
+  static targets = ["menu", "option"]
   static values = { saveUrl: String }
 
   connect() {
@@ -15,33 +15,92 @@ 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() {
-    const allCheckboxes = this.element.querySelectorAll("input[type=checkbox]")
-    const hiddenColumns = Array.from(allCheckboxes)
-      .filter(cb => !cb.checked)
-      .map(cb => cb.value)
-
-    if (this.hasSaveUrlValue) {
-      const token = document.querySelector('meta[name="csrf-token"]')?.content
-      fetch(this.saveUrlValue, {
-        method: "PATCH",
-        headers: {
-          "Content-Type": "application/json",
-          "X-CSRF-Token": token
-        },
-        body: JSON.stringify({ hidden_columns: hiddenColumns })
-      }).then(() => {
-        Turbo.visit(window.location.href, { action: "replace" })
-      })
-    }
+  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) {
+    const option = this.optionFor(event)
+    const previous = option.previousElementSibling
+    if (!previous) return
+
+    option.parentNode.insertBefore(option, previous)
+    this.moved()
+  }
+
+  moveDown(event) {
+    const option = this.optionFor(event)
+    const next = option.nextElementSibling
+    if (!next) return
+
+    option.parentNode.insertBefore(next, option)
+    this.moved()
+  }
+
+  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() {
+    return this.optionTargets.map(option => this.checkboxIn(option).value)
+  }
+
+  hiddenColumns() {
+    return this.optionTargets
+      .map(option => this.checkboxIn(option))
+      .filter(checkbox => !checkbox.checked)
+      .map(checkbox => checkbox.value)
+  }
+
+  checkboxIn(option) {
+    return option.querySelector("input[type=checkbox]")
+  }
+
+  send() {
+    if (!this.hasSaveUrlValue) return
+
+    const token = document.querySelector('meta[name="csrf-token"]')?.content
+    fetch(this.saveUrlValue, {
+      method: "PATCH",
+      headers: {
+        "Content-Type": "application/json",
+        "X-CSRF-Token": token
+      },
+      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_picker_component.html.erb

@@ -6,15 +6,27 @@
     Columns
   </button>
   <div data-column-picker-target="menu" class="<%= MENU_CLASSES %>">
-    <% hideable_columns.each do |col| %>
-      <label class="<%= OPTION_CLASSES %>">
-        <input type="checkbox"
-               value="<%= col.key %>"
-               <%= "checked" unless hidden?(col.key) %>
-               data-action="change->column-picker#save"
-               class="<%= CHECKBOX_CLASSES %>">
-        <%= col.header_text %>
-      </label>
+    <% hideable_columns.each_with_index do |col, index| %>
+      <div class="<%= OPTION_ROW_CLASSES %>" data-column-picker-target="option">
+        <label class="<%= option_classes(col.key) %>">
+          <input type="checkbox"
+                 value="<%= col.key %>"
+                 <%= "checked" unless hidden?(col.key) %>
+                 data-action="change->column-picker#mark"
+                 class="<%= CHECKBOX_CLASSES %>">
+          <%= col.header_text %>
+        </label>
+        <button type="button"
+                data-action="click->column-picker#moveUp"
+                aria-label="Move up"
+                <%= "disabled" if index.zero? %>
+                class="<%= MOVE_BUTTON_CLASSES %>">&uarr;</button>
+        <button type="button"
+                data-action="click->column-picker#moveDown"
+                aria-label="Move down"
+                <%= "disabled" if index == hideable_columns.size - 1 %>
+                class="<%= MOVE_BUTTON_CLASSES %>">&darr;</button>
+      </div>
     <% end %>
   </div>
 </div>

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

@@ -8,6 +8,9 @@ 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"
 
       COLUMNS_ICON = <<~SVG.freeze
         <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" class="w-4 h-4">
@@ -30,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"
@@ -147,10 +148,19 @@ module Keystone
         return unless saved
 
         @hidden_columns = saved[:value].to_h.fetch("hidden_columns", @hidden_columns)
+        @all_columns = ordered_columns(saved[:value].to_h["column_order"])
         @columns = visible_columns(@hidden_columns)
         @save_url = saved[:save_url]
       end
 
+      def ordered_columns(column_order)
+        return @all_columns unless column_order
+
+        positions = Array(column_order).map(&:to_sym).each_with_index.to_h
+        hideable = @all_columns.select(&:hideable?).sort_by.with_index { |col, index| [ positions.fetch(col.key, positions.size + index) ] }
+        @all_columns.map { |col| col.hideable? ? hideable.shift : col }
+      end
+
       def visible_columns(hidden_columns)
         hidden_keys = Array(hidden_columns).map(&:to_sym).to_set
         @all_columns.reject { |col| col.hideable? && hidden_keys.include?(col.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.33.1"
+  VERSION = "0.35.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.
@@ -227,21 +233,40 @@ outer element. See Conventions before using it.
   key that lists `"hidden_columns"`, the hideable columns in that list replace
   the ones passed in `hidden_columns:`, and a saved empty list shows every
   column. When the saved value is `nil` or lists no `"hidden_columns"`, the
-  table keeps the columns `hidden_columns:` hides. 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
+  table keeps the columns `hidden_columns:` hides. When the saved value lists
+  `"column_order"`, an array of column keys, the hideable columns render in
+  that order, followed by any hideable columns the list leaves out in the order
+  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 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)`
   — 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 column picker hide it.
+  sort headers; `hideable:` lets the Columns menu hide it and move it, and a
+  saved `"column_order"` place it.
 - `ui_column_picker(columns:, hidden_columns: [], save_url: nil)` — a "Columns"
-  dropdown of checkboxes for every `hideable` column. Pass it the same columns
-  and hidden keys as the table. On toggle it sends `PATCH save_url` with JSON
-  `{ "hidden_columns": ["key", ...] }` and a `X-CSRF-Token` header, then reloads
-  the page. The app must provide that endpoint and persist the list. A table
+  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, 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
   given `key:` renders its own Columns menu when the supplier gives a save
   address, so never add `ui_column_picker` beside such a table.
 
@@ -439,8 +464,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
@@ -518,11 +546,16 @@ outer element. See Conventions before using 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
    `preference_supplier`. If it does, pass `key:` and the default
-   `hidden_columns:`, and add no `ui_column_picker`. Which key names the table
-   and which columns 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`
+   `hidden_columns:`, and add no `ui_column_picker`. The order the columns are
+   declared in is the default order, and only columns declared
+   `hideable: true` can be hidden or moved from the Columns menu. Which key
+   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
 
@@ -131,9 +134,20 @@ holds the catalog.
   the table's own call hides are its default layout. A saved layout that lists
   columns to hide replaces that default, and a saved empty list shows every
   column. When nothing is saved, or the saved layout lists no columns to hide,
-  the table keeps its default. 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 table keeps its default. A saved layout can also list an order for the
+  columns. Only hideable columns move: they fill the places hideable columns
+  held in the table's own call, in the saved order, and any the order leaves
+  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, 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

@@ -26,8 +26,9 @@ built on ViewComponent; hook it in before building any screen with those helpers
   `look_supplier` (which registered look a page gets),
   `trail_supplier` (a callable that supplies the breadcrumb trail for form and
   show pages that pass none, and their Back link when they pass none either),
-  `preference_supplier` (a callable that supplies the saved column layout of a
-  data table given a `key:`, and the address its Columns menu saves to),
+  `preference_supplier` (a callable that supplies the saved hidden columns and
+  column order of a data table given a `key:`, and the address its Columns menu
+  saves to),
   and the `tailwind_imports` and `tailwind_sources` lists (extra CSS files and
   scan paths added to the Tailwind build).
 - `keystone_theme_attributes` — a layout helper placed inside the `<html>` tag.
@@ -42,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.11.0 or later with it.
    Tailwind does not have to be initialized first, because the generator creates
    the stylesheet if it is missing.
 
@@ -212,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
@@ -245,15 +251,33 @@ built on ViewComponent; hook it in before building any screen with those helpers
    - 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.
+   - `value` may also hold a list of hideable column names under the string
+     key `"column_order"`, such as
+     `{ "hidden_columns" => ["sku"], "column_order" => ["price", "sku"] }`.
+     The table renders its hideable columns in that order, in the places
+     hideable columns hold in its own call, then any hideable columns the list
+     leaves out in the order they were declared. Columns that are not hideable
+     keep their place, and names that match no hideable column are ignored.
+     With no `"column_order"` string key the columns keep their declared order.
    - 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,
-     with the currently hidden columns unchecked.
-     Toggling a column sends a `PATCH` to `save_url` with the JSON body
-     `{"hidden_columns": [...]}` and the page's CSRF token, then reloads the
-     page. The host must have a route and action at that address that store the
-     list for that key. With no `save_url`, the saved layout applies and no menu
+   - 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
+     is not applied. With no `save_url`, the saved layout applies and no menu
      is shown.
    - A companion preferences gem may set this supplier for the app. Ask the
      developer whether the app uses one, or which code stores each user's table

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.33.1
+  version: 0.35.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