keystone_ui 0.36.0 → 0.38.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d7a0b5685fe1dc1107e8e75d274e80401826ed52616ae95c20d6a288fdc5c647
-  data.tar.gz: 8220957d8d617f0c32c71b264c84c5bf8b992a3cc2e3bb512f3f4e0a1cbf8bb0
+  metadata.gz: ba03a37368cf5e1f7e0b18721a1eca9a04aae5dea7a5b3d8887e3db9956f9e8f
+  data.tar.gz: 6c0eb35d049ec308a68984f32cd787d8fa1c183057a975322844187f294c31fc
 SHA512:
-  metadata.gz: 58889e18335df436f8b13caad57648caf6ed3e13e17b50dc5d6011ae0f8fa85ceb98a9e9fd682f90cd10729ed3d3f20603ed34e438afb09a33090ec4d7493c95
-  data.tar.gz: c79c624b0a0a09e83b1f6fcee1566df17c7adf96f8141a20c8ee3ed20b361ab7faa1135be33bcf41f780e68e663e78d9ba833d27af09e72c782d4763a09463da
+  metadata.gz: 36f95ca64410c3d39cae7355a0f1f7673a66e963ecf78a67d82a5559c74eef5ea02de3dc4668aef26fdab81b7b330d8d30dbb1a0aea658f13a188fdfdf296e27
+  data.tar.gz: 41c5aff5beccf97a8fac694a8cb6e4250e9b6c4456efb78dc1335df8c5a3be086bacae0b5a28292520666bfae44f7df5b8d6cc9c2fbe36f88f619c0a61e33cc1

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_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

@@ -32,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
@@ -63,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
@@ -151,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/navigation_component.html.erb

@@ -0,0 +1,48 @@
+<% if !anything_to_show? %>
+<%= content %>
+<% elsif sidebar? %>
+<% sidebar = capture do %>
+  <nav class="<%= SIDEBAR_CLASSES %>">
+    <% if logo? %>
+      <div><%= logo %></div>
+    <% end %>
+    <% groups.each do |group, tabs| %>
+      <div class="<%= SIDEBAR_GROUP_CLASSES %>">
+        <p class="<%= sidebar_group_label_classes(tabs) %>"><%= group.label %></p>
+        <% tabs.each do |tab| %>
+          <a class="<%= sidebar_tab_classes(tab) %>" href="<%= tab.href_for(helpers) %>"><%= tab.label %></a>
+        <% end %>
+      </div>
+    <% end %>
+    <% if menus? %>
+      <div class="<%= SIDEBAR_MENUS_CLASSES %>"><%= menus %></div>
+    <% end %>
+  </nav>
+<% end %>
+<div class="<%= SIDEBAR_ROW_CLASSES %>">
+  <%= sidebar if sidebar_first? %>
+  <div class="<%= SIDEBAR_CONTENT_CLASSES %>"><%= content %></div>
+  <%= sidebar unless sidebar_first? %>
+</div>
+<% else %>
+<div class="<%= TOP_BAR_CLASSES %>">
+<%= render Keystone::Ui::NavbarComponent.new(sticky: false) do |navbar| %>
+  <% if logo? %>
+    <% navbar.with_logo do %><%= logo %><% end %>
+  <% end %>
+  <% navbar.with_desktop_links do %>
+    <% groups.each do |group, tabs| %>
+      <%= render Keystone::Ui::NavDropdownComponent.new(title: group.label, area: group.label, active: holds_current?(tabs)) do %>
+        <% tabs.each do |tab| %>
+          <%= render Keystone::Ui::NavItemComponent.new(label: tab.label, href: tab.href_for(helpers), active: current?(tab)) %>
+        <% end %>
+      <% end %>
+    <% end %>
+  <% end %>
+  <% if menus? %>
+    <% navbar.with_desktop_right do %><%= menus %><% end %>
+  <% end %>
+<% end %>
+</div>
+<%= content %>
+<% end %>

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "keystone_ui/navigation_order"
+
+module Keystone
+  module Ui
+    class NavigationComponent < ViewComponent::Base
+      TOP_BAR_CLASSES = "hidden lg:block sticky top-0 z-40"
+      SIDEBAR_ROW_CLASSES = "lg:flex"
+      SIDEBAR_CLASSES = "ks-sidebar hidden lg:flex lg:sticky lg:top-0 lg:h-screen shrink-0 overflow-y-auto"
+      SIDEBAR_GROUP_CLASSES = "flex flex-col"
+      SIDEBAR_GROUP_LABEL_CLASSES = "ks-sidebar-group-label"
+      SIDEBAR_TAB_CLASSES = "ks-sidebar-tab"
+      ACTIVE_CLASS = "active"
+      SIDEBAR_MENUS_CLASSES = "mt-auto"
+      SIDEBAR_CONTENT_CLASSES = "min-w-0 flex-1"
+      SIDEBAR_PLACEMENTS = %w[left right].freeze
+
+      renders_one :logo
+      renders_one :menus
+
+      attr_reader :groups
+
+      def before_render
+        permitted = KeystoneUi.configuration.navigation_groups
+          .map { |group| [ group, group.tabs_permitted_for(helpers) ] }
+          .reject { |_group, tabs| tabs.empty? }
+        @groups = KeystoneUi::NavigationOrder.new(saved_navigation["order"] || []).arrange(permitted)
+        @current_tab = KeystoneUi.configuration.supplied_current_tab(helpers)
+      end
+
+      def current?(tab)
+        tab.key == @current_tab
+      end
+
+      def holds_current?(tabs)
+        tabs.any? { |tab| current?(tab) }
+      end
+
+      def sidebar_group_label_classes(tabs)
+        [ SIDEBAR_GROUP_LABEL_CLASSES, (ACTIVE_CLASS if holds_current?(tabs)) ].compact.join(" ")
+      end
+
+      def sidebar_tab_classes(tab)
+        [ SIDEBAR_TAB_CLASSES, (ACTIVE_CLASS if current?(tab)) ].compact.join(" ")
+      end
+
+      def anything_to_show?
+        groups.any? || logo? || menus?
+      end
+
+      def sidebar?
+        SIDEBAR_PLACEMENTS.include?(placement)
+      end
+
+      def sidebar_first?
+        placement == "left"
+      end
+
+      private
+
+      def placement
+        saved_navigation["placement"]
+      end
+
+      def saved_navigation
+        value = KeystoneUi.configuration.supplied_preference(helpers, :navigation)&.dig(:value)
+        value.is_a?(Hash) ? value : {}
+      end
+    end
+  end
+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/app/helpers/keystone_ui_helper.rb

@@ -141,6 +141,10 @@ module KeystoneUiHelper
     render Keystone::Ui::NavbarComponent.new(**args), &block
   end
 
+  def ui_navigation(&block)
+    render Keystone::Ui::NavigationComponent.new, &block
+  end
+
   def ui_nav_item(**args)
     render Keystone::Ui::NavItemComponent.new(**args)
   end

data/lib/keystone_ui/configuration.rb

@@ -1,9 +1,11 @@
 # frozen_string_literal: true
 
+require "keystone_ui/navigation_group"
+
 module KeystoneUi
   class Configuration
-    attr_accessor :accent, :surface, :theme_mode_supplier, :look_supplier, :trail_supplier, :preference_supplier
-    attr_reader :tailwind_imports, :tailwind_sources, :looks, :default_look
+    attr_accessor :accent, :surface, :theme_mode_supplier, :look_supplier, :trail_supplier, :preference_supplier, :current_tab_supplier
+    attr_reader :tailwind_imports, :tailwind_sources, :looks, :default_look, :navigation_groups
 
     def initialize
       @accent = :blue
@@ -11,6 +13,7 @@ module KeystoneUi
       @tailwind_imports = []
       @tailwind_sources = []
       @looks = {}
+      @navigation_groups = []
     end
 
     def default_look=(name)
@@ -22,6 +25,12 @@ module KeystoneUi
       @tailwind_imports << path.to_s
     end
 
+    def navigation_group(label)
+      group = NavigationGroup.new(label)
+      yield(group)
+      @navigation_groups << group
+    end
+
     def supplied_look(view)
       look_supplier&.call(view)&.to_s
     end
@@ -37,6 +46,10 @@ module KeystoneUi
     def supplied_preference(view, key)
       preference_supplier&.call(view, key)
     end
+
+    def supplied_current_tab(view)
+      current_tab_supplier&.call(view)
+    end
   end
 
   def self.configuration

data/lib/keystone_ui/navigation_group.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module KeystoneUi
+  class NavigationGroup
+    Tab = Struct.new(:key, :label, :href, :permitted, keyword_init: true) do
+      def href_for(view)
+        href.respond_to?(:call) ? href.call(view) : href
+      end
+    end
+
+    attr_reader :label, :tabs
+
+    def initialize(label)
+      @label = label
+      @tabs = []
+    end
+
+    def tabs_permitted_for(view)
+      tabs.select { |tab| tab.permitted.call(view) }
+    end
+
+    def tab(key, label:, href:, permitted:)
+      @tabs << Tab.new(key: key, label: label, href: href, permitted: permitted)
+    end
+  end
+end

data/lib/keystone_ui/navigation_order.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module KeystoneUi
+  class NavigationOrder
+    def initialize(saved)
+      @saved = saved.is_a?(Array) ? saved.grep(Hash) : []
+    end
+
+    def arrange(groups)
+      in_saved_order(groups, group_labels) { |group, _tabs| group.label }
+        .map { |group, tabs| [ group, arrange_tabs(group, tabs) ] }
+    end
+
+    private
+
+    def in_saved_order(items, saved_names)
+      items.each_with_index
+        .sort_by { |item, declared| [ saved_names.index(yield(item)) || saved_names.size, declared ] }
+        .map(&:first)
+    end
+
+    def group_labels
+      @saved.map { |entry| entry["group"] }
+    end
+
+    def arrange_tabs(group, tabs)
+      in_saved_order(tabs, saved_tab_keys(group)) { |tab| tab.key.to_s }
+    end
+
+    def saved_tab_keys(group)
+      tabs = @saved.find { |entry| entry["group"] == group.label }&.fetch("tabs", nil)
+      tabs.is_a?(Array) ? tabs : []
+    end
+  end
+end

data/lib/keystone_ui/safelist.rb

@@ -37,6 +37,7 @@ module Keystone
       Keystone::Ui::NavItemComponent,
       Keystone::Ui::BottomNavItemComponent,
       Keystone::Ui::NavbarComponent,
+      Keystone::Ui::NavigationComponent,
       Keystone::Ui::BottomNavComponent,
       Keystone::Ui::SettingsLinkComponent,
       Keystone::Ui::FormPageComponent,

data/lib/keystone_ui/version.rb

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

data/the_local/agents/keystone_ui-develop.md

@@ -112,6 +112,28 @@ outer element. See Conventions before using it.
   `mobile_center`, `mobile_right`. Desktop slots are hidden below `lg:` and the
   mobile slots above it. `desktop_right` renders only when `desktop_links` is
   also filled.
+- `ui_navigation` — no keywords, takes a block holding the page content. Placed
+  in the layout around `yield`, it draws the tabs the app declares with
+  `config.navigation_group` as a top bar of menus from `lg:` up, then the
+  content. It leaves out tabs whose permission check fails and groups with no
+  tab left, and below `lg:` it draws only the content. Inside the block, a
+  `navigation.with_logo do ... end` block puts the app's logo at the left end
+  of the top bar, and a `navigation.with_menus do ... end` block puts menus
+  such as the account menu and the user menu at its right end, so the layout
+  draws no second bar for them. When the preference supplied for
+  `:navigation` holds `{ "placement" => "left" }` or `"right"`, it draws a
+  sidebar on that side of the content from `lg:` up instead, with each group's
+  label above its tabs, the logo at its top and the menus at its bottom, and
+  below `lg:` the content takes the full width. Any other placement draws the
+  top bar. When that value holds an `"order"` list of
+  `{ "group" => label, "tabs" => [tab key strings] }` entries, both placements
+  draw the named groups and tabs first in that order, then the rest in
+  declared order, ignoring names no longer declared. When the app sets `config.current_tab_supplier`, the tab whose key
+  it returns for the page and that tab's group are shown as active in either
+  placement, and nothing is marked when it returns `nil`, a key no declared
+  tab has, or is not set. Check whether the app's Keystone UI
+  initializer declares navigation groups before adding desktop tabs by hand;
+  declaring them is `keystone_ui-install`'s job.
 - `ui_nav_item(label:, href:, active: false)` — one desktop navigation link.
 - `ui_nav_dropdown(title:, area:, active: false)` — takes a block. A navbar
   dropdown; the block holds the menu links.
@@ -240,8 +262,11 @@ 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.
@@ -269,7 +294,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

data/the_local/agents/keystone_ui-info.md

@@ -150,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

@@ -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, the saved table layout 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, the navigation groups and current tab supplier, and extra Tailwind imports and sources.
 tools: Bash, Read, Edit
 scope: UI — pages, forms, tables, navigation, dashboards
 ---
@@ -28,7 +28,12 @@ built on ViewComponent; hook it in before building any screen with those helpers
   show pages that pass none, and their Back link when they pass none either),
   `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),
+  saves to, and the navigation's placement under the key `:navigation`),
+  `navigation_group` (a labelled group of desktop tabs that `ui_navigation`
+  draws, each tab declared with `tab key, label:, href:, permitted:`),
+  `current_tab_supplier` (a callable that supplies the key of the declared tab
+  the current page belongs to, so `ui_navigation` marks it and its group
+  active),
   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.
@@ -183,6 +188,10 @@ built on ViewComponent; hook it in before building any screen with those helpers
      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.navigation_group "Sales" do |group|
+       group.tab :quotes, label: "Quotes", href: ->(view) { view.quotes_path }, permitted: ->(view) { view.policy(Quote).index? }
+     end
+     config.current_tab_supplier = ->(view) { view.controller.try(:navigation_tab) }
      config.tailwind_imports << "/absolute/path/to/extra.css"
      config.tailwind_sources << "/absolute/path/to/components/**/*.{erb,rb}"
    end
@@ -282,9 +291,45 @@ 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.
+   - For the key `:navigation` the supplier returns the person's navigation
+     placement as `{ value: { "placement" => "left" } }`, with `"left"`,
+     `"right"` or `"top"`. `ui_navigation` draws a sidebar on the left or the
+     right of the page content on desktop screens for the first two, and the
+     top bar for `"top"`, `nil`, a value with no `"placement"` string key, or
+     any other placement.
+   - The same `:navigation` value may hold the person's order of groups and
+     tabs under `"order"`, as
+     `[ { "group" => "Admin" }, { "group" => "Sales", "tabs" => [ "orders", "quotes" ] } ]`.
+     A group is named by its declared label and a tab by its key as a string.
+     `ui_navigation` draws the named groups and tabs first in that order, then
+     the rest in declared order, and ignores names no longer declared.
    - 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.
+   - `navigation_group "Label" do |group| ... end` — declares one menu of
+     desktop tabs, in the order the groups are declared. Inside the block,
+     `group.tab key, label:, href:, permitted:` adds a tab in order. `href:` is
+     an address or a callable that receives the view and returns one.
+     `permitted:` is a callable that receives the view and returns whether the
+     current person may see the tab. The layout renders them with
+     `ui_navigation` around `yield`, setting the app's logo with
+     `navigation.with_logo` and its account and user menus with
+     `navigation.with_menus` inside the block, so the layout draws no other
+     top bar. Ask the developer which tabs and groups the app has, and which
+     permission check guards each, before declaring them.
+   - `current_tab_supplier` — a callable that receives the view and returns the
+     key of the declared tab the current page belongs to, or `nil`.
+     `ui_navigation` shows that tab and its group as active in the top bar and
+     gives that tab and its group's label the `active` class in the sidebar.
+     `nil`, a key no declared tab has, or no supplier marks nothing. The
+     callable must answer for every page the layout draws, so a page with no
+     tab returns `nil` rather than raising. Ask the developer how a page names
+     its tab, such as a method on each controller, 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

data/the_local/interface.yml

@@ -39,6 +39,7 @@ develop:
   - ui_action_menu
   - ui_action_menu_item
   - ui_navbar
+  - ui_navigation
   - ui_nav_item
   - ui_nav_dropdown
   - ui_bottom_nav
@@ -71,6 +72,8 @@ sources:
   - app/components/keystone/ui/figure_component.rb
   - lib/generators/keystone/install_generator.rb
   - lib/keystone_ui/configuration.rb
+  - lib/keystone_ui/navigation_group.rb
+  - lib/keystone_ui/navigation_order.rb
   - lib/keystone_ui/missing_back_link.rb
   - lib/keystone_ui/incomplete_trail.rb
   - lib/keystone_ui/theme_choice.rb
@@ -131,6 +134,8 @@ sources:
   - app/components/keystone/ui/nav_dropdown_component.rb
   - app/components/keystone/ui/nav_item_component.rb
   - app/components/keystone/ui/navbar_component.rb
+  - app/components/keystone/ui/navigation_component.rb
+  - app/components/keystone/ui/navigation_component.html.erb
   - app/components/keystone/ui/option_card_component.rb
   - app/components/keystone/ui/page_component.rb
   - app/components/keystone/ui/page_component.html.erb

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keystone_ui
 version: !ruby/object:Gem::Version
-  version: 0.36.0
+  version: 0.38.0
 platform: ruby
 authors:
 - Tyler Schneider
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.12.0
+        version: 0.14.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.12.0
+        version: 0.14.0
 - !ruby/object:Gem::Dependency
   name: view_component
   requirement: !ruby/object:Gem::Requirement
@@ -161,6 +161,8 @@ files:
 - app/components/keystone/ui/nav_item_component.rb
 - app/components/keystone/ui/navbar_component.html.erb
 - app/components/keystone/ui/navbar_component.rb
+- app/components/keystone/ui/navigation_component.html.erb
+- app/components/keystone/ui/navigation_component.rb
 - app/components/keystone/ui/option_card_component.html.erb
 - app/components/keystone/ui/option_card_component.rb
 - app/components/keystone/ui/page_component.html.erb
@@ -175,6 +177,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
@@ -205,6 +208,8 @@ files:
 - lib/keystone_ui/look_check.rb
 - lib/keystone_ui/look_choice.rb
 - lib/keystone_ui/missing_back_link.rb
+- lib/keystone_ui/navigation_group.rb
+- lib/keystone_ui/navigation_order.rb
 - lib/keystone_ui/safelist.rb
 - lib/keystone_ui/source_css.rb
 - lib/keystone_ui/theme_choice.rb