@lovett/ui 0.0.1

package/src/calculator-shell-v2.tsx

@@ -0,0 +1,380 @@
+/**
+ * CalculatorShell v2 — the superset calculator shell (ADR-076 D1/D4).
+ *
+ * A presentational shell with two layouts and a flat brand-ink header.
+ * It owns NO form state (same contract as v1, ADR-030 D5) — each
+ * calculator owns its `useState` and composes the `inputs` / `result`
+ * slots from kit pieces (ProfileSection Frames, StatRow, MetricCard,
+ * Slider, Input). v1 `<CalculatorShell>` is retained untouched for the
+ * existing six math calculators; v2 is the path forward.
+ *
+ *   layout="shell" (default) — a single contained card (radius 24,
+ *     --shell-shadow): flat header + padded body + bordered footer.
+ *     For compact calculators.
+ *   layout="open" — the header becomes a rounded banner and the Frames
+ *     sit directly on the page in a vertical stack; the footer is
+ *     borderless/transparent. Scales to long forms (funnels).
+ *
+ * Header (D4): a flat `--brand-ink` strip with a 46px red-glyph tile, a
+ * mono uppercase eyebrow, and an uppercase title whose LAST word renders
+ * in `--accent`. A single-word title renders entirely in accent; pass a
+ * `[lead, accentWord]` tuple for explicit control. No completion ring.
+ *
+ * Data seam (D9): `prefill` + `benchmarkSlot` are accepted but STUBBED
+ * this ADR — `prefill` is typed and not read. Per ADR-076 Amendment 1 E,
+ * `benchmarkSlot` now renders a muted "Benchmark unavailable in manual
+ * mode" placeholder when absent (was: nothing). The live data wiring is a
+ * separate future ADR.
+ *
+ * Amendment 1 additions (2026-06-05):
+ *   - `assumptions` (B) — manual-vs-connected inputs, "directional planning
+ *     math, not observed performance," and the config/formula version.
+ *     Rendered as a compact hover popover in the FOOTER (next to the footer
+ *     note), not a body strip, so honest framing never lengthens the shell.
+ *   - benchmark placeholder (E) — see above.
+ *   - `copyReport` (F) — the footer Copy action emits a structured
+ *     mini-report (inputs + result + StatRow chain + assumptions +
+ *     benchmark status), not the bare number. Shell-owned so every
+ *     calculator's Copy is consistent.
+ */
+
+import { useState, type CSSProperties, type ReactNode } from 'react'
+import { BarChart3, Copy, Info } from 'lucide-react'
+import { Button } from './button'
+import { toast } from './toast'
+
+export type CalcLayout = 'shell' | 'open'
+
+/**
+ * Brand-profile prefill source (ADR-076 D9). Typed now so the data
+ * connection is a later drop-in, not a refactor.
+ *
+ * TODO(data-layer): source = useActiveBrandProfile().brand — prefill
+ *   audience / CPM / etc. from the active brand (canonical brn_ id).
+ */
+export interface CalcPrefill {
+  source: 'none' | 'brand'
+  values?: Record<string, number>
+}
+
+export interface CalculatorShellV2Props {
+  /** Mono uppercase eyebrow (e.g. "Streaming TV · Reality Check"). */
+  eyebrow: string
+  /** Uppercase title. The last whitespace-delimited word renders in
+   *  `--accent`; a single word renders entirely in accent. Pass a
+   *  `[lead, accentWord]` tuple for explicit control (D4). */
+  title: string | [string, string]
+  /** Lucide glyph rendered red inside the header tile. */
+  icon: ReactNode
+  /** Layout — `'shell'` (compact card) or `'open'` (long-form). */
+  layout?: CalcLayout
+  /** One or more `<ProfileSection>` Frames composing the inputs. */
+  inputs: ReactNode
+  /** A `<ProfileSection>` Frame wrapping the result block + StatRow. */
+  result: ReactNode
+  /** Left-aligned muted footer note (also the data-mode signal, D9). */
+  footerNote: ReactNode
+  /** Right-aligned footer actions (Reset / Save). The Copy action is
+   *  shell-owned via `copyReport` (Amendment 1 F) — do not pass a Copy
+   *  button here. */
+  actions?: ReactNode
+  /** Assumptions content (Amendment 1 B): manual-vs-connected inputs, the
+   *  "directional planning math" disclaimer, and the config/formula version.
+   *  Rendered as a footer hover popover (not a body strip) so it never adds
+   *  shell height. Omitted when absent. */
+  assumptions?: ReactNode
+  /** Structured mini-report for the shell-owned Copy action (Amendment 1
+   *  F). A string, or a function returning one (so it captures live state
+   *  at click time). When set, the shell renders a Copy button that writes
+   *  this to the clipboard. */
+  copyReport?: string | (() => string)
+  /** STUBBED (D9) — typed, not read this ADR. */
+  prefill?: CalcPrefill
+  /** "vs. benchmark" rail. When absent, the shell renders a muted
+   *  "Benchmark unavailable in manual mode" placeholder (Amendment 1 E). */
+  benchmarkSlot?: ReactNode
+}
+
+function HeaderTitle({ title }: { title: string | [string, string] }) {
+  const accent: CSSProperties = { color: 'rgb(var(--accent))' }
+  if (Array.isArray(title)) {
+    const [lead, accentWord] = title
+    return (
+      <>
+        {lead ? `${lead} ` : ''}
+        <span style={accent}>{accentWord}</span>
+      </>
+    )
+  }
+  const parts = title.trim().split(/\s+/)
+  if (parts.length <= 1) {
+    return <span style={accent}>{title}</span>
+  }
+  const last = parts[parts.length - 1]
+  const lead = parts.slice(0, -1).join(' ')
+  return (
+    <>
+      {lead} <span style={accent}>{last}</span>
+    </>
+  )
+}
+
+/** Muted rail shown in place of `benchmarkSlot` until the benchmark data
+ *  layer exists (Amendment 1 E) — reinforces the data-backed promise. */
+function BenchmarkPlaceholder() {
+  return (
+    <div
+      className="flex items-center"
+      style={{
+        gap: 10,
+        padding: '12px 16px',
+        borderRadius: 'var(--radius-lg)',
+        background: 'rgb(var(--muted))',
+        border: '1px dashed rgb(var(--border))',
+        color: 'rgb(var(--text-muted))',
+      }}
+    >
+      <BarChart3 size={15} />
+      <span style={{ fontSize: 12, fontWeight: 500 }}>
+        Benchmark unavailable in manual mode
+      </span>
+    </div>
+  )
+}
+
+/** Footer assumptions affordance (Amendment 1 B). A compact "Assumptions"
+ *  trigger that reveals the full disclaimer in a hover/focus popover. The
+ *  popover is absolutely positioned, so it never lengthens the shell — the
+ *  honest framing is one hover away, not a permanent strip. The calculator
+ *  supplies the content. */
+function AssumptionsPopover({ children }: { children: ReactNode }) {
+  const [open, setOpen] = useState(false)
+  return (
+    <span
+      className="inline-flex"
+      style={{ position: 'relative' }}
+      onMouseEnter={() => setOpen(true)}
+      onMouseLeave={() => setOpen(false)}
+    >
+      <button
+        type="button"
+        aria-label="Planning assumptions"
+        onFocus={() => setOpen(true)}
+        onBlur={() => setOpen(false)}
+        className="inline-flex items-center"
+        style={{
+          gap: 5,
+          fontSize: 12,
+          fontWeight: 500,
+          color: 'rgb(var(--text-muted))',
+          background: 'transparent',
+          border: 'none',
+          padding: 0,
+          cursor: 'help',
+        }}
+      >
+        <Info size={14} />
+        Assumptions
+      </button>
+      <span
+        role="note"
+        style={{
+          position: 'absolute',
+          bottom: 'calc(100% + 8px)',
+          left: 0,
+          width: 320,
+          maxWidth: '78vw',
+          padding: '12px 14px',
+          borderRadius: 'var(--radius-lg)',
+          background: 'rgb(var(--bg-card))',
+          border: '1px solid rgb(var(--border))',
+          boxShadow: 'var(--shadow-lg)',
+          color: 'rgb(var(--muted-foreground))',
+          fontSize: 11.5,
+          lineHeight: 1.5,
+          fontWeight: 500,
+          opacity: open ? 1 : 0,
+          transform: open ? 'translateY(0)' : 'translateY(4px)',
+          pointerEvents: open ? 'auto' : 'none',
+          transition:
+            'opacity 160ms var(--ease-out), transform 160ms var(--ease-out)',
+          zIndex: 20,
+        }}
+      >
+        {children}
+      </span>
+    </span>
+  )
+}
+
+export function CalculatorShellV2({
+  eyebrow,
+  title,
+  icon,
+  layout = 'shell',
+  inputs,
+  result,
+  footerNote,
+  actions,
+  assumptions,
+  copyReport,
+  benchmarkSlot,
+}: CalculatorShellV2Props) {
+  const isOpen = layout === 'open'
+
+  // Shell-owned Copy = structured mini-report (Amendment 1 F). `copyReport`
+  // may be a function so it captures live state at click time.
+  const handleCopy = async () => {
+    const text = typeof copyReport === 'function' ? copyReport() : copyReport
+    if (!text) return
+    try {
+      await navigator.clipboard.writeText(text)
+      toast.success('Report copied to clipboard')
+    } catch {
+      toast.error('Clipboard unavailable')
+    }
+  }
+
+  const header = (
+    <header
+      className="flex items-center"
+      style={{
+        gap: 16,
+        padding: '20px 24px',
+        background: 'rgb(var(--brand-ink))',
+        borderRadius: isOpen ? 'var(--radius-xl)' : 0,
+      }}
+    >
+      <span
+        className="grid place-items-center shrink-0"
+        style={{
+          width: 46,
+          height: 46,
+          borderRadius: 'var(--radius-md)',
+          background: 'rgb(255 255 255 / 0.07)',
+          border: '1px solid rgb(255 255 255 / 0.1)',
+          color: 'rgb(var(--accent))',
+        }}
+      >
+        {icon}
+      </span>
+      <div className="flex-1 min-w-0">
+        <div
+          className="font-semibold uppercase"
+          style={{
+            fontFamily: 'var(--font-mono)',
+            fontSize: 11,
+            letterSpacing: '0.14em',
+            color: 'rgb(255 255 255 / 0.5)',
+          }}
+        >
+          {eyebrow}
+        </div>
+        <h1
+          className="font-extrabold uppercase"
+          style={{
+            margin: '3px 0 0',
+            fontSize: 21,
+            letterSpacing: '-0.01em',
+            color: 'rgb(255 255 255)',
+          }}
+        >
+          <HeaderTitle title={title} />
+        </h1>
+      </div>
+    </header>
+  )
+
+  const footer = (
+    <footer
+      className="flex items-center"
+      style={{
+        gap: 12,
+        padding: '16px 24px',
+        borderTop: isOpen ? 'none' : '1px solid rgb(var(--border))',
+        marginTop: isOpen ? 4 : 0,
+        background: isOpen ? 'transparent' : 'rgb(var(--bg-card))',
+      }}
+    >
+      <span
+        className="flex items-center"
+        style={{ gap: 8, minWidth: 0 }}
+      >
+        <span
+          style={{
+            fontSize: 12,
+            fontWeight: 500,
+            color: 'rgb(var(--text-muted))',
+          }}
+        >
+          {footerNote}
+        </span>
+        {assumptions != null && (
+          <>
+            <span style={{ color: 'rgb(var(--text-muted))', fontSize: 12 }}>
+              ·
+            </span>
+            <AssumptionsPopover>{assumptions}</AssumptionsPopover>
+          </>
+        )}
+      </span>
+      <span style={{ flex: 1 }} />
+      {copyReport != null && (
+        <Button
+          variant="secondary"
+          onClick={handleCopy}
+          leadingIcon={<Copy size={15} />}
+        >
+          Copy
+        </Button>
+      )}
+      {actions}
+    </footer>
+  )
+
+  const body = (
+    <>
+      {inputs}
+      {result}
+      {benchmarkSlot ?? <BenchmarkPlaceholder />}
+    </>
+  )
+
+  return (
+    <div
+      className="flex flex-col items-center"
+      style={{ paddingTop: 'var(--space-8)', paddingBottom: 'var(--space-12)' }}
+    >
+      {isOpen ? (
+        <div
+          className="flex flex-col"
+          style={{ width: 'min(980px, 100%)', gap: 'var(--space-4)' }}
+        >
+          {header}
+          {body}
+          {footer}
+        </div>
+      ) : (
+        <main
+          style={{
+            width: 'min(980px, 100%)',
+            background: 'rgb(var(--bg-card))',
+            border: '1px solid rgb(var(--border-card))',
+            borderRadius: 'var(--radius-2xl)',
+            boxShadow: 'var(--shell-shadow)',
+            overflow: 'hidden',
+          }}
+        >
+          {header}
+          <div
+            className="flex flex-col"
+            style={{ padding: 'var(--space-6)', gap: 'var(--space-4)' }}
+          >
+            {body}
+          </div>
+          {footer}
+        </main>
+      )}
+    </div>
+  )
+}

package/src/calculator-shell.tsx

@@ -0,0 +1,310 @@
+/**
+ * CalculatorShell — centered, fixed-width layout primitive for
+ * marketing / ad-performance / customer-economics calculators.
+ *
+ * Locked by ADR-030 D2 / D5 / D6 / D8 (the original shape spec) and
+ * sharpened by ADR-058 D8 (final API + first 6 consumers). Promoted to
+ * `@lovett/ui` with 6 first-day consumers (ROAS / ROI / CTR / CPC /
+ * CPM / Conversion Rate) which clears ADR-008 D3's 2+ consumer gate
+ * three-times over.
+ *
+ * Layout (per ADR-030 D2 + D8):
+ *   <PageShell crumbs={[{label: 'Tools', to: '/tools'}, {label: title}]}>
+ *     <div  max-width: var(--prose-narrow), centered>
+ *       <header>
+ *         <h1>{title}</h1>
+ *         {subtitle && <p>{subtitle}</p>}
+ *       </header>
+ *       <div role="group" aria-label="${title} inputs">
+ *         {inputs}
+ *       </div>
+ *       {formula && <div>FORMULA · {formula}</div>}
+ *       <section aria-live="polite" aria-atomic="true">
+ *         RESULT · <big>{result}</big>
+ *       </section>
+ *       {secondaryStats && <div>{secondaryStats}</div>}
+ *       {(onReset || copyValue || shareUrl) && <action row>}
+ *     </div>
+ *   </PageShell>
+ *
+ * Interaction model (ADR-030 D5):
+ *   • No submit button. The result updates live as inputs change.
+ *   • The shell is presentational — it does NOT own form state. Each
+ *     calculator route owns its `useState` and computes `result` /
+ *     `secondaryStats` reactively before passing in.
+ *   • `aria-live="polite"` on the result region so screen readers
+ *     announce the value once it stabilises (the user can finish
+ *     typing without the AT interrupting).
+ *
+ * Token + visual discipline (ADR-030 D8 / ADR-006):
+ *   • Result card: --accent-subtle background, --accent-muted border,
+ *     --accent text. Stands out from the form.
+ *   • Formula label: --text-tertiary, monospace.
+ *   • All sizing via --space-* / --radius-* / --ctrl-* tokens. Zero
+ *     hex literals.
+ *   • `tabular-nums` font-variant on the result so digit widths don't
+ *     shift during typing.
+ */
+
+import { useId, useState, type CSSProperties, type ReactNode } from 'react'
+import { Check, Link2, RotateCcw } from 'lucide-react'
+import PageShell from './page-shell'
+import { Button } from './button'
+import { toast } from './toast'
+
+export interface CalculatorShellProps {
+  /** Display title (e.g. "ROAS Calculator"). Rendered as H1 + last
+   *  crumb in <PageShell>. */
+  title: string
+  /** One-line subtitle below the title. Optional — describes what the
+   *  calculator computes. */
+  subtitle?: string
+  /** Form inputs slot. Typically a vertical stack of @lovett/ui
+   *  <Input> primitives wrapped in <label>s with `type="number"`. */
+  inputs: ReactNode
+  /** Headline result value — large, accent-tinted, tabular-nums. Pass
+   *  the FORMATTED string (use `formatCurrency` / `formatPercent` /
+   *  `formatRatio` / `formatNumber`). NaN inputs surface as `'—'`. */
+  result: ReactNode
+  /** Optional formula label (e.g. "ROAS = Revenue ÷ Ad Spend"). Small,
+   *  dim, monospace-feel. Render as a <code> node so monospace +
+   *  semantics carry. */
+  formula?: ReactNode
+  /** Optional row of secondary derived stats (smaller, dim). Pass a
+   *  node containing 1-3 stat tiles or a single inline span. */
+  secondaryStats?: ReactNode
+  /** Optional reset to defaults. Renders a secondary "Reset" button
+   *  when provided. */
+  onReset?: () => void
+  /** Optional copy-result value (the formatted result string). Renders
+   *  a "Copy result" secondary button when provided. The value is
+   *  written to the clipboard on click; the button flashes a checkmark
+   *  + emits a success toast on success. Pass `undefined` to omit the
+   *  button — typically when the underlying number is NaN. */
+  copyValue?: string | undefined
+  /** Optional share-link URL — full or path. When provided, renders a
+   *  "Copy link" secondary button; click writes the URL to the
+   *  clipboard. (No tinyURL-style encoding here — the consumer
+   *  pre-builds the URL with encoded inputs.) */
+  shareUrl?: string | undefined
+}
+
+/**
+ * CalculatorShell — the layout primitive. See file-level JSDoc for the
+ * locked layout / interaction / token rules.
+ */
+export function CalculatorShell({
+  title,
+  subtitle,
+  inputs,
+  result,
+  formula,
+  secondaryStats,
+  onReset,
+  copyValue,
+  shareUrl,
+}: CalculatorShellProps) {
+  const inputsGroupId = useId()
+  const [copiedResult, setCopiedResult] = useState(false)
+  const [copiedShare, setCopiedShare] = useState(false)
+
+  const hasActions = Boolean(onReset || copyValue || shareUrl)
+
+  const handleCopy = async (
+    value: string,
+    setFlag: (b: boolean) => void,
+    successMsg: string,
+  ) => {
+    if (!value) return
+    let ok = false
+    if (typeof navigator !== 'undefined' && navigator.clipboard) {
+      try {
+        await navigator.clipboard.writeText(value)
+        ok = true
+      } catch {
+        ok = false
+      }
+    }
+    if (ok) {
+      setFlag(true)
+      setTimeout(() => setFlag(false), 1500)
+      toast.success(successMsg)
+    } else {
+      toast.error('Clipboard unavailable')
+    }
+  }
+
+  return (
+    <PageShell
+      crumbs={[{ label: 'Tools', to: '/tools' }, { label: title }]}
+    >
+      <div
+        className="mx-auto flex flex-col"
+        style={{
+          maxWidth: 'var(--prose-narrow)',
+          gap: 'var(--space-6)',
+          paddingTop: 'var(--space-4)',
+          paddingBottom: 'var(--space-8)',
+        }}
+      >
+        {/* Header */}
+        <header className="flex flex-col" style={{ gap: 'var(--space-2)' }}>
+          <h1
+            className="text-2xl font-semibold tracking-tight"
+            style={{ color: 'rgb(var(--foreground))' }}
+          >
+            {title}
+          </h1>
+          {subtitle && (
+            <p
+              className="text-sm"
+              style={{ color: 'rgb(var(--text-secondary))' }}
+            >
+              {subtitle}
+            </p>
+          )}
+        </header>
+
+        {/* Inputs */}
+        <div
+          role="group"
+          aria-labelledby={inputsGroupId}
+          className="flex flex-col"
+          style={{ gap: 'var(--space-4)' }}
+        >
+          <span id={inputsGroupId} className="sr-only">
+            {title} inputs
+          </span>
+          {inputs}
+        </div>
+
+        {/* Formula (optional) */}
+        {formula && (
+          <div
+            className="flex items-center"
+            style={{ gap: 'var(--space-3)' }}
+          >
+            <span
+              className="text-[10px] font-semibold uppercase tracking-[0.08em]"
+              style={{ color: 'rgb(var(--text-tertiary))' }}
+            >
+              Formula
+            </span>
+            <span
+              className="text-sm font-mono"
+              style={{ color: 'rgb(var(--text-tertiary))' }}
+            >
+              {formula}
+            </span>
+          </div>
+        )}
+
+        {/* Result card */}
+        <section
+          aria-live="polite"
+          aria-atomic="true"
+          className="flex flex-col items-center text-center"
+          style={
+            {
+              gap: 'var(--space-2)',
+              padding: 'var(--space-6)',
+              background: 'rgb(var(--accent-subtle))',
+              border: '1px solid rgb(var(--accent-muted))',
+              borderRadius: 'var(--radius-lg)',
+            } satisfies CSSProperties
+          }
+        >
+          <span
+            className="text-[10px] font-semibold uppercase tracking-[0.08em]"
+            style={{ color: 'rgb(var(--text-tertiary))' }}
+          >
+            Result
+          </span>
+          <div
+            className="text-4xl font-semibold"
+            style={{
+              fontVariantNumeric: 'tabular-nums',
+              color: 'rgb(var(--accent))',
+              lineHeight: 1.1,
+            }}
+          >
+            {result}
+          </div>
+          {secondaryStats && (
+            <div
+              className="flex flex-wrap items-center justify-center"
+              style={{
+                gap: 'var(--space-3)',
+                color: 'rgb(var(--text-tertiary))',
+                fontVariantNumeric: 'tabular-nums',
+              }}
+            >
+              {secondaryStats}
+            </div>
+          )}
+        </section>
+
+        {/* Action row (optional) */}
+        {hasActions && (
+          <div
+            className="flex flex-wrap items-center justify-end"
+            style={{ gap: 'var(--space-2)' }}
+          >
+            {onReset && (
+              <Button
+                variant="secondary"
+                size="sm"
+                onClick={onReset}
+                leadingIcon={<RotateCcw className="h-4 w-4" />}
+              >
+                Reset
+              </Button>
+            )}
+            {copyValue && (
+              <Button
+                variant="secondary"
+                size="sm"
+                onClick={() =>
+                  handleCopy(
+                    copyValue,
+                    setCopiedResult,
+                    'Result copied to clipboard',
+                  )
+                }
+                leadingIcon={
+                  copiedResult ? (
+                    <Check className="h-4 w-4" />
+                  ) : undefined
+                }
+              >
+                {copiedResult ? 'Copied' : 'Copy result'}
+              </Button>
+            )}
+            {shareUrl && (
+              <Button
+                variant="secondary"
+                size="sm"
+                onClick={() =>
+                  handleCopy(
+                    shareUrl,
+                    setCopiedShare,
+                    'Share link copied to clipboard',
+                  )
+                }
+                leadingIcon={
+                  copiedShare ? (
+                    <Check className="h-4 w-4" />
+                  ) : (
+                    <Link2 className="h-4 w-4" />
+                  )
+                }
+              >
+                {copiedShare ? 'Copied' : 'Copy link'}
+              </Button>
+            )}
+          </div>
+        )}
+      </div>
+    </PageShell>
+  )
+}