keystone_ui 0.21.0 → 0.21.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3ebe6bbc917891684b563a1981daf0cc0b32a747143f52d72af17bd2a9df2e7d
-  data.tar.gz: 0320fdf4a5c56b52e6919641022b1fbd05dd2ccdcb5c8b91553f696d3ab3e115
+  metadata.gz: 2c400b566f0760e79b2808012f91e7b4d978ec0ad7e7caa8b83dc0e18b1007ec
+  data.tar.gz: 594c632edd55b0ae49c62226ae0e8ebdcc38469827abf0f508c87f9812f79aa2
 SHA512:
-  metadata.gz: b6b75345f8165d8ae02e9d7a7e6fe24a015f37f07437082dcad6d3543fa17b56013073ef9c69729be5b330b1959f69e0bb33d628df176d01fe69ae296c33713a
-  data.tar.gz: 04b8b2e35b0d24fcb507d0293142aba61723ed1737478da8376bce4b6533b97fe12ca2efe9a629c92916b1aba4fdee8f47ec7bbf85c8e74bb39e60d409ae9375
+  metadata.gz: ed9434328fd13e5c1a48060beba4174ebb78d72b36fbec129389571c40661a58ef5adc6e1245e19186a92a31738a80e4ba4896390b883b909d45d33ce1de93d9
+  data.tar.gz: 9ae4ec9ec70310c666b8c3bd810517099e5d03566f04763c706df9193b705d512c585f0b64427db6999acd0318f88047f24af0dcc6cea65971abbf6a8c558dd6

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/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/lib/keystone_ui/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module KeystoneUi
-  VERSION = "0.21.0"
+  VERSION = "0.21.1"
 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`.
@@ -63,17 +65,21 @@ outer element. See Conventions before using it.
   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.
+  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. 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.
+  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.
 - `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,12 +306,25 @@ 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
    back link comes from `ui_mobile_header`, which the navbar renders from the

data/the_local/agents/keystone_ui-info.md

@@ -26,9 +26,11 @@ 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. 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/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.21.1
 platform: ruby
 authors:
 - Tyler Schneider