@lovett/ui 0.0.11 → 0.2.0

package/src/tabs.tsx

@@ -9,11 +9,99 @@
  * section scroll-spy + section-nav-as-tabs on profile pages. <Tabs>
  * is the simpler horizontal-button-row for top-of-content tab navigation.
  *
+ * ## Three variants, and when the third one is the right answer
+ *
+ * `underline` (default) and `pill` are top-of-content navigation: the strip
+ * sits above a page's worth of content and its width is whatever the label
+ * run comes to. `segmented` is for a tab strip that has to hold a COLUMN —
+ * a boxed track with equal-width segments that fills its container, so it
+ * reads as one control rather than a run of words drifting left. It is the
+ * same box as `SegmentedChoice` (inset track, opaque raised active segment,
+ * accent border, `--shadow-sm`, concentric `--radius-md` outer /
+ * `--radius-sm` inner) and the same 36px overall height, so a segmented
+ * strip in one pane sits flush with a search + filter row in the next.
+ *
+ * `SegmentedChoice` is NOT interchangeable with it: that primitive is
+ * `role="group"` + `aria-pressed`, which is correct for a filter and wrong
+ * for a real tablist. When the segments switch panels, they are tabs, and
+ * they belong here where the APG keyboard model already lives.
+ *
+ * The active segment is an opaque step UP onto `--surface-card`, per
+ * CLAUDE.md §2 — never an alpha tint on a translucent track, which
+ * composites to a raised element darker than the well it sits in.
+ *
  * Token discipline: all colors via public tokens. Active tab uses the
  * accent token; inactive uses text-tertiary.
+ *
+ * ## Keyboard (WAI-ARIA APG "Tabs")
+ *
+ * `role="tablist"` is a promise about keyboard behaviour, and until this it
+ * was not kept: every tab was a separate tab stop, and the arrow keys did
+ * nothing. The pattern is implemented here in full —
+ *
+ *   - **Roving tabindex.** Exactly one tab is in the document's tab ring
+ *     (`tabIndex={0}`); the rest are `-1`. Tab enters the tablist once and
+ *     leaves it once, which is the whole point of the role. Disabled tabs are
+ *     never the roving one, and if the active tab is disabled (or is not in
+ *     `tabs` at all) the first enabled tab holds the stop rather than nothing
+ *     holding it.
+ *   - **ArrowLeft / ArrowRight move and WRAP**; **Home / End** jump to the
+ *     first / last enabled tab.
+ *   - **AUTOMATIC activation** — moving selects. Chosen deliberately: every
+ *     consumer in this workspace switches a panel that is already rendered
+ *     client-side, so selection is free and manual activation (move with
+ *     arrows, commit with Enter/Space) would just be a second keystroke for
+ *     no benefit. Manual activation is for tabs whose panels cost a fetch.
+ *
+ * LTR only. Nothing in this file reads `dir` or uses logical properties, so
+ * ArrowRight means "next" — mirroring it here would be half of an RTL story
+ * the rest of the component does not tell.
+ *
+ * ## Panels, ids, and the `aria-controls` promise
+ *
+ * `<Tabs>` renders the tab STRIP and nothing else — every consumer in the
+ * workspace renders its own panel. So `aria-controls` is opt-in via
+ * `Tab.panelId`, and is emitted only when the consumer says which element it
+ * points at. Emitting a generated `aria-controls` that resolves to nothing is
+ * a broken promise to assistive tech, not a partial credit (it is exactly the
+ * defect `SegmentedPill` was carrying).
+ *
+ * The other direction is exposed rather than generated: each tab's `id` is
+ * `<idPrefix>-tab-<tab.id>`, and `idPrefix` is a prop, so a consumer can
+ * point its panel's `aria-labelledby` at a tab it knows the id of. The panel
+ * itself is the consumer's to render, with `role="tabpanel"`,
+ * `aria-labelledby` back at the tab, and `tabIndex={0}` so a keyboard user
+ * can reach panel content that holds no focusable of its own.
  */
 
-import type { ReactNode } from 'react'
+import { useId, useRef, type CSSProperties, type KeyboardEvent, type ReactNode } from 'react'
+
+type TabsVariant = 'underline' | 'pill' | 'segmented'
+
+/** The track the segments sit in, per variant. */
+const TRACK_CLASS: Readonly<Record<TabsVariant, (stretch: boolean) => string>> = {
+  underline: (stretch) =>
+    `${stretch ? 'flex w-full' : 'inline-flex'} items-center gap-1 border-b`,
+  pill: (stretch) => `${stretch ? 'flex w-full' : 'inline-flex'} items-center gap-1 p-1`,
+  segmented: (stretch) =>
+    `${stretch ? 'flex w-full' : 'inline-flex'} items-center gap-[var(--space-1)] border p-[var(--space-1)]`,
+}
+
+const TRACK_STYLE: Readonly<Record<TabsVariant, CSSProperties>> = {
+  underline: { borderColor: 'rgb(var(--border))' },
+  pill: {
+    background: 'rgb(var(--surface-overlay-soft))',
+    border: '1px solid rgb(var(--border))',
+    borderRadius: 'var(--radius-full)',
+  },
+  // Outer --radius-md (12) minus the 4px of track padding leaves --radius-sm
+  // (8) for the segment: concentric, per the radius rule.
+  segmented: {
+    background: 'rgb(var(--surface-inset))',
+    borderColor: 'rgb(var(--border))',
+    borderRadius: 'var(--radius-md)',
+  },
+}
 
 export interface Tab {
   id: string
@@ -26,6 +114,13 @@ export interface Tab {
   /** Accessible name for ICON-ONLY tabs (label rendered empty) — e.g. the
    *  responsive platform switcher's compact tier (ADR-135). */
   ariaLabel?: string
+  /**
+   * `id` of the `role="tabpanel"` element this tab controls, when the
+   * consumer renders one. Supplying it emits `aria-controls`; omitting it
+   * emits nothing, because an `aria-controls` that resolves to no element is
+   * worse than none at all.
+   */
+  panelId?: string
 }
 
 export interface TabsProps {
@@ -34,10 +129,21 @@ export interface TabsProps {
   onTabChange: (id: string) => void
   /** Compact (12px label) or default (13px). */
   size?: 'sm' | 'md'
-  /** Underline (default) or pill active-state. */
-  variant?: 'underline' | 'pill'
+  /**
+   * `underline` (default) and `pill` are top-of-content nav; `segmented` is
+   * the boxed track for a strip that has to fill a column — see the
+   * docblock. `segmented` is almost always paired with `stretch`.
+   */
+  variant?: TabsVariant
   /** Stretch the tablist to full width with equal-width, centred tabs. */
   stretch?: boolean
+  /**
+   * Namespace for the generated tab `id`s, which are
+   * `<idPrefix>-tab-<tab.id>`. Pass a stable string when a panel needs to
+   * name its tab in `aria-labelledby`; leave it out and a `useId()` prefix is
+   * minted, which is unique but not knowable from outside.
+   */
+  idPrefix?: string
   className?: string
 }
 
@@ -48,34 +154,96 @@ export function Tabs({
   size = 'md',
   variant = 'underline',
   stretch = false,
+  idPrefix,
   className,
 }: TabsProps) {
   const textSize = size === 'sm' ? 'text-[12px]' : 'text-[13px]'
+
+  const reactId = useId()
+  // `useId()` returns a colon-wrapped token in React 18 and a underscore-
+  // wrapped one in 19; neither is a valid bare CSS selector, and these ids end
+  // up in `aria-labelledby` where a consumer may well want to query them.
+  const prefix = idPrefix ?? `tabs-${reactId.replace(/[^a-zA-Z0-9_-]/g, '')}`
+  const tabDomId = (id: string) => `${prefix}-tab-${id}`
+
+  // Movement runs over the ENABLED tabs only: a disabled button cannot take
+  // focus, so stepping onto one would silently strand the keyboard.
+  const enabled = tabs.filter((tab) => tab.disabled !== true)
+  const rovingId = enabled.some((tab) => tab.id === activeTabId)
+    ? activeTabId
+    : enabled[0]?.id
+
+  const buttonRefs = useRef(new Map<string, HTMLButtonElement>())
+
+  const activate = (next: Tab | undefined) => {
+    if (next === undefined) return
+    // Focus first: the button is already mounted, and moving focus before the
+    // state change means a consumer that re-renders synchronously cannot land
+    // us on `<body>`.
+    buttonRefs.current.get(next.id)?.focus()
+    if (next.id !== activeTabId) onTabChange(next.id)
+  }
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLButtonElement>, tab: Tab) => {
+    const index = enabled.findIndex((item) => item.id === tab.id)
+    if (index === -1) return
+    const count = enabled.length
+    switch (event.key) {
+      case 'ArrowRight':
+        event.preventDefault()
+        activate(enabled[(index + 1) % count])
+        break
+      case 'ArrowLeft':
+        event.preventDefault()
+        activate(enabled[(index - 1 + count) % count])
+        break
+      case 'Home':
+        event.preventDefault()
+        activate(enabled[0])
+        break
+      case 'End':
+        event.preventDefault()
+        activate(enabled[count - 1])
+        break
+      default:
+        break
+    }
+  }
+
   return (
     <div
       role="tablist"
-      className={
-        className ??
-        (variant === 'underline'
-          ? `${stretch ? 'flex w-full' : 'inline-flex'} items-center gap-1 border-b`
-          : `${stretch ? 'flex w-full' : 'inline-flex'} items-center gap-1 p-1`)
-      }
-      style={
-        variant === 'underline'
-          ? { borderColor: 'rgb(var(--border))' }
-          : {
-              background: 'rgb(var(--surface-overlay-soft))',
-              border: '1px solid rgb(var(--border))',
-              borderRadius: 'var(--radius-full)',
-            }
-      }
+      className={className ?? TRACK_CLASS[variant](stretch)}
+      style={TRACK_STYLE[variant]}
     >
       {tabs.map((tab) => {
         const isActive = tab.id === activeTabId
-        const base = `inline-flex items-center gap-1.5 px-3 h-9 ${textSize} font-medium transition-colors${stretch ? ' flex-1 justify-center' : ''}`
-        const underlineClass = `${base} border-b-2 -mb-px`
-        const pillClass = `${base}`
-        const className = variant === 'underline' ? underlineClass : pillClass
+        const grow = stretch ? ' flex-1 justify-center' : ''
+        // `segmented` sits in a 4px-padded track, so its segment is 26px —
+        // 26 + 4 + 4 + 1 + 1 = the 36px the field-list header already stands
+        // at. The other two variants keep their 36px button.
+        const base =
+          variant === 'segmented'
+            ? // `min-w-0` is load-bearing: a flex item's default `min-width:
+              // auto` refuses to shrink below its content, so at the activity
+              // pane's 280px floor the three segments stopped being equal and
+              // the last one ran out through the track's border. With it they
+              // stay equal and the label truncates instead.
+              `inline-flex min-w-0 items-center gap-1.5 h-[26px] px-[var(--space-2)] rounded-[var(--radius-sm)] border ${textSize} font-semibold transition-[background-color,color,border-color,box-shadow] duration-[var(--dur-fast)] ease-[var(--ease-out)] motion-reduce:transition-none focus-visible:outline-none focus-visible:[box-shadow:var(--ring-focus)]${grow}`
+            : `inline-flex items-center gap-1.5 px-3 h-9 ${textSize} font-medium transition-colors${grow}`
+        // Segmented carries its colours as CLASSES, not inline style, so the
+        // focus ring can beat the active segment's `--shadow-sm`; an inline
+        // box-shadow would win over `focus-visible:` unconditionally and the
+        // one variant with no underline would be the one with no focus ring.
+        const segmentedState = isActive
+          ? 'border-[rgb(var(--accent))] bg-[rgb(var(--surface-card))] text-[rgb(var(--accent-ink))] [box-shadow:var(--shadow-sm)]'
+          : 'border-transparent text-[rgb(var(--text-tertiary))] hover:text-[rgb(var(--foreground))]'
+        const className =
+          variant === 'underline'
+            ? `${base} border-b-2 -mb-px`
+            : variant === 'segmented'
+              ? `${base} ${segmentedState}`
+              : base
 
         const activeStyle =
           variant === 'underline'
@@ -106,24 +274,37 @@ export function Tabs({
         return (
           <button
             key={tab.id}
+            ref={(node) => {
+              if (node === null) buttonRefs.current.delete(tab.id)
+              else buttonRefs.current.set(tab.id, node)
+            }}
+            id={tabDomId(tab.id)}
             role="tab"
             type="button"
             aria-selected={isActive}
             aria-label={tab.ariaLabel}
+            {...(tab.panelId === undefined ? {} : { 'aria-controls': tab.panelId })}
+            // Roving tabindex — one stop for the whole strip.
+            tabIndex={tab.id === rovingId ? 0 : -1}
             disabled={tab.disabled}
+            onKeyDown={(event) => handleKeyDown(event, tab)}
             onClick={() => onTabChange(tab.id)}
             className={`${className} ${tab.disabled ? 'cursor-not-allowed opacity-40' : 'cursor-pointer'}`}
-            style={isActive ? activeStyle : inactiveStyle}
+            {...(variant === 'segmented'
+              ? {}
+              : { style: isActive ? activeStyle : inactiveStyle })}
           >
             {tab.icon && (
               <span className="flex-shrink-0" aria-hidden>
                 {tab.icon}
               </span>
             )}
-            {tab.label}
+            <span className={variant === 'segmented' ? 'min-w-0 truncate' : undefined}>
+              {tab.label}
+            </span>
             {tab.count !== undefined && (
               <span
-                className="ml-0.5 inline-flex min-w-[1.1rem] items-center justify-center rounded-full px-1 text-[10.5px] font-semibold tabular-nums"
+                className="ml-0.5 inline-flex min-w-[1.1rem] shrink-0 items-center justify-center rounded-full px-1 text-[10.5px] font-semibold tabular-nums"
                 style={
                   isActive && variant === 'pill'
                     ? {