keystone_ui 0.32.0 → 0.33.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 530dc14cf871e579dcccc21f769b304974a36af552e10e2a9eee6f0b90e531ae
-  data.tar.gz: 69ed4079d0a6fb130e50ba08afdf4b6c1ba37d8f25b035b06e686bdccdd5f1a3
+  metadata.gz: af9ebb3caf69815bf6272cf2f67028d1f4e7a98b44f5e8fb0c70654a54b84303
+  data.tar.gz: a0465bf4038d273df4d29aca184443640f113a73260842c7590e12d040557a18
 SHA512:
-  metadata.gz: 4d2f5fc1618dbe5b16114c4475d8b0e987f8e0516ed80aecfaace0741ccdad791214ffa758dd65c742d946285b26277c1345963ff9e1fa7175b9b1ff67d21f67
-  data.tar.gz: bb6877b8c6e890e4010b679ad81fa07e00bde9ccbfc73d983d666c0a97ed8182833d150c7e4535e095e1ff5d98ffe7aa3c8cab067b366e2db7c313e6b29baa00
+  metadata.gz: 986eb9e5c25dfafa87579cec226b9a7ec3511478a0a402158e2a5279f290311e3e6d513a2f082f331d01e5f2d0fd73463f7bf108a401276530963a2cecbec977
+  data.tar.gz: 1a0c99faa3fd4c3c03863adf0a467cd53de595367af6cf015c6ffe6afab5e2b31b7713110341b26aad4dd11b6ecd626146020a9aef9549b7c6e600886e383cfa

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

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

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

@@ -26,11 +26,12 @@ module Keystone
       SORT_DESC_ICON = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor"><path fill-rule="evenodd" d="M10 3a.75.75 0 0 1 .75.75v10.638l3.96-4.158a.75.75 0 1 1 1.08 1.04l-5.25 5.5a.75.75 0 0 1-1.08 0l-5.25-5.5a.75.75 0 0 1 1.08-1.04l3.96 4.158V3.75A.75.75 0 0 1 10 3Z" clip-rule="evenodd" /></svg>'
       SORT_NEUTRAL_ICON = '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 20 20" fill="currentColor"><path fill-rule="evenodd" d="M10 3a.75.75 0 0 1 .55.24l3.25 3.5a.75.75 0 1 1-1.1 1.02L10 4.852 7.3 7.76a.75.75 0 0 1-1.1-1.02l3.25-3.5A.75.75 0 0 1 10 3Zm-3.76 9.2a.75.75 0 0 1 1.06.04l2.7 2.908 2.7-2.908a.75.75 0 1 1 1.1 1.02l-3.25 3.5a.75.75 0 0 1-1.1 0l-3.25-3.5a.75.75 0 0 1 .04-1.06Z" clip-rule="evenodd" /></svg>'
 
-      def initialize(items:, columns:, empty_message: nil, sort: nil, sort_direction: nil, sort_url: nil, hidden_columns: [])
+      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_keys = Array(hidden_columns).map(&:to_sym).to_set
-        @columns = all_columns.reject { |col| col.hideable? && hidden_keys.include?(col.key) }
+        @all_columns = columns.map { |col| normalize_column(col) }
+        @hidden_columns = hidden_columns
+        @columns = visible_columns(hidden_columns)
+        @key = key
         @empty_message = empty_message
         @sort = sort&.to_sym
         @sort_direction = sort_direction&.to_sym
@@ -41,6 +42,7 @@ module Keystone
 
       def before_render
         content
+        apply_saved_layout if @key
       end
 
       def link(column_key, &block)
@@ -55,6 +57,12 @@ module Keystone
         !!@actions_block
       end
 
+      def column_picker
+        return unless @save_url
+
+        @column_picker ||= ColumnPickerComponent.new(columns: @all_columns, hidden_columns: @hidden_columns, save_url: @save_url)
+      end
+
       def column_keys
         @column_keys ||= @columns.map(&:key)
       end
@@ -134,6 +142,20 @@ module Keystone
 
       private
 
+      def apply_saved_layout
+        saved = KeystoneUi.configuration.supplied_preference(helpers, @key)
+        return unless saved
+
+        @hidden_columns = saved[:value].to_h.fetch("hidden_columns", @hidden_columns)
+        @columns = visible_columns(@hidden_columns)
+        @save_url = saved[:save_url]
+      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/lib/keystone_ui/configuration.rb

@@ -2,7 +2,7 @@
 
 module KeystoneUi
   class Configuration
-    attr_accessor :accent, :surface, :theme_mode_supplier, :look_supplier, :trail_supplier
+    attr_accessor :accent, :surface, :theme_mode_supplier, :look_supplier, :trail_supplier, :preference_supplier
     attr_reader :tailwind_imports, :tailwind_sources, :looks, :default_look
 
     def initialize
@@ -33,6 +33,10 @@ module KeystoneUi
     def supplied_trail(view)
       trail_supplier&.call(view)
     end
+
+    def supplied_preference(view, key)
+      preference_supplier&.call(view, key)
+    end
   end
 
   def self.configuration

data/lib/keystone_ui/version.rb

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

data/the_local/agents/keystone_ui-develop.md

@@ -207,7 +207,7 @@ outer element. See Conventions before using it.
 
 ### Tables
 
-- `ui_data_table(items:, columns:, empty_message: nil, sort: nil, sort_direction: nil, sort_url: nil, hidden_columns: [])`
+- `ui_data_table(items:, columns:, empty_message: nil, sort: nil, sort_direction: nil, sort_url: nil, hidden_columns: [], key: nil)`
   — takes a block yielding the table. `items:` are records or hashes; each cell
   value is read by calling the column key on the item, falling back to `item[key]`.
   `columns:` accepts plain `{ key: "Label" }` hashes or `Keystone::Ui::Column`
@@ -221,7 +221,18 @@ outer element. See Conventions before using it.
   current column key), `sort_direction:` (`:asc`/`:desc`), and `sort_url:` (a
   lambda taking `(column_key, direction)` and returning a URL); headers then
   render as links that flip direction. `hidden_columns:` drops columns
-  server-side and only affects columns declared `hideable: true`.
+  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 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
+  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
@@ -230,7 +241,9 @@ outer element. See Conventions before using it.
   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.
+  the page. The app must provide that endpoint and persist the list. 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.
 
 ### Content and status
 
@@ -502,6 +515,15 @@ outer element. See Conventions before using it.
    objects as soon as one column needs `mobile_hidden:`, `sortable:`, or
    `hideable:`.
 
+   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`
+   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.
+
 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
    and link URLs, the swipe deck's outcome events, the modal's open trigger, the

data/the_local/agents/keystone_ui-info.md

@@ -47,7 +47,8 @@ shell also uses the page container.
 This local declares no commands. The two working surfaces belong elsewhere:
 
 - **Getting the gem into a host app** — adding it, wiring Tailwind, Stimulus and
-  the theme attributes on the layout, setting the palette → **`keystone_ui-install`**.
+  the theme attributes on the layout, setting the palette, and the suppliers
+  for trails, themes, looks and saved table layouts → **`keystone_ui-install`**.
 - **Building UI with it** — which helper renders what, what keywords it takes,
   how helpers nest → **`keystone_ui-develop`**.
 
@@ -123,6 +124,18 @@ 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.
+- **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. 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. 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.
+  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
   browser offers them while the field's text is typed, and the user can still
   enter a value that is not on the list. This applies to a field with a typed
@@ -208,5 +221,5 @@ holds the catalog.
   and the theme toggle ship with the gem as Stimulus controllers registered once
   at install. A host writes no JavaScript to use them. Components that post
   somewhere, such as the column picker and the pipeline, post to endpoints the
-  host app owns.
+  host app or another gem owns.
 - Ruby >= 3.2. ViewComponent >= 2.0 and < 5.

data/the_local/agents/keystone_ui-install.md

@@ -1,6 +1,6 @@
 ---
 name: keystone_ui-install
-description: Use to hook Keystone UI into a project — adding the gem, running the install generator to wire Tailwind, the Stimulus controllers and the layout's theme attributes, and configuring the palette, the theme mode supplier, registered looks, the breadcrumb trail supplier and extra Tailwind imports and sources.
+description: Use to hook Keystone UI into a project — adding the gem, running the install generator to wire Tailwind, the Stimulus controllers and the layout's theme attributes, and configuring the palette, the theme mode supplier, registered looks, the breadcrumb trail supplier, the saved table layout supplier and extra Tailwind imports and sources.
 tools: Bash, Read, Edit
 scope: UI — pages, forms, tables, navigation, dashboards
 ---
@@ -26,6 +26,8 @@ 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),
   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.
@@ -179,6 +181,7 @@ built on ViewComponent; hook it in before building any screen with those helpers
      config.default_look = :compact
      config.look_supplier = ->(view) { view.current_user&.look }
      config.trail_supplier = ->(view) { view.breadcrumb_trail }
+     config.preference_supplier = ->(view, key) { TablePreferences.for(view.current_user, key) }
      config.tailwind_imports << "/absolute/path/to/extra.css"
      config.tailwind_sources << "/absolute/path/to/components/**/*.{erb,rb}"
    end
@@ -229,6 +232,32 @@ built on ViewComponent; hook it in before building any screen with those helpers
      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
+     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.
+   - 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
+     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
+     layouts, before writing the callable.
    - `tailwind_imports` and `tailwind_sources` — lists to append to, never
      assign. Each import becomes an `@import` line and each source becomes an
      `@source` line in `keystone_source.css` on the next boot. They are for

metadata

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