layered-ui-rails 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d5abac205810e228d971ffa9c13f2c069c56be3f143c0f25612f02c2d8b6e598
-  data.tar.gz: 3dbb48d42029cce15cb92dcbd6cc014046032cb7449f145e63854b4898936d14
+  metadata.gz: b9fe544e3cfcfc260bba58a205ada774ffcb1154b48b86fb406d25c189da5b77
+  data.tar.gz: 8d66cf1556700d9c26867ab59aa2d989bfd17f924ea1b7ec7be9cc3feb4626c5
 SHA512:
-  metadata.gz: e39b4bbc08bb0f198320dccf181de35003e0ab2927eabe3666e0f39743e652a3e9ca45dc295d40b3ce22e1a85381392d86bd202dda9d905f1b500f2c837fdb6d
-  data.tar.gz: 8efb4d5a510c8ef52541b0d9f1286e13dce5b8d64c90d7f984e4d4eccfc7153f91eafa83c5beadf54911b2a8a405e5b8c54383ea3884dc2ed6c0169c70f283ca
+  metadata.gz: 5a2aa85d87740cdf751526101c052155edf16f04136fbb164a70d30a1535bd1b68f82ccec6b333f7c001d8a8a7174868cd5f594d1613d0dd470d5f876bf28d2f
+  data.tar.gz: 33f34e0b13bd3ba0494722ffe41142cbfb3c94cd0da47a6a79bc423a9926928e332586def1e1d669b5c806f6f4fb828da14778197f0349d55e79c626071ec9c2

data/.claude/skills/layered-ui-rails/SKILL.md

@@ -103,9 +103,11 @@ Quick reference:
 
 | Helper | Purpose |
 |---|---|
-| `l_ui_navigation_item(label, path, active: nil, &block)` | Sidebar nav link with optional nesting |
+| `l_ui_navigation_item(label, path, ...)` | Sidebar nav link (supports `icon:`, `match: :starts_with`, `expandable:`) |
+| `l_ui_navigation_section(heading = nil, ...)` | Group nav items; supports `collapsible:`, `storage_key:`, `separated:` |
 | `l_ui_breadcrumbs(&block)` | Breadcrumb nav wrapper |
 | `l_ui_breadcrumb_item(label, path = nil)` | Individual breadcrumb |
+| `l_ui_title_bar(title:, breadcrumbs: [], actions: nil, &block)` | Responsive page title bar with breadcrumbs and actions |
 | `l_ui_pagy(pagy)` | Styled pagination (requires pagy gem) |
 | `l_ui_search_form(query, url:, fields:, ...)` | Search form (requires ransack gem) |
 | `l_ui_sort_link(query, attribute, label = nil, ...)` | Sortable table header (requires ransack gem) |
@@ -141,6 +143,7 @@ All controllers use the `l-ui--` namespace and are auto-registered via importmap
 |---|---|---|
 | Theme | `l-ui--theme` | Dark/light mode toggle with localStorage |
 | Navigation | `l-ui--navigation` | Responsive sidebar with backdrop |
+| Navigation section | `l-ui--navigation-section` | Collapsible nav section with localStorage persistence |
 | Panel | `l-ui--panel` | Resizable side panel (Cmd/Ctrl+I toggle) |
 | Panel button | `l-ui--panel-button` | Draggable floating action button |
 | Panel resize | `l-ui--panel-resize` | Panel width drag handle |

data/.claude/skills/layered-ui-rails/references/CONTROLLERS.md

@@ -28,9 +28,19 @@ Responsive sidebar navigation with backdrop overlay on mobile.
 **Targets:** `navigation`, `backdrop`, `toggleButton`, `openIcon`, `closeIcon`
 **Actions:** `toggle`, `close`
 **Keyboard:** Escape to close
+**Behaviour:** Locks body scroll while the mobile overlay is open
 
 The layout wires this up automatically. Navigation items are populated via `content_for :l_ui_navigation_items`.
 
+## Navigation section (`l-ui--navigation-section`)
+
+Collapsible navigation section with optional localStorage persistence. Wired up automatically by `l_ui_navigation_section` when `collapsible: true`.
+
+**Targets:** `toggle`, `panel`
+**Values:** `storageKey` (String, localStorage key), `forceOpen` (Boolean)
+**Actions:** `toggle`
+**Behaviour:** The server renders the section's default open/closed state (and forces it open when it contains the active item). On `connect`, if `forceOpen` is set the stored preference is ignored; otherwise the controller restores the user's stored preference. Clicking the toggle always works (so a force-opened section can still be collapsed) and writes the new state to localStorage.
+
 ## Modal (`l-ui--modal`)
 
 Native `<dialog>` wrapper with focus trap, scroll lock, and focus restoration.

data/.claude/skills/layered-ui-rails/references/CSS.md

@@ -170,6 +170,15 @@ WCAG 2.2 AA table pattern:
 .l-ui-breadcrumbs__link Breadcrumb link
 ```
 
+## Title bar
+
+```
+.l-ui-title-bar          Title bar wrapper used with .l-ui-container--spread
+.l-ui-title-bar__content Breadcrumbs and title column
+.l-ui-title-bar__title   Page title
+.l-ui-title-bar__actions Action area
+```
+
 ## Pagination
 
 ```
@@ -190,8 +199,18 @@ WCAG 2.2 AA table pattern:
 .l-ui-navigation                  Nav flexbox
 .l-ui-navigation__links           Nav links list
 .l-ui-navigation__item            Nav item
-.l-ui-navigation__item--active    Active nav item (with arrow)
-.l-ui-navigation__secondary       Nested nav list
+.l-ui-navigation__item--active    Active nav item (highlighted bg)
+.l-ui-navigation__item-icon       Icon image inside a nav item
+.l-ui-navigation__item-icon-slot  Wrapper for caller-supplied icon HTML (e.g. icon fonts)
+.l-ui-navigation__item-label      Label span inside a nav item
+.l-ui-navigation__section         Section group (li)
+.l-ui-navigation__section--has-heading  Section that has a visible heading
+.l-ui-navigation__section--separated    Section with top border separator
+.l-ui-navigation__section--collapsible  Section with toggle button heading
+.l-ui-navigation__section-heading       Plain section label (small, uppercase, muted)
+.l-ui-navigation__section-toggle        Collapsible section heading (item-row sized button)
+.l-ui-navigation__section-chevron       Toggle chevron (rotates when closed)
+.l-ui-navigation__section-items         Section body (ul, hidden when closed)
 .l-ui-navigation__user            User info section
 .l-ui-navigation__user-name       User name text
 .l-ui-navigation__user-email      User email text
@@ -275,6 +294,7 @@ WCAG 2.2 AA table pattern:
 .l-ui-sr-only                       Visually hidden, screen reader only
 .l-ui-skip-link                     Accessibility skip link
 .l-ui-list                          Styled list
+.l-ui-hr                            Horizontal rule with theme border and vertical spacing
 .l-ui-container--grid               1-col mobile, 2-col desktop grid
 .l-ui-container--spread             Flex row with space-between
 .l-ui-container--pagy               Pagination wrapper

data/.claude/skills/layered-ui-rails/references/HELPERS.md

@@ -5,19 +5,39 @@ All helpers are prefixed `l_ui_` and are available in all views automatically.
 ## Navigation
 
 ```ruby
-l_ui_navigation_item(label, path, active: nil, &block)
+l_ui_navigation_item(label, path, active: nil, match: :exact, icon: nil, icon_path: nil, icon_html: nil)
+l_ui_navigation_section(heading = nil, icon: nil, icon_path: nil, icon_html: nil, collapsible: false, expanded: true, storage_key: nil, separated: false, &block)
 ```
 
+`l_ui_navigation_item`:
 - `label` (String) - link text
 - `path` (String) - URL
-- `active` (Boolean, optional) - force active state; defaults to `current_page?` check
-- `&block` - optional nested navigation items
+- `active` (Boolean, optional) - force the active style; defaults to a match against the current request path. Does not affect `aria-current`, which is set only when `current_page?(path)` is true
+- `match` (Symbol) - `:exact` (default) uses `current_page?`; `:starts_with` activates when the request path begins with `path` (use for parents whose sub-routes should keep the parent highlighted)
+- `icon` (String, optional) - icon name; `"home"` ships with the gem. For others, supply the SVG in the host app at `app/assets/images/layered_ui/icon_NAME.svg`
+- `icon_path` (String, optional) - explicit asset path; takes precedence over `icon:`
+- `icon_html` (ActiveSupport::SafeBuffer, optional) - pre-rendered icon markup for icon-font libraries (e.g. `tag.i(class: "fa-solid fa-house")`); takes precedence over `icon:` and `icon_path:`. Must be already html-safe - plain strings will be escaped. Never pass user-controlled input
+
+`l_ui_navigation_section`:
+- `heading` (String, optional) - non-clickable section heading; omit for an unlabelled group. To expose the parent route of a section, add an "Overview" item inside the block
+- `icon` (String, optional) - host-app icon name next to the heading; resolves the same way as `l_ui_navigation_item`'s `icon:`
+- `icon_path` (String, optional) - explicit asset path next to the heading; takes precedence over `icon:`
+- `icon_html` (String, optional) - pre-rendered icon markup; takes precedence over `icon:` and `icon_path:`
+- `collapsible` (Boolean) - when `true` and a heading is given, renders a toggle button with a chevron and wires `aria-controls` to the panel
+- `expanded` (Boolean) - default open state for collapsible sections; a section that contains an active descendant always opens
+- `storage_key` (String, optional) - localStorage key to persist the open/closed preference
+- `separated` (Boolean) - draw a horizontal rule above the section, useful for footer-style groups
+- `&block` - section body, typically `l_ui_navigation_item`s
 
 ```erb
 <% content_for :l_ui_navigation_items do %>
-  <%= l_ui_navigation_item("Home", root_path) %>
-  <%= l_ui_navigation_item("Products", products_path, active: true) do %>
-    <%= l_ui_navigation_item("Electronics", electronics_path) %>
+  <%= l_ui_navigation_section do %>
+    <%= l_ui_navigation_item("Home", root_path, icon: "home") %>
+  <% end %>
+
+  <%= l_ui_navigation_section("Products", collapsible: true, storage_key: "products") do %>
+    <%= l_ui_navigation_item("Overview", products_path) %>
+    <%= l_ui_navigation_item("Electronics", electronics_path, match: :starts_with) %>
     <%= l_ui_navigation_item("Clothing", clothing_path) %>
   <% end %>
 <% end %>
@@ -41,6 +61,29 @@ l_ui_breadcrumb_item(label, path = nil)
 <% end %>
 ```
 
+## Title bar
+
+```ruby
+l_ui_title_bar(title:, breadcrumbs: [], actions: nil, &block)
+```
+
+- `title` (String) - page title rendered as the `<h1>`
+- `breadcrumbs` (Array, optional) - breadcrumb items as `[label, path]` arrays or `{ label:, path: }` hashes
+- `actions` (String|Array, optional) - HTML-safe action content; omit when using a block
+- `&block` - optional action markup, usually buttons or links
+
+```erb
+<%= l_ui_title_bar(
+  title: "Users",
+  breadcrumbs: [
+    ["Home", root_path],
+    ["Admin", admin_path]
+  ]
+) do %>
+  <%= link_to "New user", new_user_path, class: "l-ui-button--primary" %>
+<% end %>
+```
+
 ## Pagination (requires pagy gem)
 
 ```ruby
@@ -124,7 +167,8 @@ Returns a `<th>` element with sort link and ARIA sort attributes.
 
 ```ruby
 l_ui_table(records, columns:, caption: nil, actions: nil,
-           actions_label: "Actions", query: nil, url: nil, turbo_frame: nil)
+           actions_label: "Actions", query: nil, url: nil,
+           turbo_frame: nil, row_id: nil)
 ```
 
 - `records` (ActiveRecord::Relation or Array) - the collection to render
@@ -135,6 +179,7 @@ l_ui_table(records, columns:, caption: nil, actions: nil,
 - `query` (Ransack::Search, optional) - enables sortable column headers
 - `url` (String, optional) - sort link URL (passed to `l_ui_sort_link`)
 - `turbo_frame` (String, optional) - turbo frame target for sort links
+- `row_id` (Proc, optional) - receives (record), returns the `<tr>` id. Defaults to `dom_id(record)` for records that respond to `to_key` (ActiveRecord). Return `nil` to omit the id.
 
 Column options:
 - `attribute` (Symbol) - used for label generation and sort links

data/CHANGELOG.md

@@ -2,7 +2,32 @@
 
 All notable changes to this project will be documented in this file. This project follows [Semantic Versioning](https://semver.org/).
 
-## [Unreleased]
+## [0.10.0] - 2026-05-03
+
+### Added
+
+- Nested navigation: `l_ui_navigation_section` helper for collapsible sidebar sections, backed by an `l-ui--navigation-section` Stimulus controller and `l-ui-navigation__section`/`__toggle`/`__items` styles
+- Optional `icon:` / `icon_path:` / `icon_html:` arguments on `l_ui_navigation_item` and `l_ui_navigation_section` to render an icon alongside the label; ships with a default `icon_home.svg` as an example
+- `row_id:` option on `l_ui_table` to set a stable DOM id on each row (useful for Turbo Stream targeting)
+
+### Changed
+
+- **Breaking:** Minimum Ruby version raised to 3.3.0 (Ruby 3.2 is EOL). CI matrix now tests against Ruby 3.3, 3.4, and 4.0
+
+## [0.9.0] - 2026-04-26
+
+### Added
+
+- `l_ui_title_bar` helper for page title bars with optional actions
+- `l-ui-hr` class for styled horizontal rules
+- `color-scheme` CSS property set to match the active theme so native form controls (date pickers, scrollbars, etc.) render with matching light/dark styling
+
+### Changed
+
+- Navigation and panel controllers share an extracted `scroll_lock` utility module
+- Checkbox and radio inputs use a pointer cursor
+- Scroll-to-bottom button is centred and has a faint shadow
+- Form submit label shortened from "Save changes" to "Save"
 
 ## [0.8.0] - 2026-04-24
 

data/README.md

@@ -31,31 +31,22 @@ An open source, Rails 8+ engine that provides WCAG 2.2 AA compliant design token
   </tr>
 </table>
 
-## Getting started
-
-Add to your Gemfile and install:
-
-```bash
-bundle add layered-ui-rails
-bin/rails generate layered:ui:install
-```
-
-The install generator will:
-- Copy `layered_ui.css` to `app/assets/tailwind/`
-- Add `@import "./layered_ui";` to your `application.css`
-- Add `import "layered_ui"` to your `application.js`
-
-Then update your application layout to render the engine layout. Place any `content_for` blocks **above** the render call - the engine layout reads them when it renders, so they must be defined first:
+## Features
 
-```erb
-<% content_for :l_ui_body_class, "l-ui-body--always-show-navigation" %>
+- **Dark/light theme** - system preference detection with localStorage persistence and manual toggle
+- **Responsive layout** - header, sidebar navigation, main content area, and optional resizable panel
+- **WCAG 2.2 AA compliant** - skip links, focus indicators, ARIA attributes, and 4.5:1 contrast ratios
+- **Components** - buttons, forms, surfaces, tables, tabs, notices, badges, conversations, modals, and pagination
+- **Optional integrations** - Devise authentication and Pagy pagination with styled views
+- **Customisable branding** - Override the default logos and icons and colors
+- **Google Lighthouse** - `layered-ui-rails` scores a [perfect 100](https://github.com/layered-ai-public/layered-ui-rails/raw/refs/heads/main/test/dummy/app/assets/images/lighthouse.webp) across all four Google Lighthouse categories - performance, accessibility, best practices, and SEO
 
-<% content_for :l_ui_navigation_items do %>
-  <%= l_ui_navigation_item "Home", root_path %>
-<% end %>
+## Requirements
 
-<%= render template: "layouts/layered_ui/application" %>
-```
+- Ruby on Rails >= 8.0
+- Tailwind CSS Rails >= 4.0
+- Importmap Rails >= 2.0
+- Stimulus Rails >= 1.0
 
 ## Agent skill
 
@@ -75,22 +66,31 @@ bin/rails generate layered:ui:install_agent_skill
 curl -fsSL https://raw.githubusercontent.com/layered-ai-public/layered-ui-rails/main/install-skill.sh | sh
 ```
 
-## Requirements
+## Installation
 
-- Ruby on Rails >= 8.0
-- Tailwind CSS Rails >= 4.0
-- Importmap Rails >= 2.0
-- Stimulus Rails >= 1.0
+Add to your Gemfile and install:
 
-## Features
+```bash
+bundle add layered-ui-rails
+bin/rails generate layered:ui:install
+```
 
-- **Dark/light theme** - system preference detection with localStorage persistence and manual toggle
-- **Responsive layout** - header, sidebar navigation, main content area, and optional resizable panel
-- **WCAG 2.2 AA compliant** - skip links, focus indicators, ARIA attributes, and 4.5:1 contrast ratios
-- **Components** - buttons, forms, surfaces, tables, tabs, notices, badges, conversations, modals, and pagination
-- **Optional integrations** - Devise authentication and Pagy pagination with styled views
-- **Customisable branding** - Override the default logos and icons and colors
-- **Google Lighthouse** - `layered-ui-rails` scores a [perfect 100](https://github.com/layered-ai-public/layered-ui-rails/raw/refs/heads/main/test/dummy/app/assets/images/lighthouse.webp) across all four Google Lighthouse categories - performance, accessibility, best practices, and SEO
+The install generator will:
+- Copy `layered_ui.css` to `app/assets/tailwind/`
+- Add `@import "./layered_ui";` to your `application.css`
+- Add `import "layered_ui"` to your `application.js`
+
+Then update your application layout to render the engine layout. Place any `content_for` blocks **above** the render call - the engine layout reads them when it renders, so they must be defined first:
+
+```erb
+<% content_for :l_ui_body_class, "l-ui-body--always-show-navigation" %>
+
+<% content_for :l_ui_navigation_items do %>
+  <%= l_ui_navigation_item "Home", root_path %>
+<% end %>
+
+<%= render template: "layouts/layered_ui/application" %>
+```
 
 ## Customising theme tokens
 
@@ -223,4 +223,4 @@ Copyright 2026 LAYERED AI LIMITED (UK company number: 17056830). See [NOTICE](NO
 
 ## Trademarks
 
-The source code is fully open, but the layered.ai name, logo, and brand assets are trademarks of LAYERED AI LIMITED. The Apache 2.0 license does not grant rights to use the layered.ai branding. Forks and redistributions must use a distinct name. See [TRADEMARK.md](TRADEMARK.md) for the full policy.
+The source code is fully open, but the layered.ai name, logo, and brand assets are trademarks of LAYERED AI LIMITED. The Apache 2.0 license does not grant rights to use the layered.ai branding. Forks and redistributions must use a distinct name. See [TRADEMARK.md](TRADEMARK.md) for the full policy.

data/app/assets/images/layered_ui/icon_home.svg

@@ -0,0 +1,3 @@
+<svg fill="none" stroke="currentColor" stroke-width="1.5" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
+  <path stroke-linecap="round" stroke-linejoin="round" d="m2.25 12 8.954-8.955c.44-.439 1.152-.439 1.591 0L21.75 12M4.5 9.75v10.125c0 .621.504 1.125 1.125 1.125H9.75v-4.875c0-.621.504-1.125 1.125-1.125h2.25c.621 0 1.125.504 1.125 1.125V21h4.125c.621 0 1.125-.504 1.125-1.125V9.75M8.25 21h8.25" />
+</svg>

data/app/assets/tailwind/layered/ui/styles.css

@@ -47,6 +47,7 @@
 
 @layer base {
   :root {
+    color-scheme: light;
     /* Tier 1 - Accent */
     --accent: oklch(0.2044 0 0);
     --accent-foreground: oklch(1 0 0);
@@ -76,6 +77,7 @@
   }
 
   .dark {
+    color-scheme: dark;
     /* Tier 1 - Accent */
     --accent: oklch(1 0 0);
     --accent-foreground: oklch(0.2044 0 0);
@@ -294,6 +296,13 @@
          space-y-1;
 }
 
+/* Horizontal rule */
+
+.l-ui-hr {
+  @apply my-4
+         border-0 border-t border-border;
+}
+
 /* Markdown */
 
 .l-ui-markdown > *:first-child {
@@ -635,8 +644,8 @@
 }
 
 @utility navigation__item {
-  @apply flex items-center
-         w-full min-h-[44px]
+  @apply flex items-center gap-3
+         w-full min-h-[40px] px-3
          text-sm text-foreground-muted font-medium
          rounded-sm
          focus-ring
@@ -644,50 +653,96 @@
 }
 
 .l-ui-navigation__item {
-  @apply navigation__item
+  @apply navigation__item;
 }
 
 .l-ui-navigation__item--active {
   @apply navigation__item
-         font-bold
-         text-accent;
+         bg-surface-highlighted
+         text-foreground;
+}
 
-  &::after {
-    content: "▸";
-    @apply ml-auto
-           text-2xl font-bold;
-  }
+.l-ui-navigation__item-icon {
+  @apply w-4 h-4 shrink-0
+         dark:invert;
+}
+
+.l-ui-navigation__item-icon-slot {
+  @apply inline-flex items-center justify-center
+         w-4 h-4 shrink-0;
+}
 
-  &:has(~ .l-ui-navigation__secondary .l-ui-navigation__item--active) {
-    @apply pr-3;
+.l-ui-navigation__item-label {
+  @apply truncate;
+}
+
+.l-ui-navigation__section {
+  @apply flex flex-col;
+
+  & + .l-ui-navigation__section {
+    @apply mt-2;
+  }
 
-    &::after {
-      content: none;
-    }
+  & + .l-ui-navigation__section--separated {
+    @apply mt-3 pt-3
+           border-t border-border;
   }
 }
 
-.l-ui-navigation__secondary {
+.l-ui-navigation__section-heading {
+  @apply flex items-center gap-2
+         w-full px-3 pt-4 pb-1
+         text-xs text-foreground-muted font-medium uppercase tracking-wider;
+}
+
+.l-ui-navigation__section-toggle {
+  @apply flex items-center gap-3
+         w-full min-h-[40px] px-3
+         text-sm text-foreground-muted font-medium
+         rounded-sm
+         focus-ring
+         cursor-pointer
+         transition-colors;
+}
+
+.l-ui-navigation__section-chevron {
+  @apply ml-auto inline-block
+         w-3 h-3
+         transition-transform duration-150;
+
+  background-color: currentColor;
+  -webkit-mask-image: url('layered_ui/icon_chevron_down.svg');
+  mask-image: url('layered_ui/icon_chevron_down.svg');
+  -webkit-mask-repeat: no-repeat;
+  mask-repeat: no-repeat;
+  -webkit-mask-position: center;
+  mask-position: center;
+  -webkit-mask-size: contain;
+  mask-size: contain;
+}
+
+.l-ui-navigation__section-toggle[aria-expanded="false"] .l-ui-navigation__section-chevron {
+  @apply -rotate-90;
+}
+
+.l-ui-navigation__section-items {
   @apply flex flex-col
-         pl-4
-         border-l-4 border-border;
-
-  .l-ui-navigation__item--active {
-    @apply bg-transparent
-           font-bold
-           text-accent;
-
-    &::after {
-      content: "▸";
-      @apply ml-auto
-             text-2xl font-bold;
-    }
-  }
+         gap-2;
+}
+
+.l-ui-navigation__section-items[hidden] {
+  display: none;
+}
+
+.l-ui-navigation__section--has-heading .l-ui-navigation__section-items {
+  @apply mt-2 ml-5 pl-3
+         border-l border-border;
 }
 
 .l-ui-navigation__links {
   @apply flex flex-col flex-1
-         px-4 py-2 min-h-0
+         gap-0.5
+         px-3 py-3 min-h-0
          overflow-y-auto;
 }
 
@@ -740,6 +795,26 @@
          focus-ring rounded-sm;
 }
 
+/* Title bar */
+
+.l-ui-title-bar {
+  @apply w-full;
+}
+
+.l-ui-title-bar__content {
+  @apply min-w-0;
+}
+
+.l-ui-title-bar__title {
+  @apply mt-0;
+}
+
+.l-ui-title-bar__actions {
+  @apply flex flex-wrap items-center justify-end
+         gap-2
+         shrink-0;
+}
+
 /* Buttons */
 
 @utility button {
@@ -1017,7 +1092,8 @@ pre.l-ui-surface {
   @apply w-6 h-6
          accent-foreground
          focus-ring
-         rounded-sm;
+         rounded-sm
+         cursor-pointer;
 }
 
 /* Search */
@@ -1124,11 +1200,12 @@ pre.l-ui-surface {
   @apply w-6 h-6
          mr-2
          accent-foreground
-         focus-ring;
+         focus-ring
+         cursor-pointer;
 }
 
 .l-ui-radio__label {
-  @apply text-sm;
+  @apply text-sm cursor-pointer;
 }
 
 /* Tabs */
@@ -1659,10 +1736,11 @@ pre.l-ui-surface {
 .l-ui-scroll-to-bottom {
   @apply
     sticky bottom-2 flex items-center justify-center
-    ml-auto mr-0 -mt-9 h-9 w-9
+    mx-auto -mt-9 h-9 w-9
     rounded-full
     cursor-pointer
     bg-button-primary-bg text-button-primary-icon
+    shadow-sm
     focus-ring
     opacity-0 pointer-events-none
     transition-opacity duration-200;

data/app/helpers/layered/ui/navigation_helper.rb

@@ -1,24 +1,127 @@
+require "securerandom"
+
 module Layered
   module Ui
     module NavigationHelper
-      def l_ui_navigation_item(label, path, active: nil, &block)
-        if block_given?
-          children = capture(&block)
-          is_active = active.nil? ? (current_page?(path) || children.include?("l-ui-navigation__item--active")) : active
-          css_class = is_active ? "l-ui-navigation__item--active" : "l-ui-navigation__item"
-          options = { class: css_class }
-          options["aria-current"] = "page" if is_active && current_page?(path)
-          content_tag(:li) do
-            link_to(label, path, options) +
-              content_tag(:ul, children, class: "l-ui-navigation__secondary", role: "list")
+      def l_ui_navigation_item(label, path, active: nil, match: :exact, icon: nil, icon_path: nil, icon_html: nil)
+        is_active = active.nil? ? l_ui_navigation_item_self_active?(path, match) : active
+
+        css_class = is_active ? "l-ui-navigation__item--active" : "l-ui-navigation__item"
+        options = { class: css_class }
+        options["aria-current"] = "page" if current_page?(path)
+
+        l_ui_navigation_register_active if is_active
+
+        link_content = l_ui_navigation_item_inner(label, icon, icon_path, icon_html)
+
+        content_tag(:li) { link_to(link_content, path, options) }
+      end
+
+      def l_ui_navigation_section(heading = nil, icon: nil, icon_path: nil, icon_html: nil, collapsible: false, expanded: true, storage_key: nil, separated: false, &block)
+        stack = (Thread.current[:l_ui_navigation_section_stack] ||= [])
+        frame = { active: false }
+        stack.push(frame)
+        begin
+          children = block_given? ? capture(&block) : "".html_safe
+        ensure
+          stack.pop
+        end
+
+        has_active_descendant = frame[:active]
+
+        if (parent = stack.last) && has_active_descendant
+          parent[:active] = true
+        end
+
+        is_open = has_active_descendant || expanded
+        is_collapsible = collapsible && heading.present?
+        panel_id = is_collapsible ? "l-ui-navigation-section-#{SecureRandom.hex(4)}" : nil
+
+        section_classes = ["l-ui-navigation__section"]
+        section_classes << "l-ui-navigation__section--has-heading" if heading.present?
+        section_classes << "l-ui-navigation__section--collapsible" if is_collapsible
+        section_classes << "l-ui-navigation__section--separated" if separated
+
+        data = {}
+        if is_collapsible
+          data["controller"] = "l-ui--navigation-section"
+          data["l-ui--navigation-section-storage-key-value"] = storage_key.to_s if storage_key.present?
+          data["l-ui--navigation-section-force-open-value"] = "true" if has_active_descendant
+        end
+
+        content_tag(:li, class: section_classes.join(" "), data: data) do
+          parts = []
+
+          if heading.present?
+            heading_inner = l_ui_navigation_item_inner(heading, icon, icon_path, icon_html)
+
+            if is_collapsible
+              chevron = content_tag(:span, "", class: "l-ui-navigation__section-chevron", "aria-hidden": "true")
+              parts << content_tag(:button,
+                heading_inner + chevron,
+                type: "button",
+                class: "l-ui-navigation__section-toggle",
+                "aria-expanded": is_open.to_s,
+                "aria-controls": panel_id,
+                data: { "l-ui--navigation-section-target": "toggle", action: "click->l-ui--navigation-section#toggle" }
+              )
+            else
+              parts << content_tag(:div, heading_inner, class: "l-ui-navigation__section-heading")
+            end
+          end
+
+          panel_attrs = { class: "l-ui-navigation__section-items", role: "list" }
+          if is_collapsible
+            panel_attrs[:id] = panel_id
+            panel_attrs[:data] = { "l-ui--navigation-section-target": "panel" }
+            panel_attrs[:hidden] = true unless is_open
           end
+          parts << content_tag(:ul, children, **panel_attrs)
+
+          safe_join(parts)
+        end
+      end
+
+      private
+
+      def l_ui_navigation_register_active
+        stack = Thread.current[:l_ui_navigation_section_stack]
+        return unless stack
+        stack.each { |frame| frame[:active] = true }
+      end
+
+      def l_ui_navigation_item_self_active?(path, match)
+        case match
+        when :starts_with
+          normalized = path.to_s.chomp("/")
+          return current_page?(path) if normalized.empty?
+          request.path == path || request.path.start_with?("#{normalized}/")
+        else
+          current_page?(path)
+        end
+      end
+
+      def l_ui_navigation_item_inner(label, icon, icon_path, icon_html)
+        parts = []
+
+        if icon_html.present?
+          parts << content_tag(:span, icon_html, class: "l-ui-navigation__item-icon-slot", aria: { hidden: true })
         else
-          is_active = active.nil? ? current_page?(path) : active
-          css_class = is_active ? "l-ui-navigation__item--active" : "l-ui-navigation__item"
-          options = { class: css_class }
-          options["aria-current"] = "page" if is_active
-          content_tag(:li) { link_to label, path, options }
+          resolved_icon_path =
+            if icon_path.present?
+              icon_path
+            elsif icon.present?
+              "layered_ui/icon_#{icon}.svg"
+            end
+
+          if resolved_icon_path
+            parts << image_tag(resolved_icon_path, alt: "", class: "l-ui-navigation__item-icon", aria: { hidden: true })
+          end
         end
+
+        parts << content_tag(:span, label, class: "l-ui-navigation__item-label")
+
+        safe_join(parts)
       end
     end
   end

data/app/helpers/layered/ui/table_helper.rb

@@ -33,7 +33,12 @@ module Layered
       #
       # Pass +query:+ (a Ransack search object) and +turbo_frame:+ to enable
       # sortable column headers via +l_ui_sort_link+.
-      def l_ui_table(records, columns:, caption: nil, actions: nil, actions_label: "Actions", query: nil, url: nil, turbo_frame: nil)
+      #
+      # Each <tr> is given +id: dom_id(record)+ when the record responds to
+      # +to_key+ (i.e. ActiveRecord), so individual rows can be targeted by
+      # Turbo Streams. Pass +row_id:+ as a proc to override (return +nil+ to
+      # omit the id).
+      def l_ui_table(records, columns:, caption: nil, actions: nil, actions_label: "Actions", query: nil, url: nil, turbo_frame: nil, row_id: nil)
         columns = normalise_table_columns(columns)
         col_count = columns.size + (actions ? 1 : 0)
 
@@ -58,7 +63,7 @@ module Layered
             end
           else
             safe_join(records.map do |record|
-              tag.tr do
+              tag.tr(id: table_row_id(record, row_id)) do
                 cells = columns.map do |col|
                   table_cell(record, col)
                 end
@@ -95,6 +100,11 @@ module Layered
         end
       end
 
+      def table_row_id(record, row_id)
+        return row_id.call(record) if row_id
+        ActionView::RecordIdentifier.dom_id(record) if record.respond_to?(:to_key) && record.to_key
+      end
+
       def table_cell(record, col)
         value = col[:render].call(record)
 

data/app/helpers/layered/ui/title_bar_helper.rb

@@ -0,0 +1,52 @@
+module Layered
+  module Ui
+    module TitleBarHelper
+      include Layered::Ui::BreadcrumbsHelper
+
+      def l_ui_title_bar(title:, breadcrumbs: [], actions: nil, &block)
+        action_content = block_given? ? capture(&block) : actions
+
+        content_tag(:header, class: "l-ui-title-bar l-ui-container--spread") do
+          safe_join([
+            content_tag(:div, class: "l-ui-title-bar__content") do
+              safe_join([
+                l_ui_title_bar_breadcrumbs(breadcrumbs),
+                content_tag(:h1, title, class: "l-ui-title-bar__title")
+              ].compact)
+            end,
+            l_ui_title_bar_actions(action_content)
+          ].compact)
+        end
+      end
+
+      private
+
+      def l_ui_title_bar_breadcrumbs(breadcrumbs)
+        return if breadcrumbs.blank?
+
+        l_ui_breadcrumbs do
+          safe_join(breadcrumbs.map { |breadcrumb| l_ui_title_bar_breadcrumb_item(breadcrumb) })
+        end
+      end
+
+      def l_ui_title_bar_breadcrumb_item(breadcrumb)
+        case breadcrumb
+        when Hash
+          l_ui_breadcrumb_item(breadcrumb.fetch(:label), breadcrumb[:path])
+        when Array
+          l_ui_breadcrumb_item(breadcrumb[0], breadcrumb[1])
+        else
+          l_ui_breadcrumb_item(breadcrumb)
+        end
+      end
+
+      def l_ui_title_bar_actions(action_content)
+        return if action_content.blank?
+
+        content = action_content.is_a?(Array) ? safe_join(action_content) : action_content
+
+        content_tag(:div, content, class: "l-ui-title-bar__actions")
+      end
+    end
+  end
+end

data/app/javascript/layered_ui/controllers/l_ui/navigation_controller.js

@@ -1,6 +1,7 @@
 import { Controller } from "@hotwired/stimulus"
 import { announce, clearAnnounceTimeout } from "layered_ui/utilities/announce"
 import { isMobile } from "layered_ui/utilities/layout"
+import { lockBodyScroll, unlockBodyScroll } from "layered_ui/utilities/scroll_lock"
 
 export default class extends Controller {
   static targets = ["navigation", "backdrop", "toggleButton", "openIcon", "closeIcon"]
@@ -8,6 +9,7 @@ export default class extends Controller {
   connect() {
     this.previousActiveElement = null
     this.isOpen = false
+    this.isScrollLocked = false
     this._resizeFrame = null
     this.boundHandleResize = () => {
       if (this._resizeFrame) return
@@ -54,6 +56,7 @@ export default class extends Controller {
     this.navigationTarget.classList.add("open")
     this.backdropTarget.classList.add("open")
     this.setNavigationInteractivity(true)
+    this.updateScrollLock()
 
     // Update ARIA attributes and swap icons
     if (this.hasToggleButtonTarget) {
@@ -89,6 +92,7 @@ export default class extends Controller {
     this.navigationTarget.classList.remove("open")
     this.backdropTarget.classList.remove("open")
     this.setNavigationInteractivity(false)
+    this.unlockScroll()
 
     // Update ARIA attributes and swap icons
     if (this.hasToggleButtonTarget) {
@@ -116,6 +120,7 @@ export default class extends Controller {
     clearAnnounceTimeout(this)
     cancelAnimationFrame(this._resizeFrame)
     window.removeEventListener("resize", this.boundHandleResize)
+    this.unlockScroll()
     this.previousActiveElement = null
   }
 
@@ -125,6 +130,7 @@ export default class extends Controller {
     // In overlay mode (default), always respect isOpen state regardless of viewport
     if (isMobile() || !this.alwaysShow) {
       this.setNavigationInteractivity(this.isOpen)
+      this.updateScrollLock()
       return
     }
 
@@ -133,6 +139,7 @@ export default class extends Controller {
     this.navigationTarget.classList.remove("open")
     this.backdropTarget.classList.remove("open")
     this.setNavigationInteractivity(true)
+    this.unlockScroll()
 
     if (this.hasToggleButtonTarget) {
       this.toggleButtonTarget.setAttribute("aria-expanded", "false")
@@ -157,6 +164,28 @@ export default class extends Controller {
     this.navigationTarget.removeAttribute("aria-hidden")
   }
 
+  updateScrollLock() {
+    if (this.isOpen && isMobile()) {
+      this.lockScroll()
+    } else {
+      this.unlockScroll()
+    }
+  }
+
+  lockScroll() {
+    if (this.isScrollLocked) return
+
+    lockBodyScroll()
+    this.isScrollLocked = true
+  }
+
+  unlockScroll() {
+    if (!this.isScrollLocked) return
+
+    unlockBodyScroll()
+    this.isScrollLocked = false
+  }
+
   get alwaysShow() {
     return this.element.classList.contains("l-ui-body--always-show-navigation")
   }

data/app/javascript/layered_ui/controllers/l_ui/navigation_section_controller.js

@@ -0,0 +1,48 @@
+import { Controller } from "@hotwired/stimulus"
+
+const STORAGE_PREFIX = "l-ui-navigation-section:"
+
+export default class extends Controller {
+  static targets = ["toggle", "panel"]
+  static values = {
+    storageKey: String,
+    forceOpen: Boolean
+  }
+
+  connect() {
+    if (this.forceOpenValue) return
+    if (!this.hasStorageKeyValue || !this.storageKeyValue) return
+    let stored
+    try {
+      stored = window.localStorage.getItem(STORAGE_PREFIX + this.storageKeyValue)
+    } catch (_e) {
+      return
+    }
+    if (stored === null) return
+
+    const isOpen = stored === "true"
+    this.toggleTarget.setAttribute("aria-expanded", isOpen ? "true" : "false")
+    if (isOpen) {
+      this.panelTarget.removeAttribute("hidden")
+    } else {
+      this.panelTarget.setAttribute("hidden", "")
+    }
+  }
+
+  toggle() {
+    const isOpen = this.toggleTarget.getAttribute("aria-expanded") !== "true"
+    this.toggleTarget.setAttribute("aria-expanded", isOpen ? "true" : "false")
+    if (isOpen) {
+      this.panelTarget.removeAttribute("hidden")
+    } else {
+      this.panelTarget.setAttribute("hidden", "")
+    }
+
+    if (!this.hasStorageKeyValue || !this.storageKeyValue) return
+    try {
+      window.localStorage.setItem(STORAGE_PREFIX + this.storageKeyValue, isOpen ? "true" : "false")
+    } catch (_e) {
+      // ignore
+    }
+  }
+}

data/app/javascript/layered_ui/controllers/l_ui/panel_controller.js

@@ -2,6 +2,7 @@ import { Controller } from "@hotwired/stimulus"
 import { announce, clearAnnounceTimeout } from "layered_ui/utilities/announce"
 import { storageGet, storageSet } from "layered_ui/utilities/storage"
 import { isMobile } from "layered_ui/utilities/layout"
+import { lockBodyScroll, unlockBodyScroll } from "layered_ui/utilities/scroll_lock"
 
 export default class extends Controller {
   static targets = ["container", "hideButton", "actionButton"]
@@ -9,6 +10,7 @@ export default class extends Controller {
   connect() {
     this.previousActiveElement = null
     this.isOpen = false
+    this.isScrollLocked = false
     this.boundKeyboardShortcut = this.handleKeyboardShortcut.bind(this)
     this.boundCloseOnNavigate = this.closeOnMobileNavigate.bind(this)
     const page = document.querySelector(".l-ui-page")
@@ -34,6 +36,7 @@ export default class extends Controller {
     clearAnnounceTimeout(this)
     document.removeEventListener('keydown', this.boundKeyboardShortcut)
     document.removeEventListener('turbo:visit', this.boundCloseOnNavigate)
+    this.unlockScroll()
     this.previousActiveElement = null
   }
 
@@ -90,9 +93,7 @@ export default class extends Controller {
     if (isMobile()) {
       const main = document.querySelector("main")
       if (main) main.setAttribute("inert", "")
-      this.savedScrollY = window.scrollY
-      document.body.style.top = `-${this.savedScrollY}px`
-      document.body.classList.add("l-ui-scroll-lock")
+      this.lockScroll()
     }
 
     storageSet("panelOpen", "true")
@@ -124,11 +125,7 @@ export default class extends Controller {
 
     const main = document.querySelector("main")
     if (main) main.removeAttribute("inert")
-    document.body.classList.remove("l-ui-scroll-lock")
-    document.body.style.top = ""
-    if (this.savedScrollY !== undefined) {
-      window.scrollTo(0, this.savedScrollY)
-    }
+    this.unlockScroll()
 
     storageSet("panelOpen", "false")
     this.updatePageMargin()
@@ -161,4 +158,18 @@ export default class extends Controller {
       page.style.marginRight = ""
     }
   }
+
+  lockScroll() {
+    if (this.isScrollLocked) return
+
+    lockBodyScroll()
+    this.isScrollLocked = true
+  }
+
+  unlockScroll() {
+    if (!this.isScrollLocked) return
+
+    unlockBodyScroll()
+    this.isScrollLocked = false
+  }
 }

data/app/javascript/layered_ui/index.js

@@ -1,6 +1,7 @@
 import { application } from "controllers/application"
 import ThemeController from "layered_ui/controllers/l_ui/theme_controller"
 import NavigationController from "layered_ui/controllers/l_ui/navigation_controller"
+import NavigationSectionController from "layered_ui/controllers/l_ui/navigation_section_controller"
 import PanelController from "layered_ui/controllers/l_ui/panel_controller"
 import PanelResizeController from "layered_ui/controllers/l_ui/panel_resize_controller"
 import PanelButtonController from "layered_ui/controllers/l_ui/panel_button_controller"
@@ -11,6 +12,7 @@ import TabsController from "layered_ui/controllers/l_ui/tabs_controller"
 application.register("l-ui--search-form", SearchFormController)
 application.register("l-ui--theme", ThemeController)
 application.register("l-ui--navigation", NavigationController)
+application.register("l-ui--navigation-section", NavigationSectionController)
 application.register("l-ui--panel", PanelController)
 application.register("l-ui--panel-resize", PanelResizeController)
 application.register("l-ui--panel-button", PanelButtonController)

data/app/javascript/layered_ui/utilities/scroll_lock.js

@@ -0,0 +1,29 @@
+let lockCount = 0
+let savedScrollY = null
+
+export function lockBodyScroll() {
+  if (lockCount === 0) {
+    savedScrollY = window.scrollY
+    document.body.style.top = `-${savedScrollY}px`
+    document.body.classList.add("l-ui-scroll-lock")
+  }
+
+  lockCount++
+}
+
+export function unlockBodyScroll() {
+  if (lockCount === 0) return
+
+  lockCount--
+
+  if (lockCount === 0) {
+    document.body.classList.remove("l-ui-scroll-lock")
+    document.body.style.top = ""
+
+    if (savedScrollY !== null) {
+      window.scrollTo(0, savedScrollY)
+    }
+
+    savedScrollY = null
+  }
+}

data/app/views/layered/ui/managed_resource/_form.html.erb

@@ -10,7 +10,7 @@
   <% end %>
 
   <div class="l-ui-form__actions">
-    <%= f.submit(record.new_record? ? "Create" : "Save changes",
+    <%= f.submit(record.new_record? ? "Create" : "Save",
                  class: "l-ui-button l-ui-button--primary") %>
   </div>
 <% end %>

data/config/importmap.rb

@@ -3,11 +3,13 @@ pin "layered_ui", to: "layered_ui/index.js"
 # Utilities
 pin "layered_ui/utilities/announce", to: "layered_ui/utilities/announce.js"
 pin "layered_ui/utilities/layout", to: "layered_ui/utilities/layout.js"
+pin "layered_ui/utilities/scroll_lock", to: "layered_ui/utilities/scroll_lock.js"
 pin "layered_ui/utilities/storage", to: "layered_ui/utilities/storage.js"
 
 # Controllers
 pin "layered_ui/controllers/l_ui/modal_controller", to: "layered_ui/controllers/l_ui/modal_controller.js"
 pin "layered_ui/controllers/l_ui/navigation_controller", to: "layered_ui/controllers/l_ui/navigation_controller.js"
+pin "layered_ui/controllers/l_ui/navigation_section_controller", to: "layered_ui/controllers/l_ui/navigation_section_controller.js"
 pin "layered_ui/controllers/l_ui/panel_controller", to: "layered_ui/controllers/l_ui/panel_controller.js"
 pin "layered_ui/controllers/l_ui/panel_resize_controller", to: "layered_ui/controllers/l_ui/panel_resize_controller.js"
 pin "layered_ui/controllers/l_ui/panel_button_controller", to: "layered_ui/controllers/l_ui/panel_button_controller.js"

data/lib/layered/ui/engine.rb

@@ -31,6 +31,7 @@ module Layered
           helper Layered::Ui::NavigationHelper
           helper Layered::Ui::PagyHelper
           helper Layered::Ui::TableHelper
+          helper Layered::Ui::TitleBarHelper
           helper Layered::Ui::FormHelper
           helper Layered::Ui::RansackHelper
         end

data/lib/layered/ui/version.rb

@@ -1,5 +1,5 @@
 module Layered
   module Ui
-    VERSION = "0.8.0"
+    VERSION = "0.10.0"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: layered-ui-rails
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.10.0
 platform: ruby
 authors:
 - layered.ai
@@ -196,6 +196,7 @@ files:
 - app/assets/images/layered_ui/icon_github.svg
 - app/assets/images/layered_ui/icon_globe.svg
 - app/assets/images/layered_ui/icon_hamburger.svg
+- app/assets/images/layered_ui/icon_home.svg
 - app/assets/images/layered_ui/icon_light.svg
 - app/assets/images/layered_ui/icon_linkedin.svg
 - app/assets/images/layered_ui/icon_mail.svg
@@ -215,8 +216,10 @@ files:
 - app/helpers/layered/ui/pagy_helper.rb
 - app/helpers/layered/ui/ransack_helper.rb
 - app/helpers/layered/ui/table_helper.rb
+- app/helpers/layered/ui/title_bar_helper.rb
 - app/javascript/layered_ui/controllers/l_ui/modal_controller.js
 - app/javascript/layered_ui/controllers/l_ui/navigation_controller.js
+- app/javascript/layered_ui/controllers/l_ui/navigation_section_controller.js
 - app/javascript/layered_ui/controllers/l_ui/panel_button_controller.js
 - app/javascript/layered_ui/controllers/l_ui/panel_controller.js
 - app/javascript/layered_ui/controllers/l_ui/panel_resize_controller.js
@@ -226,6 +229,7 @@ files:
 - app/javascript/layered_ui/index.js
 - app/javascript/layered_ui/utilities/announce.js
 - app/javascript/layered_ui/utilities/layout.js
+- app/javascript/layered_ui/utilities/scroll_lock.js
 - app/javascript/layered_ui/utilities/storage.js
 - app/views/devise/confirmations/new.html.erb
 - app/views/devise/mailer/confirmation_instructions.html.erb
@@ -271,7 +275,7 @@ metadata:
   source_code_uri: https://github.com/layered-ai-public/layered-ui-rails
   bug_tracker_uri: https://github.com/layered-ai-public/layered-ui-rails/issues
   changelog_uri: https://github.com/layered-ai-public/layered-ui-rails/blob/main/CHANGELOG.md
-  documentation_uri: https://www.layered.ai
+  documentation_uri: https://layered-ui-rails.layered.ai/
   discord_uri: https://discord.gg/aCGqz9Bx
   rubygems_mfa_required: 'true'
 post_install_message: |
@@ -293,7 +297,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 3.2.0
+      version: 3.3.0
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="