keystone_ui 0.32.0 → 0.33.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 530dc14cf871e579dcccc21f769b304974a36af552e10e2a9eee6f0b90e531ae
-  data.tar.gz: 69ed4079d0a6fb130e50ba08afdf4b6c1ba37d8f25b035b06e686bdccdd5f1a3
+  metadata.gz: 599c6b4269b4ca049a5aefe106cb71dc6205554c49fb6e72824f25cc3b6f2597
+  data.tar.gz: 390d82ea8082927248351ba74796fde3a05afe4994b151c79169e0cb190ecacd
 SHA512:
-  metadata.gz: 4d2f5fc1618dbe5b16114c4475d8b0e987f8e0516ed80aecfaace0741ccdad791214ffa758dd65c742d946285b26277c1345963ff9e1fa7175b9b1ff67d21f67
-  data.tar.gz: bb6877b8c6e890e4010b679ad81fa07e00bde9ccbfc73d983d666c0a97ed8182833d150c7e4535e095e1ff5d98ffe7aa3c8cab067b366e2db7c313e6b29baa00
+  metadata.gz: 2b44fd40afcc3d275dab96ab0401f2748a5555d5e38eb319af16d998454e30f094d9e799603658b0597b7a0e8688a9a8d864aa2e170c3b750d5351a37db123d5
+  data.tar.gz: 65064fb15715bcebbe95efadb89b2a395d06889b6d4962467faeac520df18f88083acd7f5d23ffe8c6057f9434916906861a4c3f02515ae4306cf545bf9eba23

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]["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.0"
 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,15 @@ 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, 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
+  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.
 - `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 +238,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 +512,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,16 @@ 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. 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.
+  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 +219,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,24 @@ 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 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.
+   - 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
+     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.0
 platform: ruby
 authors:
 - Tyler Schneider