layered-ui-rails 0.9.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ff66e126597c535133ec15b8fa13fd0efeecfe319b9a60d383b051ce111234e1
-  data.tar.gz: 25872e652c050f87c8752a43b8f9184ee3f98f888a7b30086efa4531c329ed1a
+  metadata.gz: b9fe544e3cfcfc260bba58a205ada774ffcb1154b48b86fb406d25c189da5b77
+  data.tar.gz: 8d66cf1556700d9c26867ab59aa2d989bfd17f924ea1b7ec7be9cc3feb4626c5
 SHA512:
-  metadata.gz: 22e3a324fb57843766fc6b243071b305508d88dc8ca00dd428cce23eebb7f965cab8be974fcaeef365e74ba142bff59d28f2b8b9680ff50ab3853c94d1806079
-  data.tar.gz: d0e60d24e524aad6516e2e070db67e31d7eb049d63334f36d99463d2cd2cb392ce8e863070f1952d5387096f5bc5ec06c172346ba57c3fe2b4a78ceeb6cbe4fc
+  metadata.gz: 5a2aa85d87740cdf751526101c052155edf16f04136fbb164a70d30a1535bd1b68f82ccec6b333f7c001d8a8a7174868cd5f594d1613d0dd470d5f876bf28d2f
+  data.tar.gz: 33f34e0b13bd3ba0494722ffe41142cbfb3c94cd0da47a6a79bc423a9926928e332586def1e1d669b5c806f6f4fb828da14778197f0349d55e79c626071ec9c2

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

@@ -103,7 +103,8 @@ 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 |
@@ -142,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

@@ -32,6 +32,15 @@ Responsive sidebar navigation with backdrop overlay on mobile.
 
 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

@@ -199,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

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 %>
@@ -147,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
@@ -158,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,6 +2,18 @@
 
 All notable changes to this project will be documented in this file. This project follows [Semantic Versioning](https://semver.org/).
 
+## [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

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

@@ -644,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
@@ -653,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;
+}
 
-  &:has(~ .l-ui-navigation__secondary .l-ui-navigation__item--active) {
-    @apply pr-3;
+.l-ui-navigation__item-icon-slot {
+  @apply inline-flex items-center justify-center
+         w-4 h-4 shrink-0;
+}
 
-    &::after {
-      content: none;
-    }
+.l-ui-navigation__item-label {
+  @apply truncate;
+}
+
+.l-ui-navigation__section {
+  @apply flex flex-col;
+
+  & + .l-ui-navigation__section {
+    @apply mt-2;
+  }
+
+  & + .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;
 }
 

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/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/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/config/importmap.rb

@@ -9,6 +9,7 @@ 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/version.rb

@@ -1,5 +1,5 @@
 module Layered
   module Ui
-    VERSION = "0.9.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.9.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
@@ -218,6 +219,7 @@ files:
 - 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
@@ -273,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: |
@@ -295,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:
   - - ">="