@lovett/ui 0.0.9 → 0.0.10

package/src/modal.tsx

@@ -2,6 +2,8 @@ import {
   Children,
   isValidElement,
   useEffect,
+  useId,
+  useRef,
   type HTMLAttributes,
   type ReactElement,
   type ReactNode,
@@ -36,24 +38,167 @@ import { cn } from './lib/utils'
  *            <Button>Confirm</Button>
  *          </Modal.Footer>
  *        </Modal>
+ *
+ * Accessibility. The panel is a `role="dialog" aria-modal="true"` region
+ * named by its own `<h2>` (`aria-labelledby`), or by the `ariaLabel` prop
+ * when a caller renders a titleless modal. Opening moves focus to the
+ * panel — so a screen reader announces the dialog's name — and closing
+ * RESTORES focus to whatever was focused before it opened. Tab and
+ * Shift+Tab wrap inside the panel; Escape closes.
+ *
+ * Callers that want a specific control focused on open mark it
+ * `data-autofocus`; anything else and the panel itself takes focus.
+ *
+ * WHY A FOCUS TRAP AND NOT `inert` ON THE APP ROOT. Modal renders INLINE
+ * in the React tree — it is a descendant of `#root`, not a portal — so
+ * `inert` on the app root would make the modal itself inert. Portaling it
+ * to `document.body` to unlock that would move all 59 consuming files off
+ * the `.cs-frame`-scoped token layer and out of their current stacking /
+ * inheritance context, which is a much larger change than an a11y fix
+ * should make. Inerting `document.body`'s other children is also wrong:
+ * `DropdownMenu`, `TagChipInput` and `FolderTreePicker` portal their
+ * content THERE, so a select inside a modal would go dead. Focus trap it
+ * is — the keyboard hole is closed; pointer and AT virtual-cursor access
+ * to the background remains, which is the documented residual.
+ */
+
+/**
+ * Open panels, outermost first. Only the topmost one answers Escape and
+ * owns the tab ring, so nested modals do not both close on one Escape
+ * and do not fight over focus.
+ */
+const openPanels: HTMLElement[] = []
+
+/**
+ * Tabbable candidates. Deliberately attribute-only — no geometry check.
+ * `offsetWidth` / `getClientRects()` are always zero in jsdom, so a
+ * visibility filter would empty this list under test and silently
+ * disable the trap in exactly the environment that verifies it.
  */
+const FOCUSABLE_SELECTOR = [
+  'a[href]',
+  'area[href]',
+  'button:not([disabled])',
+  'input:not([disabled]):not([type="hidden"])',
+  'select:not([disabled])',
+  'textarea:not([disabled])',
+  'iframe',
+  'summary',
+  '[contenteditable="true"]',
+  '[tabindex]',
+].join(',')
+
+function tabbablesWithin(panel: HTMLElement): HTMLElement[] {
+  return Array.from(panel.querySelectorAll<HTMLElement>(FOCUSABLE_SELECTOR)).filter(
+    (el) =>
+      el.tabIndex >= 0 &&
+      !el.hasAttribute('inert') &&
+      el.getAttribute('aria-hidden') !== 'true' &&
+      !el.closest('[hidden]'),
+  )
+}
 
 interface ModalProps {
   isOpen: boolean
   onClose: () => void
   title: string
   children: ReactNode
-  className?: string
+  className?: string | undefined
+  /**
+   * Accessible name for a modal rendered with an empty `title`. Ignored
+   * when `title` is non-empty — the `<h2>` names the dialog then.
+   */
+  ariaLabel?: string | undefined
 }
 
-function Modal({ isOpen, onClose, title, children, className }: ModalProps) {
+function Modal({ isOpen, onClose, title, children, className, ariaLabel }: ModalProps) {
+  const panelRef = useRef<HTMLDivElement | null>(null)
+  const titleId = useId()
+
+  // Focus: move in on open, restore on close. Keyed on `isOpen` ALONE —
+  // adding `onClose` here would re-run it on every render for the many
+  // callers that pass an inline arrow, snatching focus back to the panel
+  // mid-keystroke.
+  useEffect(() => {
+    if (!isOpen) return
+    const panel = panelRef.current
+    if (!panel) return
+
+    const previous =
+      document.activeElement instanceof HTMLElement &&
+      document.activeElement !== document.body
+        ? document.activeElement
+        : null
+
+    openPanels.push(panel)
+    const initial = panel.querySelector<HTMLElement>('[data-autofocus]')
+    ;(initial ?? panel).focus()
+
+    return () => {
+      const at = openPanels.indexOf(panel)
+      if (at !== -1) openPanels.splice(at, 1)
+      // Restoring is the half that gets forgotten: without it, closing a
+      // modal drops the caret to <body> and the next Tab restarts from
+      // the top of the page.
+      if (previous && previous.isConnected) previous.focus()
+    }
+  }, [isOpen])
+
+  // Escape + tab trap. One document listener; the topmost-panel guard
+  // keeps nested modals from both reacting.
   useEffect(() => {
     if (!isOpen) return
-    const handleEscape = (e: KeyboardEvent) => {
-      if (e.key === 'Escape') onClose()
+    const panel = panelRef.current
+    if (!panel) return
+
+    const handleKeyDown = (e: KeyboardEvent) => {
+      if (openPanels[openPanels.length - 1] !== panel) return
+
+      if (e.key === 'Escape') {
+        onClose()
+        return
+      }
+      if (e.key !== 'Tab') return
+
+      const active = document.activeElement
+      // Focus is outside the panel — almost always a body-level portal
+      // (DropdownMenu / TagChipInput / FolderTreePicker) opened FROM the
+      // modal. Wrapping it back in would break that menu's own keyboard
+      // handling, so leave the event alone.
+      if (!(active instanceof HTMLElement) || !panel.contains(active)) return
+
+      const tabbables = tabbablesWithin(panel)
+      const first = tabbables[0]
+      const last = tabbables[tabbables.length - 1]
+      if (!first || !last) {
+        // Nothing to land on — keep focus on the panel rather than let
+        // Tab walk out into the page behind the backdrop.
+        e.preventDefault()
+        panel.focus()
+        return
+      }
+
+      // The panel holds focus itself right after open. Forward Tab can
+      // fall through to `first` naturally; Shift+Tab would leave the
+      // dialog, so it wraps to `last`.
+      if (active === panel) {
+        if (e.shiftKey) {
+          e.preventDefault()
+          last.focus()
+        }
+        return
+      }
+      if (e.shiftKey && active === first) {
+        e.preventDefault()
+        last.focus()
+      } else if (!e.shiftKey && active === last) {
+        e.preventDefault()
+        first.focus()
+      }
     }
-    document.addEventListener('keydown', handleEscape)
-    return () => document.removeEventListener('keydown', handleEscape)
+
+    document.addEventListener('keydown', handleKeyDown)
+    return () => document.removeEventListener('keydown', handleKeyDown)
   }, [isOpen, onClose])
 
   if (!isOpen) return null
@@ -69,8 +214,17 @@ function Modal({ isOpen, onClose, title, children, className }: ModalProps) {
       {/* Outer card — uses .ds-card-surface so the modal gets the
          same chrome as cards (border + multi-layer shadow + inner
          highlight in light mode). overflow-hidden clips children to
-         the rounded corners; the tray inside handles its own scroll. */}
+         the rounded corners; the tray inside handles its own scroll.
+
+         tabIndex={-1} makes the panel programmatically focusable so it
+         can receive focus on open without joining the tab ring. */}
       <div
+        ref={panelRef}
+        role="dialog"
+        aria-modal="true"
+        aria-labelledby={title ? titleId : undefined}
+        aria-label={title ? undefined : ariaLabel}
+        tabIndex={-1}
         data-framed="true"
         className={cn(
           'ds-card-surface relative w-full max-w-2xl flex flex-col max-h-[90vh] overflow-hidden',
@@ -89,7 +243,10 @@ function Modal({ isOpen, onClose, title, children, className }: ModalProps) {
            than the text, the BUTTON set the row height and the title
            floated in slack it never asked for. */}
         <div className="flex items-center justify-between gap-3 shrink-0 px-4 py-3">
-          <h2 className="text-[15px] font-bold tracking-[-0.01em] text-[rgb(var(--foreground))]">
+          <h2
+            id={titleId}
+            className="text-[15px] font-bold tracking-[-0.01em] text-[rgb(var(--foreground))]"
+          >
             {title}
           </h2>
           <button

package/src/page-shell.tsx

@@ -10,6 +10,7 @@ import {
 } from 'react'
 import { createPortal } from 'react-dom'
 import { Link } from 'react-router-dom'
+import { House } from 'lucide-react'
 import { cn } from './lib/utils'
 
 export type Crumb = {
@@ -60,7 +61,24 @@ interface PageShellProps {
 // per mount, never per render).
 // ---------------------------------------------------------------------------
 
+/**
+ * The app's home destination, rendered as the first breadcrumb.
+ *
+ * PER-APP AND OPT-IN, which is the whole reason it lives on the provider
+ * instead of being hardcoded in `Breadcrumbs`. `PageShell` is shared: the
+ * workspace and `apps/approvals` both render it, and approvals has no
+ * `/clients` route — a hardcoded home would have shipped it a dead link on
+ * every page. An app that wants a home crumb says where home is; an app that
+ * does not gets no icon and nothing breaks.
+ */
+export interface HomeCrumb {
+  to: string
+  /** Accessible name for the icon-only link, e.g. "Clients". */
+  label: string
+}
+
 interface PageHeaderSlotValue {
+  home: HomeCrumb | null
   hostEl: HTMLElement | null
   centerEl: HTMLElement | null
   scrollEl: HTMLElement | null
@@ -71,7 +89,14 @@ interface PageHeaderSlotValue {
 
 const PageHeaderSlotContext = createContext<PageHeaderSlotValue | null>(null)
 
-export function PageHeaderSlotProvider({ children }: { children: ReactNode }) {
+export function PageHeaderSlotProvider({
+  children,
+  home = null,
+}: {
+  children: ReactNode
+  /** Where the leading home crumb points. Omit to render no home crumb. */
+  home?: HomeCrumb | null
+}) {
   const [hostEl, setHostEl] = useState<HTMLElement | null>(null)
   const [centerEl, setCenterEl] = useState<HTMLElement | null>(null)
   const [scrollEl, setScrollEl] = useState<HTMLElement | null>(null)
@@ -84,6 +109,7 @@ export function PageHeaderSlotProvider({ children }: { children: ReactNode }) {
   return (
     <PageHeaderSlotContext.Provider
       value={{
+        home,
         hostEl,
         centerEl,
         scrollEl,
@@ -375,6 +401,50 @@ export function PageHeaderHost({
   )
 }
 
+/**
+ * The app's home destination, or null when the app has not declared one.
+ *
+ * Exported because not every breadcrumb in the app goes through `PageShell` —
+ * the Generate lens renders its own trail beside an editable project title —
+ * and those forks should read the same destination rather than each hardcoding
+ * a path that then drifts.
+ */
+export function useBreadcrumbHome(): HomeCrumb | null {
+  return useContext(PageHeaderSlotContext)?.home ?? null
+}
+
+/**
+ * The leading home crumb: an icon, not a word.
+ *
+ * WHY AN ICON REPLACES THE FIRST CRUMB RATHER THAN SITTING BESIDE IT. Thirty-one
+ * lens trails already began `Clients / …` pointing at `/clients`, which is
+ * exactly where home goes — so rendering both would put the same destination on
+ * screen twice in a row, once as a picture and once as a word. The icon takes
+ * that crumb's place when they agree and prepends when they do not (the tools
+ * trails start at `/tools`), so "first position" holds either way.
+ *
+ * It carries an `aria-label` and a `title`: an icon-only link has no accessible
+ * name otherwise, and the tooltip is what tells a first-time user that the house
+ * means the client list rather than some other notion of home.
+ */
+export function HomeCrumbLink({ home }: { home: HomeCrumb }) {
+  return (
+    <Link
+      to={home.to}
+      aria-label={home.label}
+      title={home.label}
+      className="shrink-0 flex items-center transition-colors hover:text-[rgb(var(--foreground))]"
+      style={{ color: 'inherit' }}
+    >
+      {/* 15px beside 13px crumb text, at the 1.9 stroke the theme toggle in
+          this same header band uses — the app's chrome runs heavier than
+          Lucide's default, and matching the neighbour matters more than the
+          generic rule. */}
+      <House className="h-[15px] w-[15px]" strokeWidth={1.9} aria-hidden="true" />
+    </Link>
+  )
+}
+
 function Breadcrumbs({
   parents,
   current,
@@ -382,12 +452,31 @@ function Breadcrumbs({
   parents: Crumb[]
   current: Crumb | undefined
 }) {
+  const home = useBreadcrumbHome()
+  // When the first crumb already IS home, the icon stands in for it rather
+  // than duplicating it. Compared by destination, not by label, because the
+  // label varies ("Clients", a brand name) while the route does not.
+  const visibleParents =
+    home && parents[0]?.to === home.to ? parents.slice(1) : parents
+
   return (
     <nav
       className="flex items-center gap-1.5 text-[13px] min-w-0"
       style={{ color: 'rgb(var(--text-tertiary))' }}
     >
-      {parents.map((c, i) => (
+      {home && (
+        <>
+          <HomeCrumbLink home={home} />
+          {/* Separator only when something follows it. A page with no crumbs
+              at all would otherwise render a dangling "home /". */}
+          {(visibleParents.length > 0 || current) && (
+            <span className="shrink-0" style={{ color: 'rgb(var(--text-muted))' }}>
+              /
+            </span>
+          )}
+        </>
+      )}
+      {visibleParents.map((c, i) => (
         <span key={i} className="flex items-center gap-1.5 min-w-0">
           {c.to ? (
             <Link

package/src/segmented-pill.tsx

@@ -9,12 +9,20 @@
  *   │ └──────────────┘                                              │
  *   ╰──────────────────────────────────────────────────────────────╯
  *
- *   • Whole strip sits in a subtle `--surface-overlay-soft` rounded
- *     container so the inactive segments read as text rather than
- *     borderless buttons.
- *   • The active segment is wrapped in a 1px accent border with an
- *     `--accent-subtle` fill — reads as an "outlined pill" sitting
- *     inside the strip.
+ *   • The track is an OPAQUE recessed well (`--surface-frame`) so the
+ *     inactive segments read as text rather than borderless buttons.
+ *   • The active segment steps UP off the track: an opaque
+ *     `--surface-card` fill sandwiched between the track and a 1px
+ *     accent border, plus `--shadow-sm`. It reads as a raised pill,
+ *     not a tinted one.
+ *
+ *   Both were translucent until 2026-08-30 (`--surface-overlay-soft`
+ *   track, `--accent-subtle` pill). Stacked, they composited to a 245
+ *   pill inside a 247 track in light mode — the active segment was
+ *   DARKER than the thing it sits in, so the raised element read as
+ *   recessed and the control looked washed out. Opaque surfaces cannot
+ *   invert like that, because their relationship does not depend on
+ *   whatever happens to be behind them.
  *   • Each segment is a button with an optional leading icon.
  *
  * Generic — accepts a typed `items` array. First consumer: Keywords
@@ -79,7 +87,14 @@ export function SegmentedPill<Id extends string = string>({
         className,
       )}
       style={{
-        background: 'rgb(var(--surface-overlay-soft))',
+        // OPAQUE. This was --surface-overlay-soft, a translucent tint, with a
+        // translucent --accent-subtle pill on top of it — two alpha layers
+        // stacked. In light that composited to a 245 pill inside a 247 strip:
+        // the ACTIVE segment rendered DARKER than the track it sits in, so the
+        // raised element read as recessed and the whole control looked washed
+        // out. --surface-frame is the recessed-well token and is darker than
+        // --surface-card in BOTH themes, so the direction holds either way.
+        background: 'rgb(var(--surface-frame))',
         border: '1px solid rgb(var(--border))',
         borderRadius: 'var(--radius-full)',
       }}
@@ -110,9 +125,17 @@ export function SegmentedPill<Id extends string = string>({
               borderRadius: 'var(--radius-full)',
               ...(isActive
                 ? {
-                    background: 'rgb(var(--accent-subtle))',
+                    // The active segment STEPS UP off the track: an opaque
+                    // surface sandwiched between the accent border and the
+                    // strip, plus a small shadow. --surface-card is +8 on the
+                    // frame in light and +6 in dark, so it reads raised in both.
+                    background: 'rgb(var(--surface-card))',
                     border: '1px solid rgb(var(--accent))',
-                    color: 'rgb(var(--accent))',
+                    // --accent-ink, not --accent: the brand red is 5.64:1 on a
+                    // light card but 3.05:1 on a dark one, i.e. an accent LABEL
+                    // fails AA in dark. --accent-ink is the theme-tuned form.
+                    color: 'rgb(var(--accent-ink))',
+                    boxShadow: 'var(--shadow-sm)',
                   }
                 : {
                     background: 'transparent',
@@ -126,7 +149,7 @@ export function SegmentedPill<Id extends string = string>({
                 className="inline-flex shrink-0"
                 style={{
                   color: isActive
-                    ? 'rgb(var(--accent))'
+                    ? 'rgb(var(--accent-ink))'
                     : 'rgb(var(--text-muted))',
                 }}
                 aria-hidden="true"

package/src/styles.css

@@ -131,6 +131,34 @@
   box-shadow: var(--ring-focus);
 }
 
+/* ─────────────────────────────────────────────────────────────────────────
+ * BASELINE FOCUS INDICATOR
+ *
+ * Until this existed, only elements that opted in — primitives via .btn /
+ * .input-shell, and hand-written `focus-visible:` classes — showed OUR focus
+ * ring. Everything else fell through to the browser's `outline: auto`, which
+ * on macOS paints in the USER'S SYSTEM ACCENT COLOUR. So a keyboard user with
+ * an amber system accent saw an amber ring on most controls and our red ring
+ * on a few, in the same tab sequence. Measured in the Generate lens: 115
+ * buttons, 35 with a ring.
+ *
+ * `:where()` gives this ZERO specificity, so it is a floor, not an override —
+ * .btn, .input-shell, and any component or utility class still win.
+ * ───────────────────────────────────────────────────────────────────────── */
+@layer base {
+  :where(a[href], button, input, select, textarea, summary, [tabindex]:not([tabindex^='-'])):focus-visible {
+    /* OUTLINE, not box-shadow, deliberately. Tailwind's shadow/ring utilities
+       compose onto `box-shadow`, so a zero-specificity box-shadow baseline loses
+       to any element carrying one (e.g. a `ring-1` selected state) and silently
+       renders nothing. `outline` is untouched by that chain, follows
+       border-radius in every modern browser, and matches --ring-focus's geometry.
+       Elements with their own ring set `outline: none` alongside it, so they
+       override this cleanly rather than double-drawing. */
+    outline: 2px solid rgb(var(--accent));
+    outline-offset: 0;
+  }
+}
+
 .btn-primary {
   background: rgb(var(--accent));
   color: white;