@lovett/ui 0.0.4 → 0.0.6

package/src/v2/timeline.tsx

@@ -0,0 +1,81 @@
+/**
+ * @lovett/ui v2 — Timeline
+ *
+ * An ordered sequence of events with a vertical rail. The rail is one of
+ * the few places a line is the right answer: it communicates continuity
+ * between items, which spacing alone cannot do.
+ *
+ * State is carried by the marker's glyph (tick / dot / bar) as well as
+ * its colour, and the state word is exposed to screen readers. A "done"
+ * step and a "blocked" step are distinguishable with the colour removed.
+ *
+ * Marker rings are `inset` box-shadows rather than borders, so the
+ * markers stay the same 20px whatever their state — a border would grow
+ * the box and shift the rail.
+ */
+
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react'
+import { cn } from '../lib/utils'
+import { IconCheck, IconDanger, IconDot } from './icons'
+
+export type TimelineState = 'done' | 'current' | 'todo' | 'blocked'
+
+export interface TimelineItem {
+  id: string
+  title: ReactNode
+  /** Trailing metadata — a timestamp, an actor. Tabular and nowrap. */
+  meta?: ReactNode
+  description?: ReactNode
+  state?: TimelineState
+  /** Replace the default state glyph. */
+  icon?: ReactNode
+}
+
+const STATE_ICON: Readonly<Record<TimelineState, ReactNode>> = {
+  done: <IconCheck size={12} />,
+  current: <IconDot size={12} />,
+  todo: <IconDot size={10} />,
+  blocked: <IconDanger size={12} />,
+}
+
+const STATE_WORD: Readonly<Record<TimelineState, string>> = {
+  done: 'Completed',
+  current: 'In progress',
+  todo: 'Not started',
+  blocked: 'Blocked',
+}
+
+export interface TimelineProps extends HTMLAttributes<HTMLOListElement> {
+  items: readonly TimelineItem[]
+}
+
+export const Timeline = forwardRef<HTMLOListElement, TimelineProps>(
+  function Timeline({ items, className, ...rest }, ref) {
+    return (
+      <ol ref={ref} className={cn('lv-timeline', className)} {...rest}>
+        {items.map((item) => {
+          const state = item.state ?? 'todo'
+          return (
+            <li key={item.id} className="lv-timeline-item" data-state={state}>
+              <span className="lv-timeline-marker">
+                {item.icon ?? STATE_ICON[state]}
+              </span>
+              <div className="lv-timeline-content">
+                <div className="lv-timeline-titlerow">
+                  <span className="lv-timeline-title">
+                    <span className="lv-sr-only">{STATE_WORD[state]}: </span>
+                    {item.title}
+                  </span>
+                  {item.meta && <span className="lv-timeline-meta">{item.meta}</span>}
+                </div>
+                {item.description && (
+                  <div className="lv-timeline-desc">{item.description}</div>
+                )}
+              </div>
+            </li>
+          )
+        })}
+      </ol>
+    )
+  },
+)

package/src/v2/tokens.ts

@@ -0,0 +1,228 @@
+/**
+ * @lovett/ui v2 — tokens.ts
+ *
+ * The TypeScript mirror of `theme.css`. Two jobs:
+ *
+ *  1. Give components a *typed* vocabulary for the scales, so a spacing
+ *     prop can only ever be a step on the 4px grid — arbitrary values are
+ *     not expressible, which is how a spacing scale survives contact with
+ *     a deadline.
+ *  2. Carry the handful of numbers that JS genuinely needs (sticky
+ *     offsets, IntersectionObserver rootMargin) — CSS custom properties
+ *     cannot be read by an observer.
+ *
+ * If you change a value here, change it in `theme.css` too. The CSS is
+ * the source of truth for anything a browser paints; this file is the
+ * source of truth for anything TypeScript checks.
+ */
+
+/* ══════════════════════════════════════════════════════════════════════
+   Spacing — one 4px scale
+   ══════════════════════════════════════════════════════════════════════ */
+
+/** Every legal spacing step. Off-scale values are not representable. */
+export const SPACE_STEPS = [
+  0, 1, 2, 3, 4, 5, 6, 7, 8, 10, 12, 14, 16, 20, 24,
+] as const
+
+export type SpaceStep = (typeof SPACE_STEPS)[number]
+
+/** `space(4)` → `'var(--lv-space-4)'`. */
+export function space(step: SpaceStep): string {
+  return `var(--lv-space-${step})`
+}
+
+/** Pixel value of a step, for the rare case JS needs the number. */
+export const SPACE_PX: Readonly<Record<SpaceStep, number>> = {
+  0: 0,
+  1: 4,
+  2: 8,
+  3: 12,
+  4: 16,
+  5: 20,
+  6: 24,
+  7: 28,
+  8: 32,
+  10: 40,
+  12: 48,
+  14: 56,
+  16: 64,
+  20: 80,
+  24: 96,
+}
+
+/* ══════════════════════════════════════════════════════════════════════
+   Radius, type, motion
+   ══════════════════════════════════════════════════════════════════════ */
+
+export type RadiusStep = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'full'
+
+export function radius(step: RadiusStep): string {
+  return `var(--lv-radius-${step})`
+}
+
+export type TextRole =
+  | '2xs'
+  | 'xs'
+  | 'sm'
+  | 'base'
+  | 'md'
+  | 'lg'
+  | 'xl'
+  | '2xl'
+  | '3xl'
+  | 'stat'
+
+export type ElevationStep = 0 | 1 | 2 | 3 | 4
+
+export function elevation(step: ElevationStep): string {
+  return `var(--lv-elev-${step})`
+}
+
+/** The recessed-panel shadow. Distinct from the elevation ladder — it
+ *  digs down rather than lifting up. */
+export const ELEVATION_INSET = 'var(--lv-elev-inset)'
+
+export type Duration = 'instant' | 'fast' | 'base' | 'slow'
+
+export function duration(name: Duration): string {
+  return `var(--lv-dur-${name})`
+}
+
+/** `spring` is for small elements only — buttons, toggles, badges.
+ *  Never a panel, never a data value: overshoot on a number reads as
+ *  imprecise. */
+export type Easing = 'out' | 'in-out' | 'spring'
+
+export function easing(name: Easing): string {
+  return `var(--lv-ease-${name})`
+}
+
+/* ══════════════════════════════════════════════════════════════════════
+   Surfaces — the ladder
+   ══════════════════════════════════════════════════════════════════════ */
+
+/**
+ * page → shell → section → card, each one notch brighter than the tier
+ * behind it. `inset` goes the other way on purpose: a recessed panel
+ * inside a card is the system's strongest single move, and it only
+ * reads as recessed if it is actually darker.
+ */
+export type SurfaceTier =
+  | 'page'
+  | 'shell'
+  | 'section'
+  | 'card'
+  | 'inset'
+  | 'raised'
+
+export function surface(tier: SurfaceTier): string {
+  return `var(--lv-surface-${tier})`
+}
+
+export type TextTone =
+  | 'primary'
+  | 'secondary'
+  | 'tertiary'
+  | 'faint'
+  | 'disabled'
+  | 'on-accent'
+
+export function textColor(tone: TextTone): string {
+  return `var(--lv-text-${tone})`
+}
+
+/* ══════════════════════════════════════════════════════════════════════
+   Semantic tones
+   ══════════════════════════════════════════════════════════════════════ */
+
+/**
+ * Note the hue assignment: danger is burnt orange (48°), NOT red. The
+ * brand accent is red, and a red brand beside a red danger state is not
+ * distinguishable on a page that shows both. Every component below pairs
+ * its tone with an icon and a word, so the hue is never the only signal.
+ */
+export type SemanticTone = 'success' | 'warning' | 'danger' | 'info'
+
+export type Tone = SemanticTone | 'neutral' | 'accent'
+
+export function toneText(tone: SemanticTone): string {
+  return `var(--lv-${tone}-text)`
+}
+
+export function toneMark(tone: SemanticTone): string {
+  return `var(--lv-${tone}-mark)`
+}
+
+export function toneSoft(tone: SemanticTone): string {
+  return `var(--lv-${tone}-soft)`
+}
+
+/** Chart series. Constant lightness so no series outranks another. */
+export const SERIES = [
+  'var(--lv-series-1)',
+  'var(--lv-series-2)',
+  'var(--lv-series-3)',
+  'var(--lv-series-4)',
+  'var(--lv-series-5)',
+  'var(--lv-series-6)',
+  'var(--lv-series-7)',
+  'var(--lv-series-8)',
+] as const
+
+/* ══════════════════════════════════════════════════════════════════════
+   Layout constants — mirrored from theme.css because JS needs numbers
+   ══════════════════════════════════════════════════════════════════════ */
+
+/** Height of the sticky DocumentShell header. Mirrors `--lv-doc-header-h`. */
+export const DOC_HEADER_HEIGHT = 56
+
+/** Width of the DocumentShell nav rail. Mirrors `--lv-doc-nav-w`. */
+export const DOC_NAV_WIDTH = 224
+
+/** Anchor scroll offset (header + breathing room). Mirrors `--lv-scroll-offset`. */
+export const SCROLL_OFFSET = 88
+
+/** Width the two-column document layout collapses at. Mirrors the
+ *  `@media (min-width: 900px)` breakpoint — chosen because that is where
+ *  a 224px rail plus a readable measure stops fitting, not because it is
+ *  a device size. */
+export const DOC_TWO_COLUMN_MIN_WIDTH = 900
+
+/* ══════════════════════════════════════════════════════════════════════
+   Shared prop shapes
+   ══════════════════════════════════════════════════════════════════════ */
+
+export type AlignItems = 'start' | 'center' | 'end' | 'stretch' | 'baseline'
+export type JustifyContent =
+  | 'start'
+  | 'center'
+  | 'end'
+  | 'between'
+  | 'around'
+  | 'evenly'
+
+const ALIGN_MAP: Readonly<Record<AlignItems, string>> = {
+  start: 'flex-start',
+  center: 'center',
+  end: 'flex-end',
+  stretch: 'stretch',
+  baseline: 'baseline',
+}
+
+const JUSTIFY_MAP: Readonly<Record<JustifyContent, string>> = {
+  start: 'flex-start',
+  center: 'center',
+  end: 'flex-end',
+  between: 'space-between',
+  around: 'space-around',
+  evenly: 'space-evenly',
+}
+
+export function alignValue(align: AlignItems): string {
+  return ALIGN_MAP[align]
+}
+
+export function justifyValue(justify: JustifyContent): string {
+  return JUSTIFY_MAP[justify]
+}

package/src/value-chip.tsx

@@ -0,0 +1,76 @@
+/**
+ * ValueChip — a monospace value sitting in a recessed well.
+ *
+ * The smallest unit of the tightened v2 language: any literal value the
+ * user might want to read precisely or copy (a hex, an rgb triple, a
+ * dimension, an id, a duration) renders the same way everywhere —
+ * `--surface-inset` fill, hairline border, mono + tabular figures.
+ *
+ * Lifted from the extension's Colors/Fonts tabs, which had built this
+ * three times locally as `.panel-inset` chips.
+ *
+ * Pass `copyValue` to make it a button that copies and toasts. Without
+ * it the chip is inert text and renders as a <span>, so a read-only
+ * value never advertises an interaction it doesn't have.
+ */
+import { forwardRef, type ButtonHTMLAttributes, type ReactNode } from 'react'
+import { cn } from './lib/utils'
+import { copyText } from './lib/clipboard'
+
+export interface ValueChipProps
+  extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'value'> {
+  children: ReactNode
+  /** Makes the chip copyable. The toast reads "Copied <copyLabel>". */
+  copyValue?: string
+  copyLabel?: string
+  /** `sm` for dense rows (10px), `md` default (11px). */
+  size?: 'sm' | 'md'
+  /** Stretch to fill a flex row — the equal-thirds hex/rgb/hsl layout. */
+  fill?: boolean
+}
+
+export const ValueChip = forwardRef<HTMLButtonElement, ValueChipProps>(
+  function ValueChip(
+    { children, copyValue, copyLabel, size = 'md', fill, className, ...rest },
+    ref,
+  ) {
+    const shared = cn(
+      'inline-flex items-center justify-center px-2 py-1 font-mono tabular-nums truncate',
+      size === 'sm' ? 'text-[10px]' : 'text-[11px]',
+      fill && 'flex-1 min-w-0',
+      className,
+    )
+    const surface = {
+      background: 'rgb(var(--surface-inset))',
+      border: '1px solid rgb(var(--border))',
+      borderRadius: 'var(--radius-sm)',
+      color: 'rgb(var(--text-secondary))',
+    } as const
+
+    if (!copyValue) {
+      return (
+        <span className={shared} style={surface}>
+          {children}
+        </span>
+      )
+    }
+
+    return (
+      <button
+        ref={ref}
+        type="button"
+        onClick={() => void copyText(copyValue, copyLabel)}
+        className={cn(
+          shared,
+          'cursor-pointer transition-colors',
+          'hover:border-[rgb(var(--border-strong))] hover:text-[rgb(var(--foreground))]',
+          'focus-visible:outline-none focus-visible:[box-shadow:var(--ring-focus)]',
+        )}
+        style={surface}
+        {...rest}
+      >
+        {children}
+      </button>
+    )
+  },
+)