keystone_ui 0.22.0 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59407e58c161eccb32c1dd76581bb7c0e8ea6f5005fe5f9bde9b061860ffe2ef
-  data.tar.gz: 4cf237c4e194ecb2c509765191546f633ceb3f0be82563c1eeedcb9f8fb24b06
+  metadata.gz: a2d9cae890778efeef3333b64e2e04fa14955d60171b99d1f0fced2d64d0d8aa
+  data.tar.gz: 45bb649fa4211a143e3e5c987332de6b2849423f52bcb04765120f49aff9ba87
 SHA512:
-  metadata.gz: 97139bc519bef9a218073c10d290ef335df3471fa294b392298bd4c613490baf173ab02fbd2e4395c2c2c7aba563127d19754049d6f808db8f42b8d0aebfd61b
-  data.tar.gz: 6371eaa8e6bd1a00b028f2820026e0a12c21f3e959a436de04e17ef0b288fb73513948a88c944c2be18a514a7ef54eaa624a87eee4a5dfdc7030b5202c9cd338
+  metadata.gz: 193b52fdb0006bb35f2d58e50934755a3917b4f34348051a3d64a7b5b1eda768005c9dd74c7638ba585cd2fcc46f923730816f08a04f078d46e0132405cd310d
+  data.tar.gz: d2aa6186b582a92554c1c58139351e2ebb67c8682908bbbb849d72d2fa117cb6e92f0124cb024e0d1a9ea1cc85d138eb1f4f9da08f1cb5bcbf81cd72ae32c6c0

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

@@ -17,6 +17,8 @@ module Keystone
       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?

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

@@ -17,6 +17,8 @@ module Keystone
       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?

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.22.0"
+  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

@@ -75,8 +75,11 @@ outer element. See Conventions before using it.
   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.
+  `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
@@ -84,8 +87,9 @@ outer element. See Conventions before using it.
   `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.
+  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,
@@ -338,7 +342,9 @@ outer element. See Conventions before using 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
+   `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

@@ -31,9 +31,15 @@ earlier pages instead, the shell shows breadcrumbs in place of that link, ending
 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.
+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

@@ -25,7 +25,7 @@ built on ViewComponent; hook it in before building any screen with those helpers
   `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),
+  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.
@@ -214,8 +214,20 @@ built on ViewComponent; hook it in before building any screen with those helpers
      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.
+     `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.22.0
+  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