@lovett/ui 0.0.4 → 0.0.6

package/src/v2/action.tsx

@@ -0,0 +1,91 @@
+/**
+ * @lovett/ui v2 — Action
+ *
+ * The v2 button. It exists because every other v2 primitive that offers
+ * an affordance (Callout, EmptyState, ErrorState, DocumentShell header,
+ * Section head) needs one, and pulling in the v1 `Button` would drag
+ * v1's whole stylesheet into a v2 page.
+ *
+ * The rule this component is built to enforce: **exactly one `primary`
+ * per view**. The accent earns its impact from scarcity; a screen with
+ * three filled red buttons has no primary action at all. Everything that
+ * is not *the* action is `secondary`, `ghost`, or `danger`.
+ *
+ * Size is invariant across every state. Loading keeps the label in the
+ * DOM (holding the width) and hides it behind a spinner; disabled only
+ * changes paint. The button never resizes under the pointer.
+ */
+
+import { forwardRef, type ButtonHTMLAttributes, type ReactNode } from 'react'
+import { cn } from '../lib/utils'
+import { space } from './tokens'
+
+export type ActionVariant = 'primary' | 'secondary' | 'ghost' | 'danger'
+export type ActionSize = 'sm' | 'md' | 'lg'
+
+export interface ActionProps
+  extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
+  variant?: ActionVariant
+  size?: ActionSize
+  /** Shows the spinner and blocks interaction. The box does not resize. */
+  loading?: boolean
+  /** Leading icon. Stroke weight should match the label weight (1.5). */
+  icon?: ReactNode
+  /** Trailing icon. */
+  trailingIcon?: ReactNode
+  children?: ReactNode
+  /**
+   * Required when the button has no visible label — an icon-only control
+   * with no accessible name is invisible to a screen reader.
+   */
+  'aria-label'?: string
+}
+
+export const Action = forwardRef<HTMLButtonElement, ActionProps>(function Action(
+  {
+    variant = 'secondary',
+    size = 'md',
+    loading = false,
+    icon,
+    trailingIcon,
+    disabled,
+    className,
+    children,
+    type = 'button',
+    ...rest
+  },
+  ref,
+) {
+  const iconOnly = children === undefined || children === null || children === ''
+
+  return (
+    <button
+      ref={ref}
+      type={type}
+      data-variant={variant}
+      data-size={size}
+      data-loading={loading ? 'true' : undefined}
+      data-icon-only={iconOnly ? 'true' : undefined}
+      disabled={disabled || loading}
+      aria-busy={loading || undefined}
+      className={cn('lv-action', className)}
+      {...rest}
+    >
+      {/* Wrapped together so the spinner can cover label AND icons
+          without any of them leaving the layout. */}
+      <span
+        className="lv-action-label lv-inline"
+        style={{ alignItems: 'center', gap: space(2) }}
+      >
+        {icon}
+        {children}
+        {trailingIcon}
+      </span>
+      {loading && (
+        <span className="lv-action-spinner">
+          <span className="lv-spin" />
+        </span>
+      )}
+    </button>
+  )
+})

package/src/v2/callout.tsx

@@ -0,0 +1,76 @@
+/**
+ * @lovett/ui v2 — Callout
+ *
+ * An aside that carries a state: info, success, warn, danger.
+ *
+ * Every tone ships with a default icon and every icon has a distinct
+ * silhouette (circle / circled-check / triangle / octagon), so the tone
+ * survives greyscale, colour-blindness, and a low-quality projector.
+ * Colour is never the only signal — that is not a nicety here, it is the
+ * reason `danger` is burnt orange rather than red: the house accent is
+ * red, and two reds on one page cannot be told apart.
+ *
+ * The tone is drawn as a 2px leading rule plus a soft tinted fill, not a
+ * full border. A boxed callout reads as a form field; a ruled one reads
+ * as an aside, which is what it is.
+ */
+
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react'
+import { cn } from '../lib/utils'
+import { IconDanger, IconInfo, IconSuccess, IconWarning } from './icons'
+
+export type CalloutTone = 'info' | 'success' | 'warn' | 'danger'
+
+const TONE_ICON: Readonly<Record<CalloutTone, ReactNode>> = {
+  info: <IconInfo size={18} />,
+  success: <IconSuccess size={18} />,
+  warn: <IconWarning size={18} />,
+  danger: <IconDanger size={18} />,
+}
+
+/** Screen-reader prefix. The tone must reach a non-visual reader too. */
+const TONE_WORD: Readonly<Record<CalloutTone, string>> = {
+  info: 'Note',
+  success: 'Success',
+  warn: 'Warning',
+  danger: 'Error',
+}
+
+export interface CalloutProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
+  tone?: CalloutTone
+  title?: ReactNode
+  /**
+   * Replace the default tone icon. Keep a distinct silhouette — the
+   * icon, not the hue, is what makes the tone legible.
+   */
+  icon?: ReactNode
+  /** Trailing controls. Ghost or secondary; never the view's primary. */
+  actions?: ReactNode
+  children?: ReactNode
+}
+
+export const Callout = forwardRef<HTMLDivElement, CalloutProps>(function Callout(
+  { tone = 'info', title, icon, actions, className, children, ...rest },
+  ref,
+) {
+  return (
+    <div
+      ref={ref}
+      data-tone={tone}
+      // `alert` for the two tones a reader must not miss; `note` for the
+      // two they can read in document order.
+      role={tone === 'danger' || tone === 'warn' ? 'alert' : 'note'}
+      className={cn('lv-callout', className)}
+      {...rest}
+    >
+      <span className="lv-callout-icon">{icon ?? TONE_ICON[tone]}</span>
+      <div style={{ minWidth: 0 }}>
+        <span className="lv-sr-only">{TONE_WORD[tone]}: </span>
+        {title && <p className="lv-callout-title">{title}</p>}
+        {children && <div className="lv-callout-body">{children}</div>}
+        {actions && <div className="lv-callout-actions">{actions}</div>}
+      </div>
+    </div>
+  )
+})

package/src/v2/document-section.tsx

@@ -0,0 +1,82 @@
+/**
+ * @lovett/ui v2 — DocumentSection
+ *
+ * A headed, anchored region inside a `DocumentShell`. The `id` is both
+ * the URL fragment and the key the shell's scroll-spy matches on, so it
+ * must equal the `id` of the matching entry in `sections`.
+ *
+ * `tabIndex={-1}` is deliberate: the shell moves focus here when a rail
+ * item is clicked, so keyboard users land in the same place the scroll
+ * did. It never enters the tab order on its own.
+ */
+
+import {
+  forwardRef,
+  type HTMLAttributes,
+  type ReactNode,
+} from 'react'
+import { cn } from '../lib/utils'
+import { space } from './tokens'
+
+export interface DocumentSectionProps
+  extends Omit<HTMLAttributes<HTMLElement>, 'title'> {
+  /** Anchor id. Must match the `DocumentShell` nav entry. */
+  id: string
+  title: ReactNode
+  description?: ReactNode
+  /**
+   * Trailing controls for this section. Secondary/ghost only — the one
+   * primary action on a document belongs in the shell header.
+   */
+  actions?: ReactNode
+  children?: ReactNode
+}
+
+export const DocumentSection = forwardRef<HTMLElement, DocumentSectionProps>(
+  function DocumentSection(
+    { id, title, description, actions, className, children, ...rest },
+    ref,
+  ) {
+    const headingId = `${id}-heading`
+    return (
+      <section
+        ref={ref}
+        id={id}
+        data-lv-section={id}
+        tabIndex={-1}
+        aria-labelledby={headingId}
+        className={cn('lv-docsection', className)}
+        {...rest}
+      >
+        <div className="lv-docsection-head">
+          <div style={{ minWidth: 0 }}>
+            <h2 id={headingId} className="lv-docsection-title">
+              {title}
+            </h2>
+            {description && <p className="lv-docsection-desc">{description}</p>}
+          </div>
+          {/* Always rendered. A section that gains an action later must
+              not change height when it does. */}
+          <div
+            className="lv-inline"
+            style={{ gap: space(2), alignItems: 'center', flex: '0 0 auto' }}
+          >
+            {actions}
+          </div>
+        </div>
+        <div className="lv-docsection-body">{children}</div>
+      </section>
+    )
+  },
+)
+
+/**
+ * Long-form body copy inside a document. Capped at ~68 characters so the
+ * eye can find the next line, and `text-wrap: pretty` so the last line
+ * never strands a single word.
+ */
+export const Prose = forwardRef<HTMLDivElement, HTMLAttributes<HTMLDivElement>>(
+  function Prose({ className, ...rest }, ref) {
+    return <div ref={ref} className={cn('lv-prose', className)} {...rest} />
+  },
+)

package/src/v2/field-row.tsx

@@ -0,0 +1,113 @@
+/**
+ * @lovett/ui v2 — FieldRow / DefinitionList
+ *
+ * Label/value pairs on a shared alignment grid. Every row in the app
+ * uses the same label-column width token (`--lv-dl-label-w`), so labels
+ * and values line up across unrelated components — a section heading's
+ * left edge, the field labels below it, and the footer text all sit on
+ * the same column. That shared edge is most of what makes a dense page
+ * read as designed rather than assembled.
+ *
+ * Below 640px the grid stacks instead of truncating: the value is what
+ * the reader came for, and squeezing it to fit a label column is the
+ * wrong trade.
+ *
+ * A `<div>` grouping `<dt>`/`<dd>` inside a `<dl>` is valid HTML, which
+ * is what lets each row be its own grid while still sharing one column
+ * width.
+ */
+
+import {
+  forwardRef,
+  type CSSProperties,
+  type HTMLAttributes,
+  type ReactNode,
+} from 'react'
+import { cn } from '../lib/utils'
+
+export interface DefinitionListProps extends HTMLAttributes<HTMLDListElement> {
+  /**
+   * Draw hairlines between rows. Off by default — spacing groups these
+   * perfectly well, and a rule per row is the most common way a clean
+   * detail panel turns into a spreadsheet.
+   */
+  dividers?: boolean
+  /** Override the shared label column width (px). Applies to every row
+   *  inside this list. */
+  labelWidth?: number
+  children?: ReactNode
+}
+
+export const DefinitionList = forwardRef<HTMLDListElement, DefinitionListProps>(
+  function DefinitionList({ dividers, labelWidth, className, style, ...rest }, ref) {
+    return (
+      <dl
+        ref={ref}
+        data-dividers={dividers ? 'true' : undefined}
+        className={cn('lv-dl', className)}
+        style={
+          labelWidth !== undefined
+            ? // A custom property is the only way to reach every nested
+              // row without prop-drilling; the cast is confined here.
+              ({ ...style, '--lv-dl-label-w': `${labelWidth}px` } as CSSProperties)
+            : style
+        }
+        {...rest}
+      />
+    )
+  },
+)
+
+export interface FieldRowProps extends HTMLAttributes<HTMLDivElement> {
+  label: ReactNode
+  /**
+   * The value. When `undefined` or `null` the row still renders at full
+   * height with the `emptyText` placeholder — a missing field must not
+   * change the shape of the panel around it.
+   */
+  value?: ReactNode
+  /** Shown when `value` is nullish. */
+  emptyText?: string
+  /** Small note under the value. */
+  hint?: ReactNode
+  /** Force the stacked layout regardless of width. */
+  layout?: 'inline' | 'stacked'
+  /** Render the value with tabular figures. Use for anything comparable
+   *  down a column — IDs, counts, dates, money. */
+  numeric?: boolean
+}
+
+export const FieldRow = forwardRef<HTMLDivElement, FieldRowProps>(
+  function FieldRow(
+    {
+      label,
+      value,
+      emptyText = '—',
+      hint,
+      layout = 'inline',
+      numeric,
+      className,
+      ...rest
+    },
+    ref,
+  ) {
+    const isEmpty = value === undefined || value === null || value === ''
+    return (
+      <div
+        ref={ref}
+        data-layout={layout}
+        className={cn('lv-field-row', className)}
+        {...rest}
+      >
+        <dt className="lv-field-label">{label}</dt>
+        <dd
+          className={cn('lv-field-value', numeric && 'lv-num')}
+          data-empty={isEmpty ? 'true' : undefined}
+        >
+          {isEmpty ? emptyText : value}
+          {hint && <span className="lv-field-hint">{hint}</span>}
+        </dd>
+      </div>
+    )
+  },
+)

package/src/v2/icons.tsx

@@ -0,0 +1,165 @@
+/**
+ * @lovett/ui v2 — icons.tsx
+ *
+ * A deliberately tiny inline icon set. Two reasons it exists rather than
+ * reaching for `lucide-react`:
+ *
+ *  1. Semantic components (Callout, StatusPill, ErrorState) MUST carry an
+ *     icon — colour is never allowed to be the only signal for a state.
+ *     That guarantee cannot depend on the consumer having installed an
+ *     icon library or on which one they picked.
+ *  2. Stroke weight is a typography decision. These are all authored at
+ *     `1.5` so they sit correctly beside regular/medium UI text; a
+ *     hairline icon beside semibold text reads as a rendering bug.
+ *
+ * Every icon is one SVG using `currentColor`. States (hover, active,
+ * disabled) come from CSS colour and opacity — never a second asset.
+ * Consumers who prefer their own set can pass an `icon` prop anywhere
+ * one of these is used as a default.
+ */
+
+import type { SVGProps } from 'react'
+
+export interface IconProps extends Omit<SVGProps<SVGSVGElement>, 'children'> {
+  /** Square edge length in px. Defaults to 16 — the size that pairs with
+   *  `--lv-text-sm`. */
+  size?: number
+}
+
+function iconAttrs({ size = 16, ...rest }: IconProps): SVGProps<SVGSVGElement> {
+  return {
+    width: size,
+    height: size,
+    viewBox: '0 0 24 24',
+    fill: 'none',
+    stroke: 'currentColor',
+    strokeWidth: 1.5,
+    strokeLinecap: 'round',
+    strokeLinejoin: 'round',
+    'aria-hidden': true,
+    focusable: false,
+    ...rest,
+  }
+}
+
+/** Info — the neutral aside. */
+export function IconInfo(props: IconProps) {
+  return (
+    <svg {...iconAttrs(props)}>
+      <circle cx="12" cy="12" r="9" />
+      <path d="M12 11v5" />
+      <path d="M12 7.75h.01" />
+    </svg>
+  )
+}
+
+/** Success — a check inside a circle, not a bare tick. The enclosure is
+ *  what makes it read as a *state* rather than a selection. */
+export function IconSuccess(props: IconProps) {
+  return (
+    <svg {...iconAttrs(props)}>
+      <circle cx="12" cy="12" r="9" />
+      <path d="m8.5 12.2 2.4 2.4 4.6-5" />
+    </svg>
+  )
+}
+
+/** Warning — triangle. Shape carries the meaning even in greyscale. */
+export function IconWarning(props: IconProps) {
+  return (
+    <svg {...iconAttrs(props)}>
+      <path d="M10.3 4.3 2.9 17a2 2 0 0 0 1.7 3h14.8a2 2 0 0 0 1.7-3L13.7 4.3a2 2 0 0 0-3.4 0Z" />
+      <path d="M12 9.5v4" />
+      <path d="M12 17h.01" />
+    </svg>
+  )
+}
+
+/** Danger — octagon. Distinct silhouette from the warning triangle,
+ *  which matters more than the hue difference between them. */
+export function IconDanger(props: IconProps) {
+  return (
+    <svg {...iconAttrs(props)}>
+      <path d="M8.6 2.5h6.8l4.8 4.8v6.8l-4.8 4.8H8.6l-4.8-4.8V7.3z" />
+      <path d="M12 8v4.5" />
+      <path d="M12 16h.01" />
+    </svg>
+  )
+}
+
+/** Empty — an open, unfilled container. */
+export function IconEmpty(props: IconProps) {
+  return (
+    <svg {...iconAttrs(props)}>
+      <path d="M3 9.5 5.2 4.8A2 2 0 0 1 7 3.7h10a2 2 0 0 1 1.8 1.1L21 9.5" />
+      <path d="M3 9.5h5l1.4 2.8h5.2L16 9.5h5v8a2.5 2.5 0 0 1-2.5 2.5h-13A2.5 2.5 0 0 1 3 17.5z" />
+    </svg>
+  )
+}
+
+/** Retry. */
+export function IconRetry(props: IconProps) {
+  return (
+    <svg {...iconAttrs(props)}>
+      <path d="M20 11.5A8 8 0 1 1 17.7 6" />
+      <path d="M20.5 3.5V9H15" />
+    </svg>
+  )
+}
+
+/** Check — bare tick, for completed timeline markers. */
+export function IconCheck(props: IconProps) {
+  return (
+    <svg {...iconAttrs(props)}>
+      <path d="m5 12.5 4.5 4.5L19 7" />
+    </svg>
+  )
+}
+
+/** Chevron, trailing direction. Flip with `scaleX(-1)` under RTL. */
+export function IconChevronRight(props: IconProps) {
+  return (
+    <svg {...iconAttrs(props)}>
+      <path d="m9.5 5.5 6.5 6.5-6.5 6.5" />
+    </svg>
+  )
+}
+
+/** Arrow up — a rising delta. Paired with a sign in the label, so the
+ *  direction is never carried by colour alone. */
+export function IconArrowUp(props: IconProps) {
+  return (
+    <svg {...iconAttrs(props)}>
+      <path d="M12 19.5V5" />
+      <path d="m5.5 11.5 6.5-6.5 6.5 6.5" />
+    </svg>
+  )
+}
+
+/** Arrow down — a falling delta. */
+export function IconArrowDown(props: IconProps) {
+  return (
+    <svg {...iconAttrs(props)}>
+      <path d="M12 4.5V19" />
+      <path d="m5.5 12.5 6.5 6.5 6.5-6.5" />
+    </svg>
+  )
+}
+
+/** Flat — no change. */
+export function IconFlat(props: IconProps) {
+  return (
+    <svg {...iconAttrs(props)}>
+      <path d="M5 12h14" />
+    </svg>
+  )
+}
+
+/** Dot — the neutral timeline marker. */
+export function IconDot(props: IconProps) {
+  return (
+    <svg {...iconAttrs(props)} fill="currentColor" stroke="none">
+      <circle cx="12" cy="12" r="4" />
+    </svg>
+  )
+}

package/src/v2/index.ts

@@ -0,0 +1,147 @@
+/**
+ * @lovett/ui v2 — public surface
+ *
+ *   import { DocumentShell, StatTile, Callout } from '@lovett/ui/v2'
+ *   import '@lovett/ui/src/v2/theme.css'
+ *
+ * v2 is additive. Every token it defines is namespaced `--lv-*` and
+ * every class `.lv-*`, so `theme.css` can load alongside v1's
+ * `tokens.css` / `styles.css` without changing a single v1 pixel. A page
+ * can migrate one section at a time.
+ *
+ * See ./README.md for the surface ladder, the colour formula, the
+ * spacing scale, and when to reach for each primitive.
+ */
+
+/* ── Tokens & scales ─────────────────────────────────────────────── */
+export {
+  SPACE_STEPS,
+  SPACE_PX,
+  SERIES,
+  ELEVATION_INSET,
+  DOC_HEADER_HEIGHT,
+  DOC_NAV_WIDTH,
+  DOC_TWO_COLUMN_MIN_WIDTH,
+  SCROLL_OFFSET,
+  space,
+  radius,
+  elevation,
+  duration,
+  easing,
+  surface,
+  textColor,
+  toneText,
+  toneMark,
+  toneSoft,
+  alignValue,
+  justifyValue,
+  type SpaceStep,
+  type RadiusStep,
+  type TextRole,
+  type ElevationStep,
+  type Duration,
+  type Easing,
+  type SurfaceTier,
+  type TextTone,
+  type SemanticTone,
+  type Tone,
+  type AlignItems,
+  type JustifyContent,
+} from './tokens'
+
+/* ── Layout primitives ───────────────────────────────────────────── */
+export {
+  Stack,
+  Inline,
+  Grid,
+  Section,
+  Panel,
+  Toolbar,
+  type StackProps,
+  type InlineProps,
+  type GridProps,
+  type SectionProps,
+  type PanelProps,
+  type PanelTone,
+  type ToolbarProps,
+} from './layout'
+
+/* ── Action ──────────────────────────────────────────────────────── */
+export {
+  Action,
+  type ActionProps,
+  type ActionVariant,
+  type ActionSize,
+} from './action'
+
+/* ── Document / brief primitives ─────────────────────────────────── */
+export {
+  DocumentShell,
+  type DocumentShellProps,
+  type DocumentNavItem,
+} from './document-shell'
+
+export {
+  DocumentSection,
+  Prose,
+  type DocumentSectionProps,
+} from './document-section'
+
+export {
+  DefinitionList,
+  FieldRow,
+  type DefinitionListProps,
+  type FieldRowProps,
+} from './field-row'
+
+export { StatTile, type StatTileProps, type DeltaTone } from './stat-tile'
+
+export { Callout, type CalloutProps, type CalloutTone } from './callout'
+
+export {
+  StatusPill,
+  type StatusPillProps,
+  type StatusTone,
+  type MarkShape,
+} from './status-pill'
+
+export {
+  ProgressTrack,
+  type ProgressTrackProps,
+  type ProgressTone,
+} from './progress-track'
+
+export {
+  Timeline,
+  type TimelineProps,
+  type TimelineItem,
+  type TimelineState,
+} from './timeline'
+
+/* ── States ──────────────────────────────────────────────────────── */
+export {
+  EmptyState,
+  ErrorState,
+  LoadingSkeleton,
+  type EmptyStateProps,
+  type ErrorStateProps,
+  type LoadingSkeletonProps,
+  type SkeletonVariant,
+} from './states'
+
+/* ── Icons ───────────────────────────────────────────────────────── */
+export {
+  IconInfo,
+  IconSuccess,
+  IconWarning,
+  IconDanger,
+  IconEmpty,
+  IconRetry,
+  IconCheck,
+  IconChevronRight,
+  IconArrowUp,
+  IconArrowDown,
+  IconFlat,
+  IconDot,
+  type IconProps,
+} from './icons'