keystone_ui 0.35.0 → 0.37.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2f3f4d0784444fc8cf7acde02c493fa2829dbcca367d1af4a852338b6f42212
-  data.tar.gz: 366951b7d1e19d053229c9c509db6555a8de379442e7bf0d11dfb9637992e012
+  metadata.gz: f1534a3f721376c82b75b22a653e8bcee3a0509bcd3b09cd137c93c78e15110f
+  data.tar.gz: 0df6e2e29387563688ba68bc53d8c29dc69aa322aa86c84b6416c0e3af36f703
 SHA512:
-  metadata.gz: 8f8064c88fc4ce2937ec84bff38ee5a60eab0fe03380995af9204fc2ccc58d82ec7c5cf89203ceb991088b0e0e06c6aa1b9d4106b251b099ea86e8303a686d85
-  data.tar.gz: d9453549349d298e249bab69ee78ea54d70a09c1cbf989c9aaba21c307c8525b985708f4645e3374bb99e72457954cf9c5d39c4a5f71ab7ecbe6c0e4f490f17b
+  metadata.gz: 1869494c71af590cd1fa49fcd1062b024df02950f571e5dcbd7deaaa508574ad0f0aa2bfc8e23b0dc10d35ca440a50bc12e5d18063c62888de9eb29c42c09b45
+  data.tar.gz: 45563016cb89280c2e97cca008236c9fc50ba4681486a53f0d82fc4066e7db68368ad412c43b512cb2ca4ccd4f359dd29339890e24854eae2ead04ed9db7f6db

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

@@ -1,10 +1,11 @@
 import { Controller } from "@hotwired/stimulus"
 
 export default class extends Controller {
-  static targets = ["menu", "option"]
+  static targets = ["menu", "option", "error"]
   static values = { saveUrl: String }
 
   connect() {
+    this.shown = this.optionTargets.map(option => [ option, this.checkboxIn(option).checked ])
     this._close = this.close.bind(this)
     document.addEventListener("click", this._close)
   }
@@ -66,6 +67,10 @@ export default class extends Controller {
 
   moved() {
     this.changed = true
+    this.refreshMoveButtons()
+  }
+
+  refreshMoveButtons() {
     const options = this.optionTargets
     options.forEach((option, index) => {
       option.querySelector('[data-action="click->column-picker#moveUp"]').disabled = index === 0
@@ -99,8 +104,20 @@ export default class extends Controller {
         "X-CSRF-Token": token
       },
       body: JSON.stringify({ hidden_columns: this.hiddenColumns(), column_order: this.columnOrder() })
-    }).then(() => {
+    }).then((response) => {
+      if (!response.ok) return this.failed()
+
       Turbo.visit(window.location.href, { action: "replace" })
+    }).catch(() => this.failed())
+  }
+
+  failed() {
+    this.errorTarget.classList.remove("hidden")
+    this.shown.forEach(([ option, checked ]) => {
+      option.parentNode.insertBefore(option, null)
+      this.checkboxIn(option).checked = checked
+      option.querySelector("label").classList.toggle("ks-menu-option-hidden", !checked)
     })
+    this.refreshMoveButtons()
   }
 }

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

@@ -29,4 +29,5 @@
       </div>
     <% end %>
   </div>
+  <p data-column-picker-target="error" role="alert" class="<%= ERROR_CLASSES %>">Your column changes were not saved.</p>
 </div>

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

@@ -11,6 +11,7 @@ module Keystone
       OPTION_HIDDEN_CLASSES = "ks-menu-option-hidden"
       OPTION_ROW_CLASSES = "flex items-center"
       MOVE_BUTTON_CLASSES = "ks-menu-move text-sm"
+      ERROR_CLASSES = "ks-error hidden"
 
       COLUMNS_ICON = <<~SVG.freeze
         <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor" class="w-4 h-4">
@@ -20,18 +21,17 @@ module Keystone
 
       attr_reader :save_url
 
-      def initialize(columns:, hidden_columns: [], save_url: nil)
-        @columns = columns
-        @hidden_keys = Array(hidden_columns).map(&:to_sym).to_set
+      def initialize(columns:, hidden_columns: [], save_url: nil, layout: nil)
+        @layout = layout || SavedLayout.new(columns: columns, value: nil, default_hidden: hidden_columns)
         @save_url = save_url
       end
 
       def hideable_columns
-        @columns.select(&:hideable?)
+        @layout.columns.select(&:hideable?)
       end
 
       def hidden?(key)
-        @hidden_keys.include?(key.to_sym)
+        @layout.hidden?(key)
       end
 
       def option_classes(key)

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

@@ -17,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"
@@ -30,8 +32,9 @@ module Keystone
       def initialize(items:, columns:, empty_message: nil, sort: nil, sort_direction: nil, sort_url: nil, hidden_columns: [], key: nil)
         @items = items.to_a
         @all_columns = columns.map { |col| normalize_column(col) }
-        @hidden_columns = hidden_columns
-        @columns = visible_columns(hidden_columns)
+        @default_hidden = hidden_columns
+        @layout = SavedLayout.new(columns: @all_columns, value: nil, default_hidden: hidden_columns)
+        @columns = @layout.visible_columns
         @key = key
         @empty_message = empty_message
         @sort = sort&.to_sym
@@ -61,7 +64,7 @@ module Keystone
       def column_picker
         return unless @save_url
 
-        @column_picker ||= ColumnPickerComponent.new(columns: @all_columns, hidden_columns: @hidden_columns, save_url: @save_url)
+        @column_picker ||= ColumnPickerComponent.new(columns: @all_columns, layout: @layout, save_url: @save_url)
       end
 
       def column_keys
@@ -76,6 +79,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,
@@ -119,6 +123,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),
@@ -147,25 +152,11 @@ module Keystone
         saved = KeystoneUi.configuration.supplied_preference(helpers, @key)
         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)
+        @layout = SavedLayout.new(columns: @all_columns, value: saved[:value], default_hidden: @default_hidden)
+        @columns = @layout.visible_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) }
-      end
-
       def visual_column_count
         @columns.length + (actions? ? 1 : 0)
       end

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

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Keystone
+  module Ui
+    class SavedLayout
+      def initialize(columns:, value:, default_hidden:)
+        @columns = columns
+        @value = value.is_a?(Hash) ? value : {}
+        @default_hidden = default_hidden
+      end
+
+      def columns
+        @ordered_columns ||= ordered_columns
+      end
+
+      def visible_columns
+        columns.reject { |column| hidden?(column.key) }
+      end
+
+      def hidden?(key)
+        column = @columns.find { |col| col.key == key.to_sym }
+        column&.hideable? && hidden_keys.include?(key.to_sym)
+      end
+
+      private
+
+      def ordered_columns
+        column_order = saved_list("column_order")
+        return @columns unless column_order
+
+        positions = Array(column_order).map(&:to_sym).each_with_index.to_h
+        hideable = @columns.select(&:hideable?).sort_by.with_index { |col, index| positions.fetch(col.key, positions.size + index) }
+        @columns.map { |col| col.hideable? ? hideable.shift : col }
+      end
+
+      def hidden_keys
+        @hidden_keys ||= Array(saved_list("hidden_columns") || @default_hidden).map(&:to_sym).to_set
+      end
+
+      def saved_list(name)
+        list = @value[name]
+        list if list.is_a?(Array)
+      end
+    end
+  end
+end

data/lib/keystone_ui/version.rb

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

data/the_local/agents/keystone_ui-develop.md

@@ -240,16 +240,24 @@ outer element. See Conventions before using it.
   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
+  itself, aligned right, that saves to it as `ui_column_picker` does and shows
+  the same message when a save fails, including for a person with nothing saved
+  yet. That menu lists the hideable columns in
+  the order the table shows them and leaves ticked exactly the ones the table
+  shows. 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
@@ -264,7 +272,11 @@ outer element. See Conventions before using it.
   `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
+  both lists. The endpoint must answer with a success status when it has saved
+  them. When it answers with an error status, or the request cannot reach the
+  server, the menu does not reload the page: it shows "Your column changes were
+  not saved." under the Columns button, and puts its boxes and its order back
+  to what the table shows. 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
@@ -540,8 +552,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

data/the_local/agents/keystone_ui-info.md

@@ -127,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
@@ -143,11 +150,15 @@ holds the catalog.
   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
+  down. The menu and the table read the same saved layout, so the menu's
+  ticked boxes and order always match the columns the table shows. 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.
+  changed saves nothing. When the save is refused or cannot reach the server,
+  the page does not reload. The Columns menu shows the message "Your
+  column changes were not saved." and puts its boxes and order back to what
+  the table shows.
   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.11.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.
 
@@ -248,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.
@@ -279,6 +282,11 @@ built on ViewComponent; hook it in before building any screen with those helpers
      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.
+   - The action at `save_url` must answer a stored layout with a 2xx status.
+     Any other status, or a request that cannot reach the server, leaves the
+     page unreloaded. The table then shows "Your column changes were not
+     saved." beside its Columns button, and the menu's boxes and order go back
+     to what the table shows.
    - 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
      layouts, before writing the callable.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keystone_ui
 version: !ruby/object:Gem::Version
-  version: 0.35.0
+  version: 0.37.0
 platform: ruby
 authors:
 - Tyler Schneider
@@ -175,6 +175,7 @@ files:
 - app/components/keystone/ui/progress_component.rb
 - app/components/keystone/ui/radio_card_component.html.erb
 - app/components/keystone/ui/radio_card_component.rb
+- app/components/keystone/ui/saved_layout.rb
 - app/components/keystone/ui/section_component.html.erb
 - app/components/keystone/ui/section_component.rb
 - app/components/keystone/ui/select_component.html.erb