@lovett/ui 0.0.1

package/src/page-shell.tsx

@@ -0,0 +1,440 @@
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  type ReactNode,
+  type RefObject,
+} from 'react'
+import { createPortal } from 'react-dom'
+import { Link } from 'react-router-dom'
+import { cn } from './lib/utils'
+
+export type Crumb = {
+  label: string
+  to?: string
+}
+
+interface PageShellProps {
+  /** Breadcrumb chain — last item renders as the bold current label.
+   *  For back-compat, `breadcrumb` + `title` are still accepted. */
+  crumbs?: Crumb[]
+  /** Legacy convenience: single parent crumb (label only). */
+  breadcrumb?: string
+  /** Legacy: current-page title. Used as the last crumb when `crumbs` isn't provided. */
+  title?: string
+  /** Right-side actions in the page header. */
+  actions?: ReactNode
+  /**
+   * Content for the horizontally-centered slot in `<PageHeaderHost />`
+   * (Phase 7a). Relayed via the slot portal alongside `crumbs` /
+   * `actions`. When mounted in slot-host mode, the content sits in a
+   * dedicated absolutely-centered slot between the breadcrumb cluster
+   * and the trailing chrome, so it stays centered regardless of left/
+   * right slot widths. Ignored when PageShell renders its own inline
+   * header (no `<PageHeaderHost />` mounted).
+   *
+   * Phase 7a's GeoSearch lens lifts its mode-tabs ChipNav into this
+   * slot so the AppHeader carries: sidebar-toggle | crumbs | tabs |
+   * theme-toggle. Other lenses leave it unset.
+   */
+  headerCenter?: ReactNode
+  children: ReactNode
+  /** Override content padding if needed. Default leaves room for the sticky-blend header. */
+  contentClassName?: string
+}
+
+// ---------------------------------------------------------------------------
+// PageHeaderSlot — optional "publish to host" mode (portal-based).
+//
+// By default, PageShell renders its own sticky header band with breadcrumbs +
+// actions. When the app wraps the tree in <PageHeaderSlotProvider> AND mounts
+// a <PageHeaderHost /> elsewhere, PageShell PORTALS its breadcrumbs/actions
+// into the host's slot div, and skips rendering its own header band. That
+// collapses what would be two stacked sticky bars into a single bar.
+//
+// Portal-based to avoid any state churn on the publish path — only the host
+// DOM ref + the active scroll element are stored in context (each set once
+// per mount, never per render).
+// ---------------------------------------------------------------------------
+
+interface PageHeaderSlotValue {
+  hostEl: HTMLElement | null
+  centerEl: HTMLElement | null
+  scrollEl: HTMLElement | null
+  registerHost: (el: HTMLElement | null) => void
+  registerCenter: (el: HTMLElement | null) => void
+  registerScroll: (el: HTMLElement | null) => void
+}
+
+const PageHeaderSlotContext = createContext<PageHeaderSlotValue | null>(null)
+
+export function PageHeaderSlotProvider({ children }: { children: ReactNode }) {
+  const [hostEl, setHostEl] = useState<HTMLElement | null>(null)
+  const [centerEl, setCenterEl] = useState<HTMLElement | null>(null)
+  const [scrollEl, setScrollEl] = useState<HTMLElement | null>(null)
+  const registerHost = useCallback((el: HTMLElement | null) => setHostEl(el), [])
+  const registerCenter = useCallback(
+    (el: HTMLElement | null) => setCenterEl(el),
+    [],
+  )
+  const registerScroll = useCallback((el: HTMLElement | null) => setScrollEl(el), [])
+  return (
+    <PageHeaderSlotContext.Provider
+      value={{
+        hostEl,
+        centerEl,
+        scrollEl,
+        registerHost,
+        registerCenter,
+        registerScroll,
+      }}
+    >
+      {children}
+    </PageHeaderSlotContext.Provider>
+  )
+}
+
+/**
+ * Page shell — promoted from brand-ai-extension Phase 2a (ADR-009 Decision 7).
+ *
+ * Self-contained: provides a scrollable region whose sticky-blend header
+ * gains a translucent backdrop-blur background once you scroll past a few
+ * px. Breadcrumbs render at top-left, page actions at top-right.
+ *
+ * When mounted inside <PageHeaderSlotProvider> with a <PageHeaderHost />
+ * elsewhere, PageShell portals its header content into the host instead of
+ * rendering its own bar — the workspace uses this to merge the lens crumbs
+ * onto the same row as the workspace sidebar toggle.
+ */
+export function PageShell({
+  crumbs,
+  breadcrumb,
+  title,
+  actions,
+  headerCenter,
+  children,
+  contentClassName,
+}: PageShellProps) {
+  const resolvedCrumbs: Crumb[] =
+    crumbs && crumbs.length > 0
+      ? crumbs
+      : ([
+          breadcrumb ? { label: breadcrumb } : null,
+          title ? { label: title } : null,
+        ].filter(Boolean) as Crumb[])
+
+  const slot = useContext(PageHeaderSlotContext)
+
+  return (
+    <AppScroll>
+      {(scrollRef) => (
+        <PageShellBody
+          resolvedCrumbs={resolvedCrumbs}
+          actions={actions ?? null}
+          headerCenter={headerCenter ?? null}
+          scrollRef={scrollRef}
+          slot={slot}
+          contentClassName={contentClassName}
+        >
+          {children}
+        </PageShellBody>
+      )}
+    </AppScroll>
+  )
+}
+
+function PageShellBody({
+  resolvedCrumbs,
+  actions,
+  headerCenter,
+  scrollRef,
+  slot,
+  contentClassName,
+  children,
+}: {
+  resolvedCrumbs: Crumb[]
+  actions: ReactNode | null
+  headerCenter: ReactNode | null
+  scrollRef: RefObject<HTMLDivElement | null>
+  slot: PageHeaderSlotValue | null
+  contentClassName?: string | undefined
+  children: ReactNode
+}) {
+  // Register our scroll element with the host once when this PageShell
+  // mounts. Unregisters on unmount. Effect runs once because `slot` is a
+  // stable context object (provider memoizes its callbacks) and scrollRef
+  // identity is stable across renders of the same PageShell instance.
+  useEffect(() => {
+    if (!slot) return
+    const el = scrollRef.current
+    if (!el) return
+    slot.registerScroll(el)
+    return () => slot.registerScroll(null)
+  }, [slot, scrollRef])
+
+  const headerContent = (
+    <>
+      <div className="flex items-center gap-2 min-w-0 flex-1">
+        <Breadcrumbs
+          parents={resolvedCrumbs.slice(0, -1)}
+          current={resolvedCrumbs[resolvedCrumbs.length - 1]}
+        />
+      </div>
+      {actions && (
+        <div className="flex items-center gap-1.5 shrink-0">{actions}</div>
+      )}
+    </>
+  )
+
+  return (
+    <>
+      {slot?.hostEl ? (
+        createPortal(headerContent, slot.hostEl)
+      ) : (
+        <PageHeader
+          crumbs={resolvedCrumbs}
+          actions={actions ?? undefined}
+          scrollRef={scrollRef}
+        />
+      )}
+      {/* Header-center relay: portal into the host's center slot when
+         one is mounted. Falls through silently in slot-less mode — the
+         inline `<PageHeader />` doesn't render a centered band. */}
+      {slot?.centerEl && headerCenter
+        ? createPortal(headerCenter, slot.centerEl)
+        : null}
+      <div className={cn(contentClassName ?? 'px-7 pb-7')}>{children}</div>
+    </>
+  )
+}
+
+export default PageShell
+
+interface PageHeaderProps {
+  crumbs: Crumb[]
+  actions?: ReactNode
+  scrollRef: RefObject<HTMLDivElement | null>
+}
+
+function PageHeader({ crumbs, actions, scrollRef }: PageHeaderProps) {
+  const [stuck, setStuck] = useState(false)
+
+  useEffect(() => {
+    const el = scrollRef.current
+    if (!el) return
+    const onScroll = () => setStuck(el.scrollTop > 4)
+    onScroll()
+    el.addEventListener('scroll', onScroll, { passive: true })
+    return () => el.removeEventListener('scroll', onScroll)
+  }, [scrollRef])
+
+  const parents = crumbs.slice(0, -1)
+  const current = crumbs[crumbs.length - 1]
+
+  return (
+    <header
+      className="sticky top-0 z-30 flex items-center gap-3 h-14 px-5"
+      style={{
+        background: stuck ? 'rgb(var(--main-content-bg) / 0.78)' : 'transparent',
+        backdropFilter: stuck ? 'saturate(180%) blur(14px)' : undefined,
+        WebkitBackdropFilter: stuck ? 'saturate(180%) blur(14px)' : undefined,
+        borderBottom: `1px solid ${stuck ? 'rgb(var(--border))' : 'transparent'}`,
+        transition:
+          'background var(--dur-base) var(--ease-out), border-color var(--dur-base) var(--ease-out)',
+      }}
+    >
+      <div className="flex items-center gap-2 min-w-0 flex-1">
+        <Breadcrumbs parents={parents} current={current} />
+      </div>
+      {actions && (
+        <div className="flex items-center gap-1.5 shrink-0">{actions}</div>
+      )}
+    </header>
+  )
+}
+
+/**
+ * PageHeaderHost — single workspace-level header bar that the active
+ * <PageShell> portals its breadcrumbs/actions into. Renders the `leading`
+ * slot (typically a sidebar toggle button) on the same row, so the lens's
+ * chrome doesn't stack as a separate sticky band. The `trailing` slot
+ * sits past the portal area for persistent right-cluster chrome (e.g.
+ * a theme toggle) that should never collide with per-page actions.
+ *
+ * Sticky-blend: subscribes to the scroll container the active PageShell
+ * registered with the slot so the same scroll-past-4px fade-in still fires.
+ */
+export function PageHeaderHost({
+  leading,
+  center,
+  trailing,
+  padX = 'px-3',
+}: {
+  leading?: ReactNode
+  /**
+   * Horizontal padding utility for the header bar. Defaults to `px-3`
+   * (the toggle-anchored layout). Callers with no `leading` slot (e.g. a
+   * single-lens skin that hides the sidebar toggle) pass a larger inset
+   * like `px-7` so the breadcrumbs line up with the content column below
+   * instead of hugging the edge. ADR-061 D3.
+   */
+  padX?: string
+  /**
+   * Horizontally-centered slot — Phase 7a (ADR-012 Decision 12
+   * deviation). Renders absolutely positioned at the geometric center
+   * of the header so width changes in the breadcrumb (left) and
+   * trailing (right) clusters never shift its position. The active
+   * `<PageShell>` may also portal content into this slot via its
+   * `headerCenter` prop; both routes target the same DOM node.
+   *
+   * Wrapped in a `max-w` so on narrow viewports the center stays
+   * within the breadcrumb and trailing clusters' visual lanes
+   * (truncates internally before overlapping).
+   */
+  center?: ReactNode
+  trailing?: ReactNode
+}) {
+  const slot = useContext(PageHeaderSlotContext)
+  const [stuck, setStuck] = useState(false)
+  const scrollEl = slot?.scrollEl ?? null
+
+  useEffect(() => {
+    if (!scrollEl) {
+      setStuck(false)
+      return
+    }
+    const onScroll = () => setStuck(scrollEl.scrollTop > 4)
+    onScroll()
+    scrollEl.addEventListener('scroll', onScroll, { passive: true })
+    return () => scrollEl.removeEventListener('scroll', onScroll)
+  }, [scrollEl])
+
+  const setHostRef = useCallback(
+    (el: HTMLDivElement | null) => {
+      slot?.registerHost(el)
+    },
+    [slot],
+  )
+
+  const setCenterRef = useCallback(
+    (el: HTMLDivElement | null) => {
+      slot?.registerCenter(el)
+    },
+    [slot],
+  )
+
+  return (
+    <header
+      className={cn(
+        'sticky top-0 z-30 flex items-center gap-3 h-12 shrink-0 relative',
+        padX,
+      )}
+      style={{
+        background: stuck ? 'rgb(var(--main-content-bg) / 0.78)' : 'transparent',
+        backdropFilter: stuck ? 'saturate(180%) blur(14px)' : undefined,
+        WebkitBackdropFilter: stuck ? 'saturate(180%) blur(14px)' : undefined,
+        borderBottom: `1px solid ${stuck ? 'rgb(var(--border))' : 'transparent'}`,
+        transition:
+          'background var(--dur-base) var(--ease-out), border-color var(--dur-base) var(--ease-out)',
+      }}
+    >
+      {leading && <div className="shrink-0 flex items-center">{leading}</div>}
+      <div
+        ref={setHostRef}
+        data-page-header-host="true"
+        className="flex items-center gap-3 flex-1 min-w-0"
+      />
+      {/* Absolutely-centered slot — sits above the row's flex flow so
+         it stays geometrically centered regardless of leading/host/
+         trailing widths. `pointer-events-none` on the wrapper so empty
+         space passes clicks through; inner content re-enables. */}
+      <div
+        className="absolute left-1/2 -translate-x-1/2 flex items-center justify-center pointer-events-none"
+        style={{
+          top: 0,
+          bottom: 0,
+          maxWidth: 'min(560px, 56%)',
+        }}
+        aria-hidden={center == null && !slot?.centerEl ? 'true' : undefined}
+      >
+        <div
+          ref={setCenterRef}
+          data-page-header-center="true"
+          className="pointer-events-auto flex items-center gap-2 min-w-0"
+        >
+          {center}
+        </div>
+      </div>
+      {trailing && (
+        <div className="shrink-0 flex items-center gap-1.5">{trailing}</div>
+      )}
+    </header>
+  )
+}
+
+function Breadcrumbs({
+  parents,
+  current,
+}: {
+  parents: Crumb[]
+  current: Crumb | undefined
+}) {
+  return (
+    <nav
+      className="flex items-center gap-1.5 text-[13px] min-w-0"
+      style={{ color: 'rgb(var(--text-tertiary))' }}
+    >
+      {parents.map((c, i) => (
+        <span key={i} className="flex items-center gap-1.5 min-w-0">
+          {c.to ? (
+            <Link
+              to={c.to}
+              className="truncate transition-colors hover:text-[rgb(var(--foreground))]"
+              style={{ color: 'inherit' }}
+            >
+              {c.label}
+            </Link>
+          ) : (
+            <span className="truncate">{c.label}</span>
+          )}
+          <span style={{ color: 'rgb(var(--text-muted))' }}>/</span>
+        </span>
+      ))}
+      {current && (
+        <span
+          className="truncate font-medium"
+          style={{ color: 'rgb(var(--foreground))' }}
+        >
+          {current.label}
+        </span>
+      )}
+    </nav>
+  )
+}
+
+/**
+ * Scrollable wrapper that exposes its scrollRef via a render prop so
+ * the consuming header (PageShell's internal PageHeader) can subscribe
+ * to scroll for the stuck-state effect.
+ */
+export function AppScroll({
+  children,
+  className,
+}: {
+  children: (scrollRef: RefObject<HTMLDivElement | null>) => ReactNode
+  className?: string
+}) {
+  const scrollRef = useRef<HTMLDivElement>(null)
+  return (
+    <div
+      ref={scrollRef}
+      data-app-scroll="true"
+      className={cn('flex-1 overflow-y-auto', className)}
+    >
+      {children(scrollRef)}
+    </div>
+  )
+}

package/src/pagination.tsx

@@ -0,0 +1,86 @@
+/**
+ * Pagination — "Showing X-Y of Z" + prev/next buttons.
+ *
+ * Promoted in ADR-022 (Phase 3c Discovery reports table, first
+ * committed consumer). Cross-batch consumers: Phase 3b contacts
+ * (when >50), Phase 8 keywords table, Phase 12 SEMSpec keywords tab.
+ *
+ * Stateless — parent owns currentPage state and provides onPageChange.
+ *
+ * Token discipline: all colors via public tokens.
+ */
+
+import { ChevronLeft, ChevronRight } from 'lucide-react'
+
+export interface PaginationProps {
+  /** 1-indexed current page. */
+  currentPage: number
+  /** Items per page. */
+  pageSize: number
+  /** Total item count across all pages. */
+  totalItems: number
+  onPageChange: (page: number) => void
+}
+
+export function Pagination({
+  currentPage,
+  pageSize,
+  totalItems,
+  onPageChange,
+}: PaginationProps) {
+  const totalPages = Math.max(1, Math.ceil(totalItems / pageSize))
+  const firstItem = totalItems === 0 ? 0 : (currentPage - 1) * pageSize + 1
+  const lastItem = Math.min(currentPage * pageSize, totalItems)
+  const canPrev = currentPage > 1
+  const canNext = currentPage < totalPages
+
+  if (totalPages <= 1) return null
+
+  return (
+    <div className="flex items-center justify-between gap-3 py-2">
+      <div
+        className="text-[12px] tabular-nums"
+        style={{ color: 'rgb(var(--text-tertiary))' }}
+      >
+        Showing {firstItem.toLocaleString()}–{lastItem.toLocaleString()} of{' '}
+        {totalItems.toLocaleString()}
+      </div>
+      <div className="flex items-center gap-2">
+        <span
+          className="text-[12px] tabular-nums"
+          style={{ color: 'rgb(var(--text-tertiary))' }}
+        >
+          Page {currentPage} of {totalPages}
+        </span>
+        <button
+          type="button"
+          aria-label="Previous page"
+          disabled={!canPrev}
+          onClick={() => onPageChange(currentPage - 1)}
+          className="inline-flex h-7 w-7 items-center justify-center transition-colors disabled:cursor-not-allowed disabled:opacity-40"
+          style={{
+            background: 'rgb(var(--surface-overlay))',
+            color: 'rgb(var(--text-secondary))',
+            borderRadius: 'var(--radius-sm)',
+          }}
+        >
+          <ChevronLeft className="h-4 w-4" />
+        </button>
+        <button
+          type="button"
+          aria-label="Next page"
+          disabled={!canNext}
+          onClick={() => onPageChange(currentPage + 1)}
+          className="inline-flex h-7 w-7 items-center justify-center transition-colors disabled:cursor-not-allowed disabled:opacity-40"
+          style={{
+            background: 'rgb(var(--surface-overlay))',
+            color: 'rgb(var(--text-secondary))',
+            borderRadius: 'var(--radius-sm)',
+          }}
+        >
+          <ChevronRight className="h-4 w-4" />
+        </button>
+      </div>
+    </div>
+  )
+}

package/src/pill-button.tsx

@@ -0,0 +1,103 @@
+/**
+ * PillButton — toggle-able filter pill with active / inactive states.
+ *
+ * Promoted in ADR-024 (Phase 12 SEMSpec keywords + extensions tab
+ * filters, first committed consumer). Cross-batch consumers: Phase 8
+ * Keywords (competition + brand-type filters).
+ *
+ * Distinct from <Badge> (read-only labeled chip) — PillButton is
+ * always clickable and reflects active-state via accent tone.
+ *
+ * Compose 1+ PillButton inside a lens-local <FilterGroup> wrapper
+ * when grouped with a label.
+ *
+ * Token discipline: all colors via public tokens.
+ */
+
+import type { ReactNode } from 'react'
+import type { BadgeTone } from './badge'
+
+const ACTIVE_STYLE: Record<BadgeTone, { bg: string; color: string }> = {
+  neutral: {
+    bg: 'rgb(var(--accent))',
+    color: 'rgb(var(--accent-foreground, 255 255 255))',
+  },
+  accent: {
+    bg: 'rgb(var(--accent))',
+    color: 'rgb(var(--accent-foreground, 255 255 255))',
+  },
+  success: {
+    bg: 'rgb(var(--success))',
+    color: 'rgb(var(--success-bg))',
+  },
+  warning: {
+    bg: 'rgb(var(--warning))',
+    color: 'rgb(var(--warning-bg))',
+  },
+  destructive: {
+    bg: 'rgb(var(--destructive))',
+    color: 'rgb(var(--destructive-foreground))',
+  },
+  info: {
+    bg: 'rgb(var(--info))',
+    color: 'rgb(var(--info-bg))',
+  },
+}
+
+export interface PillButtonProps {
+  active: boolean
+  onClick: () => void
+  children: ReactNode
+  /** Size variant. `sm` = compact (12px), `md` = default (13px). */
+  size?: 'sm' | 'md'
+  /** Optional active-state tone. Default = accent. */
+  tone?: BadgeTone
+  /** Optional leading icon (12-14px). */
+  icon?: ReactNode
+  disabled?: boolean
+}
+
+export function PillButton({
+  active,
+  onClick,
+  children,
+  size = 'md',
+  tone = 'accent',
+  icon,
+  disabled,
+}: PillButtonProps) {
+  const sizeClass = size === 'sm' ? 'text-[12px] px-2.5 h-7' : 'text-[13px] px-3 h-8'
+  const activeStyle = ACTIVE_STYLE[tone]
+
+  return (
+    <button
+      type="button"
+      aria-pressed={active}
+      disabled={disabled}
+      onClick={onClick}
+      className={`inline-flex items-center gap-1.5 font-medium border transition-colors ${sizeClass} ${disabled ? 'cursor-not-allowed opacity-40' : 'cursor-pointer'}`}
+      style={
+        active
+          ? {
+              background: activeStyle.bg,
+              color: activeStyle.color,
+              borderColor: activeStyle.bg,
+              borderRadius: 'var(--radius-full)',
+            }
+          : {
+              background: 'transparent',
+              color: 'rgb(var(--text-secondary))',
+              borderColor: 'rgb(var(--border))',
+              borderRadius: 'var(--radius-full)',
+            }
+      }
+    >
+      {icon && (
+        <span className="flex-shrink-0" aria-hidden>
+          {icon}
+        </span>
+      )}
+      {children}
+    </button>
+  )
+}