@lovett/ui 0.0.1

package/src/format.ts

@@ -0,0 +1,117 @@
+/**
+ * Number-formatting helpers — small set of pure, zero-dep utilities
+ * shared by the `<CalculatorShell>` consumers (ROAS / ROI / CTR / CPC
+ * / CPM / Conversion Rate and the future ad-performance + customer/
+ * business calculators).
+ *
+ * Locked by ADR-030 D6 (the helpers' existence + signatures) and
+ * sharpened by ADR-058 D8 (re-exported from `@lovett/ui` alongside the
+ * promoted `<CalculatorShell>`). Implementation rules:
+ *
+ *   • Garbage in → `'—'` out. NaN, ±Infinity, null, undefined all
+ *     produce the em-dash string. Calculator UI should never crash on
+ *     partial input (empty inputs, zero divisors).
+ *   • Uses `Intl.NumberFormat('en-US', ...)` under the hood — proper
+ *     locale-aware separators, no manual `toFixed` rounding.
+ *   • `formatPercent` expects PERCENT UNITS, not a 0–1 fraction. Pass
+ *     `2.45` to get `"2.45%"`. Passing `0.0245` would yield `"0.02%"`.
+ *
+ * Zero runtime deps — `Intl.NumberFormat` is a built-in.
+ */
+
+const EM_DASH = '—'
+
+function invalid(n: unknown): boolean {
+  return (
+    typeof n !== 'number' ||
+    Number.isNaN(n) ||
+    !Number.isFinite(n)
+  )
+}
+
+interface FormatOptions {
+  /** Decimal places. Defaults vary per helper (see each helper's JSDoc). */
+  decimals?: number
+}
+
+/**
+ * Format a number as USD currency.
+ *
+ *   formatCurrency(42.5)          → "$42.50"
+ *   formatCurrency(1234567.89)    → "$1,234,567.89"
+ *   formatCurrency(NaN)           → "—"
+ *
+ * Default decimals: 2.
+ */
+export function formatCurrency(n: number, opts: FormatOptions = {}): string {
+  if (invalid(n)) return EM_DASH
+  const decimals = opts.decimals ?? 2
+  return new Intl.NumberFormat('en-US', {
+    style: 'currency',
+    currency: 'USD',
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals,
+  }).format(n)
+}
+
+/**
+ * Format a number as a percent. Input is in PERCENT UNITS (i.e. pass
+ * `2.45` to get `"2.45%"`, NOT `0.0245`). This matches the way the
+ * calculator routes compute their results (e.g. CTR = clicks ÷
+ * impressions × 100 — the × 100 already happened upstream).
+ *
+ *   formatPercent(2.45)           → "2.45%"
+ *   formatPercent(3.2, { decimals: 1 })  → "3.2%"
+ *   formatPercent(NaN)            → "—"
+ *
+ * Default decimals: 2.
+ */
+export function formatPercent(n: number, opts: FormatOptions = {}): string {
+  if (invalid(n)) return EM_DASH
+  const decimals = opts.decimals ?? 2
+  // Use 'decimal' style with manual '%' suffix rather than 'percent' —
+  // 'percent' would re-multiply by 100, which is the wrong contract for
+  // this helper (see JSDoc above).
+  const body = new Intl.NumberFormat('en-US', {
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals,
+  }).format(n)
+  return `${body}%`
+}
+
+/**
+ * Format a number as a ratio with the `x` suffix. Used by ROAS.
+ *
+ *   formatRatio(4.25)             → "4.25x"
+ *   formatRatio(10, { decimals: 0 })  → "10x"
+ *   formatRatio(Infinity)         → "—"
+ *
+ * Default decimals: 2.
+ */
+export function formatRatio(n: number, opts: FormatOptions = {}): string {
+  if (invalid(n)) return EM_DASH
+  const decimals = opts.decimals ?? 2
+  const body = new Intl.NumberFormat('en-US', {
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals,
+  }).format(n)
+  return `${body}x`
+}
+
+/**
+ * Format a number with thousand-separators and configurable decimals.
+ *
+ *   formatNumber(1234567)         → "1,234,567"
+ *   formatNumber(1234.567, { decimals: 2 })  → "1,234.57"
+ *   formatNumber(NaN)             → "—"
+ *
+ * Default decimals: 0.
+ */
+export function formatNumber(n: number, opts: FormatOptions = {}): string {
+  if (invalid(n)) return EM_DASH
+  const decimals = opts.decimals ?? 0
+  return new Intl.NumberFormat('en-US', {
+    minimumFractionDigits: decimals,
+    maximumFractionDigits: decimals,
+  }).format(n)
+}

package/src/frame-stack.tsx

@@ -0,0 +1,73 @@
+/**
+ * FrameStack — slate outer-frame wrapper for the shell/tray pattern.
+ *
+ * Single purpose: wrap 2+ inner cards as ONE visual group. Renders a
+ * slate-tinted outer frame (--card-frame-bg, --border-card) holding
+ * the children with 10 px outer padding and 10 px gap between them.
+ *
+ *   ┌─────────────────────────────────┐  ← <FrameStack>
+ *   │ ┌─────────────────────────────┐ │     slate bg (--card-frame-bg)
+ *   │ │ Card / SectionCard 01       │ │     10 px padding, 10 px gap
+ *   │ └─────────────────────────────┘ │     1 px --border-card outline
+ *   │ ┌─────────────────────────────┐ │     --radius-xl (20 px) outer
+ *   │ │ Card / SectionCard 02       │ │
+ *   │ └─────────────────────────────┘ │  ← child Card (tray)
+ *   │ ┌─────────────────────────────┐ │     white bg, 1 px border,
+ *   │ │ Card / SectionCard 03       │ │     --radius-lg (16 px)
+ *   │ └─────────────────────────────┘ │
+ *   └─────────────────────────────────┘
+ *
+ * Why a dedicated primitive instead of <Shell>:
+ * <Shell> is overloaded in the workspace ("the route shell" / "the
+ * primitive" / "the data-framed div"). When a directive says "use a
+ * shell" or "no shell," <Shell> consumers can't reliably tell which
+ * one is meant. FrameStack does exactly one job, named clearly. If
+ * you want this pattern, wrap. If you don't, don't.
+ *
+ * Anti-pattern (DO NOT replicate): rendering N <Card> / <SectionCard>
+ * elements as direct page-background children with `gap-3`. That's
+ * "free-floating cards," not the shell/tray pattern. Wrap them.
+ *
+ * Lens-level lock: `apps/workspace/src/lenses/meta-creative/CLAUDE.md`
+ * §"The shell/tray pattern" — the Meta Creative Builder uses this
+ * primitive for the 3-section form.
+ *
+ * Token discipline: internal tokens (--card-frame-bg, --border-card)
+ * are touched HERE per ADR-006 D2 — primitives live under
+ * `packages/ui/` and may reference internal tokens.
+ */
+
+import { forwardRef, type HTMLAttributes } from 'react'
+import { cn } from './lib/utils'
+
+export interface FrameStackProps extends HTMLAttributes<HTMLDivElement> {
+  /** Visual gap between child cards. Defaults to 10 px to match the
+   *  prototype's spec. Override only with a token value
+   *  (e.g. `'var(--space-3)'` for 12 px) — never a literal. */
+  gap?: string
+}
+
+export const FrameStack = forwardRef<HTMLDivElement, FrameStackProps>(
+  function FrameStack({ className, style, gap = '10px', children, ...rest }, ref) {
+    return (
+      <div
+        ref={ref}
+        data-framed="true"
+        className={cn('flex flex-col', className)}
+        style={{
+          background: 'rgb(var(--card-frame-bg))',
+          border: '1px solid rgb(var(--border-card))',
+          borderRadius: 'var(--radius-xl)',
+          padding: '10px',
+          gap,
+          ...style,
+        }}
+        {...rest}
+      >
+        {children}
+      </div>
+    )
+  },
+)
+
+FrameStack.displayName = 'FrameStack'

package/src/hero-form-card.tsx

@@ -0,0 +1,471 @@
+/**
+ * HeroFormCard — centered hero-layout form scaffold.
+ *
+ * Shape:
+ *
+ *   ┌──────────────────────────────────────────────────┐
+ *   │              EYEBROW (uppercase, accent)         │   ← header (outside card)
+ *   │                    Title                         │
+ *   │              Subtitle / lede (muted)             │
+ *   ├──────────────────────────────────────────────────┤
+ *   │ ╭──────────────────────────────────────────────╮ │
+ *   │ │  Section title (optional icon)               │ │   ← card body
+ *   │ │  ┌────────────────────────────────────────┐  │ │
+ *   │ │  │ Field label   *required               │  │ │
+ *   │ │  │ <Input />                              │  │ │
+ *   │ │  └────────────────────────────────────────┘  │ │
+ *   │ │  ...                                          │ │
+ *   │ ╰──────────────────────────────────────────────╯ │
+ *   │   helper text (optional, muted, centered)        │
+ *   ├──────────────────────────────────────────────────┤
+ *   │                  Cancel    Primary               │   ← footer (outside card)
+ *   └──────────────────────────────────────────────────┘
+ *
+ * Compound sub-components:
+ *   • HeroFormCard.Section — labeled section with optional icon slot
+ *   • HeroFormCard.Field   — labeled field row with required / optional
+ *                            chip + error text
+ *   • HeroFormCard.Advanced — collapsible <details> styled to match
+ *                             the rest of the card
+ *   • HeroFormCard.Footer  — action cluster (right-aligned)
+ *   • HeroFormCard.Banner  — informational strip above the body (e.g.,
+ *                            "From Quick Research · 80 keywords")
+ *
+ * Icon-agnostic: the primitive does NOT import or hard-code any
+ * specific icons. Consumers pass any Lucide (or custom) ReactNode as
+ * `icon` props on Section / Field / Banner.
+ *
+ * Token discipline: every spacing, radius, color, font-weight derives
+ * from a CSS variable in tokens.css. No hex literals.
+ *
+ * First consumers: NewSetPage + NewGroupPage. Designed to also fit the
+ * SEM Spec input lens — same hero-card pattern with a different body.
+ */
+
+import {
+  forwardRef,
+  type FormEvent,
+  type FormHTMLAttributes,
+  type HTMLAttributes,
+  type ReactNode,
+} from 'react'
+import { cn } from './lib/utils'
+import { Shell } from './shell'
+
+// ─── HeroFormCard root ──────────────────────────────────────────────
+
+export interface HeroFormCardProps
+  extends Omit<FormHTMLAttributes<HTMLFormElement>, 'title' | 'onSubmit'> {
+  /** Small accent text above the title, e.g. "Brand · Research". */
+  eyebrow?: ReactNode
+  /** The page-level title. Required. */
+  title: ReactNode
+  /** Supporting copy under the title. */
+  subtitle?: ReactNode
+  /** Optional helper text rendered between the body and the footer
+   *  (centered, muted). Good for "Name is required · everything else
+   *  is optional" affordances. */
+  helperText?: ReactNode
+  /** Body — typically composed of Section + Field. */
+  children: ReactNode
+  /** Footer action cluster (right-aligned). */
+  footer?: ReactNode
+  /** Container max-width in px (default 720). */
+  maxWidth?: number
+  /** When true the wrapping element is a <form> with onSubmit attached
+   *  (default). When false, renders a <div> — useful when an outer form
+   *  owns submission. */
+  asForm?: boolean
+  /** Form submit handler. Ignored when `asForm` is false. */
+  onSubmit?: (event: FormEvent<HTMLFormElement>) => void
+  className?: string
+}
+
+function HeroFormCard({
+  eyebrow,
+  title,
+  subtitle,
+  helperText,
+  children,
+  footer,
+  maxWidth = 720,
+  asForm = true,
+  onSubmit,
+  className,
+  ...rest
+}: HeroFormCardProps) {
+  const bodyContent = (
+    <>
+      <div className="flex flex-col gap-2 pt-4 pb-7">
+        {eyebrow && (
+          <div
+            className="text-[11px] font-bold uppercase tracking-[0.12em]"
+            style={{ color: 'rgb(var(--accent))' }}
+          >
+            {eyebrow}
+          </div>
+        )}
+        <h1
+          className="text-[26px] font-bold tracking-[-0.02em] leading-tight"
+          style={{ color: 'rgb(var(--foreground))' }}
+        >
+          {title}
+        </h1>
+        {subtitle && (
+          <p
+            className="text-[14px] leading-[1.5] mt-1"
+            style={{
+              color: 'rgb(var(--text-tertiary))',
+              maxWidth: 'var(--prose-wide)',
+            }}
+          >
+            {subtitle}
+          </p>
+        )}
+      </div>
+
+      <Shell centered={false}>{children}</Shell>
+
+      {helperText && (
+        <p
+          className="text-[12px] mt-3"
+          style={{ color: 'rgb(var(--text-tertiary))' }}
+        >
+          {helperText}
+        </p>
+      )}
+
+      {footer && (
+        <div className="flex items-center justify-end gap-2 mt-6">
+          {footer}
+        </div>
+      )}
+    </>
+  )
+
+  if (!asForm) {
+    return (
+      <div
+        className={cn('mx-auto w-full', className)}
+        style={{ maxWidth }}
+      >
+        {bodyContent}
+      </div>
+    )
+  }
+
+  return (
+    <form
+      onSubmit={onSubmit}
+      className={cn('mx-auto w-full', className)}
+      style={{ maxWidth }}
+      {...rest}
+    >
+      {bodyContent}
+    </form>
+  )
+}
+
+// ─── HeroFormCard.Section ───────────────────────────────────────────
+
+export interface HeroFormCardSectionProps
+  extends Omit<HTMLAttributes<HTMLElement>, 'title'> {
+  /** Section heading. Optional — omit for an untitled body. */
+  title?: ReactNode
+  /** Optional icon node (Lucide or custom). Sized by the consumer. */
+  icon?: ReactNode
+  /** Optional supporting copy under the section title. */
+  description?: ReactNode
+  /** Optional content rendered to the RIGHT of the section title row.
+   *  Good for inline helper text ("Name is required · everything else
+   *  is optional") or action chips. */
+  trailing?: ReactNode
+  children: ReactNode
+}
+
+function Section({
+  title,
+  icon,
+  description,
+  trailing,
+  children,
+  className,
+  ...rest
+}: HeroFormCardSectionProps) {
+  // `icon` is accepted by the API for back-compat but not used in the
+  // shell-tray rendering — the prototype's tray headers are
+  // icon-free. Surface lint-friendly by void-ing the binding.
+  void icon
+
+  const hasHeader = Boolean(title || description || trailing)
+
+  return (
+    <Shell.Tray className={className} {...rest}>
+      {hasHeader && (
+        <Shell.TrayHeader
+          title={title ?? ''}
+          {...(trailing ? { meta: trailing } : {})}
+          {...(description ? { description } : {})}
+        />
+      )}
+      <Shell.TrayBody spacing="form">{children}</Shell.TrayBody>
+    </Shell.Tray>
+  )
+}
+
+// ─── HeroFormCard.Field ─────────────────────────────────────────────
+
+export interface HeroFormCardFieldProps {
+  /** Visible field label. */
+  label: ReactNode
+  /** HTML id of the underlying control — wires <label htmlFor>. */
+  htmlFor?: string
+  required?: boolean
+  optional?: boolean
+  /** Inline error string. Renders below the field. */
+  error?: string | null
+  /** Optional helper hint below the field (when no error). */
+  hint?: ReactNode
+  children: ReactNode
+  className?: string
+}
+
+function Field({
+  label,
+  htmlFor,
+  required,
+  optional,
+  error,
+  hint,
+  children,
+  className,
+}: HeroFormCardFieldProps) {
+  return (
+    <div className={cn('flex flex-col gap-1.5', className)}>
+      <label
+        htmlFor={htmlFor}
+        className="text-[12px] font-semibold tracking-[0.02em]"
+        style={{ color: 'rgb(var(--foreground))' }}
+      >
+        {label}
+        {required && (
+          <span
+            className="ml-1"
+            style={{ color: 'rgb(var(--destructive))' }}
+            aria-hidden="true"
+          >
+            *
+          </span>
+        )}
+        {optional && (
+          <span
+            className="ml-1 font-normal"
+            style={{ color: 'rgb(var(--text-tertiary))' }}
+          >
+            (optional)
+          </span>
+        )}
+      </label>
+      {children}
+      {error ? (
+        <p
+          className="text-[12px]"
+          role="alert"
+          style={{ color: 'rgb(var(--destructive))' }}
+        >
+          {error}
+        </p>
+      ) : hint ? (
+        <p
+          className="text-[12px]"
+          style={{ color: 'rgb(var(--text-tertiary))' }}
+        >
+          {hint}
+        </p>
+      ) : null}
+    </div>
+  )
+}
+
+// ─── HeroFormCard.FieldRow ──────────────────────────────────────────
+// Two-up grid for side-by-side fields. Collapses to single column on
+// narrow viewports.
+
+function FieldRow({
+  children,
+  className,
+  ...rest
+}: HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      className={cn('grid grid-cols-1 sm:grid-cols-2 gap-4', className)}
+      {...rest}
+    >
+      {children}
+    </div>
+  )
+}
+
+// ─── HeroFormCard.Banner ────────────────────────────────────────────
+
+export interface HeroFormCardBannerProps {
+  /** Optional leading icon. */
+  icon?: ReactNode
+  /** Body content — text + optional inline marks. */
+  children: ReactNode
+  /** Visual tone. Default `info`. */
+  tone?: 'info' | 'accent' | 'success' | 'warning' | 'destructive'
+  className?: string
+}
+
+const BANNER_TONE: Record<
+  NonNullable<HeroFormCardBannerProps['tone']>,
+  { bg: string; border: string; icon: string }
+> = {
+  info: {
+    bg: 'rgb(var(--surface-overlay-soft))',
+    border: 'rgb(var(--border))',
+    icon: 'rgb(var(--text-secondary))',
+  },
+  accent: {
+    bg: 'rgb(var(--accent-subtle))',
+    border: 'rgb(var(--accent-muted))',
+    icon: 'rgb(var(--accent))',
+  },
+  success: {
+    bg: 'rgb(var(--success-bg))',
+    border: 'rgb(var(--success))',
+    icon: 'rgb(var(--success))',
+  },
+  warning: {
+    bg: 'rgb(var(--warning-bg))',
+    border: 'rgb(var(--warning))',
+    icon: 'rgb(var(--warning))',
+  },
+  destructive: {
+    bg: 'rgb(var(--surface-overlay-soft))',
+    border: 'rgb(var(--ring-error))',
+    icon: 'rgb(var(--destructive))',
+  },
+}
+
+function Banner({
+  icon,
+  children,
+  tone = 'info',
+  className,
+}: HeroFormCardBannerProps) {
+  const colors = BANNER_TONE[tone]
+  return (
+    <div
+      className={cn('flex items-start gap-3 p-3', className)}
+      style={{
+        background: colors.bg,
+        border: `1px solid ${colors.border}`,
+        borderRadius: 'var(--radius-md)',
+      }}
+    >
+      {icon && (
+        <span
+          className="inline-flex shrink-0 mt-0.5"
+          style={{ color: colors.icon }}
+          aria-hidden="true"
+        >
+          {icon}
+        </span>
+      )}
+      <div
+        className="text-[13px] leading-[1.45]"
+        style={{ color: 'rgb(var(--text-secondary))' }}
+      >
+        {children}
+      </div>
+    </div>
+  )
+}
+
+// ─── HeroFormCard.Advanced ──────────────────────────────────────────
+// Collapsible "Advanced options" disclosure — native <details> styled
+// to match the card chrome.
+
+export interface HeroFormCardAdvancedProps {
+  summary?: ReactNode
+  /** Optional icon node next to the summary. */
+  icon?: ReactNode
+  defaultOpen?: boolean
+  children: ReactNode
+  className?: string
+}
+
+function Advanced({
+  summary = 'Advanced options',
+  icon,
+  defaultOpen,
+  children,
+  className,
+}: HeroFormCardAdvancedProps) {
+  return (
+    <details
+      open={defaultOpen}
+      className={cn('group flex flex-col gap-3', className)}
+    >
+      <summary
+        className="flex items-center gap-1.5 cursor-pointer select-none text-[12px] font-semibold uppercase tracking-[0.08em] list-none [&::-webkit-details-marker]:hidden"
+        style={{ color: 'rgb(var(--text-muted))' }}
+      >
+        {icon && (
+          <span className="inline-flex shrink-0" aria-hidden="true">
+            {icon}
+          </span>
+        )}
+        <span>{summary}</span>
+      </summary>
+      <div className="flex flex-col gap-4 pt-1">{children}</div>
+    </details>
+  )
+}
+
+// ─── HeroFormCard.Footer ────────────────────────────────────────────
+// Footer rendering is folded into the root layout via the `footer`
+// prop, but consumers sometimes want to render the footer cluster
+// inline (e.g., right below a banner for inline confirmation flows).
+// Footer compound provides the same styling for that use case.
+
+function Footer({
+  children,
+  className,
+  ...rest
+}: HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      className={cn('flex items-center justify-end gap-2', className)}
+      {...rest}
+    >
+      {children}
+    </div>
+  )
+}
+
+// ─── Compound binding ───────────────────────────────────────────────
+
+const HeroFormCardCompound = Object.assign(
+  forwardRef<HTMLFormElement, HeroFormCardProps>(
+    function HeroFormCardForwardRef(props, _ref) {
+      // _ref is intentionally unused — no consumer needs focus-management
+      // on the <form> yet. forwardRef is kept on the public surface so a
+      // ref can be wired later without a breaking API change. React requires
+      // the two-parameter signature even when ref is not forwarded.
+      return <HeroFormCard {...props} />
+    },
+  ),
+  {
+    Section,
+    Field,
+    FieldRow,
+    Banner,
+    Advanced,
+    Footer,
+  },
+)
+
+export { HeroFormCardCompound as HeroFormCard }