@lovett/ui 0.0.1

package/src/meta-previews/ProfileAvatar.tsx

@@ -0,0 +1,79 @@
+import { useEffect, useState } from 'react';
+import type { CSSProperties } from 'react';
+
+interface ProfileAvatarProps {
+  /** The pulled Meta page profile image. Empty/missing OR a load failure falls
+   *  back to the brand-initial letter. */
+  src?: string | undefined;
+  /** Brand / page name — its first character is the letter fallback. */
+  name: string;
+  /** Letter-fallback background — a color OR a gradient (platform-specific).
+   *  Defaults to Meta blue. */
+  background?: string;
+  /** Letter-fallback text color. Defaults to white. */
+  color?: string;
+  /** Letter-fallback font size in px. Defaults to 14. */
+  fontSize?: number;
+  /** Geometry applied to BOTH the image and the letter so they stay identical.
+   *  Defaults to filling the parent circle (the caller owns the size / radius /
+   *  ring); pass explicit width/height/margin/borderRadius for avatars that are
+   *  not a plain parent-fill (e.g. Messenger). */
+  style?: CSSProperties;
+}
+
+const FILL: CSSProperties = { width: '100%', height: '100%' };
+
+/**
+ * Unified advertiser avatar for every Meta / Instagram preview. Renders the
+ * pulled page profile image (object-cover), falling back to the brand's initial
+ * when the image is missing OR fails to load. Centralising the image↔letter
+ * logic here is what keeps every preview consistent — no preview can drift to a
+ * grey box (Search/Explore did) or an empty circle (a broken CDN URL did).
+ */
+export function ProfileAvatar({
+  src,
+  name,
+  background = 'rgb(24, 119, 242)',
+  color = 'white',
+  fontSize = 14,
+  style,
+}: ProfileAvatarProps) {
+  const [failed, setFailed] = useState(false);
+  // A new src (e.g. brand switch) gets a fresh chance to load.
+  useEffect(() => {
+    setFailed(false);
+  }, [src]);
+
+  const geom = style ?? FILL;
+
+  if (src && !failed) {
+    return (
+      <img
+        src={src}
+        alt={name}
+        style={{ objectFit: 'cover', display: 'block', ...geom }}
+        loading="lazy"
+        decoding="async"
+        onError={() => setFailed(true)}
+      />
+    );
+  }
+
+  return (
+    <div
+      aria-label={name}
+      style={{
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        background,
+        color,
+        fontSize: `${fontSize}px`,
+        fontWeight: 600,
+        ...geom,
+      }}
+    >
+      {(name.trim().charAt(0) || '?').toUpperCase()}
+    </div>
+  );
+}

package/src/meta-previews/defaults.ts

@@ -0,0 +1,27 @@
+import type { PreviewAdData } from './types'
+
+/**
+ * Placeholder copy shown in a preview when the corresponding input field is
+ * empty — so a fresh ad reads as a complete ad instead of blank gaps. Only
+ * fills BLANK fields; any typed value passes through unchanged.
+ */
+export const PREVIEW_DEFAULTS = {
+  brandName: 'Your Brand',
+  primaryText: 'Your primary text will show up here.',
+  headline: 'Your headline',
+  displayLink: 'yoursite.com',
+  callToAction: 'Learn more',
+} as const
+
+/** Fill empty `PreviewAdData` copy fields with placeholders (image/media fields
+ *  are left untouched — those have their own in-component placeholders). */
+export function withPreviewDefaults(ad: PreviewAdData): PreviewAdData {
+  return {
+    ...ad,
+    brandName: ad.brandName || PREVIEW_DEFAULTS.brandName,
+    primaryText: ad.primaryText || PREVIEW_DEFAULTS.primaryText,
+    headline: ad.headline || PREVIEW_DEFAULTS.headline,
+    displayLink: ad.displayLink || PREVIEW_DEFAULTS.displayLink,
+    callToAction: ad.callToAction || PREVIEW_DEFAULTS.callToAction,
+  }
+}

package/src/meta-previews/index.ts

@@ -0,0 +1,37 @@
+// @lovett/ui/meta-previews — public surface.
+//
+// Promoted from docs/prototype/meta/preview-package/ per ADR-060 D9a
+// (amended 2026-05-28). Pixel-accurate Meta + Instagram + Messenger
+// preview renderers; zero coupling to stores, hooks, routers, or API
+// clients. Designed for portable drop-in reuse across the workspace's
+// Meta-related lenses.
+//
+// API contract: every renderer takes one prop, `adData: PreviewAdData`.
+// Several also accept `device`, `platform`, `format`, or dominant-color
+// tinting hints — see each component's prop signature for specifics.
+
+export { CreativeMedia } from './CreativeMedia';
+export { MetaFeedPreview } from './MetaFeedPreview';
+export { MetaStoryPreview } from './MetaStoryPreview';
+export { MetaReelPreview } from './MetaReelPreview';
+export { MetaMessengerPreview } from './MetaMessengerPreview';
+export { MetaRightColumnPreview } from './MetaRightColumnPreview';
+export { MetaSearchPreview } from './MetaSearchPreview';
+export { MetaInstreamPreview } from './MetaInstreamPreview';
+export { InstagramFeedPreview } from './InstagramFeedPreview';
+export { InstagramExplorePreview } from './InstagramExplorePreview';
+export { MetaFeedCarousel } from './MetaFeedCarousel';
+export { InstagramFeedCarousel } from './InstagramFeedCarousel';
+
+export type {
+  PreviewAdData,
+  PreviewPlatform,
+  PreviewPlacement,
+  PreviewDevice,
+  PlacementPreview,
+  PreviewConfiguration,
+  CarouselCardView,
+  CarouselViewProps,
+} from './types';
+
+export { PLACEMENT_CONFIGS } from './types';

package/src/meta-previews/types.ts

@@ -0,0 +1,219 @@
+// @lovett/ui — Meta / Instagram platform-preview types.
+//
+// Promoted from docs/prototype/meta/preview-package/types/previews.ts
+// per ADR-060 D9a (amended 2026-05-28). Pixel-accurate FB+IG preview
+// renderers consume `PreviewAdData`; the 10 renderers + this types
+// module + the PLACEMENT_CONFIGS constant comprise the public surface
+// of `@lovett/ui/meta-previews`.
+
+import type { ReactNode } from 'react';
+
+export type PreviewPlatform = 'facebook' | 'instagram' | 'messenger';
+export type PreviewPlacement =
+  | 'feed'
+  | 'story'
+  | 'reel'
+  | 'inbox'
+  | 'instream'
+  | 'search'
+  | 'rightcolumn'
+  | 'explore';
+export type PreviewDevice = 'mobile' | 'desktop';
+
+export interface PreviewConfiguration {
+  platform: PreviewPlatform;
+  placement: PreviewPlacement;
+  device: PreviewDevice;
+  format: '1:1' | '4:5' | '9:16';
+}
+
+export interface PreviewAdData {
+  adName: string;
+  primaryText: string;
+  headline: string;
+  description: string;
+  callToAction: string;
+  websiteUrl: string;
+  displayLink: string;
+  brandName: string;
+  profileImage: string;
+  creativeImage: string;
+  // `| undefined` is explicit so callers may assign an absent media type
+  // under the workspace's exactOptionalPropertyTypes tsconfig.
+  creativeMediaType?: 'image' | 'video' | undefined;
+}
+
+/**
+ * A single carousel card for the presentational carousel views (ADR-119 D1).
+ * Per-card copy/destination only — the CTA is ad-level/shared (ADR-119 D3).
+ */
+export interface CarouselCardView {
+  key: string;
+  headline?: string | undefined;
+  description?: string | undefined;
+  url?: string | undefined;
+}
+
+/**
+ * Props for the pure presentational carousels (`MetaFeedCarousel`,
+ * `InstagramFeedCarousel`). They own NO data or crop logic: the caller supplies
+ * the card list, the active index + setter, and an image-render slot
+ * (`CropFrame` on the controller-driven form side; a plain <img> on static
+ * surfaces). Because the view imports neither the controller nor the crop
+ * system, it lives in `packages/ui` and earns Meta-exact hex (ADR-119 D1/D5).
+ */
+export interface CarouselViewProps {
+  cards: CarouselCardView[];
+  active: number;
+  onActive: (index: number) => void;
+  renderImage: (index: number) => ReactNode;
+  brandName: string;
+  profileImage?: string | undefined;
+  primaryText?: string | undefined;
+  /** Ad-level CTA, shared across cards (ADR-119 D3). */
+  callToAction: string;
+}
+
+export interface PlacementPreview {
+  id: string;
+  platform: PreviewPlatform;
+  placement: PreviewPlacement;
+  label: string;
+  description: string;
+  aspectRatio: '1:1' | '4:5' | '9:16';
+  device: PreviewDevice;
+  enabled: boolean;
+}
+
+export const PLACEMENT_CONFIGS: PlacementPreview[] = [
+  {
+    id: 'fb-feed',
+    platform: 'facebook',
+    placement: 'feed',
+    label: 'Facebook Feed',
+    description: 'Standard news feed placement',
+    aspectRatio: '1:1',
+    device: 'desktop',
+    enabled: true,
+  },
+  {
+    id: 'ig-feed',
+    platform: 'instagram',
+    placement: 'feed',
+    label: 'Instagram Feed',
+    description: 'Standard Instagram feed',
+    aspectRatio: '1:1',
+    device: 'mobile',
+    enabled: true,
+  },
+  {
+    id: 'fb-rightcolumn',
+    platform: 'facebook',
+    placement: 'rightcolumn',
+    label: 'Facebook Right column',
+    description: 'Desktop right column placement',
+    aspectRatio: '1:1',
+    device: 'desktop',
+    enabled: true,
+  },
+  {
+    id: 'fb-feed-mobile',
+    platform: 'facebook',
+    placement: 'feed',
+    label: 'Facebook Feed (Mobile)',
+    description: 'Mobile news feed',
+    aspectRatio: '4:5',
+    device: 'mobile',
+    enabled: false,
+  },
+  {
+    id: 'ig-story',
+    platform: 'instagram',
+    placement: 'story',
+    label: 'Instagram Stories',
+    description: 'Full-screen vertical stories',
+    aspectRatio: '9:16',
+    device: 'mobile',
+    enabled: true,
+  },
+  {
+    id: 'fb-story',
+    platform: 'facebook',
+    placement: 'story',
+    label: 'Facebook Stories',
+    description: 'Full-screen vertical stories',
+    aspectRatio: '9:16',
+    device: 'mobile',
+    enabled: true,
+  },
+  {
+    id: 'messenger-story',
+    platform: 'messenger',
+    placement: 'story',
+    label: 'Messenger Stories',
+    description: 'Full-screen vertical stories',
+    aspectRatio: '9:16',
+    device: 'mobile',
+    enabled: true,
+  },
+  {
+    id: 'ig-reel',
+    platform: 'instagram',
+    placement: 'reel',
+    label: 'Instagram Reels',
+    description: 'Short-form video placement',
+    aspectRatio: '9:16',
+    device: 'mobile',
+    enabled: true,
+  },
+  {
+    id: 'fb-reel',
+    platform: 'facebook',
+    placement: 'reel',
+    label: 'Facebook Reels',
+    description: 'Short-form video placement',
+    aspectRatio: '9:16',
+    device: 'mobile',
+    enabled: true,
+  },
+  {
+    id: 'ig-explore',
+    platform: 'instagram',
+    placement: 'explore',
+    label: 'Instagram Explore home',
+    description: 'Explore grid placement',
+    aspectRatio: '1:1',
+    device: 'mobile',
+    enabled: true,
+  },
+  {
+    id: 'messenger-inbox',
+    platform: 'messenger',
+    placement: 'inbox',
+    label: 'Messenger Inbox',
+    description: 'Sponsored message in inbox',
+    aspectRatio: '1:1',
+    device: 'mobile',
+    enabled: true,
+  },
+  {
+    id: 'fb-instream',
+    platform: 'facebook',
+    placement: 'instream',
+    label: 'Facebook In-stream videos',
+    description: 'Video ads in Facebook Watch and video feeds',
+    aspectRatio: '1:1',
+    device: 'mobile',
+    enabled: true,
+  },
+  {
+    id: 'fb-search',
+    platform: 'facebook',
+    placement: 'search',
+    label: 'Facebook Marketplace Search',
+    description: 'Ads in Facebook Marketplace search results',
+    aspectRatio: '1:1',
+    device: 'mobile',
+    enabled: true,
+  },
+];

package/src/metric-card.tsx

@@ -0,0 +1,117 @@
+/**
+ * MetricCard — KPI tile with large value + label + optional tone variant.
+ *
+ * Promoted in ADR-020 (Phase 3a Discovery Company Research, first
+ * committed consumer). Cross-batch consumers: Phase 3c (admin stats),
+ * Phase 8 (results summary), Phase 12 (review-overview summary).
+ *
+ * Designed for use inside `<StatsGrid>` (also new this batch — see
+ * `stats-grid.tsx`) but works standalone in any flex/grid container.
+ *
+ * Token discipline: all colors via public tokens. Tone variant gives
+ * the value text an accent/success/warning/destructive/info color;
+ * background is always neutral surface-overlay.
+ */
+
+import type { ReactNode } from 'react'
+
+export type MetricCardTone = 'neutral' | 'accent' | 'success' | 'warning' | 'destructive' | 'info'
+
+const TONE_COLOR: Record<MetricCardTone, string> = {
+  neutral: 'rgb(var(--foreground))',
+  accent: 'rgb(var(--accent))',
+  success: 'rgb(var(--success))',
+  warning: 'rgb(var(--warning))',
+  destructive: 'rgb(var(--destructive))',
+  info: 'rgb(var(--info))',
+}
+
+export interface MetricCardProps {
+  /** Headline value (large, semibold, tone-colored). Numbers should
+   *  use `font-mono` for tabular alignment when relevant. */
+  value: ReactNode
+  /** Small descriptive label below the value. */
+  label: string
+  /** Optional tone — colors the value text. Background stays neutral. */
+  tone?: MetricCardTone
+  /** Optional icon shown to the left of the value (h-5 w-5 expected). */
+  icon?: ReactNode
+  /**
+   * Where the label sits relative to the value. Default `'bottom'`
+   * (value-then-label — the original shape; existing consumers are
+   * unchanged). `'top'` renders a small uppercase label above the
+   * value — the KPI-chip shape used by Calculator Shell v2 (ADR-076
+   * D8). The value size is unchanged in both positions.
+   */
+  labelPosition?: 'top' | 'bottom'
+  /** Optional className override for the outer container. */
+  className?: string
+}
+
+export function MetricCard({
+  value,
+  label,
+  tone = 'neutral',
+  icon,
+  labelPosition = 'bottom',
+  className,
+}: MetricCardProps) {
+  const labelEl =
+    labelPosition === 'top' ? (
+      <div
+        className="text-[10px] font-bold uppercase tracking-[0.05em]"
+        style={{ color: 'rgb(var(--text-tertiary))' }}
+      >
+        {label}
+      </div>
+    ) : (
+      <div
+        className="text-[12px]"
+        style={{ color: 'rgb(var(--text-tertiary))' }}
+      >
+        {label}
+      </div>
+    )
+
+  const valueEl = (
+    <div className="flex items-center gap-2">
+      {icon && (
+        <span style={{ color: TONE_COLOR[tone] }} className="flex-shrink-0">
+          {icon}
+        </span>
+      )}
+      <div
+        className="text-[24px] font-semibold tabular-nums"
+        style={{ color: TONE_COLOR[tone] }}
+      >
+        {value}
+      </div>
+    </div>
+  )
+
+  return (
+    <div
+      className={
+        className ??
+        'flex flex-col gap-1 px-4 py-3 border'
+      }
+      style={{
+        background: 'rgb(var(--surface-overlay-soft))',
+        borderColor: 'rgb(var(--border))',
+        borderRadius: 'var(--radius-lg)',
+      }}
+    >
+      {labelPosition === 'top' ? (
+        <>
+          {labelEl}
+          {valueEl}
+        </>
+      ) : (
+        <>
+          {valueEl}
+          {labelEl}
+        </>
+      )}
+    </div>
+  )
+}

package/src/modal.tsx

@@ -0,0 +1,131 @@
+import { useEffect, type HTMLAttributes, type ReactNode } from 'react'
+import { X } from 'lucide-react'
+import { cn } from './lib/utils'
+
+/**
+ * Modal — a centered floating panel on top of a backdrop. Built on
+ * `.ds-card-surface` so it inherits the premium card chrome (border,
+ * radius, multi-layer shadow with inner highlight in light mode).
+ *
+ * Two layout modes:
+ *
+ *   1. Flat children (back-compat) — pass content directly:
+ *
+ *        <Modal title="..." onClose={...}>
+ *          <p>body</p>
+ *          <Button>action</Button>
+ *        </Modal>
+ *
+ *   2. Shell / Tray pattern (recommended) — body in a recessed tray,
+ *      action buttons on the outer-card bottom strip below the tray:
+ *
+ *        <Modal title="..." onClose={...}>
+ *          <Modal.Tray>
+ *            <p>body content sits in a recessed shelf</p>
+ *            <textarea ... />
+ *          </Modal.Tray>
+ *          <Modal.Footer>
+ *            <Button variant="ghost" onClick={onClose}>Cancel</Button>
+ *            <Button>Confirm</Button>
+ *          </Modal.Footer>
+ *        </Modal>
+ */
+
+interface ModalProps {
+  isOpen: boolean
+  onClose: () => void
+  title: string
+  children: ReactNode
+  className?: string
+}
+
+function Modal({ isOpen, onClose, title, children, className }: ModalProps) {
+  useEffect(() => {
+    if (!isOpen) return
+    const handleEscape = (e: KeyboardEvent) => {
+      if (e.key === 'Escape') onClose()
+    }
+    document.addEventListener('keydown', handleEscape)
+    return () => document.removeEventListener('keydown', handleEscape)
+  }, [isOpen, onClose])
+
+  if (!isOpen) return null
+
+  return (
+    <div className="fixed inset-0 z-50 flex items-center justify-center">
+      {/* Backdrop */}
+      <div
+        className="absolute inset-0"
+        style={{ background: 'rgb(var(--modal-overlay))' }}
+        onClick={onClose}
+      />
+      {/* Outer card — uses .ds-card-surface so the modal gets the
+         same chrome as cards (border + multi-layer shadow + inner
+         highlight in light mode). overflow-hidden clips children to
+         the rounded corners; the tray inside handles its own scroll. */}
+      <div
+        data-framed="true"
+        className={cn(
+          'ds-card-surface relative w-full max-w-2xl flex flex-col max-h-[90vh] overflow-hidden',
+          className,
+        )}
+        style={{ borderRadius: 'var(--radius-xl)' }}
+      >
+        {/* Header — title + close. Sits on the outer card surface,
+           outside any tray. Shrink-0 so it never collapses when the
+           body grows. */}
+        <div className="flex items-center justify-between shrink-0 px-6 pt-6 pb-4">
+          <h2 className="text-xl font-bold text-[rgb(var(--foreground))]">
+            {title}
+          </h2>
+          <button
+            onClick={onClose}
+            className="rounded-lg p-1.5 text-[rgb(var(--muted-foreground))] hover:bg-[rgb(var(--muted))] hover:text-[rgb(var(--foreground))] transition-colors"
+            aria-label="Close"
+          >
+            <X className="h-5 w-5" />
+          </button>
+        </div>
+        {children}
+      </div>
+    </div>
+  )
+}
+
+/**
+ * Modal.Tray — the recessed body panel. Sits inside the modal's outer
+ * card with --tray-inset margin and its own bg. Scrolls if content
+ * exceeds the modal's max-height.
+ */
+function Tray({ className, ...rest }: HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      className={cn(
+        'ds-card-tray flex-1 min-h-0 overflow-y-auto p-5',
+        className,
+      )}
+      {...rest}
+    />
+  )
+}
+
+/**
+ * Modal.Footer — bottom action strip on the outer card, below the
+ * tray inset. `shrink-0` keeps it pinned even when the tray scrolls.
+ */
+function Footer({ className, ...rest }: HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      className={cn(
+        'flex items-center justify-end gap-2 shrink-0 px-6 py-4',
+        className,
+      )}
+      {...rest}
+    />
+  )
+}
+
+Modal.Tray = Tray
+Modal.Footer = Footer
+
+export default Modal