@lovett/ui 0.0.5 → 0.0.7

package/src/v2/layout.tsx

@@ -0,0 +1,293 @@
+/**
+ * @lovett/ui v2 — layout primitives
+ *
+ * Stack · Inline · Grid · Section · Panel · Toolbar
+ *
+ * The whole point of these is that they make the spacing scale
+ * unavoidable. `gap` takes a step on the 4px grid and nothing else — you
+ * cannot type `gap={13}`. That single constraint removes the most common
+ * reason a nice interface feels subtly off.
+ *
+ * Grouping is done with space first, a background shape second, and a
+ * line last. `Section` and `Panel` are the background shapes; there is
+ * deliberately no `Divider` primitive, because reaching for a divider is
+ * almost always a failure of spacing.
+ */
+
+import {
+  forwardRef,
+  type CSSProperties,
+  type ForwardRefExoticComponent,
+  type HTMLAttributes,
+  type ReactNode,
+  type RefAttributes,
+} from 'react'
+import { cn } from '../lib/utils'
+import {
+  alignValue,
+  justifyValue,
+  space,
+  type AlignItems,
+  type JustifyContent,
+  type SpaceStep,
+} from './tokens'
+
+/* ══════════════════════════════════════════════════════════════════════
+   Stack — vertical flow
+   ══════════════════════════════════════════════════════════════════════ */
+
+export interface StackProps extends HTMLAttributes<HTMLDivElement> {
+  /** Gap between children, as a step on the 4px scale. */
+  gap?: SpaceStep
+  align?: AlignItems
+  justify?: JustifyContent
+  /** Inner padding, as a step on the 4px scale. */
+  padding?: SpaceStep
+  /** Fill the cross axis. */
+  grow?: boolean
+}
+
+export const Stack = forwardRef<HTMLDivElement, StackProps>(function Stack(
+  { gap = 3, align, justify, padding, grow, className, style, ...rest },
+  ref,
+) {
+  const composed: CSSProperties = {
+    gap: space(gap),
+    ...(align ? { alignItems: alignValue(align) } : null),
+    ...(justify ? { justifyContent: justifyValue(justify) } : null),
+    ...(padding !== undefined ? { padding: space(padding) } : null),
+    ...(grow ? { flex: '1 1 auto' } : null),
+    ...style,
+  }
+  return (
+    <div ref={ref} className={cn('lv-stack', className)} style={composed} {...rest} />
+  )
+})
+
+/* ══════════════════════════════════════════════════════════════════════
+   Inline — horizontal flow
+   ══════════════════════════════════════════════════════════════════════ */
+
+export interface InlineProps extends HTMLAttributes<HTMLDivElement> {
+  gap?: SpaceStep
+  align?: AlignItems
+  justify?: JustifyContent
+  padding?: SpaceStep
+  /** Allow the row to wrap. Prefer this over fixed widths: strings grow
+   *  substantially under translation, and a wrapped row survives that
+   *  where a clipped one does not. */
+  wrap?: boolean
+}
+
+export const Inline = forwardRef<HTMLDivElement, InlineProps>(function Inline(
+  { gap = 2, align = 'center', justify, padding, wrap, className, style, ...rest },
+  ref,
+) {
+  const composed: CSSProperties = {
+    gap: space(gap),
+    alignItems: alignValue(align),
+    ...(justify ? { justifyContent: justifyValue(justify) } : null),
+    ...(padding !== undefined ? { padding: space(padding) } : null),
+    ...(wrap ? { flexWrap: 'wrap' } : null),
+    ...style,
+  }
+  return (
+    <div ref={ref} className={cn('lv-inline', className)} style={composed} {...rest} />
+  )
+})
+
+/* ══════════════════════════════════════════════════════════════════════
+   Grid
+   ══════════════════════════════════════════════════════════════════════ */
+
+export interface GridProps extends HTMLAttributes<HTMLDivElement> {
+  gap?: SpaceStep
+  /** Fixed column count. Ignored when `minColumnWidth` is set. */
+  columns?: number
+  /**
+   * Responsive auto-fit: columns are added as space allows, each at
+   * least this wide (px). Preferred over `columns` + breakpoints —
+   * it breaks where the content stops fitting rather than at a device
+   * preset.
+   */
+  minColumnWidth?: number
+  align?: AlignItems
+}
+
+export const Grid = forwardRef<HTMLDivElement, GridProps>(function Grid(
+  { gap = 3, columns, minColumnWidth, align, className, style, ...rest },
+  ref,
+) {
+  const template =
+    minColumnWidth !== undefined
+      ? `repeat(auto-fit, minmax(min(${minColumnWidth}px, 100%), 1fr))`
+      : `repeat(${columns ?? 2}, minmax(0, 1fr))`
+
+  const composed: CSSProperties = {
+    gap: space(gap),
+    gridTemplateColumns: template,
+    ...(align ? { alignItems: alignValue(align) } : null),
+    ...style,
+  }
+  return (
+    <div ref={ref} className={cn('lv-grid', className)} style={composed} {...rest} />
+  )
+})
+
+/* ══════════════════════════════════════════════════════════════════════
+   Section — a titled region, one tier up the surface ladder
+   ══════════════════════════════════════════════════════════════════════ */
+
+export interface SectionProps
+  extends Omit<HTMLAttributes<HTMLElement>, 'title'> {
+  title?: ReactNode
+  /** Small uppercase kicker above the title. */
+  eyebrow?: ReactNode
+  description?: ReactNode
+  /**
+   * Trailing controls. Keep this to secondary and ghost actions — a view
+   * gets exactly one primary action, and it is rarely in a section head.
+   */
+  actions?: ReactNode
+  /** Drop the surface and padding; keep only the heading structure. */
+  flush?: boolean
+  padding?: SpaceStep
+}
+
+export const Section = forwardRef<HTMLElement, SectionProps>(function Section(
+  {
+    title,
+    eyebrow,
+    description,
+    actions,
+    flush,
+    padding,
+    className,
+    style,
+    children,
+    ...rest
+  },
+  ref,
+) {
+  const hasHead = Boolean(title || eyebrow || description || actions)
+  const composed: CSSProperties = {
+    ...(padding !== undefined ? { padding: space(padding) } : null),
+    ...style,
+  }
+  return (
+    <section
+      ref={ref}
+      data-flush={flush ? 'true' : undefined}
+      className={cn('lv-section', className)}
+      style={composed}
+      {...rest}
+    >
+      {hasHead && (
+        <div className="lv-section-head">
+          <div style={{ minWidth: 0 }}>
+            {eyebrow && <div className="lv-section-eyebrow">{eyebrow}</div>}
+            {title && <h2 className="lv-section-title">{title}</h2>}
+            {description && <p className="lv-section-desc">{description}</p>}
+          </div>
+          {/* The actions slot is rendered whenever there is a head, so a
+              section that gains a button later does not jump. */}
+          <div
+            className="lv-inline"
+            style={{ gap: space(2), alignItems: 'center', flex: '0 0 auto' }}
+          >
+            {actions}
+          </div>
+        </div>
+      )}
+      {children}
+    </section>
+  )
+})
+
+/* ══════════════════════════════════════════════════════════════════════
+   Panel — the recessed inset
+   ══════════════════════════════════════════════════════════════════════ */
+
+export type PanelTone = 'inset' | 'quiet' | 'raised'
+
+export interface PanelProps extends HTMLAttributes<HTMLDivElement> {
+  /**
+   * `inset` (default) is the recessed panel: a hole cut into the surface
+   * holding it. This is the strongest single move in the system — use it
+   * for the thing inside a card that the reader is actually here for
+   * (the extracted quote, the computed figure, the diff).
+   *
+   * `quiet` is a hairline outline with no fill, for when a recess would
+   * be too much. `raised` lifts instead, for a tray floating over a
+   * section.
+   */
+  tone?: PanelTone
+  padding?: SpaceStep
+}
+
+export const Panel = forwardRef<HTMLDivElement, PanelProps>(function Panel(
+  { tone = 'inset', padding, className, style, ...rest },
+  ref,
+) {
+  const composed: CSSProperties = {
+    ...(padding !== undefined ? { padding: space(padding) } : null),
+    ...style,
+  }
+  return (
+    <div
+      ref={ref}
+      data-tone={tone}
+      className={cn('lv-panel', className)}
+      style={composed}
+      {...rest}
+    />
+  )
+})
+
+/* ══════════════════════════════════════════════════════════════════════
+   Toolbar
+   ══════════════════════════════════════════════════════════════════════ */
+
+export interface ToolbarProps extends HTMLAttributes<HTMLDivElement> {
+  /** Stick to the top of the scroll container. Controls float above the
+   *  content layer; they never dam it. */
+  sticky?: boolean
+  'aria-label': string
+}
+
+interface ToolbarComponent
+  extends ForwardRefExoticComponent<
+    ToolbarProps & RefAttributes<HTMLDivElement>
+  > {
+  /** Pushes everything after it to the trailing edge. */
+  Spacer: typeof ToolbarSpacer
+  /** A structural rule between control groups. Try a Spacer first. */
+  Divider: typeof ToolbarDivider
+}
+
+const ToolbarRoot = forwardRef<HTMLDivElement, ToolbarProps>(function Toolbar(
+  { sticky, className, ...rest },
+  ref,
+) {
+  return (
+    <div
+      ref={ref}
+      role="toolbar"
+      data-sticky={sticky ? 'true' : undefined}
+      className={cn('lv-toolbar', className)}
+      {...rest}
+    />
+  )
+})
+
+function ToolbarSpacer() {
+  return <div className="lv-toolbar-spacer" aria-hidden="true" />
+}
+
+function ToolbarDivider() {
+  return <div className="lv-toolbar-divider" role="separator" aria-orientation="vertical" />
+}
+
+export const Toolbar = ToolbarRoot as ToolbarComponent
+Toolbar.Spacer = ToolbarSpacer
+Toolbar.Divider = ToolbarDivider

package/src/v2/progress-track.tsx

@@ -0,0 +1,89 @@
+/**
+ * @lovett/ui v2 — ProgressTrack
+ *
+ * The track is a recessed groove — the inset treatment in miniature —
+ * with the fill sitting in it. That reads as measurement; a raised bar
+ * on a raised surface reads as decoration.
+ *
+ * Two layout-stability rules are load-bearing here:
+ *  - The percentage sits in a 4ch slot with tabular figures, so 9% → 100%
+ *    never nudges the label beside it.
+ *  - The label row exists whether or not a label was passed, so adding
+ *    one later does not shift the bar down.
+ *
+ * The fill eases (never springs) to its new value: overshoot on a
+ * measured quantity reads as imprecise, which is the opposite of what a
+ * progress bar is for.
+ */
+
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react'
+import { cn } from '../lib/utils'
+
+export type ProgressTone = 'accent' | 'success' | 'warning' | 'danger' | 'neutral'
+
+export interface ProgressTrackProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+  /** 0–100. Clamped. Ignored when `indeterminate`. */
+  value?: number
+  label?: ReactNode
+  tone?: ProgressTone
+  /** Hide the numeric readout (keeps the reserved slot, so nothing
+   *  moves if it comes back). */
+  hideValue?: boolean
+  /**
+   * Work of unknown duration. Under `prefers-reduced-motion` this shows
+   * a static partial fill rather than a frozen animation — the final
+   * state, not a paused one.
+   */
+  indeterminate?: boolean
+  /** Accessible name when `label` is omitted or non-textual. */
+  'aria-label'?: string
+}
+
+function clamp(n: number): number {
+  if (Number.isNaN(n)) return 0
+  return Math.min(100, Math.max(0, n))
+}
+
+export const ProgressTrack = forwardRef<HTMLDivElement, ProgressTrackProps>(
+  function ProgressTrack(
+    {
+      value = 0,
+      label,
+      tone = 'accent',
+      hideValue = false,
+      indeterminate = false,
+      className,
+      'aria-label': ariaLabel,
+      ...rest
+    },
+    ref,
+  ) {
+    const pct = clamp(value)
+    return (
+      <div ref={ref} data-tone={tone} className={cn('lv-progress', className)} {...rest}>
+        <div className="lv-progress-head">
+          <span className="lv-progress-label">{label}</span>
+          {/* Slot is always rendered; only its contents change. */}
+          <span className="lv-progress-value" aria-hidden="true">
+            {indeterminate || hideValue ? '' : `${Math.round(pct)}%`}
+          </span>
+        </div>
+        <div
+          className="lv-progress-track"
+          role="progressbar"
+          aria-valuemin={indeterminate ? undefined : 0}
+          aria-valuemax={indeterminate ? undefined : 100}
+          aria-valuenow={indeterminate ? undefined : Math.round(pct)}
+          aria-label={ariaLabel}
+        >
+          {indeterminate ? (
+            <span className="lv-progress-indeterminate" />
+          ) : (
+            <div className="lv-progress-fill" style={{ width: `${pct}%` }} />
+          )}
+        </div>
+      </div>
+    )
+  },
+)

package/src/v2/stat-tile.tsx

@@ -0,0 +1,129 @@
+/**
+ * @lovett/ui v2 — StatTile
+ *
+ * A metric that holds still. Two mechanics do all the work:
+ *
+ *  1. `tabular-nums` on the value, so digits are the same width and a
+ *     counter going 1 → 8 does not jitter.
+ *  2. A reserved `min-width` slot sized in `ch` for the LARGEST plausible
+ *     value, so 9 → 10 → 100 → 1,284,930 never reflows the tile or its
+ *     neighbours. Set `slots` to the character count of your worst case
+ *     (including separators). Default 6.
+ *
+ * The delta row is always in the box. When there is no delta it is
+ * `visibility: hidden`, not removed — `display: none` would resize the
+ * tile the moment a comparison period loaded.
+ *
+ * Direction is carried by an arrow glyph AND the sign in the label, so
+ * green/orange is never the only thing telling you which way it went.
+ */
+
+import { forwardRef, type CSSProperties, type HTMLAttributes, type ReactNode } from 'react'
+import { cn } from '../lib/utils'
+import { IconArrowDown, IconArrowUp, IconFlat } from './icons'
+import { space } from './tokens'
+
+export type DeltaTone = 'up' | 'down' | 'flat'
+
+export interface StatTileProps extends HTMLAttributes<HTMLDivElement> {
+  label: string
+  /**
+   * The value. Pass a pre-formatted string — formatting is a product
+   * decision (locale, precision, abbreviation) and does not belong in a
+   * design primitive.
+   */
+  value?: ReactNode
+  /** Suffix rendered small and muted beside the value: `%`, `ms`, `/mo`. */
+  unit?: ReactNode
+  /**
+   * Character width of the largest plausible value, including thousands
+   * separators and any sign. `1,284,930` is 9. Getting this right is the
+   * difference between a dashboard that holds still and one that
+   * breathes on every poll.
+   */
+  slots?: number
+  /** Change vs. the comparison period, pre-formatted: `+12.4%`. */
+  delta?: string
+  deltaTone?: DeltaTone
+  /** Muted note on the foot row: `vs. last 30 days`. */
+  hint?: ReactNode
+  /** Render on the recessed inset surface instead of a raised card. Use
+   *  inside a card; the raised default is for a bare section. */
+  inset?: boolean
+  /** Swap the value for a skeleton of the same size. Nothing moves. */
+  loading?: boolean
+}
+
+const DELTA_ICON: Readonly<Record<DeltaTone, (props: { size?: number }) => ReactNode>> = {
+  up: (props) => <IconArrowUp {...props} />,
+  down: (props) => <IconArrowDown {...props} />,
+  flat: (props) => <IconFlat {...props} />,
+}
+
+export const StatTile = forwardRef<HTMLDivElement, StatTileProps>(
+  function StatTile(
+    {
+      label,
+      value,
+      unit,
+      slots = 6,
+      delta,
+      deltaTone = 'flat',
+      hint,
+      inset,
+      loading = false,
+      className,
+      style,
+      ...rest
+    },
+    ref,
+  ) {
+    const hasFoot = Boolean(delta || hint)
+    const composed = {
+      ...style,
+      '--lv-stat-slots': slots,
+    } as CSSProperties
+
+    return (
+      <div
+        ref={ref}
+        data-inset={inset ? 'true' : undefined}
+        className={cn('lv-stat', className)}
+        style={composed}
+        {...rest}
+      >
+        <div className="lv-stat-label" title={label}>
+          {label}
+        </div>
+
+        <div className="lv-stat-valuerow">
+          {loading ? (
+            <span
+              className="lv-skeleton"
+              style={{ width: `${slots}ch`, height: '1em', alignSelf: 'center' }}
+              aria-hidden="true"
+            />
+          ) : (
+            <span className="lv-stat-value">{value ?? '—'}</span>
+          )}
+          {unit && <span className="lv-stat-unit">{unit}</span>}
+        </div>
+
+        {/* Reserved regardless — see the header comment. */}
+        <div className="lv-stat-footrow" data-hidden={hasFoot ? undefined : 'true'}>
+          {delta && (
+            <span
+              className="lv-stat-delta lv-inline"
+              data-tone={deltaTone}
+              style={{ gap: space(1), alignItems: 'center' }}
+            >
+              {DELTA_ICON[deltaTone]({ size: 12 })}
+              <span>{delta}</span>
+            </span>
+          )}
+          {hint && <span className="lv-stat-hint">{hint}</span>}
+        </div>
+      </div>
+    )
+  },
+)