keystone_ui 0.21.1 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c400b566f0760e79b2808012f91e7b4d978ec0ad7e7caa8b83dc0e18b1007ec
-  data.tar.gz: 594c632edd55b0ae49c62226ae0e8ebdcc38469827abf0f508c87f9812f79aa2
+  metadata.gz: 59407e58c161eccb32c1dd76581bb7c0e8ea6f5005fe5f9bde9b061860ffe2ef
+  data.tar.gz: 4cf237c4e194ecb2c509765191546f633ceb3f0be82563c1eeedcb9f8fb24b06
 SHA512:
-  metadata.gz: ed9434328fd13e5c1a48060beba4174ebb78d72b36fbec129389571c40661a58ef5adc6e1245e19186a92a31738a80e4ba4896390b883b909d45d33ce1de93d9
-  data.tar.gz: 9ae4ec9ec70310c666b8c3bd810517099e5d03566f04763c706df9193b705d512c585f0b64427db6999acd0318f88047f24af0dcc6cea65971abbf6a8c558dd6
+  metadata.gz: 97139bc519bef9a218073c10d290ef335df3471fa294b392298bd4c613490baf173ab02fbd2e4395c2c2c7aba563127d19754049d6f808db8f42b8d0aebfd61b
+  data.tar.gz: 6371eaa8e6bd1a00b028f2820026e0a12c21f3e959a436de04e17ef0b288fb73513948a88c944c2be18a514a7ef54eaa624a87eee4a5dfdc7030b5202c9cd338

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

@@ -7,13 +7,18 @@ module Keystone
       TITLE_CLASSES = "ks-page-title text-2xl"
       SUBTITLE_CLASSES = "ks-page-header-subtitle text-sm"
 
-      def initialize(title:, back_url:, subtitle: nil, trail: nil)
+      def initialize(title:, back_url: nil, subtitle: nil, trail: nil)
         @title = title
         @back_url = back_url
         @subtitle = subtitle
         @trail = trail
       end
 
+      def before_render
+        @trail ||= KeystoneUi.configuration.supplied_trail(helpers)
+        @back_url ||= @trail&.last&.last
+      end
+
       def subtitle?
         !@subtitle.nil?
       end

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

@@ -7,13 +7,18 @@ module Keystone
       TITLE_CLASSES = "ks-page-title text-2xl"
       SUBTITLE_CLASSES = "ks-page-header-subtitle text-sm"
 
-      def initialize(title:, back_url:, subtitle: nil, trail: nil)
+      def initialize(title:, back_url: nil, subtitle: nil, trail: nil)
         @title = title
         @back_url = back_url
         @subtitle = subtitle
         @trail = trail
       end
 
+      def before_render
+        @trail ||= KeystoneUi.configuration.supplied_trail(helpers)
+        @back_url ||= @trail&.last&.last
+      end
+
       def subtitle?
         !@subtitle.nil?
       end

data/lib/keystone_ui/configuration.rb

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

data/lib/keystone_ui/version.rb

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

data/the_local/agents/keystone_ui-develop.md

@@ -64,22 +64,28 @@ outer element. See Conventions before using it.
   `sm:`). Call `header.action { ... }` in the block to place a custom control on
   the right; only what `action` receives is rendered. Passing `action_url:`
   publishes that URL and label for a mobile navbar to pick up.
-- `ui_form_page(title:, back_url:, subtitle: nil, trail: nil)` — the shell
+- `ui_form_page(title:, back_url: nil, subtitle: nil, trail: nil)` — the shell
   marker for a form screen. It renders nothing where it is called. It publishes
   the title and back URL so the navbar can render mobile header context, and
   hands `ui_page` a "Back" link to `back_url` shown from `lg:` up, then the
   title and subtitle shown from `md:` up. Call it before `ui_page`, outside
   `ui_page`'s block, or none of that appears. Passing `trail:` replaces the
   "Back" link with breadcrumbs: the trail's links followed by `title` unlinked,
-  as `ui_breadcrumbs` renders them. `back_url:` is still required with a trail,
-  because the mobile header still uses it.
-- `ui_show_page(title:, back_url:, subtitle: nil, trail: nil)` — the shell marker
-  for a detail screen. It renders nothing where it is called. It publishes the
-  title, subtitle, and back URL for the navbar, and hands `ui_page` a "Back"
-  link to `back_url` shown from `lg:` up. Call it before `ui_page`, outside
-  `ui_page`'s block. It shows no title, so put `ui_page_header` inside the
-  `ui_page` block for the desktop title. `trail:` works as it does on
-  `ui_form_page`, ending the breadcrumbs with `title` unlinked.
+  as `ui_breadcrumbs` renders them. With no `trail:`, it uses the trail the app
+  supplies for the current request, if the app supplies one. With no
+  `back_url:`, the back URL is the `href` of the trail's last link. A `trail:`
+  or `back_url:` passed here always wins over the supplied ones. With no
+  `back_url:` and no trail from either place, the "Back" link and the mobile
+  header point at the current page, so pass one.
+- `ui_show_page(title:, back_url: nil, subtitle: nil, trail: nil)` — the shell
+  marker for a detail screen. It renders nothing where it is called. It
+  publishes the title, subtitle, and back URL for the navbar, and hands
+  `ui_page` a "Back" link to `back_url` shown from `lg:` up. Call it before
+  `ui_page`, outside `ui_page`'s block. It shows no title, so put
+  `ui_page_header` inside the `ui_page` block for the desktop title. `trail:`
+  and `back_url:` work as they do on `ui_form_page`, including the supplied
+  trail and the fallback to the trail's last link, and the breadcrumbs end with
+  `title` unlinked.
 - `ui_breadcrumbs(trail:, current: nil)` — a line of links shown only from `lg:`
   up. `trail:` is `[[label, href], ...]`, from the top level down, and each pair
   renders as a link, separated by `›`. `current:` is the page being shown,
@@ -326,7 +332,13 @@ outer element. See Conventions before using it.
    Those shells supply the desktop "Back" link themselves, so never add a
    second back link or button to those screens. Whether a screen
    shows that "Back" link or breadcrumbs, and which parent screens the trail
-   names, is the developer's choice, so ask before passing `trail:`. Below `lg:` the
+   names, is the developer's choice, so ask before passing `trail:`. Check
+   first whether the app's Keystone UI initializer sets a `trail_supplier`,
+   which supplies a trail for every request: if it
+   does, a screen whose supplied trail is right passes neither `trail:` nor
+   `back_url:`, and passes its own only where the supplied one is wrong. If the
+   app supplies no trail, every form and detail screen passes `back_url:` or
+   `trail:`. Setting up a supplied trail is `keystone_ui-install`'s job. Below `lg:` the
    back link comes from `ui_mobile_header`, which the navbar renders from the
    title and back URL these shells publish. Check the app's layout: if it does not
    already render `ui_mobile_header` from that published context, ask the

data/the_local/agents/keystone_ui-info.md

@@ -28,7 +28,10 @@ these apps are often viewed in a native webview. The form and show page shells
 follow the same split for going back: the mobile header carries the back link on
 small screens, and from `lg:` up the shell shows a "Back" link. Given a trail of
 earlier pages instead, the shell shows breadcrumbs in place of that link, ending
-with the page's own title. That link or those breadcrumbs, and the form page's
+with the page's own title. A page that passes no trail gets the one the app or
+another gem supplies for the request, if any, and a page that passes no back
+link goes back to that trail's last link. A trail or back link the page passes
+itself always wins. Supplying a trail is set up through the install local. That link or those breadcrumbs, and the form page's
 title, appear at the top of the page container, inside its width and padding, so
 a page using either shell also uses the page container.
 

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 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 and extra Tailwind imports and sources.
 tools: Bash, Read, Edit
 scope: UI — pages, forms, tables, navigation, dashboards
 ---
@@ -24,6 +24,8 @@ built on ViewComponent; hook it in before building any screen with those helpers
   custom mode),
   `register_look` (a look's CSS file by name), `default_look` and
   `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 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.
@@ -176,6 +178,7 @@ built on ViewComponent; hook it in before building any screen with those helpers
      config.register_look :compact, "/absolute/path/to/compact.css"
      config.default_look = :compact
      config.look_supplier = ->(view) { view.current_user&.look }
+     config.trail_supplier = ->(view) { view.breadcrumb_trail }
      config.tailwind_imports << "/absolute/path/to/extra.css"
      config.tailwind_sources << "/absolute/path/to/components/**/*.{erb,rb}"
    end
@@ -205,6 +208,14 @@ built on ViewComponent; hook it in before building any screen with those helpers
    - `look_supplier` — a callable that receives the view and returns a look
      name for the request. A name that is not registered, or `nil`, leaves the
      page on the default look.
+   - `trail_supplier` — a callable that receives the view and returns the
+     breadcrumb trail as an array of `[label, href]` pairs, or `nil`. A form or
+     show page that passes no trail of its own shows the supplied one on `lg:`
+     screens, ending with the page's title, in place of the desktop "Back" link.
+     A page that passes no Back link goes back to the trail's last link. A page
+     that passes its own trail or Back link keeps it. With no supplier, or a
+     `nil` return, the page shows its Back link. Ask the developer
+     which code in the app knows each page's trail 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.21.1
+  version: 0.22.0
 platform: ruby
 authors:
 - Tyler Schneider