@lovett/ui 0.0.1

package/src/shell.tsx

@@ -0,0 +1,464 @@
+/**
+ * Shell — multi-tray framed-card pattern.
+ *
+ * Two-level card structure: an outer slate "wrapper" that holds one or
+ * more white panes inside it. Inspired by `src/lenses/brand/identity-
+ * rail.tsx` and codified into a reusable primitive after the utility-
+ * tools redesign (2026-05-19).
+ *
+ * Anatomy:
+ *
+ *   ┌─────────────────────────────────────────────┐
+ *   │  outer frame (--card-frame-bg + 16px        │ ← <Shell>
+ *   │  radius + border + rest-shadow + 10px       │
+ *   │  padding + 10px flex-gap)                   │
+ *   │                                              │
+ *   │  ┌───────────────────────────────────────┐  │ ← <Shell.Tray>
+ *   │  │ Title                     meta        │  │   <Shell.TrayHeader>
+ *   │  │                                       │  │
+ *   │  │   body content                        │  │   <Shell.TrayBody>
+ *   │  │                                       │  │
+ *   │  │ ─────────────────────────────────────│  │
+ *   │  │  toggle  toggle           [Primary]   │  │   <Shell.TrayFooter>
+ *   │  └───────────────────────────────────────┘  │
+ *   │  ┌───────────────────────────────────────┐  │
+ *   │  │ Title                                 │  │
+ *   │  │   body content                        │  │
+ *   │  └───────────────────────────────────────┘  │
+ *   └─────────────────────────────────────────────┘
+ *
+ * Compound API:
+ *   • <Shell>              outer frame (page-level wrapper auto-centers)
+ *   • <Shell.Tray>          inner pane
+ *   • <Shell.TrayHeader>    title + meta + optional accent numeral
+ *   • <Shell.TrayBody>      body content
+ *   • <Shell.TrayFooter>    recessed footer strip — secondary controls
+ *                           left, primary right via marginLeft:auto
+ *   • <Shell.SubCard>       card-inside-a-tray for grouped items
+ *
+ * Token discipline: internal-only tokens (--card-frame-bg, --tray-bg,
+ * --card-foot-bg, --border-card, --card-shadow-rest) are touched HERE,
+ * not in app code. Consumers compose Shell.* with their own content.
+ *
+ * Icon-agnostic. No hardcoded icons.
+ *
+ * SPACING REFERENCE (per the locked spec):
+ *   • Outer frame padding: 10px (all sides)
+ *   • Gap between trays:   10px (flex gap, NOT margin)
+ *   • Tray header padding: 20px 24px 0
+ *   • Tray body padding:   14px 24px 22px (top 14 = header bottom shim)
+ *   • Tray footer padding: 14px 18px (or 12px 18px compact)
+ *   • Outer radius: 16px (--radius-lg) — inner tray radius: 12px
+ *     (--radius-md) — DO NOT change one without the other.
+ */
+
+import {
+  forwardRef,
+  type HTMLAttributes,
+  type ReactNode,
+} from 'react'
+import { cn } from './lib/utils'
+
+// ─── Shell (outer frame) ───────────────────────────────────────────
+
+export interface ShellProps extends HTMLAttributes<HTMLDivElement> {
+  /** Max-width for the auto-centered page-level wrapper, in pixels.
+   *  Default 760 (tool-page width). New Set / similar form pages use
+   *  880. When `centered` is false, the value is ignored. */
+  maxWidth?: number
+  /** When true (default), the frame is centered horizontally inside
+   *  its parent via `mx-auto` + `max-width`. Pass `false` if you need
+   *  the frame to fill its parent (e.g. inside a tight grid cell). */
+  centered?: boolean
+}
+
+const ShellRoot = forwardRef<HTMLDivElement, ShellProps>(function Shell(
+  { maxWidth = 760, centered = true, className, style, children, ...rest },
+  ref,
+) {
+  return (
+    <div
+      ref={ref}
+      data-framed="true"
+      data-slot="shell"
+      className={cn(
+        'ds-card-surface flex flex-col',
+        centered && 'mx-auto w-full',
+        className,
+      )}
+      style={{
+        background: 'rgb(var(--card-frame-bg))',
+        // 10px padding + 10px gap is what makes the trays "float"
+        // inside the frame. Concentric 16px outer / 12px inner radii
+        // depend on the 4px wall + 10px gap working together.
+        padding: 10,
+        gap: 10,
+        ...(centered ? { maxWidth } : {}),
+        ...style,
+      }}
+      {...rest}
+    >
+      {children}
+    </div>
+  )
+})
+
+// ─── Shell.Tray ─────────────────────────────────────────────────────
+
+export interface ShellTrayProps extends HTMLAttributes<HTMLElement> {
+  /** Visual variant. `default` (white inner pane, used for primary
+   *  content) or `compact` (tighter padding for dense rows). */
+  variant?: 'default' | 'compact'
+}
+
+const Tray = forwardRef<HTMLElement, ShellTrayProps>(function ShellTray(
+  { variant = 'default', className, style, children, ...rest },
+  ref,
+) {
+  void variant
+  return (
+    <section
+      ref={ref}
+      data-slot="shell-tray"
+      // `overflow: hidden` is required so the recessed footer's flat
+      // top edge clips cleanly inside the tray's 12px corners.
+      className={cn('flex flex-col', className)}
+      style={{
+        background: 'rgb(var(--tray-bg))',
+        border: '1px solid rgb(var(--border-card))',
+        borderRadius: 12,
+        overflow: 'hidden',
+        // Reset any margin the global `.ds-card-tray` class would
+        // apply — Shell uses flex-gap on the frame instead.
+        margin: 0,
+        ...style,
+      }}
+      {...rest}
+    >
+      {children}
+    </section>
+  )
+})
+
+// ─── Shell.TrayHeader ───────────────────────────────────────────────
+
+export interface ShellTrayHeaderProps
+  extends Omit<HTMLAttributes<HTMLElement>, 'title'> {
+  title: ReactNode
+  /** Right-aligned meta — e.g. "12 lines · 3 dupes" or
+   *  "Name is required · everything else is optional". */
+  meta?: ReactNode
+  /** Optional left-side numeral chip ("01", "02") in accent color.
+   *  Skip for tools that don't need step indication. */
+  index?: ReactNode
+  /** Optional supporting copy beneath the title row. */
+  description?: ReactNode
+  /** Tighter padding for dense layouts. */
+  compact?: boolean
+}
+
+function TrayHeader({
+  title,
+  meta,
+  index,
+  description,
+  compact,
+  className,
+  style,
+  ...rest
+}: ShellTrayHeaderProps) {
+  return (
+    <header
+      data-slot="shell-tray-header"
+      className={cn('flex flex-col gap-1.5', className)}
+      style={{
+        // 20px top / 24px sides / 0 bottom — body padding shimmies
+        // the 14px top to land at 14px from the title baseline.
+        padding: compact ? '16px 18px 0' : '20px 24px 0',
+        ...style,
+      }}
+      {...rest}
+    >
+      <div className="flex items-baseline justify-between gap-3 flex-wrap">
+        <div className="flex items-baseline gap-2 min-w-0">
+          {index && (
+            <span
+              className="text-[11px] font-bold uppercase tracking-[0.12em] shrink-0"
+              style={{ color: 'rgb(var(--accent))' }}
+            >
+              {index}
+            </span>
+          )}
+          <h2
+            className="text-[15px] font-semibold leading-tight truncate"
+            style={{
+              color: 'rgb(var(--foreground))',
+              letterSpacing: '-0.005em',
+            }}
+          >
+            {title}
+          </h2>
+        </div>
+        {meta && (
+          <span
+            className="text-[11.5px] tabular-nums shrink-0"
+            style={{ color: 'rgb(var(--text-tertiary))' }}
+          >
+            {meta}
+          </span>
+        )}
+      </div>
+      {description && (
+        <p
+          className="text-[13px] leading-[1.45]"
+          style={{ color: 'rgb(var(--text-tertiary))' }}
+        >
+          {description}
+        </p>
+      )}
+    </header>
+  )
+}
+
+// ─── Shell.TrayBody ─────────────────────────────────────────────────
+
+export interface ShellTrayBodyProps extends HTMLAttributes<HTMLDivElement> {
+  /** Vertical gap between children. Default `form` (16px). `grid`
+   *  (14px) is for tighter sub-card grids. `flush` (0) lets the
+   *  consumer manage spacing entirely. */
+  spacing?: 'form' | 'grid' | 'flush'
+  /** Tighter padding for dense layouts. */
+  compact?: boolean
+}
+
+function TrayBody({
+  spacing = 'form',
+  compact,
+  className,
+  style,
+  children,
+  ...rest
+}: ShellTrayBodyProps) {
+  const gap = spacing === 'flush' ? 0 : spacing === 'grid' ? 14 : 16
+  return (
+    <div
+      data-slot="shell-tray-body"
+      className={cn('flex flex-col', className)}
+      style={{
+        padding: compact ? '12px 18px 18px' : '14px 24px 22px',
+        gap,
+        ...style,
+      }}
+      {...rest}
+    >
+      {children}
+    </div>
+  )
+}
+
+// ─── Shell.TrayFooter ───────────────────────────────────────────────
+
+export interface ShellTrayFooterProps
+  extends HTMLAttributes<HTMLDivElement> {
+  /** Tighter padding for dense layouts. */
+  compact?: boolean
+  /** Left-aligned secondary controls (toggles, disclosure, etc.).
+   *  Renders inline before any extra children. */
+  left?: ReactNode
+  /** Right-aligned primary action (button, link, etc.). Pushed to
+   *  the right edge via `margin-left: auto`. */
+  right?: ReactNode
+}
+
+function TrayFooter({
+  compact,
+  left,
+  right,
+  className,
+  style,
+  children,
+  ...rest
+}: ShellTrayFooterProps) {
+  return (
+    <div
+      data-slot="shell-tray-footer"
+      className={cn(
+        'flex items-center gap-3 flex-wrap',
+        className,
+      )}
+      style={{
+        background: 'rgb(var(--card-foot-bg))',
+        borderTop: '1px solid rgb(var(--border-card))',
+        padding: compact ? '12px 18px' : '14px 18px',
+        ...style,
+      }}
+      {...rest}
+    >
+      {left && (
+        <div className="flex items-center gap-4 flex-wrap">{left}</div>
+      )}
+      {children}
+      {right && <div className="ml-auto">{right}</div>}
+    </div>
+  )
+}
+
+// ─── Shell.SubCard ──────────────────────────────────────────────────
+// Card-inside-a-tray for grouped items (e.g. Keyword Combiner's
+// list-A / list-B sub-cards). Uses --surface-overlay-soft so it reads
+// as a sub-element of the white tray, not another framed tray.
+
+export interface ShellSubCardProps extends HTMLAttributes<HTMLDivElement> {
+  /** Optional header content rendered above the body. */
+  header?: ReactNode
+}
+
+function SubCard({
+  header,
+  className,
+  style,
+  children,
+  ...rest
+}: ShellSubCardProps) {
+  return (
+    <div
+      data-slot="shell-subcard"
+      className={cn('flex flex-col gap-3', className)}
+      style={{
+        background: 'rgb(var(--surface-overlay-soft))',
+        border: '1px solid rgb(var(--border))',
+        borderRadius: 12,
+        padding: 12,
+        ...style,
+      }}
+      {...rest}
+    >
+      {header && (
+        <div className="flex items-center justify-between gap-2 min-w-0">
+          {header}
+        </div>
+      )}
+      {children}
+    </div>
+  )
+}
+
+// ─── ShellStat (KPI card) ───────────────────────────────────────────
+// A KPI card built on the shell pattern, inverted: the metric LABEL
+// sits in the outer slate frame, the metric VALUE sits in the inner
+// white tray. Drop several into a grid for an overview row.
+
+/** Value-text tone for <ShellStat>. Semantic tones map to the public
+ *  status tokens — handy for traffic-light KPIs (e.g. competition). */
+export type ShellStatTone =
+  | 'default'
+  | 'accent'
+  | 'success'
+  | 'warning'
+  | 'destructive'
+
+const SHELL_STAT_TONE: Record<ShellStatTone, string> = {
+  default: 'rgb(var(--foreground))',
+  accent: 'rgb(var(--accent))',
+  success: 'rgb(var(--success))',
+  warning: 'rgb(var(--warning))',
+  destructive: 'rgb(var(--destructive))',
+}
+
+export interface ShellStatProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
+  /** KPI name — rendered in the outer frame, above the tray. */
+  label: ReactNode
+  /** The metric value — rendered large inside the inner white tray. */
+  value: ReactNode
+  /** Optional icon shown beside the label in the frame. */
+  icon?: ReactNode
+  /** Optional supporting text under the value (e.g. "+3 this week"). */
+  hint?: ReactNode
+  /** Value text tone — `default`, `accent`, or a semantic status
+   *  color (`success` / `warning` / `destructive`). */
+  valueTone?: ShellStatTone
+}
+
+function ShellStat({
+  label,
+  value,
+  icon,
+  hint,
+  valueTone = 'default',
+  className,
+  ...rest
+}: ShellStatProps) {
+  return (
+    // `h-full` + the flex-1 tray below let a row of ShellStats keep
+    // equal-height trays even when only some cards carry a `hint`.
+    <Shell
+      centered={false}
+      className={cn('h-full', className)}
+      {...rest}
+    >
+      <div className="flex items-center gap-1.5 px-1.5 pt-0.5">
+        {icon && (
+          <span
+            className="inline-flex shrink-0"
+            style={{ color: 'rgb(var(--text-muted))' }}
+            aria-hidden="true"
+          >
+            {icon}
+          </span>
+        )}
+        <span
+          className="text-[11px] font-bold uppercase tracking-[0.1em] truncate"
+          style={{ color: 'rgb(var(--text-secondary))' }}
+        >
+          {label}
+        </span>
+      </div>
+      {/* `justify-center` vertically centers the value block inside
+          the flex-1 tray, so a row of ShellStats keeps every number on
+          the same baseline even when only some cards carry a `hint`. */}
+      <Shell.Tray className="flex-1 justify-center">
+        <div className="flex flex-col gap-0.5 px-4 py-3.5">
+          <span
+            className="text-[26px] font-bold leading-none tabular-nums"
+            style={{
+              color: SHELL_STAT_TONE[valueTone],
+              letterSpacing: '-0.02em',
+            }}
+          >
+            {value}
+          </span>
+          {hint && (
+            <span
+              className="text-[12px]"
+              style={{ color: 'rgb(var(--text-tertiary))' }}
+            >
+              {hint}
+            </span>
+          )}
+        </div>
+      </Shell.Tray>
+    </Shell>
+  )
+}
+
+// ─── Compose the compound API ───────────────────────────────────────
+
+type ShellComponent = typeof ShellRoot & {
+  Tray: typeof Tray
+  TrayHeader: typeof TrayHeader
+  TrayBody: typeof TrayBody
+  TrayFooter: typeof TrayFooter
+  SubCard: typeof SubCard
+  Stat: typeof ShellStat
+}
+
+const Shell = ShellRoot as ShellComponent
+Shell.Tray = Tray
+Shell.TrayHeader = TrayHeader
+Shell.TrayBody = TrayBody
+Shell.TrayFooter = TrayFooter
+Shell.SubCard = SubCard
+Shell.Stat = ShellStat
+
+export { Shell, ShellStat }

package/src/slider.tsx

@@ -0,0 +1,107 @@
+/**
+ * Slider — single-value numeric slider (ADR-076 D8).
+ *
+ * Distinct from <RangeSlider>, which is dual-thumb (`value: [number,
+ * number]`) and cannot represent a single value. This is the control
+ * the Calculator Shell v2 frequency input uses: an accent fill from the
+ * track start to the current value, a `--bg-card` thumb with a 2px
+ * accent ring, and a transparent native `<input type="range">` overlaid
+ * for keyboard + accessibility (arrows / Home / End come free).
+ *
+ *   <Slider value={freq} min={1} max={10} step={0.5}
+ *           onChange={setFreq} aria-label="Target frequency" />
+ *
+ * Controlled — the parent owns `value`. Presentational otherwise.
+ */
+
+import type { CSSProperties } from 'react'
+
+export interface SliderProps {
+  value: number
+  min: number
+  max: number
+  /** Step granularity. Default 1. */
+  step?: number
+  onChange: (value: number) => void
+  /** Accessible name for the native range input. */
+  'aria-label'?: string
+  disabled?: boolean
+  className?: string
+}
+
+export function Slider({
+  value,
+  min,
+  max,
+  step = 1,
+  onChange,
+  'aria-label': ariaLabel,
+  disabled,
+  className,
+}: SliderProps) {
+  const span = max - min || 1
+  const pct = Math.max(0, Math.min(100, ((value - min) / span) * 100))
+
+  const railStyle: CSSProperties = {
+    position: 'absolute',
+    height: 7,
+    borderRadius: 'var(--radius-full)',
+  }
+
+  return (
+    <div
+      className={className}
+      style={{ position: 'relative', height: 18, display: 'flex', alignItems: 'center' }}
+    >
+      {/* base track */}
+      <div style={{ ...railStyle, left: 0, right: 0, background: 'rgb(var(--muted))' }} />
+      {/* accent fill */}
+      <div
+        style={{
+          ...railStyle,
+          left: 0,
+          width: `${pct}%`,
+          background: disabled
+            ? 'rgb(var(--border-strong))'
+            : 'rgb(var(--accent))',
+        }}
+      />
+      {/* thumb */}
+      <div
+        style={{
+          position: 'absolute',
+          left: `${pct}%`,
+          transform: 'translateX(-50%)',
+          width: 18,
+          height: 18,
+          borderRadius: 'var(--radius-full)',
+          background: 'rgb(var(--bg-card))',
+          border: `2px solid ${disabled ? 'rgb(var(--border-strong))' : 'rgb(var(--accent))'}`,
+          boxShadow: 'var(--shadow-sm)',
+          pointerEvents: 'none',
+        }}
+      />
+      {/* native range — transparent overlay for keyboard + a11y */}
+      <input
+        type="range"
+        min={min}
+        max={max}
+        step={step}
+        value={value}
+        disabled={disabled}
+        aria-label={ariaLabel}
+        aria-valuetext={String(value)}
+        onChange={(e) => onChange(Number(e.target.value))}
+        style={{
+          position: 'absolute',
+          left: 0,
+          width: '100%',
+          height: 18,
+          margin: 0,
+          opacity: 0,
+          cursor: disabled ? 'not-allowed' : 'pointer',
+        }}
+      />
+    </div>
+  )
+}