lostcoords-ui 0.4.1 → 0.5.0

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

@@ -1,27 +1,20 @@
 module Lostcoords::Ui
   module DialogHelper
-    DIALOG_SURFACE =
-      "border border-(--glass-edge) rounded-3xl bg-paper text-ink shadow-[var(--glass-rim),var(--shadow-lg)]"
-
     # Below sm these open as iOS sheets (sheet.css), which paint their own surface.
     SHEET_DIALOG_SURFACE =
-      "sm:border sm:border-(--glass-edge) sm:rounded-3xl sm:bg-paper text-ink sm:shadow-[var(--glass-rim),var(--shadow-lg)]"
+      "sm:border sm:border-(--lc-glass-edge) sm:rounded-3xl sm:bg-popover text-popover-foreground sm:shadow-[var(--lc-glass-rim),var(--lc-shadow-lg)]"
 
-    ANCHORED = "data-anchored:[inset:var(--dialog-top)_var(--dialog-right)_auto_auto] data-anchored:m-0"
+    ANCHORED = "data-anchored:[inset:var(--lc-dialog-top)_var(--lc-dialog-right)_auto_auto] data-anchored:m-0"
 
     DIALOGS = {
-      modal: "app-dialog #{SHEET_DIALOG_SURFACE} sm:w-[min(92vw,31rem)]",
+      modal: "lc-dialog #{SHEET_DIALOG_SURFACE} sm:w-[min(92vw,31rem)]",
       context:
-        "app-dialog context-dialog #{SHEET_DIALOG_SURFACE} sm:w-[min(22rem,calc(100vw-2rem))] " \
-        "sm:max-h-[calc(100dvh-2rem)] sm:origin-(--dialog-origin,center) [--dialog-from:scale(0.96)] #{ANCHORED}"
+        "lc-dialog lc-dialog-context #{SHEET_DIALOG_SURFACE} sm:w-[min(22rem,calc(100vw-2rem))] " \
+        "sm:max-h-[calc(100dvh-2rem)] sm:origin-(--lc-dialog-origin,center) [--lc-dialog-from:scale(0.96)] #{ANCHORED}"
     }.freeze
 
     def lc_dialog_class(kind = :modal, extra: nil)
-      lc_tw("squircle", lc_dialog_kinds.fetch(kind), extra)
-    end
-
-    def lc_dialog_surface_class(extra: nil)
-      lc_tw(DIALOG_SURFACE, extra)
+      lc_tw("lc-squircle", lc_dialog_kinds.fetch(kind), extra)
     end
 
     private

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

@@ -5,18 +5,37 @@ module Lostcoords::Ui
 
     SPINNER_SIZES = {
       sm: "size-4 border-2",
-      base: "size-6 border-2",
+      md: "size-6 border-2",
       lg: "size-8 border-[3px]"
     }.freeze
 
-    SKELETON_BASE = "block rounded-xl bg-paper-2 animate-pulse"
+    SKELETON_BASE = "block rounded-xl bg-muted animate-pulse"
 
     EMPTY_STATE_BASE =
-      "flex flex-col items-center text-center " \
-      "py-6 px-4 sm:py-12 sm:px-6"
+      "flex flex-col items-center gap-content text-center " \
+      "py-section px-content"
 
-    def lc_spinner_class(size: :base, extra: nil)
-      lc_tw(SPINNER_BASE, SPINNER_SIZES.fetch(size.to_sym, SPINNER_SIZES[:base]), extra)
+    ALERT_BASE = "flex items-start gap-related py-heading px-content rounded-2xl lc-squircle bg-muted text-foreground text-label"
+    ALERT_ICONS = {
+      neutral: [ "information-circle", "text-muted-foreground" ],
+      primary: [ "information-circle", "text-primary" ],
+      success: [ "check-circle", "text-success" ],
+      warning: [ "exclamation-triangle", "text-warning" ],
+      destructive: [ "exclamation-circle", "text-destructive" ]
+    }.freeze
+
+    def lc_alert_class(extra: nil)
+      lc_tw(ALERT_BASE, extra)
+    end
+
+    def lc_alert_icon(tone: :destructive)
+      tone = lc_option!(:tone, tone, ALERT_ICONS.keys)
+      name, color = ALERT_ICONS.fetch(tone)
+      lc_icon name, variant: :mini, options: { class: lc_tw("size-5 shrink-0", color), "aria-hidden": "true" }
+    end
+
+    def lc_spinner_class(size: :md, extra: nil)
+      lc_tw(SPINNER_BASE, SPINNER_SIZES.fetch(lc_option!(:size, size, SPINNER_SIZES.keys)), extra)
     end
 
     def lc_skeleton_class(extra: nil)

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

@@ -1,72 +1,62 @@
 module Lostcoords::Ui
   module FormHelper
-    SEGMENTED_BASE =
-      "inline-flex items-center gap-1 rounded-2xl bg-paper-2 p-1"
-
-    SEGMENTED_TAB_BASE =
-      "inline-flex items-center justify-center gap-1.5 whitespace-nowrap " \
-      "min-h-11 rounded-xl border-0 bg-transparent " \
-      "px-4 py-2 font-body text-sm font-medium cursor-pointer no-underline " \
-      "text-ink-2 hover:text-ink " \
-      "aria-selected:bg-paper aria-selected:text-ink " \
-      "aria-pressed:bg-paper aria-pressed:text-ink " \
-      "aria-[current]:not-aria-[current=false]:bg-paper aria-[current]:not-aria-[current=false]:text-ink " \
-      "transition-[background-color,color,box-shadow,transform] duration-[150ms] ease-out " \
-      "active:scale-[0.96] disabled:opacity-40 disabled:pointer-events-none " \
+    TOGGLE_GROUP_BASE =
+      "inline-flex items-center gap-1 rounded-2xl bg-muted p-1 lc-squircle"
+
+    TOGGLE_GROUP_ITEM_BASE =
+      "lc-press inline-flex items-center justify-center gap-1.5 whitespace-nowrap " \
+      "h-control-sm rounded-xl border-0 bg-transparent " \
+      "px-3 font-sans text-label cursor-pointer no-underline " \
+      "text-muted-foreground hover:text-foreground " \
+      "aria-selected:bg-background aria-selected:text-foreground " \
+      "aria-pressed:bg-background aria-pressed:text-foreground " \
+      "aria-[current]:not-aria-[current=false]:bg-background aria-[current]:not-aria-[current=false]:text-foreground " \
+      "transition-[background-color,color,box-shadow,transform] duration-(--lc-motion-quick) ease-(--lc-ease-out) " \
+      "disabled:opacity-40 disabled:pointer-events-none " \
       "[&_svg]:size-[1.1em] [&_svg]:shrink-0"
 
-    SEGMENTED_TAB_ACTIVE = "bg-paper text-ink hover:text-ink"
+    TOGGLE_GROUP_ITEM_ACTIVE = "bg-background text-foreground hover:text-foreground"
 
     INPUT_BASE =
       "w-full max-w-full min-w-0 " \
       "px-3 " \
-      "font-body text-base bg-(--field-bg,var(--paper-2)) text-ink placeholder:text-ink-3 " \
-      "border border-transparent rounded-2xl outline-none " \
-      "transition-[border-color,box-shadow] duration-150 ease-out " \
-      "focus:shadow-(--focus-halo) " \
-      "aria-invalid:border-berry aria-invalid:shadow-[0_0_0_3px_color-mix(in_oklab,var(--berry)_16%,transparent)]"
+      "font-sans text-base bg-(--lc-field-bg,var(--input)) text-foreground placeholder:text-muted-foreground " \
+      "border border-transparent rounded-xl lc-squircle outline-none " \
+      "transition-[border-color,box-shadow] duration-(--lc-motion-quick) ease-(--lc-ease-out) " \
+      "focus:shadow-[0_0_0_calc(var(--spacing)*0.5)_var(--ring,color-mix(in_oklab,var(--primary)_50%,transparent))] " \
+      "aria-invalid:border-destructive aria-invalid:shadow-[0_0_0_3px_color-mix(in_oklab,var(--destructive)_16%,transparent)]"
 
-    FIELD_BASE = "ui-field grid min-w-0 gap-2 has-aria-invalid:[&>label]:text-berry"
+    FIELD_BASE = "lc-field grid min-w-0 gap-related has-aria-invalid:[&>label]:text-destructive"
 
     FIELD_LABEL_BASE =
-      "block font-body text-sm font-semibold text-ink-3 " \
-      "transition-colors duration-[120ms] ease-out"
-
-    FORM_ACTIONS_BASE = "flex flex-wrap items-center justify-end gap-2"
-
-    # The toast's surface (shared/_toast), set in the flow: the tone lives in the icon, not the fill.
-    FORM_ALERT_BASE =
-      "flex items-start gap-2 mb-4 py-3 px-4 rounded-2xl bg-(--glass-hud-solid) text-(--glass-hud-ink) text-sm font-semibold " \
-      "motion-safe:animate-alert-in"
+      "block font-sans text-label font-semibold text-muted-foreground " \
+      "transition-colors duration-(--lc-motion-quick) ease-(--lc-ease-out)"
 
-    FORM_ALERT_ICONS = {
-      error: [ "exclamation-circle", "text-berry" ],
-      notice: [ "check-circle", "text-leaf" ]
-    }.freeze
-
-    def lc_segmented_class(extra: nil)
-      lc_tw(SEGMENTED_BASE, extra)
+    # form_with with Lostcoords::Ui::FormBuilder, so form.text_field, form.field and form.submit
+    # render library controls.
+    def lc_form_with(**options, &block)
+      form_with(**options, builder: Lostcoords::Ui::FormBuilder, &block)
     end
 
-    def lc_segmented_tab_class(active: false, extra: nil)
-      lc_tw(SEGMENTED_TAB_BASE, (SEGMENTED_TAB_ACTIVE if active), extra)
+    def lc_toggle_group_class(extra: nil)
+      lc_tw(TOGGLE_GROUP_BASE, extra)
     end
 
-    def lc_input_class(size: :base, extra: nil)
-      lc_tw(INPUT_BASE, TailwindHelper::CONTROL_SIZES.fetch(size.to_sym, TailwindHelper::CONTROL_SIZES[:base]), extra)
+    def lc_toggle_group_item_class(active: false, extra: nil)
+      lc_tw(TOGGLE_GROUP_ITEM_BASE, (TOGGLE_GROUP_ITEM_ACTIVE if active), extra)
     end
 
-    def lc_dropdown_trigger_class(size: :base, extra: nil)
-      lc_button_class(variant: :secondary, size: size, block: true,
-        extra: lc_tw("justify-start text-start ps-5 pe-4 gap-3 [&_.caret]:ms-auto [&_.caret]:shrink-0", extra))
+    def lc_input_class(size: :md, extra: nil)
+      lc_tw(INPUT_BASE, TailwindHelper::CONTROL_SIZES.fetch(lc_option!(:size, size, TailwindHelper::CONTROL_SIZES.keys)), extra)
     end
 
-    def lc_select_class(size: :base, extra: nil)
-      lc_tw(lc_input_class(size: size), "select-control rounded-full ps-5 pe-11 cursor-pointer hover:bg-paper-3", extra)
+
+    def lc_select_class(size: :md, extra: nil)
+      lc_tw(lc_input_class(size: size), "lc-select rounded-pill ps-4 pe-10 cursor-pointer hover:bg-(--lc-input-hover)", extra)
     end
 
     def lc_textarea_class(extra: nil)
-      lc_tw(INPUT_BASE, "min-h-28 py-2.5 resize-y", extra)
+      lc_tw(INPUT_BASE, "min-h-28 py-2 resize-y", extra)
     end
 
     def lc_field_class(extra: nil)
@@ -76,18 +66,5 @@ module Lostcoords::Ui
     def lc_field_label_class(extra: nil)
       lc_tw(FIELD_LABEL_BASE, extra)
     end
-
-    def lc_form_actions_class(extra: nil)
-      lc_tw(FORM_ACTIONS_BASE, extra)
-    end
-
-    def lc_form_alert_class(extra: nil)
-      lc_tw(FORM_ALERT_BASE, extra)
-    end
-
-    def lc_form_alert_icon(tone: :error)
-      name, color = FORM_ALERT_ICONS.fetch(tone.to_sym, FORM_ALERT_ICONS[:error])
-      lc_icon name, variant: :mini, options: { class: lc_tw("size-5 shrink-0", color), "aria-hidden": "true" }
-    end
   end
 end

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

@@ -1,25 +1,25 @@
 module Lostcoords::Ui
   module GlassHelper
     # Menus lift further, and on phones go solid: they cover rows that look like their own
-    # options, and some open where nothing blurs (the dock). Dark lifts to paper-3 to clear cards.
-    GLASS_MENU = "[--glass-shadow:var(--glass-rim),var(--shadow-lg)] max-md:[--glass-fill:var(--paper)] dark:max-md:[--glass-fill:var(--paper-3)]"
+    # options, and some open where nothing blurs (the dock). Dark lifts to surface-hover to clear cards.
+    GLASS_MENU = "[--lc-glass-shadow:var(--lc-glass-rim),var(--lc-shadow-lg)] max-md:[--lc-glass-fill:var(--background)] dark:max-md:[--lc-glass-fill:var(--accent)]"
 
     GLASS_SHAPES = {
-      bar: "rounded-full border-(--glass-bar-edge)",
+      bar: "rounded-full border-(--lc-glass-bar-edge)",
       panel: "rounded-3xl",
       disc: "rounded-full",
       menu: "rounded-3xl #{GLASS_MENU}",
       # A picker is a menu on desktop and a bottom sheet on phones, so its own CSS owns the corners.
       picker: GLASS_MENU,
-      hud: "rounded-[1.375rem] border-transparent text-(--glass-hud-ink) [--glass-fill:var(--glass-hud-fill)] [--glass-shadow:var(--glass-hud-shadow)] [--glass-solid:var(--glass-hud-solid)]"
+      hud: "rounded-[1.375rem] border-transparent text-(--lc-glass-hud-ink) [--lc-glass-fill:var(--lc-glass-hud-fill)] [--lc-glass-shadow:var(--lc-glass-hud-shadow)] [--lc-glass-solid:var(--lc-glass-hud-solid)]"
     }.freeze
 
     GLASS_THICK =
-      "max-md:[--glass-fill:color-mix(in_oklab,var(--paper)_90%,transparent)] " \
-      "dark:max-md:[--glass-fill:color-mix(in_oklab,var(--paper-2)_92%,transparent)]"
+      "max-md:[--lc-glass-fill:color-mix(in_oklab,var(--background)_90%,transparent)] " \
+      "dark:max-md:[--lc-glass-fill:color-mix(in_oklab,var(--muted)_92%,transparent)]"
 
     def lc_glass_class(shape: :bar, thick: false, extra: nil)
-      lc_tw("glass", GLASS_SHAPES.fetch(shape.to_sym, GLASS_SHAPES[:bar]), (GLASS_THICK if thick), extra)
+      lc_tw("lc-glass", GLASS_SHAPES.fetch(shape.to_sym, GLASS_SHAPES[:bar]), (GLASS_THICK if thick), extra)
     end
   end
 end

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

@@ -1,18 +1,19 @@
 module Lostcoords::Ui
   module LayoutHelper
+    # Space between things belongs to these helpers; components never set outer margin.
     LAYOUT_GAPS = {
-      tight: "gap-[var(--ui-space-tight,0.25rem)]",
-      related: "gap-[var(--ui-space-related,0.5rem)]",
-      heading: "gap-[var(--ui-space-heading,0.75rem)]",
-      content: "gap-[var(--ui-space-content,1rem)]",
-      inset: "gap-[var(--ui-space-inset,1.25rem)]",
-      section: "gap-[var(--ui-space-section,2rem)]"
+      tight: "gap-tight",
+      related: "gap-related",
+      heading: "gap-heading",
+      content: "gap-content",
+      inset: "gap-inset",
+      section: "gap-section"
     }.freeze
 
     CONTAINER_SIZES = {
-      page: "ui-container-page max-w-[var(--ui-page-max,75rem)]",
-      reading: "max-w-[var(--ui-reading-measure,65ch)]",
-      form: "max-w-[var(--ui-form-max,32rem)]"
+      page: "lc-container-page max-w-page",
+      reading: "max-w-reading",
+      form: "max-w-form"
     }.freeze
 
     def lc_stack_class(gap: :content, extra: nil)
@@ -30,8 +31,9 @@ module Lostcoords::Ui
       lc_tw("mx-auto min-w-0 w-full", CONTAINER_SIZES.fetch(size), extra)
     end
 
+    # The header keeps a control's height, so a section with actions and one without line up.
     def lc_section_header_class(extra: nil)
-      lc_inline_class(extra: lc_tw("min-h-[var(--ui-section-header-height,2.75rem)] justify-between", extra))
+      lc_inline_class(extra: lc_tw("min-h-control-md justify-between", extra))
     end
 
     def lc_stack(gap: :content, **attributes, &block)
@@ -50,7 +52,7 @@ module Lostcoords::Ui
       raise ArgumentError, "title must not be blank" if title.blank?
 
       tag.section(**lc_attributes({ class: lc_stack_class(gap: :heading) }, attributes)) do
-        heading = lc_heading(title, level: level, size: :section)
+        heading = lc_heading(title, level: level, size: :heading)
         action_content = actions.respond_to?(:call) ? capture(&actions) : actions
         header = tag.header(class: lc_section_header_class) { safe_join([ heading, action_content ].compact) }
         safe_join([ header, lc_stack(&block) ])

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

@@ -2,10 +2,10 @@ module Lostcoords::Ui
   module MenuHelper
     # FloatingPanel sets [data-open]; the caller picks the display.
     POPOVER_BASE =
-      "row-menu__popover squircle popover-shell hidden absolute top-[calc(100%+--spacing(1))] end-0 overscroll-contain [&_form]:m-0"
+      "lc-menu__popover lc-squircle lc-popover-shell hidden absolute top-[calc(100%+--spacing(1))] end-0 overscroll-contain [&_form]:m-0"
 
     MENU_POPOVER_BASE =
-      "data-open:flex flex-col gap-0.5 z-nav-popover p-2 " \
+      "data-open:flex flex-col gap-px z-(--lc-z-popover) p-related " \
       "min-w-56 max-w-[calc(100vw-clamp(1rem,3vw,1.5rem)*2)] max-h-[min(24rem,70vh)] overflow-y-auto"
 
     MENU_POPOVER_ALIGN = {
@@ -15,15 +15,15 @@ module Lostcoords::Ui
     }.freeze
 
     MENU_OPTION_BASE =
-      "row-menu__item press [--press-scale:0.98] group/option grid grid-cols-[auto_minmax(0,1fr)_auto] items-center gap-x-3 w-full " \
-      "min-h-11 px-3 py-2 rounded-xl border-none bg-transparent text-start font-body text-[0.9375rem] font-medium text-ink " \
-      "no-underline cursor-pointer transition-[background-color] duration-120 [--avatar-size:--spacing(7)] " \
-      "hover:bg-paper-2 focus-visible:bg-paper-2 focus-visible:outline-none " \
-      "disabled:text-ink-3 disabled:cursor-not-allowed disabled:hover:bg-transparent"
+      "lc-menu__item lc-press [--lc-press-scale:0.98] group/option grid grid-cols-[auto_minmax(0,1fr)_auto] items-center gap-x-3 w-full " \
+      "min-h-control-md px-3 py-1.5 rounded-2xl lc-squircle border-none bg-transparent text-start font-sans text-label text-foreground " \
+      "no-underline cursor-pointer transition-[background-color] duration-120 [--lc-avatar-size:--spacing(7)] " \
+      "hover:bg-accent focus-visible:bg-accent focus-visible:outline-none " \
+      "disabled:text-muted-foreground disabled:cursor-not-allowed disabled:hover:bg-transparent"
 
     MENU_OPTION_TONES = {
       default: "",
-      danger: "text-danger hover:bg-danger-soft focus-visible:bg-danger-soft"
+      destructive: "text-destructive hover:bg-destructive-soft focus-visible:bg-destructive-soft"
     }.freeze
 
     def lc_popover_class(align: :end, extra: nil)

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

@@ -0,0 +1,131 @@
+module Lostcoords::Ui
+  module NavigationHelper
+    BREADCRUMB_LINK = "rounded-sm text-muted-foreground no-underline underline-offset-4 hover:text-foreground hover:underline"
+
+    LINK_TONES = {
+      inherit: "text-inherit decoration-current/40 hover:decoration-current",
+      muted: "text-muted-foreground decoration-current/40 hover:text-foreground hover:decoration-current",
+      primary: "text-primary decoration-current/40 hover:decoration-current"
+    }.freeze
+
+    NAV_LINK = "flex min-w-0 items-center rounded-xl lc-squircle no-underline transition-colors duration-(--lc-motion-quick) " \
+      "text-muted-foreground hover:text-foreground aria-[current=page]:text-foreground"
+
+    # An inline text link. Prose inside lc_prose styles its links already.
+    def lc_link_class(tone: :inherit, extra: nil)
+      tone = lc_option!(:tone, tone, LINK_TONES.keys)
+      lc_tw("rounded-sm underline underline-offset-4 decoration-1 transition-colors duration-(--lc-motion-quick)", LINK_TONES.fetch(tone), extra)
+    end
+
+    def lc_link(content = nil, url = nil, tone: :inherit, **attributes, &block)
+      if block
+        url = content
+        content = capture(&block)
+      end
+      raise ArgumentError, "lc_link needs a URL" if url.blank?
+
+      link_to(content, url, **lc_attributes({ class: lc_link_class(tone: tone), data: { slot: "link" } }, attributes))
+    end
+
+    # compact: true is the quieter style for an "On this page" list.
+    def lc_nav_link_class(compact: false, extra: nil)
+      size = compact ? "py-tight text-small aria-[current=page]:font-medium" : "min-h-control-md px-3 py-1.5 text-label hover:bg-accent aria-[current=page]:bg-accent aria-[current=page]:font-semibold"
+      lc_tw(NAV_LINK, size, extra)
+    end
+
+    # Yields a builder with link and group parts; links mark the current page with aria-current.
+    def lc_nav_list(label:, compact: false, **attributes, &block)
+      lc_label!(label, :label)
+      tag.nav(**lc_attributes({ aria: { label: label }, data: { slot: "nav-list", compact: (true if compact) } }, attributes)) do
+        tag.ul(capture(Parts::NavList.new(self, compact), &block), class: "m-0 flex list-none flex-col gap-px 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)
+      pages = { previous: previous, next: binding.local_variable_get(:next) }
+      raise ArgumentError, "lc_pager needs a previous or next page" if pages.values.none?
+
+      tag.nav(**lc_attributes({ aria: { label: label }, class: lc_tw("flex items-stretch gap-related", ("justify-between" unless compact)), data: { slot: "pager" } }, attributes)) do
+        safe_join(pages.map do |direction, page|
+          next tag.span(class: "flex-1", aria: { hidden: true }) if page.nil? && !compact
+          next if page.nil?
+
+          title, url = page
+          word = lc_t("lostcoords.ui.pager.#{direction}")
+          icon = direction == :previous ? "arrow-left" : "arrow-right"
+          glyph = lc_icon(icon, variant: :mini, options: { class: "size-4 shrink-0 rtl:rotate-180", "aria-hidden": true })
+          if compact
+            link_to(glyph, url, class: lc_icon_button_class(size: :sm), aria: { label: "#{word}: #{title}" }, rel: (direction == :previous ? "prev" : "next"), data: { slot: "pager-#{direction}" })
+          else
+            link_to(url, rel: (direction == :previous ? "prev" : "next"), data: { slot: "pager-#{direction}" },
+              class: lc_tw("flex min-w-0 flex-1 basis-0 flex-col gap-tight rounded-2xl lc-squircle bg-card p-content no-underline text-inherit transition-colors hover:bg-accent sm:max-w-80", ("ms-auto items-end text-end" if direction == :next))) do
+              safe_join([
+                tag.span(safe_join(direction == :previous ? [ glyph, word ] : [ word, glyph ]), class: "inline-flex items-center gap-tight text-caption text-muted-foreground"),
+                tag.span(title, class: "max-w-full truncate text-label")
+              ], " ")
+            end
+          end
+        end.compact)
+      end
+    end
+
+    # The first focusable element on a page; it stays hidden until it receives keyboard focus.
+    def lc_skip_link(target = "#main", label: lc_t("lostcoords.ui.skip_link.label"), **attributes)
+      defaults = { class: "sr-only focus:not-sr-only focus:fixed focus:top-content focus:start-content focus:z-(--lc-z-toast) " \
+        "focus:rounded-xl focus:bg-popover focus:px-content focus:py-related focus:text-label focus:text-popover-foreground focus:shadow-(--lc-shadow-lg)",
+        data: { slot: "skip-link" } }
+      link_to(label, target, **lc_attributes(defaults, attributes))
+    end
+
+    # items: [[label, url], …, label]. The last item is the current page.
+    def lc_breadcrumb(items, label: lc_t("lostcoords.ui.breadcrumb.label"), **attributes)
+      items = Array(items).map { |item| Array(item) }
+      raise ArgumentError, "lc_breadcrumb needs at least one item" if items.empty?
+
+      tag.nav(**lc_attributes({ aria: { label: label }, data: { slot: "breadcrumb" } }, attributes)) do
+        tag.ol(class: "m-0 flex min-w-0 list-none flex-wrap items-center gap-tight p-0 text-small") do
+          safe_join(items.each_with_index.map do |(text, url), index|
+            current = index == items.size - 1
+            tag.li(class: "inline-flex min-w-0 items-center gap-tight", data: { slot: "breadcrumb-item" }) do
+              safe_join([
+                (current || url.nil? ? tag.span(text, class: "truncate font-medium text-foreground", aria: { current: ("page" if current) }) : link_to(text, url, class: BREADCRUMB_LINK)),
+                (lc_icon("chevron-right", variant: :mini, options: { class: "size-4 shrink-0 text-muted-foreground rtl:rotate-180", "aria-hidden": true }) unless current)
+              ].compact)
+            end
+          end)
+        end
+      end
+    end
+
+    # Yields a builder; each `tabs.panel "Label" do … end` adds a tab and its panel.
+    def lc_tabs(id:, label:, selected: nil, **attributes, &block)
+      lc_label!(id, :id)
+      lc_label!(label, :label)
+      tabs = Parts::Tabs.new(self)
+      capture(tabs, &block) if block
+      raise ArgumentError, "lc_tabs needs at least one panel" if tabs.panels.empty?
+
+      selected = (selected || tabs.panels.first.value).to_s
+      raise ArgumentError, "selected tab #{selected.inspect} has no panel" unless tabs.panels.any? { |panel| panel.value == selected }
+
+      key = ->(panel) { "#{id}-#{panel.value.gsub(/[^\w-]+/, '-')}" }
+      list = tag.div(role: "tablist", aria: { label: label }, class: lc_toggle_group_class(extra: "max-w-full overflow-x-auto lc-scroll-fade-x"), data: { slot: "tabs-list" }) do
+        safe_join(tabs.panels.map do |panel|
+          active = panel.value == selected
+          tag.button(panel.label, type: "button", role: "tab", id: "#{key.(panel)}-tab", tabindex: (active ? 0 : -1),
+            aria: { selected: active, controls: "#{key.(panel)}-panel" }, class: lc_toggle_group_item_class,
+            data: { slot: "tabs-trigger", value: panel.value, lc_tabs_target: "tab", action: "click->lc-tabs#select keydown->lc-tabs#navigate" })
+        end)
+      end
+      panels = tabs.panels.map do |panel|
+        tag.div(panel.content, **lc_attributes({ role: "tabpanel", id: "#{key.(panel)}-panel", tabindex: 0, hidden: (panel.value != selected),
+          aria: { labelledby: "#{key.(panel)}-tab" }, class: "min-w-0 rounded-lg outline-offset-4", data: { slot: "tabs-panel", lc_tabs_target: "panel" } }, panel.attributes))
+      end
+      tag.div(**lc_attributes({ id: id, class: "flex min-w-0 flex-col gap-content", data: { slot: "tabs", controller: "lc-tabs" } }, attributes)) do
+        safe_join([ list, *panels ])
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+module Lostcoords::Ui
+  module OverlayHelper
+    TOOLTIP_SIDES = %i[top bottom].freeze
+
+    # Yields attributes for the trigger; splat them with `**tip` so the trigger is described by the tooltip.
+    # The tooltip shows on hover and keyboard focus, and Escape hides it. It is a hint: keep essential information visible.
+    def lc_tooltip(text, id:, side: :top, **attributes, &block)
+      lc_label!(text, :text)
+      lc_label!(id, :id)
+      side = lc_option!(:side, side, TOOLTIP_SIDES)
+      trigger = capture({ aria: { describedby: id } }, &block) if block
+      tag.span(**lc_attributes({ class: "lc-tooltip relative inline-flex", data: { slot: "tooltip", side: side, controller: "lc-tooltip", action: "keydown@window->lc-tooltip#dismiss mouseleave->lc-tooltip#reset focusout->lc-tooltip#reset" } }, attributes)) do
+        safe_join([ trigger, tag.span(text, id: id, role: "tooltip", class: "lc-tooltip__content", data: { slot: "tooltip-content" }) ].compact)
+      end
+    end
+  end
+end