keystone_ui 0.20.0 → 0.21.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2831a7bc53b87bd905d8b270f78c26d1d47a8fe32bff2bf53c60093b8c84cf03
-  data.tar.gz: 36cf740c39fbeb33f4cc27d9ea4942e3ddfac9712856c195de49d3cde4989f66
+  metadata.gz: 3ebe6bbc917891684b563a1981daf0cc0b32a747143f52d72af17bd2a9df2e7d
+  data.tar.gz: 0320fdf4a5c56b52e6919641022b1fbd05dd2ccdcb5c8b91553f696d3ab3e115
 SHA512:
-  metadata.gz: ddf44be2fc4062b9ab5655f72d613dad4d6e367cfd138c95513adfd1cb749df42c7b1309972d688b629247b792cceba97f568c55850609209e6e1ae9426972c9
-  data.tar.gz: 70507b228b07861f2ca48449bfa3dbeb0b28019bd5f3a5a22eaf2cfa4ba852d160a7401ec0058c7a8e832afea1a06e1c548b312bab74a8f5efa93d5f05f903b1
+  metadata.gz: b6b75345f8165d8ae02e9d7a7e6fe24a015f37f07437082dcad6d3543fa17b56013073ef9c69729be5b330b1959f69e0bb33d628df176d01fe69ae296c33713a
+  data.tar.gz: 04b8b2e35b0d24fcb507d0293142aba61723ed1737478da8376bce4b6533b97fe12ca2efe9a629c92916b1aba4fdee8f47ec7bbf85c8e74bb39e60d409ae9375

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,6 +2,12 @@
 <% content_for :form_page_title, @title %>
 <% content_for :form_page_back_url, @back_url %>
 
+<% if @trail %>
+  <%= render Keystone::Ui::BreadcrumbsComponent.new(trail: @trail, current: @title) %>
+<% else %>
+  <%= render Keystone::Ui::DesktopBackLinkComponent.new(url: @back_url) %>
+<% end %>
+
 <div class="<%= DESKTOP_WRAPPER_CLASSES %>">
   <h1 class="<%= TITLE_CLASSES %>"><%= @title %></h1>
   <% if subtitle? %>

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/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 %>
+  <%= render Keystone::Ui::BreadcrumbsComponent.new(trail: @trail, current: @title) %>
+<% else %>
+  <%= 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.0"
 end

data/the_local/agents/keystone_ui-develop.md

@@ -62,12 +62,23 @@ 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. 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_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
 
@@ -293,8 +304,12 @@ outer element. See Conventions before using it.
    - a detail screen → `ui_show_page`
    - 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
+   `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
+   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 +384,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,11 @@ 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 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.
 
 ## Interface
 
@@ -91,7 +95,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
@@ -118,6 +124,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.0
 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