@lovett/ui 0.0.9 → 0.0.11

package/src/tokens.css

@@ -49,6 +49,9 @@
  *                                      colored backgrounds — switches,
  *                                      sliders, badges-on-accent)
  *         --muted                     (muted fill for ghost UI)
+ *         --surface-subtle            (lightest structural tint — header bands
+ *                                      and zebra on an already-bordered
+ *                                      surface; 1.04:1, matched across themes)
  *         --header-height             (sticky AppHeader height — referenced
  *                                      by sticky chip bars; same value lives
  *                                      in src/lib/layout.ts for JS callsites)
@@ -92,6 +95,49 @@
   --accent-muted: 207 14 15 / 0.12;
   --accent-subtle: 207 14 15 / 0.06;
   --accent-glow: 207 14 15 / 0.25;
+  /* Text-selection highlight. PUBLIC, and a full colour (not a triple) so
+     `::selection { background: var(--selection-bg) }` is valid at :root.
+     `@lovett/shell` ships that exact global rule while defining the
+     variable only inside `.cs-frame`; unset at the root, `background`
+     computed to transparent and every selection in the app was invisible
+     (ADR-145 amendment, 2026-09-04). Neutral blue like a native selection,
+     not the accent — the accent earns impact from scarcity. */
+  --selection-bg: rgb(var(--info) / 0.34);
+  /* Ink ON an accent fill. PUBLIC, and theme-independent because --accent is:
+     the brand red does not change between light and dark, so its foreground
+     must not either. Measures 5.64:1 on --accent.
+     Added 2026-08-29 — needs a token ADR (CLAUDE.md §4). It closes a real gap:
+     app code had three different answers for "text on accent" (a `text-white`
+     literal, the INTERNAL --primary-foreground, and a reference to this very
+     name with an inline fallback), and one of them — `rgb(var(--foreground))`
+     — inverted to near-black on red at 3.34:1 in light mode. The public
+     --accent family had every value EXCEPT its foreground, so lens code had
+     nothing correct to reach for. */
+  --accent-foreground: 255 255 255;
+  /* Accent as TEXT on a normal surface — a different problem from
+     --accent-foreground (ink ON an accent fill). PUBLIC, and unlike --accent it
+     IS theme-tuned: the brand red measures 5.64:1 on a light card but only
+     3.05:1 on a dark one, so an accent-coloured LABEL is legible in light and
+     fails AA in dark. The dark value is the lifted red that clears it (4.57:1).
+     Use for selected-state labels, accent links, accent metric values — never
+     as a fill. */
+  --accent-ink: 239 68 68;
+
+  /* SEMANTIC INK — PUBLIC. Same problem as --accent-ink, same shape of answer.
+     `--success` / `--warning` are sized to work as FILLS and as icon strokes;
+     used as TEXT ON THEIR OWN 10-12% TINT they are only legible in one theme.
+     Measured over the card: success reads 5.64:1 dark but 3.33:1 light, and
+     warning 6.46:1 dark but 2.86:1 light — both fail AA for body text in light
+     mode, which is exactly where the generate lens's tip panels and word-count
+     chips live. Dark keeps the base colour; light gets a darkened ink that
+     clears 4.5:1 while still reading green and amber rather than near-black.
+     Text only — never a fill, and never a border. */
+  --success-ink: var(--success);
+  --warning-ink: var(--warning);
+  /* Destructive is the one that fails in BOTH themes as text on its own tint
+     (3.53:1 light, 3.67:1 dark), so unlike the other two the dark value is not
+     the base — it is lifted 18% toward white to clear 5.11:1 / 4.51:1. */
+  --destructive-ink: 242 102 102;
 
   /* ============================================================
      HIERARCHY MAP PALETTE — PUBLIC, theme-INDEPENDENT.
@@ -167,6 +213,17 @@
   --folder-slate: 148 163 184;
   --folder-ink: 203 213 225;
 
+  /* OPAQUE categorical tints — the chip/pill FILL for a --folder-* hue.
+     Pre-composited (hue at 0.12 over --surface-card) so a chip needs no
+     alpha and therefore does not change appearance when the surface
+     under it changes. Only the two hues with consumers are defined;
+     extend per hue as consumers land rather than all nine up front.
+     NOTE: the hue itself is a FILL/GRAPHIC value, not an ink — e.g.
+     --folder-amber on its own tint measures 2.86:1 in light. Chip TEXT
+     is --foreground; the tint + border carry the category. */
+  --folder-amber-tint: 53 43 28;
+  --folder-blue-tint: 31 39 56;
+
   /* ============================================================
      SIDEBAR — INTERNAL (only <Sidebar/> reads these)
      ============================================================ */
@@ -298,8 +355,18 @@
   --shadow-xl: 0 16px 40px rgb(0 0 0 / 0.55);
   --shadow-2xl: 0 24px 60px rgb(0 0 0 / 0.60);
 
-  --ring-focus: 0 0 0 3px rgb(207 14 15 / 0.25);
-  --ring-error: 0 0 0 3px rgb(239 68 68 / 0.25);
+  /* Thin and SOLID, not a soft halo — and this is a legibility fix as much as
+     a look. The old 3px @ 0.25/0.20 composited to rgb(245 207 207) on a light
+     card and rgb(63 24 27) on a dark one: 1.43:1 and 1.11:1 against the surface
+     it sits on, against the 3:1 that WCAG 2.2 SC 2.4.11 (Focus Appearance)
+     asks of a focus indicator. Alpha was measured across the range and NOTHING
+     below fully-opaque clears 3:1 in dark mode, so the ring is solid: 5.64:1
+     light, 3.05:1 dark. 2px keeps the >=2px perimeter the same SC requires
+     while reading crisper than the 3px glow it replaces.
+     Both resolve through the theme-aware tokens, so the light block needs no
+     override — var() resolves at use time. */
+  --ring-focus: 0 0 0 2px rgb(var(--accent));
+  --ring-error: 0 0 0 2px rgb(var(--destructive));
 
   --radius-xs: 6px;
 
@@ -339,6 +406,18 @@
   --surface-card: 27 27 30;
   --surface-inset: 45 45 48;
   --surface-hover: 55 55 59;
+  /* THE LIGHTEST STRUCTURAL TINT — PUBLIC. A header band or zebra stripe on a
+     surface that ALREADY HAS A BORDER, where the fill only has to hint that a
+     row is chrome rather than content.
+     Measured: the border alone is 1.25:1 in dark and 1.32:1 in light, stronger
+     than any fill step in the neutral ramp — so the fill is decoration on top
+     of structure that already reads, and it can go very light indeed.
+     Sized by OKLCH lightness so the two themes are the SAME design: ΔL 0.017
+     dark, 0.014 light (1.045:1 / 1.042:1). That symmetry is the point. Using
+     --muted for this job gave ΔL 0.075 in dark against 0.038 in light — twice
+     the step in one theme, which is why a header that looked right in dark read
+     as a grey slab in light. */
+  --surface-subtle: 31 31 34;
   /* A control you can act on — input, select, option tile, chip-button.
      Sits at CARD level on purpose: in light that is white against the
      frame behind it, which reads "type here"; in dark it is raised above
@@ -389,6 +468,21 @@
 [data-theme="light"], [data-theme="combo"] {
   /* Brand accent — base stays, hover darkens, glow softens */
   --accent-hover: 178 8 9;
+  --selection-bg: rgb(var(--info) / 0.24);
+  /* Brand red passes on a light card (5.64:1) — see the :root note. */
+  --accent-ink: var(--accent);
+  /* Solved against the DARKEST tint these inks land on, not the lightest.
+     The lens mixes success at both 10% (tip panels) and 20% (score chips); an
+     ink tuned only to the 10% tint cleared 4.61:1 there and still failed at
+     4.09:1 on the 20% chip. This value clears BOTH — 5.12:1 and 4.54:1 — and
+     at 77% of --success it is still unmistakably green. */
+  --success-ink: 4 116 81;
+  /* Same reasoning as --success-ink: solved against the 20% tint as well as
+     the 10% one (5.03:1 / 4.52:1, up from 2.86:1 / 4.05:1). 72% of --warning,
+     still unmistakably amber. */
+  --warning-ink: 156 86 4;
+  /* 5.28:1 / 4.51:1 on the 10% and 20% tints, up from 3.53:1. */
+  --destructive-ink: 189 33 33;
   --accent-muted: 207 14 15 / 0.10;
   --accent-subtle: 207 14 15 / 0.05;
   --accent-glow: 207 14 15 / 0.20;
@@ -406,9 +500,28 @@
   --card-foreground: 17 17 19;
   --popover-foreground: 17 17 19;
   --muted-foreground: 82 82 91;
-  --text-secondary: 82 82 91;
-  /* --text-tertiary stays from :root */
-  /* Lifted 161->137 — was 2.56:1 on a white card. */
+  /* Byte-identical to --muted-foreground in both themes since they were
+     introduced. Aliased rather than duplicated so the two names cannot
+     drift apart; prefer --muted-foreground in new code. */
+  --text-secondary: var(--muted-foreground);
+  /* Was "stays from :root" — but :root IS the dark theme, so light
+     inherited the dark-tuned 132 132 141, which measures 3.71:1 on a
+     255 card and fails AA for the 13px body text that consumes it.
+     Re-picked by measurement, not by eye: 110 110 119 is the first rung
+     with headroom on every light surface it can land on —
+     5.05:1 on --surface-card/page (255), 4.72:1 on --surface-frame (247),
+     4.52:1 on --surface-inset (242). Keeps the ramp's 286° cool cast.
+     Side effect: it also repairs the ink ramp's shape. The tiers were
+     L 0.442 / 0.616 / 0.633 — a wide gap then a collision, tertiary and
+     muted less than half a surface-step apart. They are now
+     0.442 / 0.541 / 0.633: three evenly-spread rungs. */
+  --text-tertiary: 110 110 119;
+  /* Lifted 161->137 — was 2.56:1 on a white card. Still only 3.47:1 on
+     255, i.e. it clears the 3:1 non-text floor and NOT the 4.5:1 text
+     floor. That is deliberate: --text-muted is the quietest rung and is
+     for NON-TEXT and DISABLED chrome only — quiet icons, chevrons,
+     disabled labels. Real text one tier up (--text-tertiary) or higher.
+     Lifting this to pass 4.5:1 would collapse it into --text-tertiary. */
   --text-muted: 137 137 146;
   --secondary-foreground: 17 17 19;
 
@@ -446,9 +559,6 @@
   --shadow-2xl: 0 24px 60px rgb(0 0 0 / 0.16);
   --shadow-glow: 0 0 20px rgb(207 14 15 / 0.20);
 
-  --ring-focus: 0 0 0 3px rgb(207 14 15 / 0.20);
-  --ring-error: 0 0 0 3px rgb(220 38 38 / 0.18);
-
   /* Match --page-bg (254/254/254). Was 241/245/249 (slate) — that's
    * what was actually painting "the steely background" the owner
    * flagged; --page-bg is the body, but MainLayout's content area
@@ -508,6 +618,8 @@
   --surface-frame: 247 247 249;
   --surface-inset: 242 242 244;
   --surface-hover: 238 238 240;
+  /* 1.042:1 against the card — a band, not a slab. See the :root note. */
+  --surface-subtle: 250 250 252;
   /* A control you can act on — input, select, option tile, chip-button.
      Sits at CARD level on purpose: in light that is white against the
      frame behind it, which reads "type here"; in dark it is raised above
@@ -606,6 +718,9 @@
   --folder-pink: 219 39 119;
   --folder-slate: 71 85 105;
   --folder-ink: 15 23 42;
+  /* Opaque categorical tints — hue at 0.10 over the 255 light card. */
+  --folder-amber-tint: 251 241 230;
+  --folder-blue-tint: 232 237 251;
 }
 
 /* ============================================================

package/src/tooltip.tsx

@@ -0,0 +1,297 @@
+/**
+ * Tooltip — a short, non-interactive label that appears on hover or focus.
+ *
+ * Wraps ONE trigger element (always "asChild": the child is cloned with the
+ * ref, the hover / focus handlers and `aria-describedby`; no wrapper node is
+ * added). The tip is `role="tooltip"`, portals to `document.body`, positions
+ * through `useAnchoredPosition` (default: above, centred; flips below when
+ * there is no room), enters with `.ds-enter-pop` once positioned, and is
+ * `pointer-events: none` so it never blocks the thing under it.
+ *
+ * Timing: hover opens after `openDelay` (300 ms) and closes after
+ * `closeDelay` (0 ms) — the delay is what keeps a mouse sweeping across a
+ * toolbar from flashing every label. Keyboard focus opens IMMEDIATELY (a
+ * keyboard user has already committed to the control); a focus that arrives
+ * by pointer (clicking a button) does not open it, and pressing the trigger
+ * dismisses it. Escape dismisses through the shared layer stack, so it never
+ * steals the keypress from a Modal underneath — a tooltip is pushed above
+ * the modal only while it is showing.
+ *
+ * Never traps or moves focus: the tip is not focusable and the trigger keeps
+ * whatever focus it had. Only non-interactive content belongs in it — the
+ * trigger should still have its own accessible name (`aria-label`) when it
+ * is icon-only; the tooltip DESCRIBES, it does not name.
+ *
+ * Promoted per ADR-0030 Decision G (meta-ads-audit-dashboard task manager:
+ * truncated cells, icon-only row actions, relative timestamps). Second
+ * consumer is the workspace app, which hand-rolls two today —
+ * `tools/_shared/calc/info-tip.tsx` and
+ * `components/ui/sidebar/rail-tooltip.tsx` — and leans on 900+ `title`
+ * attributes elsewhere.
+ *
+ * Token discipline: token-only inline surface like Kbd — INTERNAL
+ * `--popover` / `--popover-foreground` (allowed inside packages/ui) with
+ * public `--border`, `--shadow-md`, `--radius-sm`, `--space-*`. The same
+ * chrome family as Popover / DropdownMenu, so a tip and a menu read as one
+ * system. Geometry from the hook; motion from `.ds-enter-pop`, which
+ * honours prefers-reduced-motion in styles.css.
+ *
+ * Usage:
+ *
+ *   <Tooltip content="Archive task">
+ *     <Button variant="secondary" aria-label="Archive task"><Archive /></Button>
+ *   </Tooltip>
+ *
+ *   <Tooltip content={fullTitle} side="bottom" align="start">
+ *     <span className="truncate">{fullTitle}</span>
+ *   </Tooltip>
+ */
+
+import {
+  cloneElement,
+  isValidElement,
+  useCallback,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+  type CSSProperties,
+  type FocusEvent as ReactFocusEvent,
+  type HTMLAttributes,
+  type PointerEvent as ReactPointerEvent,
+  type ReactElement,
+  type ReactNode,
+  type Ref,
+} from 'react'
+import { createPortal } from 'react-dom'
+import { cn } from './lib/utils'
+import { composeRefs } from './lib/refs'
+import { useLayer } from './lib/layer-stack'
+import { useAnchoredPosition, type AnchorAlign, type AnchorSide } from './lib/anchor'
+
+export interface TooltipProps {
+  /** The tip's content. Nothing renders (children pass through untouched) when null. */
+  content: ReactNode
+  /** Exactly one element — it becomes the trigger. */
+  children: ReactElement<TooltipTriggerProps>
+  /** Default `top`. Flips when it cannot fit. */
+  side?: AnchorSide
+  /** Default `center`. */
+  align?: AnchorAlign
+  /** Gap from the trigger, px. Default 6. */
+  offset?: number
+  /** Hover-open delay, ms. Default 300. Focus opens immediately. */
+  openDelay?: number
+  /** Close delay, ms. Default 0. */
+  closeDelay?: number
+  /** Controlled open state. Omit for internal state. */
+  open?: boolean
+  defaultOpen?: boolean
+  onOpenChange?: (open: boolean) => void
+  /** Extra classes on the tip surface. */
+  className?: string
+}
+
+/** What the cloned trigger element must accept. */
+export type TooltipTriggerProps = HTMLAttributes<HTMLElement> & {
+  ref?: Ref<HTMLElement>
+}
+
+const TOOLTIP_SURFACE_STYLE: CSSProperties = {
+  background: 'rgb(var(--popover))',
+  color: 'rgb(var(--popover-foreground))',
+  border: '1px solid rgb(var(--border))',
+  boxShadow: 'var(--shadow-md)',
+  borderRadius: 'var(--radius-sm)',
+  padding: 'var(--space-1) var(--space-2)',
+}
+
+export function Tooltip({
+  content,
+  children,
+  side = 'top',
+  align = 'center',
+  offset = 6,
+  openDelay = 300,
+  closeDelay = 0,
+  open: openProp,
+  defaultOpen,
+  onOpenChange,
+  className,
+}: TooltipProps) {
+  const [uncontrolledOpen, setUncontrolledOpen] = useState(Boolean(defaultOpen))
+  const isControlled = openProp !== undefined
+  const open = isControlled ? Boolean(openProp) : uncontrolledOpen
+  const setOpen = useCallback(
+    (next: boolean) => {
+      if (!isControlled) setUncontrolledOpen(next)
+      onOpenChange?.(next)
+    },
+    [isControlled, onOpenChange],
+  )
+
+  const triggerRef = useRef<HTMLElement | null>(null)
+  const tipRef = useRef<HTMLDivElement | null>(null)
+  const timerRef = useRef<number | null>(null)
+  // Set on pointerdown, cleared on the next pointerup / pointercancel
+  // anywhere: a focus that arrives during that window came from the pointer,
+  // not the keyboard. The document listener is held in a ref so an
+  // interrupted press (unmount mid-press, a second pointerdown) removes it
+  // rather than leaving a stale closure on document.
+  const pointerDownRef = useRef(false)
+  const pressEndListenerRef = useRef<(() => void) | null>(null)
+  const clearPressEndListener = useCallback(() => {
+    const listener = pressEndListenerRef.current
+    if (listener === null) return
+    pressEndListenerRef.current = null
+    document.removeEventListener('pointerup', listener)
+    document.removeEventListener('pointercancel', listener)
+  }, [])
+  useEffect(() => clearPressEndListener, [clearPressEndListener])
+
+  const tipId = `tooltip-${useId().replace(/[^a-zA-Z0-9_-]/g, '')}`
+
+  const clearTimer = useCallback(() => {
+    if (timerRef.current !== null) {
+      window.clearTimeout(timerRef.current)
+      timerRef.current = null
+    }
+  }, [])
+  useEffect(() => clearTimer, [clearTimer])
+
+  const scheduleOpen = useCallback(
+    (delay: number) => {
+      clearTimer()
+      if (delay <= 0) {
+        setOpen(true)
+        return
+      }
+      timerRef.current = window.setTimeout(() => {
+        timerRef.current = null
+        setOpen(true)
+      }, delay)
+    },
+    [clearTimer, setOpen],
+  )
+  const scheduleClose = useCallback(
+    (delay: number) => {
+      clearTimer()
+      if (delay <= 0) {
+        setOpen(false)
+        return
+      }
+      timerRef.current = window.setTimeout(() => {
+        timerRef.current = null
+        setOpen(false)
+      }, delay)
+    },
+    [clearTimer, setOpen],
+  )
+
+  const {
+    ref: positionRef,
+    style: positionStyle,
+    placement,
+    positioned,
+  } = useAnchoredPosition<HTMLDivElement>({
+    anchorRef: triggerRef,
+    side,
+    align,
+    offset,
+    enabled: open,
+  })
+
+  useLayer({
+    enabled: open,
+    kind: 'popover',
+    elementRef: tipRef,
+    onEscape: () => {
+      clearTimer()
+      setOpen(false)
+    },
+  })
+
+  const tipRefs = useMemo(
+    () => composeRefs<HTMLDivElement>(tipRef, positionRef),
+    [positionRef],
+  )
+
+  if (!isValidElement<TooltipTriggerProps>(children)) {
+    throw new Error('Tooltip expects exactly one element child to use as its trigger.')
+  }
+  if (content === null || content === undefined || content === false) return children
+
+  const childProps = children.props
+  const describedBy = open
+    ? [childProps['aria-describedby'], tipId].filter(Boolean).join(' ')
+    : childProps['aria-describedby']
+
+  const trigger = cloneElement(children, {
+    ref: composeRefs<HTMLElement>(childProps.ref, triggerRef),
+    'aria-describedby': describedBy,
+    onPointerEnter: (event: ReactPointerEvent<HTMLElement>) => {
+      childProps.onPointerEnter?.(event)
+      // Touch has no hover; a long-press tooltip is a different pattern.
+      if (event.pointerType === 'touch') return
+      scheduleOpen(openDelay)
+    },
+    onPointerLeave: (event: ReactPointerEvent<HTMLElement>) => {
+      childProps.onPointerLeave?.(event)
+      scheduleClose(closeDelay)
+    },
+    onPointerDown: (event: ReactPointerEvent<HTMLElement>) => {
+      childProps.onPointerDown?.(event)
+      pointerDownRef.current = true
+      clearPressEndListener()
+      const onPressEnd = () => {
+        pointerDownRef.current = false
+        clearPressEndListener()
+      }
+      pressEndListenerRef.current = onPressEnd
+      document.addEventListener('pointerup', onPressEnd)
+      document.addEventListener('pointercancel', onPressEnd)
+      // Pressing the trigger is the user acting on it; the label is in the way.
+      clearTimer()
+      setOpen(false)
+    },
+    onFocus: (event: ReactFocusEvent<HTMLElement>) => {
+      childProps.onFocus?.(event)
+      if (pointerDownRef.current) return
+      scheduleOpen(0)
+    },
+    onBlur: (event: ReactFocusEvent<HTMLElement>) => {
+      childProps.onBlur?.(event)
+      scheduleClose(0)
+    },
+  })
+
+  return (
+    <>
+      {trigger}
+      {open && typeof document !== 'undefined'
+        ? createPortal(
+            <div
+              ref={tipRefs}
+              id={tipId}
+              role="tooltip"
+              data-slot="tooltip"
+              data-state="open"
+              data-side={placement?.side}
+              data-align={placement?.align}
+              data-positioned={positioned ? 'true' : 'false'}
+              className={cn(
+                'pointer-events-none fixed z-[110] max-w-xs text-xs font-medium leading-snug',
+                positioned && 'ds-enter-pop',
+                className,
+              )}
+              style={{ ...positionStyle, ...TOOLTIP_SURFACE_STYLE }}
+            >
+              {content}
+            </div>,
+            document.body,
+          )
+        : null}
+    </>
+  )
+}

package/src/react-syntax-highlighter-prism.d.ts

@@ -1,34 +0,0 @@
-// Bridges a conflict between two resolvers, neither of which is wrong.
-//
-// `@types/react-syntax-highlighter` declares the DIRECTORY module
-// `react-syntax-highlighter/dist/esm/styles/prism`. Node's ESM resolver refuses
-// a directory import and needs the explicit `.../prism/index.js`. So the
-// specifier TypeScript can type is the one Node rejects, and the specifier Node
-// accepts is the one TypeScript cannot find — see the note in `code-block.tsx`
-// for what that cost.
-//
-// This declares the file path by RE-EXPORTING the real types from the directory
-// module, so the values stay fully typed. The alternative — a `@ts-expect-error`
-// or an `any` import — would silence the error by discarding `oneLight` and
-// `vscDarkPlus`'s types, which is trading a build failure for a typing hole at
-// the one site that already proved it can ship broken.
-//
-// ── AND THE SAME APPLIES TO THE 13 LANGUAGE IMPORTS ─────────────────────────
-// Fixing only the styles directory shipped `0.0.8`, which failed on
-// `.../languages/prism/bash` — a FILE imported without its extension, which
-// Node's ESM resolver also refuses. The directory import was merely the FIRST
-// failure, not the defect. Caught by loading the published artifact under Node
-// rather than trusting the local build, which is the whole of PN-015.
-//
-// Removable when upstream's types declare the file paths directly.
-declare module 'react-syntax-highlighter/dist/esm/styles/prism/index.js' {
-  export * from 'react-syntax-highlighter/dist/esm/styles/prism';
-}
-
-declare module 'react-syntax-highlighter/dist/esm/languages/prism/*.js' {
-  // Upstream types these as `any`-shaped syntax definitions passed straight to
-  // `registerLanguage`; the wildcard keeps that contract rather than inventing
-  // a stricter one this package cannot verify.
-  const language: unknown;
-  export default language;
-}