@dowel-ui/react 0.1.1 → 0.2.0

package/src/components/ai-structured-output/ai-structured-output.tsx

@@ -0,0 +1,244 @@
+"use client";
+
+import {
+  createContext,
+  useContext,
+  useMemo,
+  type ComponentPropsWithRef,
+  type ReactNode,
+} from "react";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * An object arriving field by field from the model.
+ *
+ * Most AI features inside real software are not chatbots. They are invoice
+ * extraction, CRM enrichment, resume parsing, form autofill — a schema goes in
+ * and a filled object comes back. Every one of them streams a partial object
+ * into a layout, and almost every one reflows on each token because the fields
+ * appear as they arrive.
+ *
+ * The honest limitation, stated here rather than discovered later: there is no
+ * per-field completion signal anywhere in the stack. A streaming API hands you
+ * successive partial snapshots, and a string that has stopped growing is
+ * indistinguishable from one still arriving. So this component does not pretend
+ * to know. It takes the field list up front, reserves the layout from it, and
+ * lets the caller say which fields are settled — defaulting to the rule that a
+ * field is settled once a later field has appeared, which is true of
+ * depth-first JSON streaming and is documented rather than assumed silently.
+ */
+
+export type FieldState = "pending" | "streaming" | "settled" | "error";
+
+export interface OutputField {
+  /** Key in the streamed object. */
+  name: string;
+  label: string;
+  /** Rough height reserved before the value arrives, in lines. */
+  lines?: number;
+}
+
+interface StructuredOutputContextValue {
+  fields: OutputField[];
+  value: Record<string, unknown>;
+  stateOf: (name: string) => FieldState;
+  formatValue: (value: unknown, name: string) => string;
+}
+
+const StructuredOutputContext = createContext<StructuredOutputContextValue | null>(null);
+
+function useStructuredOutputContext(component: string): StructuredOutputContextValue {
+  const context = useContext(StructuredOutputContext);
+  if (!context) {
+    throw new Error(`${component} must be rendered inside <StructuredOutput>.`);
+  }
+  return context;
+}
+
+function defaultFormat(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "bigint") return String(value);
+  if (typeof value === "boolean") return value ? "Yes" : "No";
+  if (Array.isArray(value)) return value.map(defaultFormat).join(", ");
+  return JSON.stringify(value);
+}
+
+export interface StructuredOutputProps extends Omit<ComponentPropsWithRef<"dl">, "children"> {
+  /** Declared up front, so layout is reserved before anything arrives. */
+  fields: OutputField[];
+  /** The latest partial snapshot. */
+  value: Record<string, unknown>;
+  /**
+   * True while more of the object is still expected. When false every present
+   * field is settled, which is the only completion signal that is ever certain.
+   */
+  streaming?: boolean;
+  /**
+   * Fields the caller knows are finished. Supply this when the API gives a
+   * real signal; otherwise the default rule applies.
+   */
+  settled?: string[];
+  /** Fields that failed to extract, with the reason shown in place. */
+  errors?: Record<string, string>;
+  formatValue?: (value: unknown, name: string) => string;
+  children?: ReactNode;
+}
+
+export function StructuredOutput({
+  className,
+  fields,
+  value,
+  streaming = false,
+  settled,
+  errors,
+  formatValue = defaultFormat,
+  children,
+  ...props
+}: StructuredOutputProps) {
+  const stateOf = useMemo(() => {
+    const explicit = settled ? new Set(settled) : null;
+    const lastPresentIndex = fields.reduce(
+      (last, field, index) => (value[field.name] !== undefined ? index : last),
+      -1,
+    );
+
+    return (name: string): FieldState => {
+      if (errors?.[name]) return "error";
+
+      const index = fields.findIndex((field) => field.name === name);
+      const present = value[name] !== undefined;
+
+      if (!present) return "pending";
+      if (explicit) return explicit.has(name) ? "settled" : "streaming";
+      // No explicit signal. Once a later field has appeared this one cannot
+      // still be growing, which holds for depth-first JSON streaming. The last
+      // present field stays "streaming" until the caller says streaming ended.
+      if (!streaming) return "settled";
+      return index < lastPresentIndex ? "settled" : "streaming";
+    };
+  }, [fields, value, streaming, settled, errors]);
+
+  const context = useMemo<StructuredOutputContextValue>(
+    () => ({ fields, value, stateOf, formatValue }),
+    [fields, value, stateOf, formatValue],
+  );
+
+  return (
+    <StructuredOutputContext.Provider value={context}>
+      <dl
+        data-slot="structured-output"
+        data-streaming={streaming || undefined}
+        // Fields arrive one at a time and each is a small, self-contained fact,
+        // so the region is polite and additive rather than re-reading the whole
+        // object on every token.
+        aria-live="polite"
+        aria-busy={streaming}
+        className={cn("flex flex-col gap-3", className)}
+        {...props}
+      >
+        {children ??
+          fields.map((field) => <StructuredField key={field.name} name={field.name} />)}
+      </dl>
+    </StructuredOutputContext.Provider>
+  );
+}
+
+export interface StructuredFieldProps extends Omit<ComponentPropsWithRef<"div">, "children"> {
+  name: string;
+  children?: ReactNode;
+}
+
+/**
+ * One field: its label, its value, and the space it will occupy before it has
+ * one.
+ *
+ * The reserved height is what stops the layout jumping as the object fills in.
+ */
+export function StructuredField({ className, name, children, ...props }: StructuredFieldProps) {
+  const { fields, value, stateOf, formatValue } = useStructuredOutputContext("StructuredField");
+
+  const field = fields.find((candidate) => candidate.name === name);
+  if (!field) {
+    throw new Error(`StructuredField "${name}" is not declared in the fields prop.`);
+  }
+
+  const state = stateOf(name);
+  const raw = value[name];
+
+  return (
+    <div
+      data-slot="structured-field"
+      data-state={state}
+      data-field={name}
+      className={cn("flex flex-col gap-1", className)}
+      {...props}
+    >
+      <dt className="text-xs text-muted-foreground">{field.label}</dt>
+      <dd
+        className={cn(
+          "m-0 text-sm",
+          state === "pending" && "text-muted-foreground",
+          state === "error" && "text-destructive",
+        )}
+        // Height is reserved from the declared line count so the value lands in
+        // space already set aside for it rather than pushing the page down.
+        // Computed rather than left to calc() so the reserved height is a plain
+        // value that can be asserted and reasoned about.
+        style={{ minHeight: `${String((field.lines ?? 1) * 1.25)}rem` }}
+      >
+        {state === "pending" ? (
+          <span
+            data-slot="structured-field-placeholder"
+            aria-hidden="true"
+            className="block h-4 w-24 animate-pulse-soft rounded bg-muted"
+          />
+        ) : (
+          (children ?? formatValue(raw, name))
+        )}
+      </dd>
+    </div>
+  );
+}
+
+/**
+ * A confidence score for one field.
+ *
+ * Rendered as text with the number, never as a bare colour, because "how much
+ * should I trust this" is exactly the thing a colour cannot answer.
+ */
+export function StructuredConfidence({
+  className,
+  value: confidence,
+  lowBelow = 0.7,
+  ...props
+}: ComponentPropsWithRef<"p"> & { value: number; lowBelow?: number }) {
+  const low = confidence < lowBelow;
+  const percent = new Intl.NumberFormat(undefined, {
+    style: "percent",
+    maximumFractionDigits: 0,
+  }).format(confidence);
+
+  return (
+    <p
+      data-slot="structured-confidence"
+      data-low={low || undefined}
+      className={cn("text-xs", low ? "text-warning" : "text-muted-foreground", className)}
+      {...props}
+    >
+      {low ? `Low confidence, ${percent} — worth checking` : `${percent} confidence`}
+    </p>
+  );
+}
+
+/** The reason a field could not be extracted, shown where the value would be. */
+export function StructuredFieldError({ className, ...props }: ComponentPropsWithRef<"p">) {
+  return (
+    <p
+      data-slot="structured-field-error"
+      className={cn("text-xs text-destructive", className)}
+      {...props}
+    />
+  );
+}

package/src/components/ai-structured-output/index.ts

@@ -0,0 +1,10 @@
+export {
+  StructuredConfidence,
+  StructuredField,
+  StructuredFieldError,
+  StructuredOutput,
+  type FieldState,
+  type OutputField,
+  type StructuredFieldProps,
+  type StructuredOutputProps,
+} from "./ai-structured-output";

package/src/components/ai-structured-output/meta.ts

@@ -0,0 +1,18 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "ai-structured-output",
+  title: "AI Structured Output",
+  description: "An object arriving field by field from the model, without the layout jumping.",
+  category: "ai",
+  status: "stable",
+  dependencies: [],
+  registryDependencies: [],
+  files: ["ai-structured-output.tsx"],
+  a11y:
+    "A description list, so each value is associated with its label rather than floating beside " +
+    'it. The region is aria-live="polite" with aria-busy while streaming, so fields are ' +
+    "announced as they settle instead of re-reading the whole object on every token. Height is " +
+    "reserved from the declared field list, which keeps focus and reading position stable as " +
+    "values arrive. Confidence is stated as a number in words, never as a colour alone.",
+});

package/src/components/meter/index.ts

@@ -0,0 +1,8 @@
+export {
+  Meter,
+  MeterLegend,
+  MeterValue,
+  type MeterProps,
+  type MeterSegment,
+  type MeterTone,
+} from "./meter";

package/src/components/meter/meta.ts

@@ -0,0 +1,20 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "meter",
+  title: "Meter",
+  description:
+    "A measurement against a capacity — quota, seats, spend — segmented by category.",
+  category: "feedback",
+  status: "stable",
+  dependencies: [],
+  registryDependencies: [],
+  files: ["meter.tsx"],
+  a11y:
+    'Uses role="meter", not role="progressbar": a meter reports a level with no expectation of ' +
+    "reaching the end, and screen readers phrase the two differently. The bar is one meter and " +
+    "the segments inside it are decoration — making each its own widget would put several " +
+    "unlabelled meters in the tab order to describe one quantity. aria-valuetext carries the " +
+    'unit and the capacity, because a bare "4" says nothing about 4 of what. Per-segment detail ' +
+    "lives in MeterLegend as text, where it can be read.",
+});

package/src/components/meter/meter.tsx

@@ -0,0 +1,219 @@
+"use client";
+
+import { createContext, useContext, useMemo, type ComponentPropsWithRef } from "react";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * A measurement against a known capacity: storage against a quota, seats
+ * against a plan, spend against a budget.
+ *
+ * Not a Progress. Progress reports how far along a task is and is expected to
+ * reach the end; a meter reports a level that has no reason to move at all, and
+ * where being near the top is the thing worth noticing. They carry different
+ * ARIA roles for exactly that reason, and screen readers phrase them
+ * differently.
+ *
+ * The bar is a single `role="meter"` and the segments inside it are decoration.
+ * Making each segment its own widget would put five unlabelled meters in the
+ * tab order to describe one quantity; the legend carries the per-segment detail
+ * as text instead, where it can actually be read.
+ */
+
+const TONES = {
+  primary: "bg-primary",
+  info: "bg-info",
+  success: "bg-success",
+  warning: "bg-warning",
+  destructive: "bg-destructive",
+  neutral: "bg-border-strong",
+} as const;
+
+export type MeterTone = keyof typeof TONES;
+
+export interface MeterSegment {
+  /** Stable identity, so a re-order does not re-animate every segment. */
+  id: string;
+  /** Named in the legend and in the accessible summary. */
+  label: string;
+  value: number;
+  tone?: MeterTone;
+}
+
+interface MeterContextValue {
+  segments: MeterSegment[];
+  total: number;
+  max: number;
+  format: (value: number) => string;
+  over: boolean;
+}
+
+const MeterContext = createContext<MeterContextValue | null>(null);
+
+function useMeterContext(component: string): MeterContextValue {
+  const context = useContext(MeterContext);
+  if (!context) {
+    throw new Error(`${component} must be rendered inside <Meter>.`);
+  }
+  return context;
+}
+
+function defaultFormat(value: number): string {
+  return new Intl.NumberFormat().format(value);
+}
+
+export interface MeterProps extends Omit<ComponentPropsWithRef<"div">, "children"> {
+  /** Parts making up the measurement. One segment is the ordinary case. */
+  segments: MeterSegment[];
+  /** The capacity being measured against. */
+  max: number;
+  /** Names the meter. Required — an unnamed measurement is unreadable. */
+  label: string;
+  /**
+   * Fraction of `max` past which the meter reports strain, between 0 and 1.
+   * Presentation only: it never changes the reported value.
+   */
+  warnAt?: number;
+  /** Optional marker on the track, for a soft limit or an alert threshold. */
+  threshold?: { value: number; label: string };
+  /** Formats every number that reaches the reader. */
+  format?: (value: number) => string;
+  /** Shown after the bar. Compose `MeterLegend` here, or your own summary. */
+  children?: React.ReactNode;
+}
+
+export function Meter({
+  className,
+  segments,
+  max,
+  label,
+  warnAt = 0.9,
+  threshold,
+  format = defaultFormat,
+  children,
+  ...props
+}: MeterProps) {
+  const total = segments.reduce((sum, segment) => sum + Math.max(0, segment.value), 0);
+  const over = total > max;
+  const strained = max > 0 && total / max >= warnAt;
+
+  // Widths are a share of capacity, not of the total, so a half-full meter
+  // renders half full. Dividing by the total instead would make every meter
+  // look completely full, which is the usual bug in hand-rolled versions.
+  const denominator = over ? total : max;
+
+  const context = useMemo<MeterContextValue>(
+    () => ({ segments, total, max, format, over }),
+    [segments, total, max, format, over],
+  );
+
+  return (
+    <MeterContext.Provider value={context}>
+      <div
+        data-slot="meter"
+        data-over={over || undefined}
+        data-strained={strained || undefined}
+        className={cn("flex w-full flex-col gap-1.5", className)}
+        {...props}
+      >
+        <div
+          role="meter"
+          aria-label={label}
+          aria-valuenow={total}
+          aria-valuemin={0}
+          aria-valuemax={max}
+          // Without this a screen reader announces a bare number with no unit
+          // and no capacity — "4" tells the reader nothing about 4 of what.
+          aria-valuetext={`${format(total)} of ${format(max)}${over ? ", over capacity" : ""}`}
+          data-slot="meter-track"
+          className="relative h-2 w-full overflow-hidden rounded-full bg-muted"
+        >
+          <div className="flex h-full w-full">
+            {segments.map((segment) => {
+              const value = Math.max(0, segment.value);
+              // A zero segment renders nothing at all. A one-pixel sliver reads
+              // as a small amount rather than as none.
+              if (value === 0 || denominator === 0) return null;
+
+              return (
+                <div
+                  key={segment.id}
+                  data-slot="meter-segment"
+                  data-tone={segment.tone ?? "primary"}
+                  className={cn(
+                    "h-full first:rounded-l-full last:rounded-r-full",
+                    "transition-[width] duration-[var(--duration-slow)] ease-[var(--ease-out-quint)]",
+                    TONES[segment.tone ?? "primary"],
+                  )}
+                  style={{ width: `${String((value / denominator) * 100)}%` }}
+                />
+              );
+            })}
+          </div>
+
+          {threshold && max > 0 && threshold.value > 0 && threshold.value < max ? (
+            <div
+              data-slot="meter-threshold"
+              // The marker repeats what the legend states in words, so it is
+              // decoration. Announcing it would interrupt the value.
+              aria-hidden="true"
+              className="absolute inset-y-0 w-px bg-foreground/45"
+              style={{ left: `${String((threshold.value / denominator) * 100)}%` }}
+            />
+          ) : null}
+        </div>
+
+        {children}
+      </div>
+    </MeterContext.Provider>
+  );
+}
+
+/**
+ * The per-segment breakdown, as text.
+ *
+ * This is where the detail lives. The bar communicates one number; anyone who
+ * needs to know that images account for most of it reads it here.
+ */
+export function MeterLegend({ className, ...props }: ComponentPropsWithRef<"ul">) {
+  const { segments, format } = useMeterContext("MeterLegend");
+
+  return (
+    <ul
+      data-slot="meter-legend"
+      className={cn("flex flex-wrap gap-x-4 gap-y-1 text-xs", className)}
+      {...props}
+    >
+      {segments.map((segment) => (
+        <li key={segment.id} className="flex items-center gap-1.5">
+          <span
+            aria-hidden="true"
+            className={cn("size-2 shrink-0 rounded-full", TONES[segment.tone ?? "primary"])}
+          />
+          <span className="text-muted-foreground">{segment.label}</span>
+          <span className="tabular-nums">{format(segment.value)}</span>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+/** The headline "4.2 GB of 10 GB" line, with an over-capacity state. */
+export function MeterValue({ className, ...props }: ComponentPropsWithRef<"p">) {
+  const { total, max, format, over } = useMeterContext("MeterValue");
+
+  return (
+    <p
+      data-slot="meter-value"
+      className={cn(
+        "text-xs tabular-nums",
+        over ? "text-destructive" : "text-muted-foreground",
+        className,
+      )}
+      {...props}
+    >
+      {format(total)} of {format(max)}
+      {over ? " — over capacity" : null}
+    </p>
+  );
+}

package/src/components/metric-delta/index.ts

@@ -0,0 +1,6 @@
+export {
+  MetricDelta,
+  deltaVariants,
+  type MetricDeltaProps,
+  type MetricPolarity,
+} from "./metric-delta";

package/src/components/metric-delta/meta.ts

@@ -0,0 +1,18 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "metric-delta",
+  title: "Metric Delta",
+  description: "A headline number with a change indicator that knows which direction is good.",
+  category: "data",
+  status: "stable",
+  dependencies: ["class-variance-authority"],
+  registryDependencies: [],
+  files: ["metric-delta.tsx"],
+  a11y:
+    "The meaning is never carried by colour and an arrow alone, which fails WCAG 1.4.1 — the " +
+    "direction and the comparison are always stated in text. The tile reads as one sentence " +
+    "rather than three fragments: the visible number and delta are aria-hidden and a single " +
+    "screen-reader description carries value, direction, comparison and, where given, sample " +
+    "size. A zero baseline is announced as having no percentage rather than as an infinite one.",
+});