keystone_ui 0.20.0 → 0.21.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2831a7bc53b87bd905d8b270f78c26d1d47a8fe32bff2bf53c60093b8c84cf03
-  data.tar.gz: 36cf740c39fbeb33f4cc27d9ea4942e3ddfac9712856c195de49d3cde4989f66
+  metadata.gz: 2c400b566f0760e79b2808012f91e7b4d978ec0ad7e7caa8b83dc0e18b1007ec
+  data.tar.gz: 594c632edd55b0ae49c62226ae0e8ebdcc38469827abf0f508c87f9812f79aa2
 SHA512:
-  metadata.gz: ddf44be2fc4062b9ab5655f72d613dad4d6e367cfd138c95513adfd1cb749df42c7b1309972d688b629247b792cceba97f568c55850609209e6e1ae9426972c9
-  data.tar.gz: 70507b228b07861f2ca48449bfa3dbeb0b28019bd5f3a5a22eaf2cfa4ba852d160a7401ec0058c7a8e832afea1a06e1c548b312bab74a8f5efa93d5f05f903b1
+  metadata.gz: ed9434328fd13e5c1a48060beba4174ebb78d72b36fbec129389571c40661a58ef5adc6e1245e19186a92a31738a80e4ba4896390b883b909d45d33ce1de93d9
+  data.tar.gz: 9ae4ec9ec70310c666b8c3bd810517099e5d03566f04763c706df9193b705d512c585f0b64427db6999acd0318f88047f24af0dcc6cea65971abbf6a8c558dd6

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

@@ -0,0 +1,14 @@
+<nav aria-label="Breadcrumb" class="<%= CLASSES %>">
+  <% @trail.each_with_index do |(label, href), index| %>
+    <% if index.positive? %>
+      <span aria-hidden="true"><%= SEPARATOR %></span>
+    <% end %>
+    <%= link_to label, href %>
+  <% end %>
+  <% if @current %>
+    <% if @trail.any? %>
+      <span aria-hidden="true"><%= SEPARATOR %></span>
+    <% end %>
+    <span aria-current="page"><%= @current %></span>
+  <% end %>
+</nav>

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

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Keystone
+  module Ui
+    class BreadcrumbsComponent < ViewComponent::Base
+      CLASSES = "ks-mobile-header-back hidden lg:block text-sm"
+      SEPARATOR = "›"
+
+      def initialize(trail:, current: nil)
+        @trail = trail
+        @current = current
+      end
+    end
+  end
+end

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

@@ -0,0 +1,4 @@
+<%= link_to @url, class: CLASSES do %>
+  <%= Keystone::Ui::MobileHeaderComponent::BACK_ICON.html_safe %>
+  <%= LABEL %>
+<% end %>

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

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Keystone
+  module Ui
+    class DesktopBackLinkComponent < ViewComponent::Base
+      CLASSES = "ks-mobile-header-back hidden lg:inline-flex items-center"
+      LABEL = "Back"
+
+      def initialize(url:)
+        @url = url
+      end
+    end
+  end
+end

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

@@ -2,9 +2,17 @@
 <% content_for :form_page_title, @title %>
 <% content_for :form_page_back_url, @back_url %>
 
-<div class="<%= DESKTOP_WRAPPER_CLASSES %>">
-  <h1 class="<%= TITLE_CLASSES %>"><%= @title %></h1>
-  <% if subtitle? %>
-    <p class="<%= SUBTITLE_CLASSES %>"><%= @subtitle %></p>
-  <% end %>
-</div>
+<% if @trail %>
+  <% content_for :keystone_page_header, render(Keystone::Ui::BreadcrumbsComponent.new(trail: @trail, current: @title)) %>
+<% else %>
+  <% content_for :keystone_page_header, render(Keystone::Ui::DesktopBackLinkComponent.new(url: @back_url)) %>
+<% end %>
+
+<% 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,10 +7,11 @@ module Keystone
       TITLE_CLASSES = "ks-page-title text-2xl"
       SUBTITLE_CLASSES = "ks-page-header-subtitle text-sm"
 
-      def initialize(title:, back_url:, subtitle: nil)
+      def initialize(title:, back_url:, subtitle: nil, trail: nil)
         @title = title
         @back_url = back_url
         @subtitle = subtitle
+        @trail = trail
       end
 
       def subtitle?

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

@@ -2,3 +2,9 @@
 <% content_for :show_page_title, @title %>
 <% content_for :show_page_back_url, @back_url %>
 <% content_for :show_page_subtitle, @subtitle if @subtitle.present? %>
+
+<% if @trail %>
+  <% content_for :keystone_page_header, render(Keystone::Ui::BreadcrumbsComponent.new(trail: @trail, current: @title)) %>
+<% else %>
+  <% content_for :keystone_page_header, render(Keystone::Ui::DesktopBackLinkComponent.new(url: @back_url)) %>
+<% end %>

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

@@ -7,10 +7,11 @@ module Keystone
       TITLE_CLASSES = "ks-page-title text-2xl"
       SUBTITLE_CLASSES = "ks-page-header-subtitle text-sm"
 
-      def initialize(title:, back_url:, subtitle: nil)
+      def initialize(title:, back_url:, subtitle: nil, trail: nil)
         @title = title
         @back_url = back_url
         @subtitle = subtitle
+        @trail = trail
       end
 
       def subtitle?

data/app/helpers/keystone_ui_helper.rb

@@ -117,6 +117,10 @@ module KeystoneUiHelper
     render Keystone::Ui::ShowPageComponent.new(**args)
   end
 
+  def ui_breadcrumbs(**args)
+    render Keystone::Ui::BreadcrumbsComponent.new(**args)
+  end
+
   def ui_mobile_header(**args)
     render Keystone::Ui::MobileHeaderComponent.new(**args)
   end

data/lib/keystone_ui/safelist.rb

@@ -57,7 +57,9 @@ module Keystone
       Keystone::Ui::CodeComponent,
       Keystone::Ui::DisclosureComponent,
       Keystone::Ui::ThemeToggleComponent,
-      Keystone::Ui::CalculationComponent
+      Keystone::Ui::CalculationComponent,
+      Keystone::Ui::DesktopBackLinkComponent,
+      Keystone::Ui::BreadcrumbsComponent
     ].freeze
 
     # Constants that hold non-CSS values (e.g. HTML input type maps)

data/lib/keystone_ui/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module KeystoneUi
-  VERSION = "0.20.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`.
@@ -62,12 +64,27 @@ 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)` — the shell marker for a form
-  screen. Renders the desktop title block and publishes the title and back URL so
-  the navbar can render mobile header context.
-- `ui_show_page(title:, back_url:, subtitle: nil)` — the shell marker for a
-  detail screen. Renders nothing itself; only publishes the title, subtitle, and
-  back URL for the navbar.
+- `ui_form_page(title:, back_url:, 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.
+- `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,
+  rendered last, unlinked, and marked as the current page. On a form or detail
+  screen pass `trail:` to the shell instead of calling this helper.
 
 ### Navigation
 
@@ -289,12 +306,29 @@ 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` publish their title and back URL for the
-   navbar to render as a mobile header. Check the app's layout: if it does not
+   ```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
+   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
    developer whether to wire it before adding more screens that depend on it.
 
@@ -369,7 +403,7 @@ outer element. See Conventions before using it.
   through it, so anything else emitted inside their block is discarded.
 - **Mobile is not an afterthought.** Several helpers render only on one side of
   the `lg:` (or `sm:`) breakpoint — page headers, mobile headers, mobile actions,
-  bottom navigation. A screen needs both treatments; check the small viewport
+  bottom navigation, breadcrumbs. A screen needs both treatments; check the small viewport
   before calling it done.
 - Out of scope for this local: installing or upgrading the gem, changing the
   palette or theme defaults, and editing the components themselves. Building a

data/the_local/agents/keystone_ui-info.md

@@ -13,7 +13,7 @@ It changes nothing and gives no steps.
 Keystone UI is a Rails engine gem that supplies a host app's visual layer as a
 library of view helpers built on ViewComponent. Screens are built from named
 pieces — page shells, sections, panels, grids, form fields, data tables,
-navigation bars, cards, stat tiles, charts, funnels, goal buckets, pipelines,
+navigation bars, breadcrumbs, cards, stat tiles, charts, funnels, goal buckets, pipelines,
 banners, the calculation behind a figure — instead of hand-written ERB and
 Tailwind. Every class the UI renders lives inside the gem, in frozen constants,
 so the look is defined in one place.
@@ -24,7 +24,13 @@ cannot disagree about spacing, color or dark-mode treatment, and a change to a
 component updates every page that uses it. It is mobile-first — components ship
 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.
+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.
 
 ## Interface
 
@@ -91,7 +97,7 @@ holds the catalog.
   chart card, card link, CTA banner, feature grid, hero, data table, code,
   accordion, disclosure, calculation, tab switcher, progress, funnel, bucket,
   pipeline and swipe deck. So do the navigation components: navbar, nav item,
-  nav dropdown, bottom nav, mobile header and settings link. A host imports its
+  nav dropdown, bottom nav, mobile header, breadcrumbs and settings link. A host imports its
   look after `keystone_source.css`, and a gem ships one through
   `tailwind_imports`, both set up through the install local.
 - **Registered looks.** Looks can also be registered by name, and each page

data/the_local/agents/keystone_ui-install.md

@@ -154,8 +154,9 @@ built on ViewComponent; hook it in before building any screen with those helpers
    disclosure, calculation, tab switcher, progress, funnel, bucket, pipeline and
    swipe deck.
    So do the navigation components: navbar, nav item, nav dropdown, bottom nav,
-   mobile header and settings link. The keystone_ui-styles README lists every
-   variable and its default.
+   mobile header and settings link. The desktop "Back" link and the breadcrumbs
+   on form and show pages use the mobile header's back link variables. The
+   keystone_ui-styles README lists every variable and its default.
 
    To offer several looks and choose one per page, register them by name in
    step 7 rather than importing them here.
@@ -197,6 +198,10 @@ built on ViewComponent; hook it in before building any screen with those helpers
      this way scopes its variables to `:root[data-look="<name>"]` instead of
      `:root`, so several can be imported at once.
    - `default_look = :name` — the look a page gets when nothing else chooses one.
+   - The app refuses to boot when `default_look` names a look that is not
+     registered, when a registered look's file does not exist, or when the file
+     sets no `--ks-` variable inside a `:root[data-look="<name>"]` rule. Use an
+     absolute path for each look file.
    - `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.

data/the_local/interface.yml

@@ -33,6 +33,7 @@ develop:
   - ui_alert
   - ui_form_page
   - ui_show_page
+  - ui_breadcrumbs
   - ui_mobile_header
   - ui_mobile_actions
   - ui_navbar
@@ -92,6 +93,11 @@ sources:
   - app/components/keystone/ui/form_component.rb
   - app/components/keystone/ui/form_field_component.rb
   - app/components/keystone/ui/form_page_component.rb
+  - app/components/keystone/ui/form_page_component.html.erb
+  - app/components/keystone/ui/desktop_back_link_component.rb
+  - app/components/keystone/ui/desktop_back_link_component.html.erb
+  - app/components/keystone/ui/breadcrumbs_component.rb
+  - app/components/keystone/ui/breadcrumbs_component.html.erb
   - app/components/keystone/ui/funnel_component.rb
   - app/components/keystone/ui/bucket_component.rb
   - app/components/keystone/ui/bucket_series_component.rb
@@ -108,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
@@ -118,6 +125,7 @@ sources:
   - app/components/keystone/ui/select_component.rb
   - app/components/keystone/ui/settings_link_component.rb
   - app/components/keystone/ui/show_page_component.rb
+  - app/components/keystone/ui/show_page_component.html.erb
   - app/components/keystone/ui/stat_card_component.rb
   - app/components/keystone/ui/stat_card_component.html.erb
   - app/components/keystone/ui/swipe_deck_component.rb

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keystone_ui
 version: !ruby/object:Gem::Version
-  version: 0.20.0
+  version: 0.21.1
 platform: ruby
 authors:
 - Tyler Schneider
@@ -81,6 +81,8 @@ files:
 - app/components/keystone/ui/bottom_nav_component.rb
 - app/components/keystone/ui/bottom_nav_item_component.html.erb
 - app/components/keystone/ui/bottom_nav_item_component.rb
+- app/components/keystone/ui/breadcrumbs_component.html.erb
+- app/components/keystone/ui/breadcrumbs_component.rb
 - app/components/keystone/ui/bucket_component.html.erb
 - app/components/keystone/ui/bucket_component.rb
 - app/components/keystone/ui/bucket_series_component.html.erb
@@ -110,6 +112,8 @@ files:
 - app/components/keystone/ui/cta_banner_component.rb
 - app/components/keystone/ui/data_table_component.html.erb
 - app/components/keystone/ui/data_table_component.rb
+- app/components/keystone/ui/desktop_back_link_component.html.erb
+- app/components/keystone/ui/desktop_back_link_component.rb
 - app/components/keystone/ui/disclosure_component.html.erb
 - app/components/keystone/ui/disclosure_component.rb
 - app/components/keystone/ui/feature_grid_component.html.erb