keystone_ui 0.21.0 → 0.22.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ebe6bbc917891684b563a1981daf0cc0b32a747143f52d72af17bd2a9df2e7d
-  data.tar.gz: 0320fdf4a5c56b52e6919641022b1fbd05dd2ccdcb5c8b91553f696d3ab3e115
+  metadata.gz: 59407e58c161eccb32c1dd76581bb7c0e8ea6f5005fe5f9bde9b061860ffe2ef
+  data.tar.gz: 4cf237c4e194ecb2c509765191546f633ceb3f0be82563c1eeedcb9f8fb24b06
 SHA512:
-  metadata.gz: b6b75345f8165d8ae02e9d7a7e6fe24a015f37f07437082dcad6d3543fa17b56013073ef9c69729be5b330b1959f69e0bb33d628df176d01fe69ae296c33713a
-  data.tar.gz: 04b8b2e35b0d24fcb507d0293142aba61723ed1737478da8376bce4b6533b97fe12ca2efe9a629c92916b1aba4fdee8f47ec7bbf85c8e74bb39e60d409ae9375
+  metadata.gz: 97139bc519bef9a218073c10d290ef335df3471fa294b392298bd4c613490baf173ab02fbd2e4395c2c2c7aba563127d19754049d6f808db8f42b8d0aebfd61b
+  data.tar.gz: 6371eaa8e6bd1a00b028f2820026e0a12c21f3e959a436de04e17ef0b288fb73513948a88c944c2be18a514a7ef54eaa624a87eee4a5dfdc7030b5202c9cd338

data/app/components/keystone/ui/form_page_component.html.erb

@@ -3,14 +3,16 @@
 <% content_for :form_page_back_url, @back_url %>
 
 <% if @trail %>
-  <%= render Keystone::Ui::BreadcrumbsComponent.new(trail: @trail, current: @title) %>
+  <% content_for :keystone_page_header, render(Keystone::Ui::BreadcrumbsComponent.new(trail: @trail, current: @title)) %>
 <% else %>
-  <%= render Keystone::Ui::DesktopBackLinkComponent.new(url: @back_url) %>
+  <% content_for :keystone_page_header, render(Keystone::Ui::DesktopBackLinkComponent.new(url: @back_url)) %>
 <% end %>
 
-<div class="<%= DESKTOP_WRAPPER_CLASSES %>">
-  <h1 class="<%= TITLE_CLASSES %>"><%= @title %></h1>
-  <% if subtitle? %>
-    <p class="<%= SUBTITLE_CLASSES %>"><%= @subtitle %></p>
-  <% end %>
-</div>
+<% content_for :keystone_page_header do %>
+  <div class="<%= DESKTOP_WRAPPER_CLASSES %>">
+    <h1 class="<%= TITLE_CLASSES %>"><%= @title %></h1>
+    <% if subtitle? %>
+      <p class="<%= SUBTITLE_CLASSES %>"><%= @subtitle %></p>
+    <% end %>
+  </div>
+<% end %>

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/page_component.html.erb

@@ -1,3 +1,4 @@
 <div class="<%= classes %>">
+  <%= content_for(:keystone_page_header) %>
   <%= content %>
 </div>

data/app/components/keystone/ui/show_page_component.html.erb

@@ -4,7 +4,7 @@
 <% content_for :show_page_subtitle, @subtitle if @subtitle.present? %>
 
 <% if @trail %>
-  <%= render Keystone::Ui::BreadcrumbsComponent.new(trail: @trail, current: @title) %>
+  <% content_for :keystone_page_header, render(Keystone::Ui::BreadcrumbsComponent.new(trail: @trail, current: @title)) %>
 <% else %>
-  <%= render Keystone::Ui::DesktopBackLinkComponent.new(url: @back_url) %>
+  <% content_for :keystone_page_header, render(Keystone::Ui::DesktopBackLinkComponent.new(url: @back_url)) %>
 <% 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.0"
+  VERSION = "0.22.0"
 end

data/the_local/agents/keystone_ui-develop.md

@@ -42,7 +42,9 @@ outer element. See Conventions before using it.
 - `ui_page(max_width: :full, padding: :standard, top_offset: nil, class: nil)` —
   takes a block. The outer wrapper for a screen. `max_width:` `:sm` `:md` `:lg`
   `:xl` `:full`; `padding:` `:standard` or `:none`; `top_offset:` `:sm` `:md`
-  `:lg` `:xl` to clear a fixed navbar.
+  `:lg` `:xl` to clear a fixed navbar. When `ui_form_page` or `ui_show_page` was
+  called earlier on the same screen, `ui_page` renders their back link or
+  breadcrumbs, and the form page's title, at its top, above the block.
 - `ui_section(title: nil, subtitle: nil, action: nil, spacing: :md, class: nil)`
   — takes a block. A titled block of content with an optional right-aligned
   link. `action:` is `{ label:, href: }`; `spacing:` `:sm` `:md` `:lg`.
@@ -62,18 +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
-  marker for a form screen. Renders a "Back" link to `back_url` shown from `lg:`
-  up, then the title and subtitle shown from `md:` up, and publishes the title
-  and back URL so the navbar can render mobile header context. 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. Renders a "Back" link to `back_url` shown from `lg:` up,
-  and publishes the title, subtitle, and back URL for the navbar. It renders no
-  title, so pair it with `ui_page_header` for the desktop title. `trail:` works
-  as it does on `ui_form_page`, ending the breadcrumbs with `title` unlinked.
+- `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. 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,
@@ -300,14 +312,33 @@ outer element. See Conventions before using it.
    composition before inventing one; that screen is the house style.
 
 3. Pick the page shell for what you are building:
-   - a form screen → `ui_form_page`
-   - a detail screen → `ui_show_page`
+   - a form screen → `ui_form_page`, then `ui_page` holding the form
+   - a detail screen → `ui_show_page`, then `ui_page` holding `ui_page_header`
+     and the details
    - anything else → `ui_page`, with `ui_page_header` for the desktop title.
 
-   `ui_form_page` and `ui_show_page` render the desktop "Back" link themselves,
-   so never add a second back link or button to those screens. Whether a screen
+   ```erb
+   <%= ui_form_page(title: "New quote", back_url: quotes_path) %>
+   <%= ui_page(max_width: :md) do %>
+     <%= ui_form(action: quotes_path) do %>
+       ...
+     <% end %>
+   <% end %>
+   ```
+
+   The shell call always comes first and sits outside `ui_page`'s block,
+   because `ui_page` renders what the shell handed it at its own top. A form or
+   detail screen without `ui_page` shows no desktop "Back" link or form title.
+   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

@@ -26,9 +26,14 @@ separate mobile and desktop treatments (a bottom tab bar and mobile header on
 small screens, a full navigation bar from the `lg:` breakpoint up), because
 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 the shell renders a "Back" link above the title from `lg:` up.
-Given a trail of earlier pages instead, the shell renders breadcrumbs there in
-place of that link, ending with the page's own title.
+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. 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.
 
 ## 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 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

data/the_local/interface.yml

@@ -114,6 +114,7 @@ sources:
   - app/components/keystone/ui/navbar_component.rb
   - app/components/keystone/ui/option_card_component.rb
   - app/components/keystone/ui/page_component.rb
+  - app/components/keystone/ui/page_component.html.erb
   - app/components/keystone/ui/page_header_component.rb
   - app/components/keystone/ui/panel_component.rb
   - app/components/keystone/ui/pipeline_component.rb

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keystone_ui
 version: !ruby/object:Gem::Version
-  version: 0.21.0
+  version: 0.22.0
 platform: ruby
 authors:
 - Tyler Schneider