keystone_ui 0.33.0 → 0.34.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 599c6b4269b4ca049a5aefe106cb71dc6205554c49fb6e72824f25cc3b6f2597
-  data.tar.gz: 390d82ea8082927248351ba74796fde3a05afe4994b151c79169e0cb190ecacd
+  metadata.gz: ac460729f806dac1343306018aab4560b2c75f39ad05ec5a775886c24f5084fb
+  data.tar.gz: 89e7107f63d2d0b6f4b2b27907c464b09cc44375d12fc59e7958bae8e99efbb7
 SHA512:
-  metadata.gz: 2b44fd40afcc3d275dab96ab0401f2748a5555d5e38eb319af16d998454e30f094d9e799603658b0597b7a0e8688a9a8d864aa2e170c3b750d5351a37db123d5
-  data.tar.gz: 65064fb15715bcebbe95efadb89b2a395d06889b6d4962467faeac520df18f88083acd7f5d23ffe8c6057f9434916906861a4c3f02515ae4306cf545bf9eba23
+  metadata.gz: '097bdb96a57af1b3b1f886b522fa4bd3a5be40f89b433be36df0c5c74ae895ba4c5dda568a6bbea8c5e32743ee6d072cd61ba553ee9d381fc90c8917399b768f'
+  data.tar.gz: e0b238491fc14b93e2cb32e67871290bb8a5a0d606f3663c3c839a62964ce2c8a954d1f6242a158da01713eb7e1b3565f2b3371b46c7e54607cc9e4aae77967a

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() {
@@ -25,23 +25,53 @@ export default class extends Controller {
   }
 
   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" })
-      })
-    }
+    this.send(this.columnOrder())
+  }
+
+  moveUp(event) {
+    this.move(event, -1)
+  }
+
+  moveDown(event) {
+    this.move(event, 1)
+  }
+
+  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)
+  }
+
+  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(columnOrder) {
+    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: columnOrder })
+    }).then(() => {
+      Turbo.visit(window.location.href, { action: "replace" })
+    })
   }
 }

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 %>">
+          <input type="checkbox"
+                 value="<%= col.key %>"
+                 <%= "checked" unless hidden?(col.key) %>
+                 data-action="change->column-picker#save"
+                 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,8 @@ 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_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">

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

@@ -146,11 +146,20 @@ module Keystone
         saved = KeystoneUi.configuration.supplied_preference(helpers, @key)
         return unless saved
 
-        @hidden_columns = saved[:value]["hidden_columns"]
+        @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/lib/keystone_ui/version.rb

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

data/the_local/agents/keystone_ui-develop.md

@@ -224,21 +224,39 @@ outer element. See Conventions before using it.
   server-side and only affects columns declared `hideable: true`. `key:` (a
   symbol or string) names the table so it looks up a saved layout through the
   app's preference supplier. When the supplier returns a saved value for the
-  key, the hideable columns listed under its `"hidden_columns"` replace the
-  ones passed in `hidden_columns:`, and when it also returns a save address the
-  table renders a "Columns" menu above itself that saves to it. When the
+  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. 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 above itself that
+  saves to it, 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, so
-  `hidden_columns:` is the table's default layout.
+  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. 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
+  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.
 
@@ -515,9 +533,11 @@ 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.
 

data/the_local/agents/keystone_ui-info.md

@@ -127,11 +127,21 @@ holds the catalog.
 - **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
-  columns to hide, and only columns marked hideable can be hidden. When a
-  layout is saved, it replaces the columns the table hides by default. When
-  nothing is saved, the table hides the columns its own call names, so those
-  are its default layout. When the supplier also gives an address to save to,
-  a "Columns" menu appears above the table and saves the user's choice there.
+  columns to hide, and only columns marked hideable can be hidden. The columns
+  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. 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 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.
   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.
@@ -233,19 +234,40 @@ built on ViewComponent; hook it in before building any screen with those helpers
      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 nothing is
-     saved for that key. It is asked only for tables rendered with a `key:`. A
-     table with no `key:`, a supplier returning `nil`, or no supplier at all
-     renders with the hidden columns its own call passes.
-   - `value` must hold the hidden column names under the string key
-     `"hidden_columns"`, such as `{ "hidden_columns" => ["sku"] }`. A symbol key
-     is not read, and the table then hides no columns. Only columns marked
-     hideable are hidden.
+     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
+     tables rendered with a `key:`. A table with no `key:`, a supplier returning
+     `nil`, or no supplier at all renders with the hidden columns its own call
+     passes and shows no Columns menu.
+   - `value` holds the hidden column names under the string key
+     `"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.
+   - 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.
-     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
+     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.
+   - 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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keystone_ui
 version: !ruby/object:Gem::Version
-  version: 0.33.0
+  version: 0.34.0
 platform: ruby
 authors:
 - Tyler Schneider