@dowel-ui/react 0.1.0 → 0.2.0

package/src/components/metric-delta/metric-delta.tsx

@@ -0,0 +1,180 @@
+"use client";
+
+import { cva, type VariantProps } from "class-variance-authority";
+import type { ComponentPropsWithRef } from "react";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * A headline number with an honest change indicator.
+ *
+ * The visual is a commodity; the correctness is not. Three things go wrong in
+ * almost every hand-rolled version, and all three are handled here:
+ *
+ * 1. Direction is assumed to be good news. Rising churn, rising latency and
+ *    rising cost are all bad, and painting them green is worse than showing no
+ *    colour at all. `polarity` decides.
+ * 2. A zero baseline produces `+∞%` or `NaN`. There is no percentage change
+ *    from nothing, so this says so in words instead of inventing one.
+ * 3. Meaning is carried by colour and an arrow alone, which fails WCAG 1.4.1
+ *    and is unreadable to anyone who does not already know the convention. The
+ *    direction is always stated in text.
+ *
+ * What this deliberately does NOT do is claim statistical significance. A
+ * component holding two numbers cannot know whether a change is significant —
+ * that needs the sample size and a test. `insignificantBelow` is a presentation
+ * threshold and is described as one; passing `sampleSize` only adds it to the
+ * accessible description, it does not license a stronger claim.
+ */
+
+export type MetricPolarity = "higher-is-better" | "lower-is-better" | "neutral";
+
+const deltaVariants = cva("inline-flex items-center gap-1 text-xs font-medium tabular-nums", {
+  variants: {
+    sentiment: {
+      good: "text-success",
+      bad: "text-destructive",
+      neutral: "text-muted-foreground",
+    },
+  },
+  defaultVariants: { sentiment: "neutral" },
+});
+
+/** What the change means, once polarity is applied. */
+function sentimentOf(
+  change: number,
+  polarity: MetricPolarity,
+  meaningful: boolean,
+): "good" | "bad" | "neutral" {
+  if (!meaningful || change === 0 || polarity === "neutral") return "neutral";
+  const improved = polarity === "higher-is-better" ? change > 0 : change < 0;
+  return improved ? "good" : "bad";
+}
+
+export interface MetricDeltaProps
+  extends Omit<ComponentPropsWithRef<"div">, "children">, VariantProps<typeof deltaVariants> {
+  /** The current value. */
+  value: number;
+  /** The value being compared against. Omit when there is nothing to compare. */
+  previous?: number;
+  /** Names the metric. */
+  label: string;
+  /**
+   * Whether a rise is good news. Churn, latency, error rate and cost are all
+   * `lower-is-better`, and getting this wrong paints bad news green.
+   */
+  polarity?: MetricPolarity;
+  /**
+   * Relative change below which the delta is shown without sentiment, as a
+   * fraction. Presentation only — this is not a significance test.
+   */
+  insignificantBelow?: number;
+  /**
+   * Included in the accessible description when given, so a reader can judge
+   * the change for themselves. Never used to compute significance.
+   */
+  sampleSize?: number;
+  /** What the previous value represents, e.g. "vs last week". */
+  comparisonLabel?: string;
+  /** Formats the headline value. */
+  format?: (value: number) => string;
+}
+
+function defaultFormat(value: number): string {
+  return new Intl.NumberFormat().format(value);
+}
+
+const percentFormatter = new Intl.NumberFormat(undefined, {
+  style: "percent",
+  maximumFractionDigits: 1,
+  signDisplay: "exceptZero",
+});
+
+export function MetricDelta({
+  className,
+  value,
+  previous,
+  label,
+  polarity = "higher-is-better",
+  insignificantBelow = 0,
+  sampleSize,
+  comparisonLabel = "vs previous period",
+  format = defaultFormat,
+  ...props
+}: MetricDeltaProps) {
+  const hasComparison = previous !== undefined;
+  const absoluteChange = hasComparison ? value - previous : 0;
+
+  // A percentage change from zero is undefined, not infinite. Reporting it as
+  // a number at all is the lie; the component says "no prior value" instead.
+  const canComputeRelative = hasComparison && previous !== 0;
+  const relativeChange = canComputeRelative ? absoluteChange / Math.abs(previous) : null;
+
+  const meaningful =
+    relativeChange === null
+      ? absoluteChange !== 0
+      : Math.abs(relativeChange) >= insignificantBelow;
+
+  const sentiment = hasComparison
+    ? sentimentOf(absoluteChange, polarity, meaningful)
+    : "neutral";
+
+  const direction = absoluteChange > 0 ? "up" : absoluteChange < 0 ? "down" : "flat";
+
+  const changeText = !hasComparison
+    ? null
+    : relativeChange !== null
+      ? percentFormatter.format(relativeChange)
+      : `${absoluteChange > 0 ? "+" : ""}${format(absoluteChange)}`;
+
+  // Everything a screen reader needs, in one sentence, in the order it matters.
+  const description = [
+    `${label}: ${format(value)}`,
+    hasComparison
+      ? relativeChange !== null
+        ? `${direction === "flat" ? "unchanged" : direction} ${changeText ?? ""} ${comparisonLabel}`
+        : `${direction === "flat" ? "unchanged" : direction} by ${format(Math.abs(absoluteChange))} ${comparisonLabel}, no percentage available from a zero baseline`
+      : null,
+    hasComparison && !meaningful && direction !== "flat" ? "not a meaningful change" : null,
+    sampleSize !== undefined ? `sample size ${format(sampleSize)}` : null,
+  ]
+    .filter(Boolean)
+    .join(", ");
+
+  return (
+    <div
+      data-slot="metric-delta"
+      data-direction={direction}
+      data-sentiment={sentiment}
+      className={cn("flex flex-col gap-1", className)}
+      {...props}
+    >
+      <p className="text-xs text-muted-foreground">{label}</p>
+
+      {/* One accessible sentence for the whole tile. The parts below are hidden
+          so the reader gets the meaning once, not as three fragments. */}
+      <p className="sr-only">{description}</p>
+
+      <p
+        aria-hidden="true"
+        className="text-2xl leading-tight font-semibold tracking-tight tabular-nums"
+      >
+        {format(value)}
+      </p>
+
+      {hasComparison ? (
+        <p aria-hidden="true" className="flex flex-wrap items-center gap-x-1.5 gap-y-0.5">
+          <span className={cn(deltaVariants({ sentiment }))} data-slot="metric-delta-change">
+            <span aria-hidden="true">
+              {direction === "up" ? "↑" : direction === "down" ? "↓" : "→"}
+            </span>
+            {changeText}
+          </span>
+          <span className="text-xs text-muted-foreground">{comparisonLabel}</span>
+        </p>
+      ) : null}
+    </div>
+  );
+}
+
+export { deltaVariants };

package/src/components/record-diff/index.ts

@@ -0,0 +1,10 @@
+export {
+  RecordDiff,
+  RecordDiffSummary,
+  RecordDiffTable,
+  diffRecords,
+  type FieldChange,
+  type RecordDiffProps,
+  type RecordDiffTableProps,
+  type RecordField,
+} from "./record-diff";

package/src/components/record-diff/meta.ts

@@ -0,0 +1,19 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "record-diff",
+  title: "Record Diff",
+  description:
+    "Field-level before and after, for audit entries, settings history and revisions.",
+  category: "data",
+  status: "stable",
+  dependencies: [],
+  registryDependencies: [],
+  files: ["record-diff.tsx"],
+  a11y:
+    'A real table, not a grid of divs. Each field name is a th with scope="row", so a value is ' +
+    "announced with the field it belongs to rather than as a loose cell. The kind of change is " +
+    "never carried by row colour alone — every row states added, removed or changed in text for " +
+    "screen readers, satisfying WCAG 1.4.1. The unchanged-field toggle is a real button with " +
+    "aria-expanded. Redacted values never reach the DOM at all.",
+});

package/src/components/record-diff/record-diff.tsx

@@ -0,0 +1,341 @@
+"use client";
+
+import {
+  createContext,
+  useContext,
+  useMemo,
+  useState,
+  type ComponentPropsWithRef,
+} from "react";
+
+import { cn } from "@/lib/utils";
+
+/**
+ * What changed about a record, field by field.
+ *
+ * Every diff package on npm compares lines of text. That is the wrong shape for
+ * an audit entry, a settings revision or a config history, where the change is
+ * "role went from viewer to admin" and rendering it as two lines of JSON makes
+ * the reader do the comparison themselves.
+ *
+ * Scope is deliberately flat records. Nested objects and arrays are formatted as
+ * values rather than recursed into, because a recursive differ is a different
+ * and much larger component, and pretending otherwise would produce a shallow
+ * one that quietly lies about deep changes. `formatValue` is the escape hatch.
+ *
+ * Redaction is by key pattern and applied before formatting, so a secret is
+ * never handed to a formatter that might log it.
+ */
+
+export type FieldChange = "added" | "removed" | "changed" | "unchanged";
+
+export interface RecordField {
+  key: string;
+  label: string;
+  change: FieldChange;
+  before: unknown;
+  after: unknown;
+  redacted: boolean;
+}
+
+/** Values that read as absent, so "" → null is not reported as a change. */
+function isEmpty(value: unknown): boolean {
+  return value === null || value === undefined || value === "";
+}
+
+function classify(before: unknown, after: unknown): FieldChange {
+  const hadBefore = !isEmpty(before);
+  const hasAfter = !isEmpty(after);
+
+  if (!hadBefore && hasAfter) return "added";
+  if (hadBefore && !hasAfter) return "removed";
+  // Both absent. Falling through would compare "" against null, which
+  // serialise differently and would report a change that did not happen.
+  if (!hadBefore && !hasAfter) return "unchanged";
+  // Structural comparison, so {a:1} and {a:1} are equal. Key order differences
+  // would report a false change, so keys are sorted before comparing.
+  return stableStringify(before) === stableStringify(after) ? "unchanged" : "changed";
+}
+
+function stableStringify(value: unknown): string {
+  if (value === null || typeof value !== "object") return JSON.stringify(value) ?? "";
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(",")}]`;
+  const entries = Object.entries(value as Record<string, unknown>).sort(([a], [b]) =>
+    a.localeCompare(b),
+  );
+  return `{${entries.map(([k, v]) => `${k}:${stableStringify(v)}`).join(",")}}`;
+}
+
+function defaultFormatValue(value: unknown): string {
+  if (value === null || value === undefined) return "—";
+  if (value === "") return "empty";
+  if (typeof value === "string") return value;
+  if (typeof value === "boolean") return value ? "yes" : "no";
+  if (typeof value === "number" || typeof value === "bigint") return String(value);
+  if (Array.isArray(value)) {
+    return value.length === 0 ? "none" : value.map(defaultFormatValue).join(", ");
+  }
+  if (typeof value === "object") return JSON.stringify(value);
+  // Symbols and functions have no sensible representation as a field value, and
+  // String() would yield "[object Object]" or a function body. Say what it is.
+  return `[${typeof value}]`;
+}
+
+/** Keys whose values must never be rendered, however the record was built. */
+const DEFAULT_REDACT = /password|secret|token|api[-_]?key|authorization|credential/i;
+
+export interface RecordDiffProps extends Omit<ComponentPropsWithRef<"div">, "children"> {
+  before: Record<string, unknown>;
+  after: Record<string, unknown>;
+  /** Overrides the humanised key. */
+  labels?: Record<string, string>;
+  /** Keys to render as redacted. Defaults to common secret-shaped names. */
+  redact?: RegExp;
+  /** Only these keys, in this order. Anything else is ignored. */
+  fields?: string[];
+  /** Hides unchanged fields behind a toggle. */
+  collapseUnchanged?: boolean;
+  formatValue?: (value: unknown, key: string) => string;
+  children?: React.ReactNode;
+}
+
+interface RecordDiffContextValue {
+  fields: RecordField[];
+  changedCount: number;
+  formatValue: (value: unknown, key: string) => string;
+}
+
+const RecordDiffContext = createContext<RecordDiffContextValue | null>(null);
+
+function useRecordDiffContext(component: string): RecordDiffContextValue {
+  const context = useContext(RecordDiffContext);
+  if (!context) {
+    throw new Error(`${component} must be rendered inside <RecordDiff>.`);
+  }
+  return context;
+}
+
+/** "billingEmail" and "billing_email" both read as "Billing email". */
+function humanise(key: string): string {
+  const spaced = key
+    .replace(/[_-]+/g, " ")
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .trim();
+  return spaced.charAt(0).toUpperCase() + spaced.slice(1).toLowerCase();
+}
+
+export function diffRecords(
+  before: Record<string, unknown>,
+  after: Record<string, unknown>,
+  options: { labels?: Record<string, string>; redact?: RegExp; fields?: string[] } = {},
+): RecordField[] {
+  const { labels = {}, redact = DEFAULT_REDACT, fields } = options;
+
+  // The union of both sides, so a removed key is still reported. Iterating only
+  // `after` is how removals go missing from audit logs.
+  const keys = fields ?? [...new Set([...Object.keys(before), ...Object.keys(after)])];
+
+  return keys.map((key) => ({
+    key,
+    label: labels[key] ?? humanise(key),
+    change: classify(before[key], after[key]),
+    before: before[key],
+    after: after[key],
+    redacted: redact.test(key),
+  }));
+}
+
+const CHANGE_STYLES: Record<FieldChange, string> = {
+  added: "text-success",
+  removed: "text-destructive",
+  changed: "text-foreground",
+  unchanged: "text-muted-foreground",
+};
+
+export function RecordDiff({
+  className,
+  before,
+  after,
+  labels,
+  redact = DEFAULT_REDACT,
+  fields: fieldKeys,
+  collapseUnchanged = true,
+  formatValue = defaultFormatValue,
+  children,
+  ...props
+}: RecordDiffProps) {
+  const fields = useMemo(
+    () => diffRecords(before, after, { labels, redact, fields: fieldKeys }),
+    [before, after, labels, redact, fieldKeys],
+  );
+
+  const changedCount = fields.filter((field) => field.change !== "unchanged").length;
+
+  const context = useMemo<RecordDiffContextValue>(
+    () => ({ fields, changedCount, formatValue }),
+    [fields, changedCount, formatValue],
+  );
+
+  return (
+    <RecordDiffContext.Provider value={context}>
+      <div
+        data-slot="record-diff"
+        data-changed={changedCount}
+        className={cn("flex flex-col gap-2", className)}
+        {...props}
+      >
+        {children ?? (
+          <>
+            <RecordDiffSummary />
+            <RecordDiffTable collapseUnchanged={collapseUnchanged} />
+          </>
+        )}
+      </div>
+    </RecordDiffContext.Provider>
+  );
+}
+
+/** "3 fields changed" — the thing a reviewer scanning a log needs first. */
+export function RecordDiffSummary({ className, ...props }: ComponentPropsWithRef<"p">) {
+  const { changedCount, fields } = useRecordDiffContext("RecordDiffSummary");
+
+  return (
+    <p
+      data-slot="record-diff-summary"
+      className={cn("text-xs text-muted-foreground", className)}
+      {...props}
+    >
+      {changedCount === 0
+        ? "No fields changed"
+        : `${String(changedCount)} of ${String(fields.length)} field${fields.length === 1 ? "" : "s"} changed`}
+    </p>
+  );
+}
+
+export interface RecordDiffTableProps extends ComponentPropsWithRef<"table"> {
+  collapseUnchanged?: boolean;
+}
+
+export function RecordDiffTable({
+  className,
+  collapseUnchanged = true,
+  ...props
+}: RecordDiffTableProps) {
+  const { fields, formatValue, changedCount } = useRecordDiffContext("RecordDiffTable");
+  const [showUnchanged, setShowUnchanged] = useState(!collapseUnchanged);
+
+  const unchangedCount = fields.length - changedCount;
+  const visible = showUnchanged
+    ? fields
+    : fields.filter((field) => field.change !== "unchanged");
+
+  return (
+    <div className="flex flex-col gap-2">
+      <div className="overflow-x-auto">
+        <table
+          data-slot="record-diff-table"
+          className={cn("w-full border-collapse text-sm", className)}
+          {...props}
+        >
+          <thead>
+            <tr className="border-b border-border">
+              <th
+                scope="col"
+                className="px-3 py-2 text-left text-xs font-medium text-muted-foreground"
+              >
+                Field
+              </th>
+              <th
+                scope="col"
+                className="px-3 py-2 text-left text-xs font-medium text-muted-foreground"
+              >
+                Before
+              </th>
+              <th
+                scope="col"
+                className="px-3 py-2 text-left text-xs font-medium text-muted-foreground"
+              >
+                After
+              </th>
+            </tr>
+          </thead>
+          <tbody>
+            {visible.map((field) => (
+              <tr
+                key={field.key}
+                data-slot="record-diff-row"
+                data-change={field.change}
+                className="border-b border-border last:border-0"
+              >
+                {/* scope="row" so each value is announced with its field name
+                    rather than as a loose cell in a wall of table. */}
+                <th
+                  scope="row"
+                  className="px-3 py-2 text-left align-top font-medium whitespace-nowrap"
+                >
+                  {field.label}
+                  {/* The change kind must not be carried by row colour alone. */}
+                  <span className="sr-only">{`, ${field.change}`}</span>
+                </th>
+                <td className="px-3 py-2 align-top text-muted-foreground">
+                  {field.redacted ? (
+                    <RedactedValue />
+                  ) : field.change === "added" ? (
+                    <span className="text-muted-foreground">—</span>
+                  ) : (
+                    <span className="line-through decoration-muted-foreground/50">
+                      {formatValue(field.before, field.key)}
+                    </span>
+                  )}
+                </td>
+                <td className={cn("px-3 py-2 align-top", CHANGE_STYLES[field.change])}>
+                  {field.redacted ? (
+                    <RedactedValue />
+                  ) : field.change === "removed" ? (
+                    <span className="text-muted-foreground">—</span>
+                  ) : (
+                    formatValue(field.after, field.key)
+                  )}
+                </td>
+              </tr>
+            ))}
+          </tbody>
+        </table>
+      </div>
+
+      {collapseUnchanged && unchangedCount > 0 ? (
+        <button
+          type="button"
+          data-slot="record-diff-toggle"
+          aria-expanded={showUnchanged}
+          onClick={() => {
+            setShowUnchanged((shown) => !shown);
+          }}
+          className={cn(
+            "self-start rounded-md px-1.5 py-0.5 text-xs text-muted-foreground",
+            "transition-colors hover:text-foreground",
+            "outline-none focus-visible:ring-2 focus-visible:ring-ring/55",
+          )}
+        >
+          {showUnchanged
+            ? `Hide ${String(unchangedCount)} unchanged`
+            : `Show ${String(unchangedCount)} unchanged`}
+        </button>
+      ) : null}
+    </div>
+  );
+}
+
+/**
+ * A value that is never rendered.
+ *
+ * Redaction happens before formatting, so a secret is not passed to a formatter
+ * that might log or transform it — the value simply does not reach the DOM.
+ */
+function RedactedValue() {
+  return (
+    <span data-slot="record-diff-redacted" className="text-muted-foreground italic">
+      redacted
+    </span>
+  );
+}

package/src/index.ts

@@ -1,5 +1,8 @@
 export * from "./components/accordion";
 export * from "./components/activity-feed";
+export * from "./components/ai-action-ledger";
+export * from "./components/ai-inline-completion";
+export * from "./components/ai-structured-output";
 export * from "./components/ai-agent-status";
 export * from "./components/ai-conversation";
 export * from "./components/ai-message";
@@ -29,6 +32,9 @@ export * from "./components/empty-state";
 export * from "./components/form";
 export * from "./components/input";
 export * from "./components/label";
+export * from "./components/meter";
+export * from "./components/metric-delta";
+export * from "./components/record-diff";
 export * from "./components/pagination";
 export * from "./components/popover";
 export * from "./components/progress";

package/src/registry/components.ts

@@ -2,14 +2,17 @@ import type { ComponentMeta } from "./schema";
 
 import { meta as accordionMeta } from "@/components/accordion/meta";
 import { meta as activityFeedMeta } from "@/components/activity-feed/meta";
+import { meta as aiActionLedgerMeta } from "@/components/ai-action-ledger/meta";
 import { meta as aiAgentStatusMeta } from "@/components/ai-agent-status/meta";
 import { meta as aiConversationMeta } from "@/components/ai-conversation/meta";
+import { meta as aiInlineCompletionMeta } from "@/components/ai-inline-completion/meta";
 import { meta as aiMessageMeta } from "@/components/ai-message/meta";
 import { meta as aiModelSelectorMeta } from "@/components/ai-model-selector/meta";
 import { meta as aiPromptInputMeta } from "@/components/ai-prompt-input/meta";
 import { meta as aiReasoningMeta } from "@/components/ai-reasoning/meta";
 import { meta as aiResponseMeta } from "@/components/ai-response/meta";
 import { meta as aiSourcesMeta } from "@/components/ai-sources/meta";
+import { meta as aiStructuredOutputMeta } from "@/components/ai-structured-output/meta";
 import { meta as aiTokenUsageMeta } from "@/components/ai-token-usage/meta";
 import { meta as aiToolMeta } from "@/components/ai-tool/meta";
 import { meta as alertMeta } from "@/components/alert/meta";
@@ -31,10 +34,13 @@ import { meta as emptyStateMeta } from "@/components/empty-state/meta";
 import { meta as formMeta } from "@/components/form/meta";
 import { meta as inputMeta } from "@/components/input/meta";
 import { meta as labelMeta } from "@/components/label/meta";
+import { meta as meterMeta } from "@/components/meter/meta";
+import { meta as metricDeltaMeta } from "@/components/metric-delta/meta";
 import { meta as paginationMeta } from "@/components/pagination/meta";
 import { meta as popoverMeta } from "@/components/popover/meta";
 import { meta as progressMeta } from "@/components/progress/meta";
 import { meta as radioGroupMeta } from "@/components/radio-group/meta";
+import { meta as recordDiffMeta } from "@/components/record-diff/meta";
 import { meta as selectMeta } from "@/components/select/meta";
 import { meta as separatorMeta } from "@/components/separator/meta";
 import { meta as sheetMeta } from "@/components/sheet/meta";
@@ -61,14 +67,17 @@ import { meta as tooltipMeta } from "@/components/tooltip/meta";
 export const componentMetas: ComponentMeta[] = [
   accordionMeta,
   activityFeedMeta,
+  aiActionLedgerMeta,
   aiAgentStatusMeta,
   aiConversationMeta,
+  aiInlineCompletionMeta,
   aiMessageMeta,
   aiModelSelectorMeta,
   aiPromptInputMeta,
   aiReasoningMeta,
   aiResponseMeta,
   aiSourcesMeta,
+  aiStructuredOutputMeta,
   aiTokenUsageMeta,
   aiToolMeta,
   alertMeta,
@@ -90,10 +99,13 @@ export const componentMetas: ComponentMeta[] = [
   formMeta,
   inputMeta,
   labelMeta,
+  meterMeta,
+  metricDeltaMeta,
   paginationMeta,
   popoverMeta,
   progressMeta,
   radioGroupMeta,
+  recordDiffMeta,
   selectMeta,
   separatorMeta,
   sheetMeta,