keystone_ui 0.21.1 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2c400b566f0760e79b2808012f91e7b4d978ec0ad7e7caa8b83dc0e18b1007ec
-  data.tar.gz: 594c632edd55b0ae49c62226ae0e8ebdcc38469827abf0f508c87f9812f79aa2
+  metadata.gz: a2d9cae890778efeef3333b64e2e04fa14955d60171b99d1f0fced2d64d0d8aa
+  data.tar.gz: 45bb649fa4211a143e3e5c987332de6b2849423f52bcb04765120f49aff9ba87
 SHA512:
-  metadata.gz: ed9434328fd13e5c1a48060beba4174ebb78d72b36fbec129389571c40661a58ef5adc6e1245e19186a92a31738a80e4ba4896390b883b909d45d33ce1de93d9
-  data.tar.gz: 9ae4ec9ec70310c666b8c3bd810517099e5d03566f04763c706df9193b705d512c585f0b64427db6999acd0318f88047f24af0dcc6cea65971abbf6a8c558dd6
+  metadata.gz: 193b52fdb0006bb35f2d58e50934755a3917b4f34348051a3d64a7b5b1eda768005c9dd74c7638ba585cd2fcc46f923730816f08a04f078d46e0132405cd310d
+  data.tar.gz: d2aa6186b582a92554c1c58139351e2ebb67c8682908bbbb849d72d2fa117cb6e92f0124cb024e0d1a9ea1cc85d138eb1f4f9da08f1cb5bcbf81cd72ae32c6c0

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

@@ -7,13 +7,20 @@ 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
+        raise KeystoneUi::MissingBackLink, @title unless @back_url
+        raise KeystoneUi::IncompleteTrail, @title if @trail&.any? { |label, href| label.blank? || href.blank? }
+      end
+
       def subtitle?
         !@subtitle.nil?
       end

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

@@ -7,13 +7,20 @@ 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
+        raise KeystoneUi::MissingBackLink, @title unless @back_url
+        raise KeystoneUi::IncompleteTrail, @title if @trail&.any? { |label, href| label.blank? || href.blank? }
+      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/incomplete_trail.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module KeystoneUi
+  class IncompleteTrail < StandardError
+    def initialize(title)
+      super(%(The page "#{title}" has a breadcrumb trail with a link that has no label or no address. Give every link in the trail both.))
+    end
+  end
+end

data/lib/keystone_ui/missing_back_link.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module KeystoneUi
+  class MissingBackLink < StandardError
+    def initialize(title)
+      super(%(The page "#{title}" has no Back link. Pass back_url: or trail:, or supply a trail for it through config.trail_supplier.))
+    end
+  end
+end

data/lib/keystone_ui/version.rb

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

data/lib/keystone_ui.rb

@@ -3,6 +3,8 @@
 require "view_component"
 require "keystone_ui/styles"
 require "keystone_ui/configuration"
+require "keystone_ui/missing_back_link"
+require "keystone_ui/incomplete_trail"
 require "keystone_ui/theme_choice"
 require "keystone_ui/look_choice"
 require "keystone_ui/engine"

data/the_local/agents/keystone_ui-develop.md

@@ -64,22 +64,32 @@ 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, or a trail that is empty or whose
+  last link has no `href`, rendering raises `KeystoneUi::MissingBackLink`, naming
+  the page's title. A trail with any link whose label or `href` is `nil` or
+  blank raises `KeystoneUi::IncompleteTrail`, naming the page's title, even when
+  `back_url:` is passed.
+- `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, the fallback to the trail's last link, and the
+  `KeystoneUi::MissingBackLink` and `KeystoneUi::IncompleteTrail` errors, 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 +336,15 @@ 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:`, since a screen with neither raises `KeystoneUi::MissingBackLink`
+   when it renders. Every link in a trail needs both a label and an `href`, or
+   the screen raises `KeystoneUi::IncompleteTrail`. 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,9 +28,18 @@ 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
-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.
+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.
+
+Every form and show page must end up with a Back link. A page with no back
+link, no trail and no supplied trail raises `KeystoneUi::MissingBackLink` when it
+renders, and the message names the page's title. A trail with a link missing
+its label or its address raises `KeystoneUi::IncompleteTrail`, also naming the
+page. 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.
 
 ## Interface
 

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 their Back link when they pass none either),
   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,26 @@ 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. Return `nil`, not an empty
+     array, for a page with no trail, because an empty array replaces the
+     page's Back link with breadcrumbs holding only its title.
+   - Every form and show page must end up with a Back link. A page that passes
+     no Back link and no trail, and gets no trail from the supplier, raises
+     `KeystoneUi::MissingBackLink` naming the page's title when it renders.
+     So does a page whose trail's last link has no address.
+   - Every link the supplier returns needs both a label and an address. A trail
+     with a blank label or address raises `KeystoneUi::IncompleteTrail` naming
+     the page's title.
+   - Ask the developer which code in the app knows each page's trail before
+     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.
    - `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

@@ -65,6 +65,8 @@ develop:
 sources:
   - lib/generators/keystone/install_generator.rb
   - lib/keystone_ui/configuration.rb
+  - lib/keystone_ui/missing_back_link.rb
+  - lib/keystone_ui/incomplete_trail.rb
   - lib/keystone_ui/theme_choice.rb
   - lib/keystone_ui/look_choice.rb
   - app/helpers/keystone_ui_helper.rb

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keystone_ui
 version: !ruby/object:Gem::Version
-  version: 0.21.1
+  version: 0.23.0
 platform: ruby
 authors:
 - Tyler Schneider
@@ -189,9 +189,11 @@ files:
 - lib/keystone_ui.rb
 - lib/keystone_ui/configuration.rb
 - lib/keystone_ui/engine.rb
+- lib/keystone_ui/incomplete_trail.rb
 - lib/keystone_ui/leftover_stylesheet.rb
 - lib/keystone_ui/look_check.rb
 - lib/keystone_ui/look_choice.rb
+- lib/keystone_ui/missing_back_link.rb
 - lib/keystone_ui/safelist.rb
 - lib/keystone_ui/source_css.rb
 - lib/keystone_ui/theme_choice.rb