@lovett/ui 0.0.1

package/src/index.ts

@@ -0,0 +1,372 @@
+// @lovett/ui — public exports.
+//
+// The set below is the contract from ADR-008 Decision 3 plus the toast
+// surface (Decision 5). Nothing else lands here without an ADR
+// promotion. Apps consume via `import { Button, toast } from '@lovett/ui'`.
+//
+// CSS surface (apps import these alongside the JS):
+//   `@lovett/ui/tokens.css` — the token vocabulary
+//   `@lovett/ui/styles.css` — component CSS the primitives render through
+
+export { default as Card, IconTile, TagRow } from './card'
+export { Button, type ButtonProps, type ButtonVariant, type ButtonSize, type ButtonShape } from './button'
+export { ButtonGroup, type ButtonGroupProps } from './button-group'
+export { Input, type InputProps, type InputSize } from './input'
+export { Textarea, type TextareaProps } from './textarea'
+export { default as Modal } from './modal'
+export {
+  FloatingDrawer,
+  DetailSection,
+  type FloatingDrawerProps,
+} from './floating-drawer'
+export { default as BrandLogoTile, type BrandLogoTileProps, type BrandLogoTileSize } from './brand-logo-tile'
+export { default as ProfileSection, type ProfileSectionProps } from './profile-section'
+export { default as ChipNav, type ChipNavItem } from './chip-nav'
+export { default as CompletionRing, type CompletionRingProps } from './completion-ring'
+export { default as Choropleth, type ChoroplethProps } from './choropleth'
+export {
+  default as PageShell,
+  AppScroll,
+  PageHeaderHost,
+  PageHeaderSlotProvider,
+  type Crumb,
+} from './page-shell'
+export { Toaster, toast } from './toast'
+
+// Brand-profile atoms — promoted in Phase 2b (ADR-010 Decision 3). Section
+// files across the brand-profile lens (and later sibling lenses) import
+// these from `@lovett/ui` rather than a local `./atoms`.
+export {
+  SectionLabel,
+  IdentityLabel,
+  IdentityValue,
+  TextInput,
+  TextareaInput,
+  EmptyPlaceholder,
+  ListItem,
+} from './atoms'
+
+// Sortable primitives — promoted in Phase 2b (ADR-010 Decision 5). Wraps
+// @dnd-kit/core + sortable + utilities (CLAUDE.md §1 amendment in same phase).
+export { SortableList, SortableItem, DragHandle } from './sortable'
+
+// EmptyState — promoted post-phase-15 (ADR-019). 4-consumer trigger:
+// Products / Personas / Competitors / Assets lenses all forked their own
+// full-area empty-state pattern. Canonical shape derived from the Phase
+// 15 Assets implementation. Distinct from EmptyPlaceholder (atoms.tsx),
+// which is the in-card dashed-border variant for brand-profile sections.
+export { EmptyState, type EmptyStateProps } from './empty-state'
+
+// Form primitives promoted post-utility-tools-batch-1 (ADR-029). The
+// 4 lens-local tinted-card-with-input forks (Convert Case, Text
+// Formatter, Replace/Dedupe modals) consolidated into OptionTile.
+// Radio + RadioGroup for stand-alone radios outside the tile context.
+export { Radio, RadioGroup, type RadioProps, type RadioGroupProps } from './radio'
+export {
+  OptionTile,
+  OptionTileGroup,
+  type OptionTileProps,
+  type OptionTileGroupProps,
+} from './option-tile'
+
+// Phase 3a/3b/3c/8/12 batch promotions (ADRs 020-024) — shipped via
+// pre-batch coordination commit per ADR-023 D20. Each primitive has
+// 2+ committed consumers across the batch.
+export { MetricCard, type MetricCardProps, type MetricCardTone } from './metric-card'
+export { ProgressBar, type ProgressBarProps } from './progress-bar'
+export { StepLoader, type StepLoaderProps, type StepLoaderStep } from './step-loader'
+export { Badge, type BadgeProps, type BadgeTone } from './badge'
+export { StatsGrid, type StatsGridProps } from './stats-grid'
+export {
+  SortableTable,
+  type SortableTableProps,
+  type Column as SortableTableColumn,
+} from './sortable-table'
+export { Pagination, type PaginationProps } from './pagination'
+export { Tabs, type TabsProps, type Tab } from './tabs'
+export { PillButton, type PillButtonProps } from './pill-button'
+
+// DataGrid + supporting primitives — intaked from gray-ui-csm under
+// MIT per ADR-025 (first external-component intake under
+// SPEC-DEV-FOR-WORKSPACE §8). DropdownMenu trigger inherits the
+// secondary Button visual per ADR-026 D4 (DQ-4 LIFT).
+export { Checkbox, type CheckboxProps } from './checkbox'
+export {
+  DropdownMenu,
+  DropdownMenuTrigger,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuCheckboxItem,
+  DropdownMenuSeparator,
+  DropdownMenuLabel,
+  DropdownMenuGroup,
+  type DropdownMenuProps,
+  type DropdownMenuTriggerProps,
+  type DropdownMenuContentProps,
+  type DropdownMenuItemProps,
+  type DropdownMenuCheckboxItemProps,
+  type DropdownMenuLabelProps,
+} from './dropdown-menu'
+export {
+  DataGrid,
+  DataGridColumnOptionsMenu,
+  DataGridDragOverlay,
+  DataGridDropIndicator,
+  type DataGridColumn,
+  type DataGridDrawerPanelProps,
+  type DataGridProps,
+  type DataGridRowBase,
+  type DataGridSortState,
+  type DataGridToolbarRenderProps,
+  type DataGridIcon,
+  type EditingCell,
+} from './data-grid'
+
+// DropdownButton — Button-styled trigger + rich popover menu. Composed
+// over <DropdownMenu> primitives. First consumer: Keywords dashboard's
+// "New Keyword Plan" CTA (Set/Group picker). Reusable across other
+// lenses with a multi-create CTA pattern.
+export {
+  DropdownButton,
+  type DropdownButtonProps,
+  type DropdownButtonItem,
+} from './dropdown-button'
+
+// Accordion — controlled collapsible-section group. Compound:
+// Accordion + Accordion.Section. First consumer: SEM Spec "New
+// campaign spec" form (ADR-033).
+export {
+  Accordion,
+  type AccordionProps,
+  type AccordionSectionProps,
+} from './accordion'
+
+// MenuButton — toolbar-style dropdown for menu-bar affordances (File /
+// Edit). Transparent trigger + compact action rows. Composed over
+// <DropdownMenu>. First consumer: utility-tool workbench header
+// (ADR-031).
+export {
+  MenuButton,
+  type MenuButtonProps,
+  type MenuButtonItem,
+  type MenuButtonEntry,
+  type MenuButtonSeparator,
+} from './menu-button'
+
+// CopyField — input/output field with a copy button pinned top-right.
+// Owns the copy interaction (clipboard + ✓ feedback + toast). First
+// consumer: utility-tool workbench body (ADR-031). Reusable anywhere a
+// field's contents need a one-click copy.
+export { CopyField, type CopyFieldProps } from './copy-field'
+
+// TagChipInput — chips + autocomplete + type-to-create. First consumers:
+// Keywords NewSetPage + NewGroupPage. Reusable anywhere a multi-tag
+// input is needed.
+export { TagChipInput, type TagChipInputProps } from './tag-chip-input'
+
+// FolderTreePicker — dropdown picker over a nestable folder tree with
+// optional inline-create. Generic shape (`{ id, name, parentId }`) so
+// any folder-like data structure can use it. First consumers: Keywords
+// NewSetPage + NewGroupPage.
+export {
+  FolderTreePicker,
+  type FolderTreeNode,
+  type FolderTreePickerProps,
+} from './folder-tree-picker'
+
+// HeroFormCard — centered hero-layout form scaffold (eyebrow + title +
+// subtitle + body card + footer). Compound sub-components: Section,
+// Field, FieldRow, Banner, Advanced, Footer. Icon-agnostic — consumers
+// pass any Lucide / custom node as `icon`. First consumers: Keywords
+// NewSetPage + NewGroupPage. Reusable for SEM Spec input + other
+// centered create / config flows.
+export {
+  HeroFormCard,
+  type HeroFormCardProps,
+  type HeroFormCardSectionProps,
+  type HeroFormCardFieldProps,
+  type HeroFormCardBannerProps,
+  type HeroFormCardAdvancedProps,
+} from './hero-form-card'
+
+// RangeSlider — dual-thumb numeric range selector built on two
+// stacked native range inputs. First consumer: Keywords filter bar
+// (Volume + Avg CPC range filters).
+export { RangeSlider, type RangeSliderProps } from './range-slider'
+
+// SegmentedPill — segmented control with outlined-accent active state.
+// Generic items shape so any small mutually-exclusive choice can use
+// it. First consumer: Keywords lens research-mode picker.
+export {
+  SegmentedPill,
+  type SegmentedPillProps,
+  type SegmentedPillItem,
+} from './segmented-pill'
+
+// Shell — multi-tray framed-card pattern. Outer slate frame holds one
+// or more white inner trays. Each tray has a rich header (title +
+// meta + optional accent numeral), body (form/grid/flush spacing
+// variants), and optional recessed footer strip (secondary controls
+// left, primary action right). First consumers: 5 utility tools
+// (Dedupe / Combine / Replace / ConvertCase / TextFormatter) and the
+// New Set / New Group pages.
+export {
+  Shell,
+  ShellStat,
+  type ShellProps,
+  type ShellTrayProps,
+  type ShellTrayHeaderProps,
+  type ShellTrayBodyProps,
+  type ShellTrayFooterProps,
+  type ShellSubCardProps,
+  type ShellStatProps,
+  type ShellStatTone,
+} from './shell'
+
+// FolderCard — drive-style folder tile (colour-keyed swatch + name +
+// count + hover checkbox / menu slot). Promoted in ADR-035 (Assets
+// lens redesign); a card surface, so it owns the internal surface
+// tokens as a primitive. Reusable by the v1.1 Swipes / Collections
+// lenses (PRD §5.6).
+export {
+  FolderCard,
+  FOLDER_COLOR_KEYS,
+  folderColorVar,
+  type FolderCardProps,
+  type FolderColorKey,
+} from './folder-card'
+
+// BulkActionBar — floating bottom-centred selection action bar.
+// Promoted in ADR-035 — two consumers (Assets page + Manage Folders
+// page). Owns the shell; callers pass their own action buttons.
+export { BulkActionBar, type BulkActionBarProps } from './bulk-action-bar'
+
+// File-upload subtree — promoted from brand-ai-extension (ADR-036 D20).
+// D14 fix: uploadUrl + authHeaders are caller-supplied; the primitive never
+// reads import.meta.env or hardcodes a URL.
+export {
+  FileUploadButton,
+  FileDropZone,
+  FilePreviewGrid,
+  FilePreviewItem,
+  FileThumbnail,
+  useFileUpload,
+  type PendingFile,
+  type UploadResult,
+  type UseFileUploadOptions,
+} from './file-upload/index'
+
+// CodeBlock + MarkdownCode — syntax-highlighted code block and react-markdown
+// code element adapter. Promoted from brand-ai-extension (ADR-036 D20).
+export { CodeBlock, MarkdownCode, type CodeBlockProps } from './code-block'
+
+// MarkdownRenderer — full markdown surface with GFM support (headings, lists,
+// code via CodeBlock, tables, task lists, links). Promoted from
+// brand-ai-extension chat-message.tsx (ADR-036 D20, BUILD_FRESH extraction).
+export { MarkdownRenderer, type MarkdownRendererProps } from './markdown'
+
+// ResizableHandle — pointer-driven splitter with WAI-ARIA splitter a11y.
+// Promoted from the Generate lens's local mouse-event resize per
+// ADR-049 D8/D9 (ADR-008 D3 2+ consumer gate: Generate lens + sidebar
+// pinned-panel resize). ResizablePane is an optional thin <aside> wrapper.
+export {
+  ResizableHandle,
+  ResizablePane,
+  type ResizableHandleProps,
+  type ResizablePaneProps,
+} from './resizable'
+
+// Kbd — semantic keyboard-input chip. Promoted post-ADR-050 D11 — 3+
+// committed consumers (Chat title chip, palette body + footer, sidebar
+// switcher-popout Esc hint). Renders <kbd> with sm/md size variants.
+export { Kbd, type KbdProps } from './kbd'
+
+// FrameStack — slate outer-frame wrapper for the shell/tray pattern.
+// Wraps 2+ Card / SectionCard children as ONE visual group with 10 px
+// padding + 10 px gap. Dedicated single-purpose primitive (avoids the
+// "Shell" name collision with the lens-shell + the data-framed div).
+// See `frame-stack.tsx` docstring for the visual diagram. Lens-level
+// lock: Meta Creative `CLAUDE.md` §"The shell/tray pattern".
+export { FrameStack, type FrameStackProps } from './frame-stack'
+
+// CalculatorShell — centered, fixed-width layout primitive for marketing
+// / ad-performance / customer-economics calculators. Promoted under
+// ADR-058 D8 (sharpens ADR-030 D2/D3/D5/D6/D8). First-day consumers
+// (ADR-008 D3 gate cleared 3×): ROAS / ROI / CTR / CPC / CPM /
+// Conversion Rate. The shell is presentational; each calculator route
+// owns its `useState` and computes `result` reactively.
+export { CalculatorShell, type CalculatorShellProps } from './calculator-shell'
+
+// Calculator Shell v2 kit (ADR-076). Additive — v1 above is retained for
+// the existing six math calculators. v2 = a superset shell with two
+// layouts + a flat brand-ink header, the StatRow signature primitive, and
+// a single-value Slider. Frame = ProfileSection (reused, D3); KPI chips =
+// MetricCard labelPosition="top" (D8). First consumer: /tools/ctv-frequency.
+export {
+  CalculatorShellV2,
+  type CalculatorShellV2Props,
+  type CalcLayout,
+  type CalcPrefill,
+} from './calculator-shell-v2'
+export { StatRow, type StatRowProps, type StatRowStep } from './stat-row'
+export { Slider, type SliderProps } from './slider'
+
+// Number-formatting helpers — `formatCurrency` / `formatPercent` /
+// `formatRatio` / `formatNumber`. Pure functions, zero deps (built on
+// `Intl.NumberFormat`). Spec'd in ADR-030 D6 and re-exported here per
+// ADR-058 D8 so calculator routes consume the shell + helpers from a
+// single `@lovett/ui` import. All four return `'—'` on NaN / ±Infinity
+// so partial-input UI never crashes.
+export { formatCurrency, formatPercent, formatRatio, formatNumber } from './format'
+
+// Shared utilities — used by primitives, also re-exported for app/lens code
+// that needs the same class-composition or layout numerics (e.g. Phase 2's
+// brand-profile atoms when they promote into packages/ui/).
+export { cn } from './lib/utils'
+export { HEADER_HEIGHT, SECTION_SCROLL_OFFSET } from './lib/layout'
+
+// v1.1 lens-port-batch promotions (Phase A pre-pass). 3+ consumers each
+// in the v1.1 batch (Swipes / Collections / Discover / Prompts). Source:
+// `brand-ai-extension/webapp/src/components/ui/` — same shape, tokens
+// scrubbed to use --foreground / --text-tertiary / public surfaces only
+// where the original used --text-muted (still allowed inside packages/ui).
+export { PageHero, type PageHeroProps } from './page-hero'
+export { SearchBar, type SearchBarProps } from './search-bar'
+export {
+  FilterBar,
+  type FilterBarProps,
+  type FilterBarSearchProps,
+  type FilterBarCountProps,
+} from './filter-bar'
+export {
+  FilterDropdown,
+  type FilterDropdownProps,
+  type FilterOption,
+} from './filter-dropdown'
+
+// Meta / Instagram platform previews — promoted from
+// docs/prototype/meta/preview-package/ per ADR-060 D9a (amended
+// 2026-05-28). Pixel-accurate FB+IG+Messenger renderers; zero coupling
+// to stores/hooks/routers. Consumed by the Meta Creative lens's
+// PreviewRail; available for future Meta-related lenses (the D9a
+// promotion rationale). Namespace import keeps the 10 platform-named
+// components out of the root `@lovett/ui` export.
+// DeviceFrame — generic, content-agnostic device bezel (macOS Safari
+// window or iPhone). Genericized/promoted from the sem-spec source app's
+// SerpCard MacOSFrame + IPhoneFrame (all Google/SERP specifics stripped).
+// Device-replica chrome colors are owned by the primitive (like the
+// platform-chrome allowlist), not the theme palette. First reuse target:
+// AdStage. Ratified by ADR-087 (accepted 2026-06-07); sem-spec retrofit is a
+// tracked follow-up in that ADR.
+export { DeviceFrame, type DeviceFrameProps } from './device-frame'
+
+export * as MetaPreviews from './meta-previews'
+export type {
+  PreviewAdData,
+  PreviewPlatform,
+  PreviewPlacement,
+  PreviewDevice,
+  PlacementPreview,
+  PreviewConfiguration,
+} from './meta-previews/types'
+export { PLACEMENT_CONFIGS } from './meta-previews/types'

package/src/input.tsx

@@ -0,0 +1,130 @@
+/**
+ * Input — typed text input wrapped in the .input-shell from styles.css.
+ * Supports leading/trailing affixes (icon, badge, action button), three
+ * sizes (sm 32 / md 40 / lg 48), and the standard error/disabled states.
+ *
+ *   <Input value={v} onChange={e => setV(e.target.value)} placeholder="Search…" />
+ *
+ *   <Input
+ *     leadingAffix={<Search className="h-4 w-4" />}
+ *     trailingAffix={<KeyboardShortcut keys="⌘K" />}
+ *     placeholder="Type to search"
+ *   />
+ *
+ *   <Input error placeholder="Invalid" />
+ *
+ *   <Input
+ *     type="password"
+ *     showPasswordToggle
+ *     autoComplete="current-password"
+ *   />
+ */
+import {
+  forwardRef,
+  useState,
+  type InputHTMLAttributes,
+  type ReactNode,
+} from 'react'
+import { Eye, EyeOff } from 'lucide-react'
+import { cn } from './lib/utils'
+
+export type InputSize = 'sm' | 'md' | 'lg'
+
+export interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'prefix'> {
+  inputSize?: InputSize
+  error?: boolean
+  /** Element rendered before the input — typically an icon. Static, no interaction. */
+  leadingAffix?: ReactNode
+  /** Element rendered after the input. Pass an `<button class="affix action">` for clickable. */
+  trailingAffix?: ReactNode
+  /** Override classes on the .input-shell wrapper. */
+  shellClassName?: string
+  /**
+   * Show/hide affordance for `type="password"`. Manages visibility state
+   * internally and renders an Eye/EyeOff toggle in the trailing affix slot.
+   * No-op when `type !== "password"`. Caller-supplied `trailingAffix`
+   * wins — the toggle is only injected when the slot is otherwise empty.
+   */
+  showPasswordToggle?: boolean
+  /**
+   * Numeric variant (ADR-076 D8) — renders the field in the monospace
+   * face with `tabular-nums` so digits align as the value changes.
+   * Pair with the existing `leadingAffix` (e.g. a `$`) / `trailingAffix`
+   * (e.g. a unit suffix) for calculator inputs. No new prefix/suffix
+   * props — affixes are the canonical adornment slots.
+   */
+  numeric?: boolean
+}
+
+const SIZE_CLASS: Record<InputSize, string> = {
+  sm: 'size-sm',
+  md: '',
+  lg: 'size-lg',
+}
+
+export const Input = forwardRef<HTMLInputElement, InputProps>(function Input(
+  {
+    inputSize = 'md',
+    error,
+    leadingAffix,
+    trailingAffix,
+    shellClassName,
+    className,
+    disabled,
+    type,
+    showPasswordToggle,
+    numeric,
+    ...rest
+  },
+  ref,
+) {
+  const [revealed, setRevealed] = useState(false)
+  const isPasswordToggle =
+    showPasswordToggle === true && type === 'password' && !trailingAffix
+  const resolvedType = isPasswordToggle && revealed ? 'text' : type
+  const resolvedTrailingAffix = isPasswordToggle ? (
+    <button
+      type="button"
+      onClick={() => setRevealed((v) => !v)}
+      aria-label={revealed ? 'Hide password' : 'Show password'}
+      aria-pressed={revealed}
+      className="affix action"
+      tabIndex={-1}
+    >
+      {revealed ? (
+        <EyeOff className="h-4 w-4" aria-hidden />
+      ) : (
+        <Eye className="h-4 w-4" aria-hidden />
+      )}
+    </button>
+  ) : (
+    trailingAffix
+  )
+
+  return (
+    <div
+      className={cn(
+        'input-shell',
+        SIZE_CLASS[inputSize],
+        numeric && 'is-numeric',
+        leadingAffix && 'has-leading',
+        resolvedTrailingAffix && 'has-trailing',
+        error && 'is-error',
+        disabled && 'is-disabled',
+        shellClassName,
+      )}
+    >
+      {leadingAffix && <span className="affix">{leadingAffix}</span>}
+      <input
+        ref={ref}
+        type={resolvedType}
+        disabled={disabled}
+        className={className}
+        {...rest}
+      />
+      {resolvedTrailingAffix && (
+        <span className="affix">{resolvedTrailingAffix}</span>
+      )}
+    </div>
+  )
+})

package/src/kbd.tsx

@@ -0,0 +1,41 @@
+/**
+ * Kbd — semantic keyboard-input chip.
+ *
+ * Promoted from the Chat lens's inline title-chip markup per ADR-050 D11.
+ * Committed consumers (ADR-008 D3 promotion gate):
+ *   • Chat lens title-bar chip (apps/workspace/src/lenses/chat/index.tsx) —
+ *     first migrated consumer, lands in this phase.
+ *   • Command palette body / footer hints (ADR-050 Phases B–E).
+ *   • Sidebar switcher-popout Esc hint (ADR-049 Phase C).
+ *
+ * Renders a `<kbd>` semantic element (screen readers announce as keyboard
+ * input). Token-driven styling — no hex literals, all colors flow through
+ * public tokens.
+ */
+
+import type { ReactNode, CSSProperties } from 'react'
+
+export interface KbdProps {
+  /** Child text — typically a single key glyph or short string. */
+  children: ReactNode
+  /** Optional size — defaults to 'md'. */
+  size?: 'sm' | 'md'
+}
+
+export function Kbd({ children, size = 'md' }: KbdProps) {
+  const style: CSSProperties = {
+    display: 'inline-flex',
+    alignItems: 'center',
+    justifyContent: 'center',
+    gap: '0.125rem',
+    background: 'rgb(var(--surface-overlay-soft))',
+    border: '1px solid rgb(var(--border))',
+    color: 'rgb(var(--text-tertiary))',
+    fontFamily: 'var(--font-mono)',
+    fontSize: size === 'sm' ? '10.5px' : '11.5px',
+    padding: size === 'sm' ? '1px 6px' : '2px 8px',
+    borderRadius: 'var(--radius-xs)',
+    lineHeight: 1,
+  }
+  return <kbd style={style}>{children}</kbd>
+}

package/src/lib/layout.ts

@@ -0,0 +1,22 @@
+/**
+ * Layout constants shared between CSS and JS.
+ *
+ * Some primitives (e.g. ChipNav) need numeric pixel values for
+ * `IntersectionObserver` rootMargin or `position: sticky` `top` style
+ * — those can't read from CSS custom properties. To keep the layout
+ * coherent, this module mirrors the canonical values from `tokens.css`.
+ * If you change one, change the other.
+ *
+ * The corresponding CSS tokens are:
+ *   --header-height          → HEADER_HEIGHT
+ *   --section-scroll-offset  → SECTION_SCROLL_OFFSET
+ */
+
+/** Height of the sticky AppHeader, in px. Mirrors `--header-height`. */
+export const HEADER_HEIGHT = 56
+
+/**
+ * Vertical offset for in-page section anchors (header + chip nav +
+ * breathing room). Mirrors `--section-scroll-offset`.
+ */
+export const SECTION_SCROLL_OFFSET = 120

package/src/lib/utils.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from 'clsx'
+import { twMerge } from 'tailwind-merge'
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}