@lovett/ui 0.0.5 → 0.0.7

package/src/v2/states.tsx

@@ -0,0 +1,271 @@
+/**
+ * @lovett/ui v2 — EmptyState · LoadingSkeleton · ErrorState
+ *
+ * These three live in one file because the contract between them is the
+ * whole point: **all three reserve the same box**. A region that swaps
+ * loading → error → empty → loaded must not change height at any step.
+ *
+ * The mechanism is a shared `reserve` prop feeding one `min-height`
+ * token (`--lv-state-min-h`, 216px). Give all three the same value as
+ * the loaded content's typical height and the page stops jumping.
+ *
+ * `LoadingSkeleton` additionally offers shape variants that mirror the
+ * real primitives (`stat`, `fields`, `document`), so the skeleton is
+ * genuinely the same size as what replaces it rather than a grey box of
+ * roughly the right area.
+ */
+
+import {
+  forwardRef,
+  type CSSProperties,
+  type HTMLAttributes,
+  type ReactNode,
+} from 'react'
+import { cn } from '../lib/utils'
+import { IconDanger, IconEmpty } from './icons'
+import { space } from './tokens'
+
+type StateSurface = 'none' | 'inset' | 'card'
+
+interface StateFrameProps
+  extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
+  /** Reserved min-height in px. Match this across all three states AND
+   *  to the loaded content's typical height. */
+  reserve?: number
+  surface?: StateSurface
+}
+
+function frameStyle(
+  reserve: number | undefined,
+  style: CSSProperties | undefined,
+): CSSProperties | undefined {
+  if (reserve === undefined) return style
+  return { ...style, minHeight: `${reserve}px` }
+}
+
+/* ══════════════════════════════════════════════════════════════════════
+   EmptyState
+   ══════════════════════════════════════════════════════════════════════ */
+
+export interface EmptyStateProps extends StateFrameProps {
+  title: ReactNode
+  /** One sentence saying what would be here and how it gets here. */
+  description?: ReactNode
+  icon?: ReactNode
+  /**
+   * The one thing to do about it. An empty state gets at most one
+   * primary action — if there are two ways forward, one of them is
+   * secondary.
+   */
+  actions?: ReactNode
+}
+
+export const EmptyState = forwardRef<HTMLDivElement, EmptyStateProps>(
+  function EmptyState(
+    { title, description, icon, actions, reserve, surface = 'none', className, style, ...rest },
+    ref,
+  ) {
+    return (
+      <div
+        ref={ref}
+        data-surface={surface === 'none' ? undefined : surface}
+        className={cn('lv-state', className)}
+        style={frameStyle(reserve, style)}
+        {...rest}
+      >
+        <span className="lv-state-icon">{icon ?? <IconEmpty size={18} />}</span>
+        <p className="lv-state-title">{title}</p>
+        {description && <p className="lv-state-body">{description}</p>}
+        {/* Rendered unconditionally: the action row is part of the
+            reserved box whether or not it holds a button. */}
+        <div className="lv-state-actions">{actions}</div>
+      </div>
+    )
+  },
+)
+
+/* ══════════════════════════════════════════════════════════════════════
+   ErrorState
+   ══════════════════════════════════════════════════════════════════════ */
+
+export interface ErrorStateProps extends StateFrameProps {
+  title?: ReactNode
+  /** What went wrong, in the reader's terms. */
+  description?: ReactNode
+  /**
+   * The raw error, tucked behind a disclosure. Never the headline: a
+   * stack trace is not a message. Rendered in a recessed panel.
+   */
+  detail?: string
+  detailLabel?: string
+  actions?: ReactNode
+  icon?: ReactNode
+}
+
+export const ErrorState = forwardRef<HTMLDivElement, ErrorStateProps>(
+  function ErrorState(
+    {
+      title = 'Something went wrong',
+      description,
+      detail,
+      detailLabel = 'Show details',
+      actions,
+      icon,
+      reserve,
+      surface = 'none',
+      className,
+      style,
+      ...rest
+    },
+    ref,
+  ) {
+    return (
+      <div
+        ref={ref}
+        role="alert"
+        data-tone="error"
+        data-surface={surface === 'none' ? undefined : surface}
+        className={cn('lv-state', className)}
+        style={frameStyle(reserve, style)}
+        {...rest}
+      >
+        <span className="lv-state-icon">{icon ?? <IconDanger size={18} />}</span>
+        <p className="lv-state-title">{title}</p>
+        {description && <p className="lv-state-body">{description}</p>}
+        <div className="lv-state-actions">{actions}</div>
+        {detail && (
+          <details className="lv-state-detail">
+            <summary>{detailLabel}</summary>
+            <pre>{detail}</pre>
+          </details>
+        )}
+      </div>
+    )
+  },
+)
+
+/* ══════════════════════════════════════════════════════════════════════
+   LoadingSkeleton
+   ══════════════════════════════════════════════════════════════════════ */
+
+export type SkeletonVariant = 'text' | 'block' | 'stat' | 'fields' | 'document'
+
+export interface LoadingSkeletonProps extends StateFrameProps {
+  /**
+   * Shape of the thing being loaded. Each variant mirrors the geometry
+   * of the real primitive so the swap is invisible:
+   *   text     — n lines of body copy, last one short
+   *   block    — one solid rectangle (`height`)
+   *   stat     — a StatTile's label / value / delta stack
+   *   fields   — DefinitionList rows on the shared label column
+   *   document — a section heading plus a paragraph
+   */
+  variant?: SkeletonVariant
+  /** Line/row count for `text`, `fields`, `document`. */
+  lines?: number
+  /** Height in px for `block`. */
+  height?: number
+  /** Accessible status text announced while loading. */
+  label?: string
+}
+
+function Bar({ width, height }: { width: string; height: number }) {
+  return (
+    <span className="lv-skeleton" style={{ width, height: `${height}px` }} />
+  )
+}
+
+export const LoadingSkeleton = forwardRef<HTMLDivElement, LoadingSkeletonProps>(
+  function LoadingSkeleton(
+    {
+      variant = 'text',
+      lines = 3,
+      height = 96,
+      label = 'Loading',
+      reserve,
+      surface = 'none',
+      className,
+      style,
+      ...rest
+    },
+    ref,
+  ) {
+    let content: ReactNode
+    switch (variant) {
+      case 'block':
+        content = <Bar width="100%" height={height} />
+        break
+      case 'stat':
+        content = (
+          <>
+            <Bar width="52%" height={10} />
+            <Bar width="72%" height={28} />
+            <Bar width="40%" height={10} />
+          </>
+        )
+        break
+      case 'fields':
+        content = (
+          <>
+            {Array.from({ length: lines }, (_, i) => (
+              <span
+                key={i}
+                className="lv-grid"
+                style={{
+                  gridTemplateColumns: 'var(--lv-dl-label-w) minmax(0, 1fr)',
+                  gap: space(4),
+                  alignItems: 'center',
+                  // Derived from the type scale, not guessed: this is
+                  // exactly one FieldRow's line box plus its block
+                  // padding, so the skeleton is the same height as the
+                  // rows that replace it.
+                  minHeight:
+                    'calc(var(--lv-text-sm) * var(--lv-lh-sm) + var(--lv-space-2))',
+                }}
+              >
+                <Bar width="72%" height={10} />
+                <Bar width={i % 3 === 0 ? '46%' : '84%'} height={10} />
+              </span>
+            ))}
+          </>
+        )
+        break
+      case 'document':
+        content = (
+          <>
+            <Bar width="38%" height={18} />
+            <span style={{ height: space(2) }} />
+            {Array.from({ length: lines }, (_, i) => (
+              <Bar key={i} width={i === lines - 1 ? '58%' : '100%'} height={12} />
+            ))}
+          </>
+        )
+        break
+      case 'text':
+      default:
+        content = (
+          <>
+            {Array.from({ length: lines }, (_, i) => (
+              <Bar key={i} width={i === lines - 1 ? '62%' : '100%'} height={12} />
+            ))}
+          </>
+        )
+    }
+
+    return (
+      <div
+        ref={ref}
+        role="status"
+        aria-busy="true"
+        aria-live="polite"
+        data-surface={surface === 'none' ? undefined : surface}
+        className={cn('lv-skeleton-group', className)}
+        style={frameStyle(reserve, style)}
+        {...rest}
+      >
+        <span className="lv-sr-only">{label}</span>
+        {content}
+      </div>
+    )
+  },
+)

package/src/v2/status-pill.tsx

@@ -0,0 +1,74 @@
+/**
+ * @lovett/ui v2 — StatusPill
+ *
+ * A compact state badge. The marker's SHAPE changes with the tone as
+ * well as its colour — filled dot, hollow ring, square, triangle, bar —
+ * so the pill still reads correctly in greyscale or to a colour-blind
+ * reader. Shape is the primary signal; hue reinforces it.
+ *
+ * The pill is a fixed 20px tall and never changes size between tones,
+ * states, or loading. Long labels ellipsize rather than wrapping, since
+ * a two-line pill in a table row looks broken.
+ */
+
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react'
+import { cn } from '../lib/utils'
+
+export type StatusTone =
+  | 'neutral'
+  | 'accent'
+  | 'success'
+  | 'warning'
+  | 'danger'
+  | 'info'
+
+export type MarkShape = 'dot' | 'ring' | 'square' | 'triangle' | 'bar'
+
+/**
+ * Default shape per tone. Chosen so no two commonly co-occurring states
+ * share a silhouette: `success` (dot) next to `warning` (triangle) next
+ * to `danger` (square) is legible with the colour stripped out.
+ */
+const TONE_SHAPE: Readonly<Record<StatusTone, MarkShape>> = {
+  neutral: 'ring',
+  accent: 'bar',
+  success: 'dot',
+  warning: 'triangle',
+  danger: 'square',
+  info: 'dot',
+}
+
+export interface StatusPillProps extends HTMLAttributes<HTMLSpanElement> {
+  tone?: StatusTone
+  /** Override the marker silhouette. */
+  shape?: MarkShape
+  /** Drop the marker entirely — only for pills whose label is already
+   *  unambiguous on its own (a version number, a count). */
+  hideMark?: boolean
+  children?: ReactNode
+}
+
+export const StatusPill = forwardRef<HTMLSpanElement, StatusPillProps>(
+  function StatusPill(
+    { tone = 'neutral', shape, hideMark, className, children, ...rest },
+    ref,
+  ) {
+    return (
+      <span
+        ref={ref}
+        data-tone={tone}
+        className={cn('lv-pill', className)}
+        {...rest}
+      >
+        {!hideMark && (
+          <span
+            className="lv-pill-mark"
+            data-shape={shape ?? TONE_SHAPE[tone]}
+            aria-hidden="true"
+          />
+        )}
+        <span className="lv-pill-text">{children}</span>
+      </span>
+    )
+  },
+)