lostcoords-ui 0.8.2 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa5ef0cc7f548cfccfe27e49a88e68fea79cd6225b41ee8cb2ff75c744c055e5
-  data.tar.gz: 1df3317a043db991a631bd76d94f90a453605e78cfdc716b40b7e99c8374db11
+  metadata.gz: 6c7fa09422f0fbfb2b1e2caa70338f1c842d12d900097efe8d9577c610041e46
+  data.tar.gz: 1b366575265b9d3662710ec2131fe7bfe64e7b2afcce0662d222189643aa1fbd
 SHA512:
-  metadata.gz: 2469f7423e3a9efafa8ecba6de19a051d68b832e66b8e8859ee604d24102fb7b4594d3911e37a3afac037005c318447c07c6adb21e6ee6ca7794a8a1cc5489d0
-  data.tar.gz: 94b26a83e133249ee797542f66fdd365f303f025da5189e8b6398390a3d2b10a4484e5d5f3dee3a15e91c44fa6431d368a9735751ab19e0b2c9d5975896469a8
+  metadata.gz: 27d701fa2951f3a60871a013ef2618a6dfb09ee9f932bf93b91b3aaae85371c349345e10fbfdfb92c6645e3b24769b2d8c4c55dd144389a05ee4a7cf41f69116
+  data.tar.gz: a1ca746f2c919e114d2a0dbf5995704cacc6389eec9b545c9b26bf3055dd1b8803d03a8adb689dda3463dac5cea925aa81934f61e441d24ff943366167100490

data/README.md

@@ -1,8 +1,8 @@
 # lostcoords-ui
 
-Render complete UI components from Rails or standalone ActionView ERB. Helpers include semantic HTML,
-accessible attributes and Stimulus wiring. Tailwind v4 supplies the styles. Rails integrates Propshaft
-and importmap automatically; standalone applications own their asset build.
+Render complete UI components from Rails views. Helpers include semantic HTML, accessible attributes and
+Stimulus wiring. Tailwind v4 supplies the styles. The Rails engine integrates Propshaft, importmap and
+`tailwindcss-rails`.
 
 ```erb
 <%= lc_button "Save changes", type: :submit, icon: "check" %>
@@ -15,52 +15,33 @@ and importmap automatically; standalone applications own their asset build.
 <% end %>
 ```
 
-The supported stack is ActionView, ERB, Tailwind and Stimulus. Each host application's lockfile pins
-its gem version, so publishing a library update does not upgrade consumers.
+The supported stack is Rails 8 or later with ERB, Tailwind and Stimulus. Each host application's
+lockfile pins its gem version, so publishing a library update does not upgrade consumers.
 
 ## Install
 
 ```ruby
-gem "lostcoords-ui", "~> 0.8.0"
+gem "lostcoords-ui", "~> 0.9.0"
 ```
 
-The engine adds its rendering helpers to host views, its JavaScript to the asset paths and its pins to
-the importmap. Translations live under `lostcoords.ui.*`.
+The engine adds its rendering helpers to host views, its views and translations to the host's lookup
+paths, its JavaScript to the asset paths and its pins to the importmap. Translations live under
+`lostcoords.ui.*`; a host locale file overrides any of them.
 
-### Standalone ActionView
+### Stylesheets
 
-```ruby
-require "lostcoords/ui/action_view"
-
-class ViewContext < ActionView::Base
-  include Lostcoords::Ui::Helpers
-end
+Import the engine's stylesheet after your Tailwind imports. `tailwindcss-rails` generates this path from
+the installed gem on every build:
 
-view = ViewContext.with_empty_template_cache.with_view_paths(Lostcoords::Ui.view_paths)
-view.lc_button("Save", icon: "check")
+```css
+/* app/assets/tailwind/application.css */
+@import "../builds/tailwind/lostcoords_ui.css";
 ```
 
-For an existing view context, include the helpers and append `Lostcoords::Ui.view_paths` to its
-lookup paths after application paths. The loader registers the library's translations without changing
-the default locale. If the host has its own locale handling, override private `lc_locale` in the view
-context; components do not call the host's `t` helper.
-
-Standalone applications compile Tailwind and register Stimulus controllers through their own asset
-pipeline. `Lostcoords::Ui.root` locates the gem's source assets. Rails applications receive automatic
-registration; use `require "lostcoords/ui/rails"` explicitly if Rails loads after the components.
-
-### Standalone assets
-
-Import `app/assets/tailwind/lostcoords/ui/components.css` from the Bundler-resolved gem root
-into your Tailwind build. This entry includes component rules, default tokens and source scanning.
-It does not set body styles, heading defaults, global inline-code styles or document corner radii.
-Map the library's tokens to your app's theme and keep your Tailwind theme declarations after the import.
-The full `ui.css` entry includes those document defaults and remains the Rails default.
-
 Tailwind always ships component rules, used or not, and generates every utility the scanned helpers
 mention. For a smaller build, import `core.css` and the opt-in components you render instead of
-everything. Each entry carries the rules and scans the sources of its own component only. In Rails,
-every Tailwind build writes stable paths for them next to the engine's own import:
+everything. Each entry carries the rules and scans the sources of its own component only. Every
+Tailwind build writes stable paths for them next to the engine's own import:
 
 ```css
 /* app/assets/tailwind/application.css, instead of ../builds/tailwind/lostcoords_ui.css */
@@ -70,34 +51,17 @@ every Tailwind build writes stable paths for them next to the engine's own impor
 @import "../builds/tailwind/lostcoords_ui/components/menu.css";
 ```
 
-Outside Rails, import the same files from `app/assets/tailwind/lostcoords/ui/` in the gem.
-`base.css` holds the document defaults that `ui.css` adds; skip it when the host owns its base styles.
+`base.css` holds the document defaults: body styles, heading defaults, global inline-code styles and
+document corner radii. Skip it when the host owns its base styles, map the library's tokens to your
+app's theme and keep your Tailwind theme declarations after the imports.
 `core.css` holds the tokens, buttons, badges, avatars, cards, alerts, form controls, choices,
 toggles, layout, typography and navigation. The opt-in entries are `dialog` (with the phone sheet),
 `menu` (menus and popovers), `toast`, `search`, `tooltip`, `collapsible`, `code-block`,
-`emoji-picker`, `table` and `prose`. A component whose entry is missing renders unstyled.
-
-Start one Stimulus application in the host, then register the controllers you use:
-
-```javascript
-import { Application } from "@hotwired/stimulus"
-import { registerControllers } from "lostcoords/ui"
-
-const application = Application.start()
-registerControllers(application, { only: ["lc-copy", "lc-collapsible"] })
-```
-
-Resolve `lostcoords/ui/*` to the gem's `app/javascript/lostcoords/ui/*` and `@hotwired/stimulus` to
-the host's installed package. `registerControllers` imports every controller, so a bundle carries
-them all; to bundle only some, import them directly:
-`import Dialog from "lostcoords/ui/controllers/lc_dialog_controller"` and
-`application.register("lc-dialog", Dialog)`. Build configuration belongs to the host. The entry does not start
-Stimulus or register anything on import. Omit `only` to register all library controllers. Register
-defaults before application overrides. Repeated calls on the same application preserve later
-overrides; unknown controller identifiers raise before registration.
+`emoji-picker`, `table`, `prose` and `shell` (`lc_app_header`, `lc_docs_shell` and `lc_dock`; the dock's action
+menu also needs `menu`). A component whose entry is missing renders unstyled.
 
 The gem's stylesheets write into the `components` and `modules` layers, so the host declares that layer order.
-The theme defines the `dark:` variant with `html[data-theme="dark"]`. `ui.css` carries its own `@source` lines, so Tailwind
+The theme defines the `dark:` variant with `html[data-theme="dark"]`. Each entry carries its own `@source` lines, so Tailwind
 scans the gem's helpers, views and JavaScript wherever the gem is installed.
 
 ### Theming
@@ -194,6 +158,53 @@ lazyLoadControllersFrom("controllers", application)
 `eagerLoadControllersFrom` also works and downloads all of them on every page. A host file with the
 same name, such as `app/javascript/controllers/lc_dialog_controller.js`, replaces the gem's.
 
+To register controllers by hand instead, import `registerControllers` from the `lostcoords/ui` pin:
+
+```javascript
+import { registerControllers } from "lostcoords/ui"
+
+registerControllers(application, { only: ["lc-copy", "lc-collapsible"] })
+```
+
+Omit `only` to register every library controller. Unknown identifiers raise before anything is
+registered, and repeated calls on the same application keep later overrides, so register defaults
+before application overrides.
+
+## Changes in 0.9.0
+
+The gem is Rails-only. It loads through its Rails engine, and the standalone ActionView mode is gone:
+
+- **`require "lostcoords/ui/action_view"` and `require "lostcoords/ui/rails"` are removed.** Use
+  `require "lostcoords/ui"`, or let Bundler require the gem. Both load the engine.
+- **`Lostcoords::Ui.view_paths`, `Lostcoords::Ui.load_translations!` and `Lostcoords::Ui.root` are removed.**
+  The engine adds the gem's views and translations to the host's lookup paths. Use
+  `Lostcoords::Ui::Engine.root` to locate the gem's files.
+- **Components no longer call a private `lc_locale`.** They translate with `I18n.locale`. Set the locale
+  through Rails, for example with `I18n.with_locale` in a controller `around_action`.
+- **The gem depends on `railties` instead of `activesupport`.** An app outside Rails moves to a Rails
+  application and the engine's asset setup above.
+
+Rails apps that load the gem through Bundler need no edits.
+
+New components and options:
+
+- **`lc_toc` is an "On this page" list that follows the reader.** It marks the section scrolled to with
+  `aria-current="location"` and slides an indicator to it. Pass links with `toc.link "Usage", "#usage"`, or
+  rendered HTML with `lc_toc(headings: html)` to list its `h2` and `h3` that carry an id.
+- **Headings and sections can link to themselves.** `lc_heading "Usage", id: "usage", anchor: true` and
+  `lc_section title: "Usage", id: "usage", anchor: true` wrap the title in a link with a `#` mark on hover.
+  `anchor: "section-id"` links a heading to an element around it. `lc_prose(anchors: true)` does the same for
+  rendered Markdown, whose headings Kiln gives ids.
+- **Anchored targets clear sticky chrome.** `.lc-anchor-target` sets a scroll margin of `--lc-sticky-offset`,
+  which `lc_app_header` sets to `5rem` while it renders. Override the property if your header is taller.
+- **`lc_app_header`, `lc_docs_shell` and `lc_dock` move from the Blocks examples into the gem**, in the new
+  `shell` stylesheet entry, with the `lc-app-header` and `lc-dock` controllers. `lc_app_header` yields
+  `header.brand`, `header.nav` and `header.actions`. `lc_docs_shell(navigation:, contents:)` lays out a sidebar,
+  the page and an `lc_toc`. `lc_dock` yields `dock.nav` and `dock.menu`, reserves its height at the end of the
+  page and hides while the on-screen keyboard is open. If you copied the Application header, Documentation
+  layout or Mobile navigation block, you can replace the copy with the helper and delete its stylesheet and
+  controller.
+
 ## Changes in 0.8.2
 
 Nothing needs an edit. New options, and one change you may see:
@@ -540,8 +551,31 @@ on the scroll container to keep its position across Turbo visits and reloads. Co
 `data-lc-scroll-keeper-key-value` share one position for the browser tab. Without a saved position,
 it scrolls the `aria-current="page"` link into view.
 
-This documentation site is built with these components and two copyable blocks: the application
-header and the documentation layout.
+Page chrome lives in the `shell` stylesheet entry. `lc_app_header` is a sticky glass header,
+`lc_docs_shell` lays out a documentation page, and `lc_toc` lists the page's sections and marks the one
+the reader has scrolled to. This documentation site is built with them.
+
+```erb
+<%= lc_app_header do |header| %>
+  <%= header.brand root_path, label: "Acme home" do %><%= image_tag "logo.svg", alt: "" %> Acme<% end %>
+  <%= header.nav class: "max-sm:hidden" do |nav| %>
+    <%= nav.link "Guides", guides_path, current: true %>
+  <% end %>
+  <%= header.actions do %><%= lc_icon_button "Search", icon: "magnifying-glass", size: :sm %><% end %>
+<% end %>
+
+<% contents = lc_toc do |toc| %>
+  <%= toc.link "Usage", "#usage" %>
+  <%= toc.link "Sizes", "#sizes", indent: true %>
+<% end %>
+<%= lc_docs_shell navigation: render("guides/sidebar"), contents: do %>
+  <%= lc_section title: "Usage", id: "usage", anchor: true do %>…<% end %>
+<% end %>
+```
+
+For rendered Markdown, such as a Kiln `.md` view, pass the HTML to both: `lc_prose(anchors: true) { html }`
+links its headings, and `lc_toc(headings: html)` lists them. On phones, `lc_dock` floats `dock.nav` and a
+`dock.menu` of quick actions at the bottom of the screen; render it last, since it reserves its height there.
 
 ```erb
 <%= lc_menu id: "member-actions", label: "Actions for #{member.name}", trigger: :icon do %>
@@ -935,11 +969,15 @@ Blocks live in the docs app. They add no rendering helpers or installable block
 ## Docs
 
 The docs app lives in `test/dummy`. Run `parcela up --detach` and open https://ui.localhost.
-Parcela starts Rails and the Tailwind watcher. `parcela down` stops this environment.
-
-`bin/rails lostcoords:ui:showcase` exports the home, component pages, blocks, token reference, machine-readable
-API and assets to `docs/` for GitHub Pages. CI checks that the export matches the source and that every
-public rendering helper has a runnable example.
+Parcela starts Rails (with live reload through Hotwire Spark) and the Tailwind watcher.
+`parcela down` stops this environment.
+
+`bin/rails kiln:build` exports every docs route to `docs/` for GitHub Pages with
+[Kiln](https://github.com/davafons/kiln): pages, blocks, the token reference, the machine-readable API and
+assets. Param sources for the component and block pages live in `test/dummy/config/kiln.rb`, and a route
+without one fails the build. `bin/rails kiln:serve` serves the export the way GitHub Pages does. CI runs
+`bin/rails kiln:build` and fails when `docs/` changes, and checks that every public rendering helper has a
+runnable example.
 
 ## Development
 

data/app/assets/tailwind/lostcoords/ui/components/shell.css

@@ -0,0 +1,4 @@
+/* lc_app_header, lc_docs_shell and lc_dock. */
+@import "../shell.css";
+@source "../../../../../helpers/lostcoords/ui/shell_helper.rb";
+@source "../../../../../javascript/lostcoords/ui/controllers/lc_{app_header,dock}_controller.js";

data/app/assets/tailwind/lostcoords/ui/components.css

@@ -11,3 +11,4 @@
 @import "./components/emoji-picker.css";
 @import "./components/table.css";
 @import "./components/prose.css";
+@import "./components/shell.css";

data/app/assets/tailwind/lostcoords/ui/core.css

@@ -5,7 +5,7 @@
 @import "./theme.css";
 @source "../../../../helpers/lostcoords/ui/{badge,button,card,choice,copy_button,description_list,feedback,form,glass,icon,layout,list_group,navigation,primitives,render_attributes,structures,tailwind,translation,typography}_helper.rb";
 @source "../../../../javascript/lostcoords/ui/helpers/*.js";
-@source "../../../../javascript/lostcoords/ui/controllers/lc_{copy,kbd,nav,scroll_keeper,selection,shortcut,tabs,toggle}_controller.js";
+@source "../../../../javascript/lostcoords/ui/controllers/lc_{copy,kbd,nav,scroll_keeper,selection,shortcut,tabs,toc,toggle}_controller.js";
 @source "../../../../../lib/lostcoords/ui/parts.rb";
 
 @import "./glass.css";

data/app/assets/tailwind/lostcoords/ui/prose.css

@@ -64,3 +64,12 @@
     @apply lc-inline-code;
   }
 }
+
+@layer utilities {
+  /* A heading's link to itself keeps the heading's look, not a link's. */
+  .lc-prose .lc-anchor {
+    color: inherit;
+    font-weight: inherit;
+    text-decoration: none;
+  }
+}

data/app/assets/tailwind/lostcoords/ui/shell.css

@@ -0,0 +1,161 @@
+/* A sticky lc_app_header covers the top of the page; anchors and the docs
+   sidebars start below it. Override --lc-sticky-offset if your header is taller. */
+:root:has(.lc-app-header) {
+  --lc-sticky-offset: 5rem;
+}
+
+@layer components {
+  .lc-app-header__glass {
+    opacity: 0;
+    transition: opacity 300ms ease;
+  }
+
+  .lc-app-header[data-scrolled] .lc-app-header__glass {
+    opacity: 1;
+  }
+
+  /* The sidebar scrolls on its own without a visible scrollbar. */
+  .lc-docs-shell__sidebar {
+    scrollbar-width: none;
+  }
+
+  .lc-docs-shell__sidebar::-webkit-scrollbar {
+    display: none;
+  }
+
+  .lc-dock {
+    --lc-dock-edge: max(1rem, env(safe-area-inset-left));
+    --lc-dock-gap: max(1rem, env(safe-area-inset-right));
+    --lc-dock-bottom: max(0.75rem, env(safe-area-inset-bottom));
+    --lc-dock-size: 4rem;
+  }
+
+  /* Holds the dock's height at the end of the page, so the last content scrolls clear of it. */
+  .lc-dock__space {
+    block-size: calc(var(--lc-dock-bottom) + var(--lc-dock-size) + 1rem);
+  }
+
+  .lc-dock__menu {
+    position: fixed;
+    z-index: calc(var(--lc-z-sticky) + 1);
+    inset-inline-end: var(--lc-dock-gap);
+    bottom: var(--lc-dock-bottom);
+  }
+
+  .lc-dock__trigger,
+  .lc-dock__action {
+    display: grid;
+    width: var(--lc-dock-size);
+    height: var(--lc-dock-size);
+    place-items: center;
+    padding: 0;
+    color: var(--primary);
+    cursor: pointer;
+  }
+
+  .lc-dock__trigger {
+    position: relative;
+    z-index: 2;
+  }
+
+  .lc-dock__trigger svg {
+    transition: rotate 300ms var(--lc-ease-sheet, ease);
+  }
+
+  .lc-dock__trigger[aria-expanded="true"] svg {
+    rotate: 135deg;
+  }
+
+  .lc-dock__actions {
+    visibility: hidden;
+    pointer-events: none;
+  }
+
+  .lc-dock__actions[data-open] {
+    visibility: visible;
+  }
+
+  .lc-dock__scrim {
+    position: fixed;
+    inset: 0;
+    border: 0;
+    background: color-mix(in oklab, var(--foreground) 18%, transparent);
+    opacity: 0;
+    -webkit-backdrop-filter: blur(calc(var(--spacing) * 2));
+    backdrop-filter: blur(calc(var(--spacing) * 2));
+    transition: opacity 220ms ease;
+  }
+
+  .lc-dock__actions[data-open] .lc-dock__scrim {
+    pointer-events: auto;
+    opacity: 1;
+  }
+
+  .lc-dock__action {
+    position: absolute;
+    z-index: 1;
+    inset: 0;
+    width: calc(var(--lc-dock-size) - 0.5rem);
+    height: calc(var(--lc-dock-size) - 0.5rem);
+    margin: 0.25rem;
+    color: var(--foreground);
+    opacity: 0;
+    transform: scale(0.4);
+    transition: transform 300ms ease, opacity 150ms ease;
+  }
+
+  .lc-dock__actions[data-open] .lc-dock__action {
+    pointer-events: auto;
+    opacity: 1;
+    transform: translateY(calc(var(--lc-dock-action-index, 1) * -4.5rem)) scale(1);
+    transition: transform 420ms cubic-bezier(0.34, 1.45, 0.64, 1), opacity 160ms ease;
+    transition-delay: calc((var(--lc-dock-action-index, 1) - 1) * 40ms);
+  }
+
+  .lc-dock__action-label {
+    position: absolute;
+    inset-inline-end: calc(100% + 0.75rem);
+    width: max-content;
+    max-width: calc(100vw - 7rem);
+    padding: 0.5rem 0.875rem;
+    border-radius: var(--radius-pill);
+    background: var(--background);
+    box-shadow: var(--lc-shadow);
+    color: var(--foreground);
+    font-size: 0.875rem;
+    font-weight: 600;
+  }
+
+  .lc-dock[data-keyboard] :is(.lc-dock__nav, .lc-dock__menu, .lc-dock__space) {
+    display: none;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .lc-app-header__glass,
+    .lc-dock__trigger svg,
+    .lc-dock__scrim,
+    .lc-dock__action,
+    .lc-dock__actions[data-open] .lc-dock__action {
+      transition: none;
+    }
+  }
+}
+
+/* The nav is an lc_nav_list, whose relative position is a utility, so the dock's
+   placement sits in the utilities layer too. */
+@layer utilities {
+  .lc-dock__nav {
+    position: fixed;
+    z-index: var(--lc-z-sticky);
+    inset-inline: var(--lc-dock-edge) var(--lc-dock-gap);
+    bottom: var(--lc-dock-bottom);
+  }
+
+  .lc-dock:has(.lc-dock__menu) .lc-dock__nav {
+    inset-inline-end: calc(var(--lc-dock-gap) + var(--lc-dock-size) + 0.75rem);
+  }
+
+  .lc-dock[data-keyboard] .lc-dock__nav {
+    display: none;
+  }
+}

data/app/assets/tailwind/lostcoords/ui/typography.css

@@ -12,6 +12,32 @@
     overflow-wrap: anywhere;
   }
 
+  /* Headings and sections a link can point to. --lc-sticky-offset is the height
+     of sticky chrome, such as lc_app_header, so the target lands below it. */
+  :where(.lc-anchor-target) {
+    scroll-margin-block-start: calc(var(--lc-sticky-offset, 0rem) + var(--lc-anchor-gap, 1.5rem));
+  }
+
+  /* A heading that links to itself. The mark shows on hover and keyboard focus. */
+  :where(.lc-anchor) {
+    color: inherit;
+    text-decoration: none;
+    border-radius: var(--radius-sm);
+  }
+
+  .lc-anchor::after {
+    content: "#" / "";
+    margin-inline-start: 0.4em;
+    color: var(--muted-foreground);
+    opacity: 0;
+    transition: opacity var(--lc-motion-quick) ease;
+  }
+
+  .lc-anchor:hover::after,
+  .lc-anchor:focus-visible::after {
+    opacity: 1;
+  }
+
   :where(.lc-eyebrow) {
     font-family: var(--font-eyebrow);
     text-transform: uppercase;

data/app/helpers/lostcoords/ui/emoji_picker_helper.rb

@@ -15,9 +15,9 @@ module Lostcoords::Ui
         picker_class: picker_class, trigger_class: trigger_class, popover_class: popover_class, attributes: attributes
     end
 
-    SEARCH_NAMES_PATH = Lostcoords::Ui.root.join("config/emoji_search_names.yml")
-    SEARCH_NAMES_JA_PATH = Lostcoords::Ui.root.join("config/emoji_search_names_ja.yml")
-    SEARCH_ALIASES_PATH = Lostcoords::Ui.root.join("config/emoji_search_aliases.yml")
+    SEARCH_NAMES_PATH = Lostcoords::Ui::Engine.root.join("config/emoji_search_names.yml")
+    SEARCH_NAMES_JA_PATH = Lostcoords::Ui::Engine.root.join("config/emoji_search_names_ja.yml")
+    SEARCH_ALIASES_PATH = Lostcoords::Ui::Engine.root.join("config/emoji_search_aliases.yml")
 
     # Representative glyph for each category's tab in the picker navigation.
     CATEGORY_ICONS = {

data/app/helpers/lostcoords/ui/layout_helper.rb

@@ -51,11 +51,13 @@ module Lostcoords::Ui
       tag.div(**lc_attributes({ class: lc_container_class(size: size) }, attributes), &block)
     end
 
-    def lc_section(title:, level: 2, actions: nil, **attributes, &block)
+    # anchor: true links the heading to the section's id:, for pages readers link into.
+    def lc_section(title:, level: 2, actions: nil, anchor: false, **attributes, &block)
       raise ArgumentError, "title must not be blank" if title.blank?
+      raise ArgumentError, "anchor: true needs an id" if anchor && attributes[:id].blank?
 
-      tag.section(**lc_attributes({ class: lc_stack_class(gap: :heading) }, attributes)) do
-        heading = lc_heading(title, level: level, size: :heading)
+      tag.section(**lc_attributes({ class: lc_stack_class(gap: :heading, extra: ("lc-anchor-target" if anchor)) }, attributes)) do
+        heading = lc_heading(title, level: level, size: :heading, anchor: (attributes[:id] if anchor))
         action_content = actions.respond_to?(:call) ? capture(&actions) : actions
         header = lc_section_header { safe_join([ heading, action_content ].compact) }
         safe_join([ header, lc_stack(&block) ])

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

@@ -84,6 +84,35 @@ module Lostcoords::Ui
       end
     end
 
+    TOC_INDICATOR = "pointer-events-none absolute -start-px top-0 h-0 w-0.5 rounded-pill bg-primary opacity-0 " \
+      "transition-[translate,height,opacity] duration-300 ease-(--lc-ease-out-expo) motion-reduce:transition-none"
+
+    # An "On this page" list that marks the section the reader has scrolled to with aria-current="location".
+    # Yields a builder: `toc.link "Usage", "#usage"`, with indent: true for a subsection. headings: takes
+    # rendered HTML, such as Markdown output, and lists its headings that carry an id, nesting the deeper level.
+    def lc_toc(label: lc_t("lostcoords.ui.toc.label"), headings: nil, levels: 2..3, **attributes, &block)
+      lc_label!(label, :label)
+      raise ArgumentError, "lc_toc takes headings: or a block, not both" if headings && block
+      raise ArgumentError, "lc_toc needs headings: or a block" unless headings || block
+      levels = Array(levels)
+      raise ArgumentError, "levels must be heading levels from 1 to 6" unless levels.any? && levels.all? { |level| (1..6).cover?(level) }
+
+      toc = Parts::Toc.new(self)
+      links = if block
+        capture(toc, &block)
+      else
+        found = Nokogiri::HTML5.fragment(headings.to_s).css(levels.map { |level| "h#{level}[id]" }.join(", "))
+        safe_join(found.map { |heading| toc.link(heading.text.strip, "##{heading['id']}", indent: heading.name.delete("h").to_i > levels.min) })
+      end
+
+      tag.nav(**lc_attributes({ class: "relative", aria: { label: label }, data: { slot: "toc", controller: "lc-toc" } }, attributes)) do
+        safe_join([
+          tag.span(class: TOC_INDICATOR, aria: { hidden: true }, data: { slot: "toc-indicator", lc_toc_target: "indicator" }),
+          tag.ul(links, class: "m-0 flex list-none flex-col border-s border-border p-0")
+        ])
+      end
+    end
+
     # Previous and next links between pages in a sequence. Each side takes [title, url] or nil.
     # compact: true shows icon buttons, for a page header.
     def lc_pager(previous: nil, next: nil, label: lc_t("lostcoords.ui.pager.label"), compact: false, **attributes)

data/app/helpers/lostcoords/ui/reading_helper.rb

@@ -8,8 +8,29 @@ module Lostcoords::Ui
       lc_tw(PROSE_BASE, extra)
     end
 
-    def lc_prose(**attributes, &block)
-      tag.div(**lc_attributes({ class: lc_prose_class }, attributes), &block)
+    # anchors: true links every h2, h3 and h4 that has an id to itself, as rendered Markdown's headings
+    # do. Pass the same HTML to lc_toc(headings:) for an "On this page" list.
+    def lc_prose(anchors: false, **attributes, &block)
+      content = capture(&block) if block
+      content = lc_anchor_headings(content) if anchors && content
+      tag.div(content, **lc_attributes({ class: lc_prose_class }, attributes))
     end
+
+    private
+      def lc_anchor_headings(html)
+        fragment = Nokogiri::HTML5.fragment(html.to_s)
+        fragment.css("h2[id], h3[id], h4[id]").each do |heading|
+          next if heading.at_css("a.lc-anchor")
+
+          heading["class"] = [ heading["class"], "lc-anchor-target" ].compact.join(" ")
+          link = Nokogiri::XML::Node.new("a", fragment.document)
+          link["href"] = "##{heading['id']}"
+          link["class"] = "lc-anchor"
+          link["data-slot"] = "heading-anchor"
+          link.children = heading.children
+          heading.add_child(link)
+        end
+        fragment.to_html.html_safe
+      end
   end
 end

data/app/helpers/lostcoords/ui/shell_helper.rb

@@ -0,0 +1,64 @@
+module Lostcoords::Ui
+  # Page chrome: the sticky application header, the documentation layout and the phone dock.
+  module ShellHelper
+    DOCS_SHELL = "lc-docs-shell mx-auto flex w-full max-w-360 gap-10 px-5 sm:px-8 lg:px-10"
+    DOCS_SHELL_ASIDE = "sticky top-(--lc-sticky-offset,0rem) hidden h-[calc(100dvh-var(--lc-sticky-offset,0rem))] shrink-0 overflow-y-auto"
+
+    # A sidebar, the page and an optional "On this page" column. navigation: is the sidebar, usually
+    # lc_nav_list; it also fills a collapsible menu above the page below lg. contents: is usually lc_toc
+    # and shows from xl. main: adds attributes to the <main>, such as a max width for reading pages.
+    def lc_docs_shell(navigation:, contents: nil, menu_label: lc_t("lostcoords.ui.docs_shell.menu"), sidebar_label: lc_t("lostcoords.ui.docs_shell.sidebar"), main: {}, **attributes, &block)
+      lc_label!(menu_label, :menu_label)
+      lc_label!(sidebar_label, :sidebar_label)
+      raise ArgumentError, "lc_docs_shell needs navigation:" if navigation.blank?
+
+      chevron = lc_icon("chevron-down", options: { class: "size-4 transition-transform duration-(--lc-motion-quick) group-open/menu:rotate-180", "aria-hidden": true })
+      menu = tag.details(class: "group/menu relative z-raised rounded-2xl lc-squircle bg-muted lg:hidden", data: { slot: "docs-shell-menu" }) do
+        safe_join([
+          tag.summary(safe_join([ menu_label, chevron ]), class: "flex min-h-12 cursor-pointer list-none items-center justify-between gap-content px-4 text-label [&::-webkit-details-marker]:hidden"),
+          tag.div(navigation, class: "max-h-[60dvh] overflow-y-auto p-3 pt-0")
+        ])
+      end
+      page = tag.main(**lc_attributes({ id: "main", class: "isolate min-w-0 flex-1 py-5 lg:py-10", data: { slot: "docs-shell-main" } }, main)) do
+        safe_join([ menu, tag.div(capture(&block), class: "pt-6 lg:pt-0") ])
+      end
+
+      tag.div(**lc_attributes({ class: DOCS_SHELL, data: { slot: "docs-shell" } }, attributes)) do
+        safe_join([
+          tag.aside(navigation, tabindex: 0, aria: { label: sidebar_label }, class: lc_tw(DOCS_SHELL_ASIDE, "lc-docs-shell__sidebar w-52 py-8 pe-4 lg:block"),
+            data: { slot: "docs-shell-sidebar", controller: "lc-scroll-keeper", lc_scroll_keeper_key_value: "lc-docs-shell" }),
+          page,
+          (tag.aside(contents, class: lc_tw(DOCS_SHELL_ASIDE, "w-44 py-12 ps-4 xl:block"), data: { slot: "docs-shell-contents" }) if contents.present?)
+        ].compact)
+      end
+    end
+
+    # A sticky header whose glass fades in once the page scrolls. Yields a builder: header.brand,
+    # header.nav and header.actions render in that order along the bar. bar: adds attributes to the
+    # bar, such as a max width. While it renders, --lc-sticky-offset clears it for anchors and sidebars.
+    def lc_app_header(bar: {}, **attributes, &block)
+      raise ArgumentError, "lc_app_header needs a block" unless block
+
+      content = capture(Parts::AppHeader.new(self), &block)
+      tag.header(**lc_attributes({ class: "lc-app-header sticky top-0 z-sticky px-3 pt-3 pb-4 sm:px-6",
+        data: { slot: "app-header", controller: "lc-app-header", action: "scroll@window->lc-app-header#scroll" } }, attributes)) do
+        tag.div(**lc_attributes({ class: "relative isolate mx-auto flex min-h-16 w-full max-w-page items-center gap-related px-3 py-2 sm:gap-content sm:px-5", data: { slot: "app-header-bar" } }, bar)) do
+          safe_join([ tag.span(class: lc_glass_class(thick: true, extra: "lc-app-header__glass pointer-events-none absolute inset-0 -z-(--lc-z-raised)"), aria: { hidden: true }), content ])
+        end
+      end
+    end
+
+    # A floating bar at the bottom of a phone screen: dock.nav for primary destinations and dock.menu
+    # for a button whose actions fan out above it. It reserves its height at the end of the page, so
+    # render it last, and it hides while the on-screen keyboard is open.
+    def lc_dock(**attributes, &block)
+      raise ArgumentError, "lc_dock needs a block" unless block
+
+      content = capture(Parts::Dock.new(self), &block)
+      tag.div(**lc_attributes({ class: "lc-dock", data: { slot: "dock", controller: "lc-dock",
+        action: "resize@window->lc-dock#keyboard focusin@document->lc-dock#keyboard focusout@document->lc-dock#keyboard" } }, attributes)) do
+        safe_join([ content, tag.div(class: "lc-dock__space", aria: { hidden: true }) ])
+      end
+    end
+  end
+end

data/app/helpers/lostcoords/ui/translation_helper.rb

@@ -3,11 +3,7 @@ module Lostcoords::Ui
     private
 
     def lc_t(key, **options)
-      I18n.translate(key, **options, locale: lc_locale)
-    end
-
-    def lc_locale
-      I18n.locale
+      I18n.translate(key, **options)
     end
   end
 end

data/app/helpers/lostcoords/ui/typography_helper.rb

@@ -24,10 +24,17 @@ module Lostcoords::Ui
       lc_tw(KBD_BASE, extra)
     end
 
-    def lc_heading(content = nil, level: 2, size: :heading, trim: false, **attributes, &block)
+    # anchor: true links the heading to itself, so readers can copy a link to it; it needs id:.
+    # anchor: "section-id" links it to an element around it instead, such as its <section>.
+    def lc_heading(content = nil, level: 2, size: :heading, trim: false, anchor: false, **attributes, &block)
       raise ArgumentError, "Invalid level: #{level.inspect}. Expected an integer from 1 to 6" unless (1..6).include?(level) && level.is_a?(Integer)
 
-      tag.public_send("h#{level}", content, **lc_attributes({ class: lc_heading_class(size: size, trim: trim) }, attributes), &block)
+      target = anchor == true ? attributes[:id].to_s : anchor.presence&.to_s
+      raise ArgumentError, "anchor: true needs an id" if anchor == true && target.blank?
+
+      content = capture(&block) if block
+      content = tag.a(content, href: "##{target}", class: "lc-anchor", data: { slot: "heading-anchor" }) if target
+      tag.public_send("h#{level}", content, **lc_attributes({ class: lc_heading_class(size: size, trim: trim, extra: ("lc-anchor-target" if anchor == true)) }, attributes))
     end
 
     # as: picks the element, such as :span inside a row or :h3 for a heading set in a text role.

data/app/javascript/lostcoords/ui/controllers/lc_app_header_controller.js

@@ -0,0 +1,15 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Fades the header's glass in once the page scrolls.
+export default class extends Controller {
+  connect() {
+    this.scroll()
+  }
+
+  // An open modal pins the body, so scrollY reads 0 until it closes; the header keeps the
+  // state it had rather than fading the glass out behind the dialog.
+  scroll() {
+    if (document.body.dataset.modalScrollLock === "true") return
+    this.element.toggleAttribute("data-scrolled", window.scrollY > 8)
+  }
+}

data/app/javascript/lostcoords/ui/controllers/lc_dock_controller.js

@@ -0,0 +1,21 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Hides the dock while the on-screen keyboard is open, so it doesn't cover the field being typed in.
+export default class extends Controller {
+  connect() {
+    this.viewportHandler = () => this.keyboard()
+    window.visualViewport?.addEventListener("resize", this.viewportHandler)
+  }
+
+  disconnect() {
+    window.visualViewport?.removeEventListener("resize", this.viewportHandler)
+  }
+
+  keyboard() {
+    const typing = document.activeElement?.matches(
+      "input, textarea, select, [contenteditable]:not([contenteditable=false])",
+    )
+    const inset = window.innerHeight - (window.visualViewport?.height ?? window.innerHeight)
+    this.element.toggleAttribute("data-keyboard", Boolean(typing) && inset > 150)
+  }
+}

data/app/javascript/lostcoords/ui/controllers/lc_toc_controller.js

@@ -0,0 +1,96 @@
+import { Controller } from "@hotwired/stimulus"
+
+// Marks the link to the section the reader has scrolled to with aria-current="location" and slides
+// the indicator to it. A section is current once its top passes its own scroll margin, which is
+// where a click on its link puts it.
+export default class extends Controller {
+  static targets = ["link", "indicator"]
+
+  connect() {
+    this.schedule = () => {
+      this.frame ||= requestAnimationFrame(() => {
+        this.frame = null
+        this.update()
+      })
+    }
+    addEventListener("scroll", this.schedule, { passive: true })
+    addEventListener("resize", this.schedule, { passive: true })
+    this.update({ animate: false })
+  }
+
+  disconnect() {
+    removeEventListener("scroll", this.schedule)
+    removeEventListener("resize", this.schedule)
+    cancelAnimationFrame(this.frame)
+    this.frame = null
+  }
+
+  // The last sections can't scroll up to the top, so at the end of the page the clicked one stays current.
+  select(event) {
+    this.chosen = event.currentTarget
+  }
+
+  update({ animate = true } = {}) {
+    const sections = this.linkTargets.flatMap((link) => {
+      const target = document.getElementById(decodeURIComponent(link.hash.slice(1)))
+      return target ? [{ link, target, top: target.getBoundingClientRect().top }] : []
+    })
+    let current = null
+    for (const section of sections) {
+      const margin = Number.parseFloat(getComputedStyle(section.target).scrollMarginTop) || 0
+      if (section.top <= margin + 4) current = section.link
+    }
+
+    const root = document.scrollingElement ?? document.documentElement
+    if (root.scrollTop > 0 && root.scrollTop + innerHeight >= root.scrollHeight - 2) {
+      const visible = sections.filter((section) => section.top < innerHeight)
+      const chosen = visible.find((section) => section.link === this.chosen)
+      current = (chosen ?? visible.at(-1))?.link ?? current
+    }
+    if (current === this.current && !animate) return this.place(current, { animate })
+    if (current === this.current) return
+
+    this.current = current
+    for (const link of this.linkTargets) {
+      if (link === current) link.setAttribute("aria-current", "location")
+      else link.removeAttribute("aria-current")
+    }
+    this.place(current, { animate })
+    this.reveal(current)
+  }
+
+  place(link, { animate }) {
+    if (!this.hasIndicatorTarget) return
+
+    const style = this.indicatorTarget.style
+    style.transition = animate ? "" : "none"
+    if (link) {
+      style.translate = `0 ${link.offsetTop}px`
+      style.height = `${link.offsetHeight}px`
+    }
+    style.opacity = link ? "1" : "0"
+    if (!animate) {
+      this.indicatorTarget.offsetWidth
+      style.transition = ""
+    }
+  }
+
+  // Keeps the current link inside a scrolling sidebar without scrolling the page.
+  reveal(link) {
+    if (!link) return
+
+    let box = this.element.parentElement
+    while (box && box !== document.body) {
+      const { overflowY } = getComputedStyle(box)
+      if ((overflowY === "auto" || overflowY === "scroll") && box.scrollHeight > box.clientHeight)
+        break
+      box = box.parentElement
+    }
+    if (!box || box === document.body) return
+
+    const linkBox = link.getBoundingClientRect()
+    const frame = box.getBoundingClientRect()
+    if (linkBox.top < frame.top) box.scrollTop -= frame.top - linkBox.top
+    else if (linkBox.bottom > frame.bottom) box.scrollTop += linkBox.bottom - frame.bottom
+  }
+}

data/app/javascript/lostcoords/ui/index.js

@@ -1,7 +1,9 @@
+import AppHeader from "lostcoords/ui/controllers/lc_app_header_controller"
 import CodeBlock from "lostcoords/ui/controllers/lc_code_block_controller"
 import Collapsible from "lostcoords/ui/controllers/lc_collapsible_controller"
 import Copy from "lostcoords/ui/controllers/lc_copy_controller"
 import Dialog from "lostcoords/ui/controllers/lc_dialog_controller"
+import Dock from "lostcoords/ui/controllers/lc_dock_controller"
 import EmojiPicker from "lostcoords/ui/controllers/lc_emoji_picker_controller"
 import Kbd from "lostcoords/ui/controllers/lc_kbd_controller"
 import Menu from "lostcoords/ui/controllers/lc_menu_controller"
@@ -15,14 +17,17 @@ import Shortcut from "lostcoords/ui/controllers/lc_shortcut_controller"
 import Tabs from "lostcoords/ui/controllers/lc_tabs_controller"
 import Toast from "lostcoords/ui/controllers/lc_toast_controller"
 import ToastRegion from "lostcoords/ui/controllers/lc_toast_region_controller"
+import Toc from "lostcoords/ui/controllers/lc_toc_controller"
 import Toggle from "lostcoords/ui/controllers/lc_toggle_controller"
 import Tooltip from "lostcoords/ui/controllers/lc_tooltip_controller"
 
 const controllers = {
+  "lc-app-header": AppHeader,
   "lc-collapsible": Collapsible,
   "lc-code-block": CodeBlock,
   "lc-copy": Copy,
   "lc-dialog": Dialog,
+  "lc-dock": Dock,
   "lc-emoji-picker": EmojiPicker,
   "lc-kbd": Kbd,
   "lc-menu": Menu,
@@ -34,6 +39,7 @@ const controllers = {
   "lc-sheet": Sheet,
   "lc-shortcut": Shortcut,
   "lc-tabs": Tabs,
+  "lc-toc": Toc,
   "lc-toast": Toast,
   "lc-toast-region": ToastRegion,
   "lc-toggle": Toggle,

data/config/locales/en.yml

@@ -20,6 +20,15 @@ en:
         label: "Actions"
       popover:
         trigger: "Open popover"
+      toc:
+        label: "On this page"
+      docs_shell:
+        menu: "Menu"
+        sidebar: "Documentation sidebar"
+      app_header:
+        navigation: "Main"
+      dock:
+        close: "Close %{label}"
       breadcrumb:
         label: "Breadcrumb"
       code_block:

data/config/locales/es.yml

@@ -20,6 +20,15 @@ es:
         label: "Acciones"
       popover:
         trigger: "Abrir panel"
+      toc:
+        label: "En esta página"
+      docs_shell:
+        menu: "Menú"
+        sidebar: "Barra lateral de la documentación"
+      app_header:
+        navigation: "Principal"
+      dock:
+        close: "Cerrar %{label}"
       breadcrumb:
         label: "Ruta de navegación"
       code_block:

data/config/locales/ja.yml

@@ -20,6 +20,15 @@ ja:
         label: "操作"
       popover:
         trigger: "パネルを開く"
+      toc:
+        label: "このページの内容"
+      docs_shell:
+        menu: "メニュー"
+        sidebar: "ドキュメントのサイドバー"
+      app_header:
+        navigation: "メイン"
+      dock:
+        close: "%{label}を閉じる"
       breadcrumb:
         label: "パンくずリスト"
       code_block:

data/lib/lostcoords/ui/helpers.rb

@@ -1,6 +1,6 @@
 module Lostcoords::Ui
   module Helpers
-    paths = Dir[Lostcoords::Ui.root.join("app/helpers/lostcoords/ui/*_helper.rb")].sort_by do |path|
+    paths = Dir[Lostcoords::Ui::Engine.root.join("app/helpers/lostcoords/ui/*_helper.rb")].sort_by do |path|
       [ %w[tailwind_helper.rb button_helper.rb].index(File.basename(path)) || 2, path ]
     end
     paths.each do |path|

data/lib/lostcoords/ui/icons.rb

@@ -8,7 +8,7 @@ module Lostcoords::Ui
 
     def self.fetch(name, variant)
       LOCK.synchronize do
-        @catalog ||= JSON.parse(File.read(Lostcoords::Ui.root.join("vendor/heroicons/icons.json")), freeze: true).fetch("icons")
+        @catalog ||= JSON.parse(File.read(Lostcoords::Ui::Engine.root.join("vendor/heroicons/icons.json")), freeze: true).fetch("icons")
         source = @catalog.fetch(variant.to_s).fetch(name.to_s)
         template = TEMPLATES[source] ||= begin
           document = Nokogiri::XML(source) { |config| config.strict.nonet }

data/lib/lostcoords/ui/parts.rb

@@ -195,6 +195,93 @@ module Lostcoords::Ui
       end
     end
 
+    class Toc < Base
+      LINK = "relative block py-tight ps-content pe-tight text-small text-muted-foreground no-underline transition-colors " \
+        "duration-(--lc-motion-quick) hover:text-foreground aria-[current=location]:font-medium aria-[current=location]:text-foreground"
+
+      # url: an in-page anchor such as "#usage". indent: true nests the entry under the one above it.
+      def link(label, url, indent: false, **attributes)
+        view.send(:lc_label!, label, :label)
+        raise ArgumentError, "toc link needs an anchor URL, such as \"#usage\"" unless url.to_s.match?(/#./)
+
+        view.tag.li(data: { slot: "toc-item" }) do
+          view.link_to(label, url, **merge({ class: view.lc_tw(LINK, ("ps-[calc(var(--spacing-content)*2)]" if indent)),
+            data: { slot: "toc-link", lc_toc_target: "link", action: "lc-toc#select" } }, attributes))
+        end
+      end
+    end
+
+    class AppHeader < Base
+      # The home link. label: names it for screen readers, since the block is usually a logo.
+      def brand(url = "/", label:, **attributes, &block)
+        view.send(:lc_label!, label, :label)
+        raise ArgumentError, "header brand needs a block" unless block
+
+        view.link_to(url, **merge({ class: "flex min-h-11 shrink-0 items-center gap-related pe-2 font-semibold tracking-tight text-inherit no-underline",
+          aria: { label: label }, data: { slot: "app-header-brand" } }, attributes), &block)
+      end
+
+      # A row of links with a sliding indicator; yields the lc_nav_list builder. Hide it on phones
+      # with class: "max-sm:hidden" when a dock or menu carries the same links.
+      def nav(label: view.send(:lc_t, "lostcoords.ui.app_header.navigation"), **attributes, &block)
+        view.lc_nav_list(label: label, layout: :row, indicator: true, **attributes, &block)
+      end
+
+      # Controls at the end of the bar, such as search, a theme switch or an account menu.
+      def actions(**attributes, &block)
+        part(:div, "app-header-actions", "ms-auto flex shrink-0 items-center gap-related", attributes, &block)
+      end
+    end
+
+    class Dock < Base
+      # The primary destinations, icon above label; yields the lc_nav_list builder.
+      def nav(label:, **attributes, &block)
+        view.lc_nav_list(label: label, layout: :dock, indicator: true,
+          **merge({ class: view.lc_glass_class(shape: :panel, thick: true, extra: "lc-dock__nav rounded-pill") }, attributes), &block)
+      end
+
+      # A round button at the end of the dock whose actions fan out above it. Yields a builder:
+      # `menu.action "New note", icon: "pencil-square"`.
+      def menu(label:, icon: "plus", id: nil, **attributes, &block)
+        view.send(:lc_label!, label, :label)
+        raise ArgumentError, "dock menu needs a block" unless block
+
+        id ||= "#{label.parameterize.presence || 'dock'}-menu"
+        actions = view.capture(DockMenu.new(view), &block)
+        view.tag.div(**merge({ class: "lc-dock__menu", data: { slot: "dock-menu", controller: "lc-menu", lc_menu_lift_value: false } }, attributes)) do
+          view.safe_join([
+            view.tag.button(view.lc_icon(icon, options: { class: "size-7", "aria-hidden": true }), type: "button",
+              class: view.lc_glass_class(shape: :disc, thick: true, extra: "lc-dock__trigger"), aria: { label: label, haspopup: "menu", expanded: false, controls: id },
+              data: { slot: "dock-menu-trigger", lc_menu_target: "trigger", action: "lc-menu#toggle" }),
+            view.tag.div(id: id, class: "lc-dock__actions", role: "menu", aria: { label: label }, data: { lc_menu_target: "popover" }) do
+              view.safe_join([
+                view.tag.button(type: "button", class: "lc-dock__scrim", tabindex: -1, aria: { label: view.send(:lc_t, "lostcoords.ui.dock.close", label: label) }, data: { action: "lc-menu#close" }),
+                actions
+              ])
+            end
+          ])
+        end
+      end
+    end
+
+    class DockMenu < Base
+      def initialize(view)
+        super
+        @count = 0
+      end
+
+      # An action that fans out above the dock button. Pass data: { action: "…" } for your controller;
+      # the menu closes after it runs.
+      def action(label, icon:, **attributes)
+        view.send(:lc_label!, label, :label)
+        @count += 1
+        defaults = { class: view.lc_glass_class(shape: :disc, thick: true, extra: "lc-dock__action"), data: { slot: "dock-action", action: "lc-menu#close" } }
+        view.tag.button(**merge(defaults, attributes), type: "button", role: "menuitem", style: "--lc-dock-action-index: #{@count}") do
+          view.safe_join([ view.tag.span(label, class: "lc-dock__action-label"), view.lc_icon(icon, options: { class: "size-6", "aria-hidden": true }) ])
+        end
+      end
+    end
+
     class Panel < Base
       include CustomTrigger
 

data/lib/lostcoords/ui/version.rb

@@ -1,5 +1,5 @@
 module Lostcoords
   module Ui
-    VERSION = "0.8.2"
+    VERSION = "0.9.0"
   end
 end

data/lib/lostcoords/ui.rb

@@ -1,2 +1,12 @@
-require "lostcoords/ui/action_view"
-require "lostcoords/ui/rails" if defined?(::Rails::Engine)
+require "rails/engine"
+require "action_view"
+require "active_support/core_ext/hash"
+require "active_support/core_ext/object/blank"
+require "tailwind_merge"
+require "lostcoords/ui/version"
+require "lostcoords/ui/engine"
+require "lostcoords/ui/icons"
+require "lostcoords/ui/parts"
+require "lostcoords/ui/form_builder"
+require "lostcoords/ui/helpers"
+require "lostcoords/ui/stylesheets"

data/lib/tasks/lostcoords_ui.rake

@@ -15,7 +15,6 @@ namespace :lostcoords do
 end
 
 # Runs with tailwindcss-rails' own engines step, before every tailwindcss:build and tailwindcss:watch.
-# Apps without tailwindcss-rails import the gem's stylesheets by path instead.
 if defined?(Tailwindcss::Engines)
   namespace :tailwindcss do
     task :engines do

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: lostcoords-ui
 version: !ruby/object:Gem::Version
-  version: 0.8.2
+  version: 0.9.0
 platform: ruby
 authors:
 - Lost Coordinates
@@ -24,7 +24,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '8.0'
 - !ruby/object:Gem::Dependency
-  name: activesupport
+  name: railties
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -99,6 +99,7 @@ files:
 - app/assets/tailwind/lostcoords/ui/components/menu.css
 - app/assets/tailwind/lostcoords/ui/components/prose.css
 - app/assets/tailwind/lostcoords/ui/components/search.css
+- app/assets/tailwind/lostcoords/ui/components/shell.css
 - app/assets/tailwind/lostcoords/ui/components/table.css
 - app/assets/tailwind/lostcoords/ui/components/toast.css
 - app/assets/tailwind/lostcoords/ui/components/tooltip.css
@@ -113,6 +114,7 @@ files:
 - app/assets/tailwind/lostcoords/ui/prose.css
 - app/assets/tailwind/lostcoords/ui/search.css
 - app/assets/tailwind/lostcoords/ui/sheet.css
+- app/assets/tailwind/lostcoords/ui/shell.css
 - app/assets/tailwind/lostcoords/ui/squircle.css
 - app/assets/tailwind/lostcoords/ui/table.css
 - app/assets/tailwind/lostcoords/ui/theme.css
@@ -145,6 +147,7 @@ files:
 - app/helpers/lostcoords/ui/render_attributes_helper.rb
 - app/helpers/lostcoords/ui/search_helper.rb
 - app/helpers/lostcoords/ui/sheet_helper.rb
+- app/helpers/lostcoords/ui/shell_helper.rb
 - app/helpers/lostcoords/ui/structures_helper.rb
 - app/helpers/lostcoords/ui/table_helper.rb
 - app/helpers/lostcoords/ui/tailwind_helper.rb
@@ -152,10 +155,12 @@ files:
 - app/helpers/lostcoords/ui/tooltip_helper.rb
 - app/helpers/lostcoords/ui/translation_helper.rb
 - app/helpers/lostcoords/ui/typography_helper.rb
+- app/javascript/lostcoords/ui/controllers/lc_app_header_controller.js
 - app/javascript/lostcoords/ui/controllers/lc_code_block_controller.js
 - app/javascript/lostcoords/ui/controllers/lc_collapsible_controller.js
 - app/javascript/lostcoords/ui/controllers/lc_copy_controller.js
 - app/javascript/lostcoords/ui/controllers/lc_dialog_controller.js
+- app/javascript/lostcoords/ui/controllers/lc_dock_controller.js
 - app/javascript/lostcoords/ui/controllers/lc_emoji_picker_controller.js
 - app/javascript/lostcoords/ui/controllers/lc_kbd_controller.js
 - app/javascript/lostcoords/ui/controllers/lc_menu_controller.js
@@ -169,6 +174,7 @@ files:
 - app/javascript/lostcoords/ui/controllers/lc_tabs_controller.js
 - app/javascript/lostcoords/ui/controllers/lc_toast_controller.js
 - app/javascript/lostcoords/ui/controllers/lc_toast_region_controller.js
+- app/javascript/lostcoords/ui/controllers/lc_toc_controller.js
 - app/javascript/lostcoords/ui/controllers/lc_toggle_controller.js
 - app/javascript/lostcoords/ui/controllers/lc_tooltip_controller.js
 - app/javascript/lostcoords/ui/helpers/catalog_picker.js
@@ -200,7 +206,6 @@ files:
 - config/locales/es.yml
 - config/locales/ja.yml
 - lib/lostcoords/ui.rb
-- lib/lostcoords/ui/action_view.rb
 - lib/lostcoords/ui/builders.rb
 - lib/lostcoords/ui/components.rb
 - lib/lostcoords/ui/engine.rb
@@ -208,8 +213,6 @@ files:
 - lib/lostcoords/ui/helpers.rb
 - lib/lostcoords/ui/icons.rb
 - lib/lostcoords/ui/parts.rb
-- lib/lostcoords/ui/rails.rb
-- lib/lostcoords/ui/resources.rb
 - lib/lostcoords/ui/stylesheets.rb
 - lib/lostcoords/ui/tokens.rb
 - lib/lostcoords/ui/version.rb
@@ -241,5 +244,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.6
 specification_version: 4
-summary: ActionView UI components with Tailwind CSS and Stimulus.
+summary: Rails UI components with Tailwind CSS and Stimulus.
 test_files: []

data/lib/lostcoords/ui/action_view.rb

@@ -1,13 +0,0 @@
-require "bigdecimal"
-require "action_view"
-require "active_support/core_ext/hash"
-require "active_support/core_ext/object/blank"
-require "tailwind_merge"
-require_relative "resources"
-require_relative "icons"
-require_relative "parts"
-require_relative "form_builder"
-require_relative "helpers"
-require_relative "stylesheets"
-
-Lostcoords::Ui.load_translations!

data/lib/lostcoords/ui/rails.rb

@@ -1,3 +0,0 @@
-require "rails/engine"
-require "lostcoords/ui/action_view"
-require "lostcoords/ui/engine"

data/lib/lostcoords/ui/resources.rb

@@ -1,17 +0,0 @@
-require "pathname"
-require_relative "version"
-
-module Lostcoords::Ui
-  def self.root
-    @root ||= Pathname.new(File.expand_path("../../..", __dir__)).freeze
-  end
-
-  def self.view_paths
-    [ root.join("app/views").to_s ]
-  end
-
-  def self.load_translations!
-    paths = (Dir[root.join("config/locales/*.yml")] + I18n.load_path).uniq
-    I18n.load_path = paths unless I18n.load_path == paths
-  end
-end