keystone_ui 0.37.0 → 0.39.0

data/the_local/agents/keystone_ui-info.md

@@ -1,250 +1,106 @@
 ---
 name: keystone_ui-info
-description: Use to learn what Keystone UI offers — what the component system covers, its layout, color and theme model, and the vocabulary the install and develop locals assume.
+description: Use to learn what keystone_ui offers — its UI components for pages, forms, tables, navigation and dashboards, its look, colour and theme model, and the vocabulary the install and develop locals assume.
 tools: Read
 scope: UI — pages, forms, tables, navigation, dashboards
 ---
 
-This local explains Keystone UI and sends you to the local that does the work.
-It changes nothing and gives no steps.
+This local explains keystone_ui and says which local does the work. It changes
+nothing and gives no steps.
 
-## What Keystone UI is
+## What keystone_ui is
 
-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, breadcrumbs, cards, stat tiles, charts, funnels, goal buckets, pipelines,
-banners, the calculation behind a figure, a breakdown of amounts and their
-total, a figure coloured as a gain or a loss, an info button — 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.
+keystone_ui is a Rails engine gem that supplies a host app's UI as view helpers
+built on ViewComponent. Screens are built from named pieces — page shells,
+sections, panels, grids, forms and fields, data tables, navigation, cards, stat
+tiles, charts, funnels, goal buckets, pipelines, breakdowns and info buttons —
+instead of hand-written ERB and Tailwind. Every class the UI renders lives in the
+gem, so two pages built from the same helpers cannot disagree about spacing,
+colour or dark-mode treatment, and a change to a component reaches every page
+that uses it.
 
 Reach for it whenever you build or change a screen in an app that has it
-installed. It exists to stop UI drift: two pages built from the same helpers
-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. The form and show page shells
-follow the same split for going back: the mobile header carries the back arrow on
-small screens, and from `lg:` up the shell shows a "Back" link. Given a trail of
-earlier pages, the shell shows breadcrumbs under that "Back" 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.
-
-A nav tab's own page has nowhere to go back to, and it says so by passing an
-empty trail. Such a page shows no "Back" link and no breadcrumbs, and its mobile
-header shows no back arrow. Every other 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 and says an empty trail marks a nav tab's page. A trail with a link
-missing its label or its address raises `KeystoneUi::IncompleteTrail`, also
-naming the page. The "Back" link, the 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.
+installed. It is mobile-first, because these apps are often shown in a native
+web view: small screens get a mobile header and a bottom tab bar, and from the
+`lg:` breakpoint up the app gets a full navigation bar or sidebar.
 
 ## Interface
 
-This local declares no commands. The two working surfaces belong elsewhere:
+This local declares no commands. The working surfaces belong to the other two:
 
-- **Getting the gem into a host app** — adding it, wiring Tailwind, Stimulus and
-  the theme attributes on the layout, setting the palette, and the suppliers
-  for trails, themes, looks and saved table layouts → **`keystone_ui-install`**.
-- **Building UI with it** — which helper renders what, what keywords it takes,
-  how helpers nest → **`keystone_ui-develop`**.
+- **Getting the gem into a host app** — the install generator, the
+  configuration block, the theme and look attributes on the layout, the palette,
+  registered looks, the navigation groups, and the suppliers for trails, themes,
+  looks, the current tab and saved preferences → **`keystone_ui-install`**.
+- **Building screens with it** — which helper renders what, the keywords each
+  takes, and how they nest → **`keystone_ui-develop`**.
 
 ## How to use it
 
-One decision: is Keystone UI already set up in the app?
+One decision: is keystone_ui set up in the app?
 
 - No, or the setup is out of date → **`keystone_ui-install`**.
-- Yes, and you have a screen to build or edit → **`keystone_ui-develop`**. Do not
-  hand-write ERB or Tailwind for UI it covers.
-
-Questions about which piece fits a scenario also go to the develop local, which
-holds the catalog.
+- Yes, and there is a screen to build or edit, or a question about which piece
+  fits → **`keystone_ui-develop`**. Do not hand-write ERB or Tailwind for UI it
+  covers.
 
 ## Conventions
 
-- **Helpers, not classes.** Every piece of UI is a view helper prefixed `ui_`,
-  called from ERB. The one layout helper that is not prefixed `ui_` writes the
-  theme onto the page's `html` tag, and it belongs to the install local.
-  Components live under the `Keystone::Ui` namespace, but a host app does not
-  name a component class directly. The one exception is the table column value
-  object, which is passed as an argument and renders nothing.
-- **Containers take blocks, leaves take keywords.** Helpers that wrap content
-  (page shells, sections, panels, grids, forms, tables) yield a block. Helpers
-  that render one thing (a button, a badge, a field, a stat, a bucket) are
-  configured entirely by keyword arguments. The navigation bar exposes named
-  slots instead of a single block.
-- **Action menus.** An action menu is an ellipsis button that opens a dropdown
-  of actions, shown at every screen size. The mobile action menu is the one
-  hidden from `lg:` up. Each action is a label, an address and an HTTP method.
-  A plain visit renders as a link. Any other method renders as a button that
-  sends that method, so an action that changes data is never a bare link. An
-  action can carry a question that Turbo asks before it runs. A delete asks
-  "<label> this? This cannot be undone." unless it is given its own question,
-  and other actions ask nothing unless given one. A data table puts each row's actions in one action menu at the end of the row,
-  and a section can carry an action menu in its header beside its title.
-- **Info panels.** A stat card, a radio card and a checkbox row can each carry
-  extra text about themselves. Given that text, the piece shows an info button,
-  and the text stays hidden until the button is hovered or tapped. A piece
-  given no such text shows no button. On a radio card and a checkbox row the
-  button sits on the line with the label. Wherever it is placed, the button
-  sits level with the text beside it.
-- **Standalone info button.** The same info button can be placed on its own,
-  beside anything. It takes a short summary, which is required, and shows it
-  when the button is hovered. Given nothing more, a tap shows the summary too.
-  Given a block of further detail, a tap opens that detail instead, in a panel
-  under the button, and the summary stays the hover text. Both popups are
-  placed against the screen, not against the element the button sits in, so a
-  table or any other container that clips its contents does not cut them off.
-  Each opens under the button with its right edge on the button's, the first
-  time as well as every later time, and is kept on the screen when the button
-  is near the left edge. The detail panel is wider than the summary. Both carry
-  one shared popup class from keystone_ui-styles, which decides how their text
-  wraps and how they fit a narrow screen. A second tap closes
-  what the first opened, a click anywhere else closes the detail, and
-  scrolling the page closes both.
-- **A breakdown is text.** A breakdown lists amounts, each beside a label
-  saying what it is, and ends with a total set apart from the lines above it.
-  Every line and the total are an amount and a label, passed as
-  already-formatted text and shown as written. The component adds nothing up,
-  so the total is whatever it is given. Its whole layout comes from
-  keystone_ui-styles' `ks-breakdown` classes: how the amounts and labels line
-  up, and how the total is set apart. The component sets no widths or spacing
-  of its own, so a breakdown looks right only with a keystone_ui-styles version
-  that defines those classes. It has no button and no hidden state of
-  its own, and it can be placed inside an info button's detail.
-- **A toned figure is text.** A figure shows one amount inline, in plain text
-  or in the success or danger colour, so it reads as a gain or a loss without a
-  badge around it. The amount is passed as already-formatted text and shown as
-  written, and the tone is chosen by name. An unknown tone raises at render
-  time. The colours come from keystone_ui-styles, so a figure shows its tone
-  only with a keystone_ui-styles version that defines those classes.
-- **The last table column is right-aligned.** In a data table with no actions
-  column, the last column's header is right-aligned like the cells beneath it,
-  so a figure or total placed in that header lines up with the figures below.
-- **A locked first column.** A table column can be marked locked. When it is
-  the table's first column, its header and cells stay in view while the rest
-  of the table scrolls sideways, styled by keystone_ui-styles' locked header
-  and cell classes. A locked column anywhere else renders as an ordinary
-  column. A locked column cannot be hidden or moved, so it never appears in the
-  "Columns" menu and a saved layout leaves it where it is, even when it is also
-  marked hideable.
-- **Saved table layouts.** A data table can be given a key naming it. A table
-  with a key asks the app, or another gem such as keystone_ui-preferences, for
-  the layout saved under that key for the request. A saved layout lists the
-  columns to hide, and only columns marked hideable can be hidden. The columns
-  the table's own call hides are its default layout. A saved layout that lists
-  columns to hide replaces that default, and a saved empty list shows every
-  column. When nothing is saved, or the saved layout lists no columns to hide,
-  the table keeps its default. A saved layout can also list an order for the
-  columns. Only hideable columns move: they fill the places hideable columns
-  held in the table's own call, in the saved order, and any the order leaves
-  out follow the ones it names. Every other column keeps its place, and a
-  layout with no order keeps the order the columns were declared in. When the
-  supplier gives an address to save to, a "Columns" menu appears above the
-  table, at its right, and saves the user's choice there, even before anything
-  has been saved. The menu lists the hideable columns in the order the table
-  shows them, each with a box to show or hide it and buttons to move it up or
-  down. The menu and the table read the same saved layout, so the menu's
-  ticked boxes and order always match the columns the table shows. An unticked column's name is greyed at once. Ticking boxes and moving
-  columns sends nothing while the menu is open. Closing the menu, with its
-  Columns button or by clicking anywhere outside it, saves the hidden columns
-  and the order together once, then reloads the page. Closing it with nothing
-  changed saves nothing. When the save is refused or cannot reach the server,
-  the page does not reload. The Columns menu shows the message "Your
-  column changes were not saved." and puts its boxes and order back to what
-  the table shows.
-  A table with no key, or an app with no supplier, renders from its own call
-  alone. Setting up the supplier belongs to the install local.
-- **Suggestions.** A form field can carry a list of suggested values. The
-  browser offers them while the field's text is typed, and the user can still
-  enter a value that is not on the list. This applies to a field with a typed
-  input, such as text, number, email, password or date. A textarea, select or
-  checkbox field ignores the list, and a field given no list offers nothing.
-  It needs no JavaScript.
-- **Options are symbols, and each component accepts its own set.** Appearance is
-  chosen by name — `variant:`, `size:`, `type:`, `padding:`, `spacing:`,
-  `max_width:`, `radius:` — on a size scale (`:sm` … `:xl`) or a short list of
-  named choices. A button's `variant:` and a badge's `variant:` accept
-  different symbols, and the develop local carries the real values. Most
-  components raise on a symbol they do not know, so a wrong guess fails at
-  render time.
-- **Measured values are numbers.** Components that measure or compare values, such as
-  progress bars, funnels and buckets, do arithmetic on them. Pass a number, not
-  a formatted string such as `"9,000"`. A bucket raises on one.
-- **A funnel has two shapes.** Both size each step against the first step and
-  show the percent carried from one step to the next. The default draws one bar
-  per step, each with its label and value on a row above it. The joined shape
-  draws the steps as one figure: each step's value and label sit in a column on
-  the left, each step is a block centred at its width, and a neutral band
-  between two blocks narrows from one width to the next and holds the percent.
-  Any other shape raises `ArgumentError`. Neither shape needs JavaScript.
-- **A line chart is labelled or dated.** A line chart draws one line per
-  series, and each series is a name and its values, with an optional colour
-  and an optional dashed line. Its horizontal axis is given one of two ways,
-  never both and never neither, and the wrong combination raises
-  `ArgumentError`. Labels are text, one per value, spaced evenly and shown as
-  written. Dates are one day per value, and a dated chart places each point by
-  its day, so a gap of a week is seven times as wide as a gap of a day. A dated
-  axis runs from the first day to the last, marks only whole days, and reads
-  each day as a date such as "Oct 2, 2026", which is also what a hovered point
-  shows. A time of day is dropped, so a dated chart has one position per day.
-- **A calculation is text.** The calculation behind a figure is the opposite
-  case. It is a list of groups, each with an optional title and its lines, and
-  each line is a label, the working and the result. They are passed as
-  already-formatted text and shown as written. The component does no
-  arithmetic, and it is closed by default under a quiet summary row.
-- **Semantic color, not literal color.** The themed hue is `accent-*` and the
-  themed neutral family is `surface-*`, both CSS custom properties whose
-  defaults (blue and zinc) come from the keystone_ui-styles gem. Retheming an
-  app changes those values, not the components. Some components still use
-  Tailwind's stock `gray-*` and `zinc-*` neutrals, or fixed status colors such
-  as green and amber, directly. Changing the defaults belongs to the install
-  local.
-- **Looks.** A look is one CSS file that sets the `--ks-` variables from
-  keystone_ui-styles 0.6.0 or later: corner radius, font, label weight, border
-  width, padding and colours. Each colour variable has a `-dark` partner read
-  on a dark page. Buttons, panels, cards, alerts, badges, form fields, the
-  modal, the action menu, the mobile action menu, the column picker, multi select, copy button,
-  theme toggle, checkbox row, radio card, option card, file upload and colour
-  picker read these variables. So do the data display components: stat card,
-  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, 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
-  gets one: the name another gem supplies for the request, then the configured
-  default, each used only when registered. The layout's `<html>` tag carries
-  `data-look="<name>"`, and a registered look file scopes its variables to
-  `:root[data-look="<name>"]`. A host with no registered looks gets no
-  `data-look`. Registering and choosing looks is set up through the install
-  local.
-- **Light, dark, system and custom themes.** Every component has dark-mode
-  styling. The theme is chosen in this order: the user's choice stored in a
+- **Helpers, not classes.** Every piece of UI is a view helper prefixed `ui_`.
+  Components sit under the `Keystone::Ui` namespace, but a host app does not
+  name a component class. The one class a host does name is the table column
+  value object, which is passed as an argument and renders nothing.
+- **Containers take blocks, leaves take keywords.** Page shells, sections,
+  panels, grids, forms and tables wrap a block. A button, badge, field, stat or
+  bucket is set entirely by keyword arguments. The navigation bar takes named
+  slots.
+- **Options are symbols.** Appearance is chosen by name, such as `variant:`,
+  `size:` or `padding:`, and each component accepts its own set. Most raise on a
+  symbol they do not know, so a wrong guess fails at render time.
+- **Numbers and text are different inputs.** Progress bars, funnels and buckets
+  do arithmetic, so they take numbers, and a bucket raises on `"9,000"`. A
+  breakdown, a calculation and a toned figure take already-formatted text, show
+  it as written and add nothing up.
+- **Going back.** A form or show page shell needs a way back: a back link, a
+  trail of earlier pages shown as breadcrumbs, or a trail the app supplies for
+  the request. A nav tab's own page passes an empty trail and shows no back
+  link. A page with none of these raises `KeystoneUi::MissingBackLink`, and a
+  trail link missing a label or an address raises `KeystoneUi::IncompleteTrail`.
+- **Navigation.** The app declares navigation groups, each a label and its tabs,
+  and each tab a key, label, address and permission check. Tabs the user may
+  not see are left out, and a group left with no tabs is left out. A saved
+  preference can place the navigation as a top bar or a left or right sidebar
+  and set the order of groups and tabs. A supplier names the current tab, which
+  is marked active with its group. A declaration with an empty group, a tab with
+  no label or address, or two tabs sharing a key stops the app at boot with
+  `KeystoneUi::NavigationCheck::Error`.
+- **Saved table layouts.** A data table given a key reads the layout saved under
+  it: which hideable columns to hide and their order. With a save address, a
+  "Columns" menu lets the user change it. A locked first column stays in view
+  while the table scrolls sideways and is never hidden or moved.
+- **Action menus.** Each action is a label, an address and an HTTP method. A
+  plain visit is a link, and any other method is a button, so an action that
+  changes data is never a bare link. A delete asks for confirmation by default.
+- **Semantic colour.** The themed hue is `accent-*` and the themed neutrals are
+  `surface-*`, CSS custom properties whose defaults (blue and zinc) come from
+  the keystone_ui-styles gem. Retheming changes those values, not the
+  components.
+- **Looks.** A look is one CSS file setting keystone_ui-styles' `--ks-`
+  variables for radius, font, weight, border, spacing and colour, each colour
+  with a `-dark` partner. Components render `ks-` classes that read them, and
+  their own Tailwind constants hold only layout, size and behaviour. Looks can
+  be registered by name, and the page's `html` tag carries `data-look` for the
+  supplied look or the default, when that name is registered.
+- **Themes.** Light, dark, system and custom. The mode comes from the user's
   cookie, then a mode another gem supplies, then light. System leaves the page
-  to follow the operating system. Custom marks the page for a palette another
-  gem defines. The theme toggle does not offer it, so a page reaches it when
-  another gem supplies it. On a Turbo visit, the page being shown sets the
-  theme, so a change to the mode on the server shows up without a full reload.
-  Marking the layout with the theme is set up through the install local, and
-  placing the toggle on a screen goes through the develop local.
-- **Tailwind classes are static strings.** Class names are never interpolated,
-  so Tailwind's scanner can find them. Widths and heights that depend on data,
-  such as a progress bar or a bucket's fill, are set with an inline style
-  instead. The host needs tailwindcss-rails v4+, and the engine tells Tailwind
-  at boot where the component files are.
-- **Interactivity is Stimulus.** Dropdowns, modals, dismissible alerts, file
-  uploads, the color picker, the multi-select, tab switchers, accordions, the
-  swipe deck, column pickers, info panels, line charts, clipboard copy
-  and the theme toggle ship with the gem as Stimulus controllers registered once
-  at install. A host writes no JavaScript to use them. Components that post
-  somewhere, such as the column picker and the pipeline, post to endpoints the
-  host app or another gem owns.
-- Ruby >= 3.2. ViewComponent >= 2.0 and < 5.
+  to follow the operating system, and custom marks the page for a palette
+  another gem defines, which the theme toggle does not offer.
+- **Static Tailwind classes.** Class names are never interpolated, so Tailwind's
+  scanner finds them. Sizes that depend on data, such as a progress bar's
+  width, use an inline style. The host needs tailwindcss-rails v4+.
+- **Interactivity is Stimulus.** Dropdowns, modals, tab switchers, the column
+  picker, info buttons, charts, copy buttons and the theme toggle ship as
+  Stimulus controllers, so a host writes no JavaScript. Components that post,
+  such as the column picker and the pipeline, post to endpoints the host or
+  another gem owns.
+- Ruby >= 3.2, ViewComponent >= 2.0 and < 5, keystone_ui-styles >= 0.14.0.

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, the breadcrumb trail supplier, the saved table layout supplier 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, the saved table layout supplier, the navigation groups and current tab supplier, and extra Tailwind imports and sources.
 tools: Bash, Read, Edit
 scope: UI — pages, forms, tables, navigation, dashboards
 ---
@@ -28,7 +28,12 @@ built on ViewComponent; hook it in before building any screen with those helpers
   show pages that pass none, and their Back link when they pass none either),
   `preference_supplier` (a callable that supplies the saved hidden columns and
   column order of a data table given a `key:`, and the address its Columns menu
-  saves to),
+  saves to, and the navigation's placement under the key `:navigation`),
+  `navigation_group` (a labelled group of desktop tabs that the navigation
+  helper draws, each tab declared with `tab key, label:, href:, permitted:`),
+  `current_tab_supplier` (a callable that supplies the key of the declared tab
+  the current page belongs to, so the navigation marks it and its group
+  active),
   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.
@@ -43,7 +48,7 @@ built on ViewComponent; hook it in before building any screen with those helpers
 ## How to use it
 
 1. Confirm the prerequisites: Ruby >= 3.2 and **tailwindcss-rails v4+** in the
-   host app. The gem brings ViewComponent and keystone_ui-styles 0.12.0 or later with it.
+   host app. The gem brings ViewComponent and keystone_ui-styles 0.14.0 or later with it.
    Tailwind does not have to be initialized first, because the generator creates
    the stylesheet if it is missing.
 
@@ -183,6 +188,10 @@ built on ViewComponent; hook it in before building any screen with those helpers
      config.look_supplier = ->(view) { view.current_user&.look }
      config.trail_supplier = ->(view) { view.breadcrumb_trail }
      config.preference_supplier = ->(view, key) { TablePreferences.for(view.current_user, key) }
+     config.navigation_group "Sales" do |group|
+       group.tab :quotes, label: "Quotes", href: ->(view) { view.quotes_path }, permitted: ->(view) { view.policy(Quote).index? }
+     end
+     config.current_tab_supplier = ->(view) { view.controller.try(:navigation_tab) }
      config.tailwind_imports << "/absolute/path/to/extra.css"
      config.tailwind_sources << "/absolute/path/to/components/**/*.{erb,rb}"
    end
@@ -226,9 +235,9 @@ built on ViewComponent; hook it in before building any screen with those helpers
      pages, and `nil` for a page whose Back link comes from its own
      `back_url:`.
    - Every other form and show page must end up with a Back link. A page that
-     passes no `back_url:`, and has no trail or a trail whose last link has no
-     address, raises `KeystoneUi::MissingBackLink` naming the page's title when
-     it renders. The message tells the developer to pass `back_url:` or
+     passes no `back_url:`, and has no trail or a trail whose last link's
+     address is `nil`, raises `KeystoneUi::MissingBackLink` naming the page's
+     title when it renders. The message tells the developer to pass `back_url:` or
      `trail:`, to supply a trail through `trail_supplier`, or to pass
      `trail: []` on a nav tab's own page.
    - Every link in a trail needs both a label and an address. A trail with a
@@ -287,9 +296,44 @@ built on ViewComponent; hook it in before building any screen with those helpers
      page unreloaded. The table then shows "Your column changes were not
      saved." beside its Columns button, and the menu's boxes and order go back
      to what the table shows.
+   - For the key `:navigation` the supplier returns the person's navigation
+     placement as `{ value: { "placement" => "left" } }`, with `"left"`,
+     `"right"` or `"top"`. The navigation draws a sidebar on the left or the
+     right of the page content on desktop screens for the first two, and the
+     top bar for `"top"`, `nil`, a value with no `"placement"` string key, or
+     any other placement.
+   - The same `:navigation` value may hold the person's order of groups and
+     tabs under `"order"`, as
+     `[ { "group" => "Admin" }, { "group" => "Sales", "tabs" => [ "orders", "quotes" ] } ]`.
+     A group is named by its declared label and a tab by its key as a string.
+     The navigation draws the named groups and tabs first in that order, then
+     the rest in declared order, and ignores names no longer declared.
    - A companion preferences gem may set this supplier for the app. Ask the
      developer whether the app uses one, or which code stores each user's table
      layouts, before writing the callable.
+   - `navigation_group "Label" do |group| ... end` — declares one menu of
+     desktop tabs, in the order the groups are declared. Inside the block,
+     `group.tab key, label:, href:, permitted:` adds a tab in order. `href:` is
+     an address or a callable that receives the view and returns one.
+     `permitted:` is a callable that receives the view and returns whether the
+     current person may see the tab. A tab the person may not see is left
+     out, and a group with no tab left is left out. Ask the developer which
+     tabs and groups the app has, and which permission check guards each,
+     before declaring them. Boot stops with
+     `KeystoneUi::NavigationCheck::Error` when a tab has no label or no
+     `href:`, when two tabs share a key, or when a group has no tabs. Drawing
+     the declared groups in the layout is done with the navigation helper,
+     which belongs to `keystone_ui-develop`.
+   - `current_tab_supplier` — a callable that receives the view and returns the
+     key of the declared tab the current page belongs to, or `nil`.
+     The navigation shows that tab and its group as active in the top bar and
+     gives that tab and its group's label the `active` class in the sidebar.
+     The key must equal the declared key exactly, so a tab declared as
+     `:quotes` is not matched by the string `"quotes"`.
+     `nil`, a key no declared tab has, or no supplier marks nothing. The
+     callable must answer for every page the layout draws, so a page with no
+     tab returns `nil` rather than raising. Ask the developer how a page names
+     its tab, such as a method on each controller, 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

@@ -39,6 +39,7 @@ develop:
   - ui_action_menu
   - ui_action_menu_item
   - ui_navbar
+  - ui_navigation
   - ui_nav_item
   - ui_nav_dropdown
   - ui_bottom_nav
@@ -71,6 +72,9 @@ sources:
   - app/components/keystone/ui/figure_component.rb
   - lib/generators/keystone/install_generator.rb
   - lib/keystone_ui/configuration.rb
+  - lib/keystone_ui/navigation_group.rb
+  - lib/keystone_ui/navigation_order.rb
+  - lib/keystone_ui/visible_navigation.rb
   - lib/keystone_ui/missing_back_link.rb
   - lib/keystone_ui/incomplete_trail.rb
   - lib/keystone_ui/theme_choice.rb
@@ -131,6 +135,8 @@ sources:
   - app/components/keystone/ui/nav_dropdown_component.rb
   - app/components/keystone/ui/nav_item_component.rb
   - app/components/keystone/ui/navbar_component.rb
+  - app/components/keystone/ui/navigation_component.rb
+  - app/components/keystone/ui/navigation_component.html.erb
   - app/components/keystone/ui/option_card_component.rb
   - app/components/keystone/ui/page_component.rb
   - app/components/keystone/ui/page_component.html.erb

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: keystone_ui
 version: !ruby/object:Gem::Version
-  version: 0.37.0
+  version: 0.39.0
 platform: ruby
 authors:
 - Tyler Schneider
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.12.0
+        version: 0.14.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.12.0
+        version: 0.14.0
 - !ruby/object:Gem::Dependency
   name: view_component
   requirement: !ruby/object:Gem::Requirement
@@ -161,6 +161,8 @@ files:
 - app/components/keystone/ui/nav_item_component.rb
 - app/components/keystone/ui/navbar_component.html.erb
 - app/components/keystone/ui/navbar_component.rb
+- app/components/keystone/ui/navigation_component.html.erb
+- app/components/keystone/ui/navigation_component.rb
 - app/components/keystone/ui/option_card_component.html.erb
 - app/components/keystone/ui/option_card_component.rb
 - app/components/keystone/ui/page_component.html.erb
@@ -206,10 +208,14 @@ files:
 - lib/keystone_ui/look_check.rb
 - lib/keystone_ui/look_choice.rb
 - lib/keystone_ui/missing_back_link.rb
+- lib/keystone_ui/navigation_check.rb
+- lib/keystone_ui/navigation_group.rb
+- lib/keystone_ui/navigation_order.rb
 - lib/keystone_ui/safelist.rb
 - lib/keystone_ui/source_css.rb
 - lib/keystone_ui/theme_choice.rb
 - lib/keystone_ui/version.rb
+- lib/keystone_ui/visible_navigation.rb
 - the_local/agents/keystone_ui-develop.md
 - the_local/agents/keystone_ui-info.md
 - the_local/agents/keystone_ui-install.md