@dowel-ui/react 0.2.0 → 0.4.0

package/src/components/ai-disclosure/ai-disclosure.tsx

@@ -0,0 +1,244 @@
+"use client";
+
+import { cva, type VariantProps } from "class-variance-authority";
+import type { ComponentPropsWithRef, ReactNode } from "react";
+
+import { Popover, PopoverContent, PopoverTrigger } from "@/components/popover";
+import { focusRing, iconSlot } from "@/lib/styles";
+import { cn } from "@/lib/utils";
+
+/**
+ * Telling someone they are looking at AI.
+ *
+ * Not one registry ships this — not AI Elements, assistant-ui, prompt-kit,
+ * CopilotKit or shadcn — while every one of them ships the chat surface that
+ * needs it. The gap is the reason this exists.
+ *
+ * The four `kind`s are not invented. They are the four human-visible situations
+ * the EU AI Act's Article 50 actually creates, which has applied since 2 August
+ * 2026: you are talking to a machine (50(1)); this media was generated or
+ * manipulated and resembles something real (50(4), "deep fakes"); this text was
+ * published to inform the public (50(4)); and the assisted case, which the same
+ * paragraph exempts where there is human review or editorial control — worth
+ * saying out loud rather than leaving to inference.
+ *
+ * What this cannot do, and what no React component can: Article 50(2) requires
+ * synthetic output to be marked *in a machine-readable format*, in the artifact
+ * itself, by whoever generated it. Rendering a badge does not do that, and a
+ * component that let you believe otherwise would be worse than none. Read the
+ * accessibility note and the docs page: this is a disclosure control, not a
+ * compliance product, and nothing here is legal advice.
+ */
+
+export type DisclosureKind = "interaction" | "generated" | "manipulated" | "assisted";
+
+/**
+ * What each kind says by default.
+ *
+ * Phrased for a reader rather than for a lawyer, and every one of them is
+ * overridable — the Act says the disclosure must be clear, not that it must use
+ * these words, and the right words depend on the product.
+ */
+const DEFAULT_LABEL: Record<DisclosureKind, string> = {
+  interaction: "You are chatting with an AI assistant",
+  generated: "Generated by AI",
+  manipulated: "This media was altered by AI",
+  assisted: "AI-assisted, reviewed by a person",
+};
+
+const disclosureVariants = cva(
+  cn(
+    "inline-flex w-fit items-center gap-1.5 font-medium",
+    "[&_svg:not([class*='size-'])]:size-3.5",
+    iconSlot,
+  ),
+  {
+    variants: {
+      variant: {
+        /** Sits beside the thing it describes. */
+        inline: "rounded-full border border-border-strong px-2 py-0.5 text-xs",
+        /** Above a conversation, where Article 50(1) usually belongs. */
+        banner:
+          "w-full rounded-lg border border-border bg-muted/40 px-3 py-2 text-xs text-muted-foreground",
+        /**
+         * Over the corner of an image or video. `--overlay` is a dark scrim in
+         * every shipped theme, so the text is white on purpose rather than
+         * following the theme — a label that inverts over a photograph is
+         * unreadable on half of them.
+         */
+        overlay: "rounded-md bg-overlay px-2 py-1 text-2xs text-white backdrop-blur-sm",
+      },
+    },
+    defaultVariants: { variant: "inline" },
+  },
+);
+
+function SparkIcon() {
+  return (
+    <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
+      <path
+        d="M12 3l1.9 5.1L19 10l-5.1 1.9L12 17l-1.9-5.1L5 10l5.1-1.9L12 3Z"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinejoin="round"
+      />
+    </svg>
+  );
+}
+
+export interface AIDisclosureProps
+  extends
+    Omit<ComponentPropsWithRef<"div">, "children">,
+    VariantProps<typeof disclosureVariants> {
+  kind: DisclosureKind;
+  /** Replaces the default wording. The default is a starting point, not a rule. */
+  label?: ReactNode;
+  /**
+   * Replaces the mark. The Commission publishes three icons for this and lets
+   * anyone use them without attribution — they are deliberately not bundled
+   * here, because an official mark shipped inside a component library ends up
+   * on content nobody checked. Bring your own, and the Commission's own words
+   * apply: using them "does not establish legal compliance by itself".
+   */
+  icon?: ReactNode;
+  /** A provenance panel, or anything else that belongs after the label. */
+  children?: ReactNode;
+}
+
+/**
+ * A disclosure, in words.
+ *
+ * The icon is decorative and the text is the disclosure. A sparkle alone is not
+ * a notice — it is a decoration that a sighted reader may or may not decode and
+ * that a screen reader passes over in silence, which is the failure mode the
+ * whole component exists to avoid.
+ */
+export function AIDisclosure({
+  className,
+  kind,
+  variant,
+  label,
+  icon,
+  children,
+  ...props
+}: AIDisclosureProps) {
+  return (
+    <div
+      data-slot="ai-disclosure"
+      data-kind={kind}
+      className={cn(disclosureVariants({ variant }), className)}
+      {...props}
+    >
+      {icon ?? <SparkIcon />}
+      <span>{label ?? DEFAULT_LABEL[kind]}</span>
+      {children}
+    </div>
+  );
+}
+
+/* ------------------------------------------------------------------ */
+/*  Provenance                                                         */
+/* ------------------------------------------------------------------ */
+
+export interface ProvenanceClaim {
+  label: string;
+  value: ReactNode;
+}
+
+export interface AIDisclosureProvenanceProps extends Omit<
+  ComponentPropsWithRef<"button">,
+  "children"
+> {
+  /**
+   * What is being claimed about this content, and by whom.
+   *
+   * Claims, not findings. They arrive as data — from a C2PA manifest your
+   * server read, from your own pipeline, from a vendor — and this renders them.
+   */
+  claims: ProvenanceClaim[];
+  /** Who asserts the claims. Named, because an unattributed claim is a rumour. */
+  source?: string;
+  /**
+   * Whether something you trust checked the claims, and said so.
+   *
+   * Supplied, never computed. Verifying a C2PA manifest means parsing signed
+   * COSE and walking a certificate chain; doing that in the browser would mean
+   * a wasm blob you cannot read, and "you own the source" would stop being
+   * true. It also cannot be trusted client-side even when it succeeds, because
+   * the page doing the checking is the page making the claim. Verify on a
+   * server and pass the answer down. Left undefined, this says so.
+   */
+  verified?: boolean;
+  triggerLabel?: string;
+}
+
+type CheckStatus = "verified" | "failed" | "unchecked";
+
+function statusText(status: CheckStatus, source?: string): string {
+  const by = source ? ` by ${source}` : "";
+  if (status === "verified") return `Checked${by} and the claims matched.`;
+  if (status === "failed") return `Checked${by} and the claims did not match.`;
+  return "Not checked. These are claims made about the content, not findings.";
+}
+
+/**
+ * The metadata behind a disclosure, presented as claims rather than proof.
+ *
+ * The distinction is the entire point. "Made with Model X on 3 September" looks
+ * like a fact and is a string somebody put in a file. Rendering it beside a
+ * checkmark would launder an assertion into evidence, so the panel names who is
+ * asserting and states plainly whether anyone checked.
+ */
+export function AIDisclosureProvenance({
+  className,
+  claims,
+  source,
+  verified,
+  triggerLabel = "Content details",
+  ...props
+}: AIDisclosureProvenanceProps) {
+  const status = verified === undefined ? "unchecked" : verified ? "verified" : "failed";
+
+  return (
+    <Popover>
+      <PopoverTrigger asChild>
+        <button
+          type="button"
+          data-slot="ai-disclosure-provenance-trigger"
+          className={cn(
+            "rounded-sm underline decoration-dotted underline-offset-2 hover:decoration-solid",
+            focusRing,
+            className,
+          )}
+          {...props}
+        >
+          {triggerLabel}
+        </button>
+      </PopoverTrigger>
+      <PopoverContent aria-label={triggerLabel} className="w-80 text-xs">
+        <dl className="grid grid-cols-[auto_1fr] gap-x-3 gap-y-1.5">
+          {claims.map((claim) => (
+            <div key={claim.label} className="contents">
+              <dt className="text-muted-foreground">{claim.label}</dt>
+              <dd className="break-words">{claim.value}</dd>
+            </div>
+          ))}
+        </dl>
+        {/* Said in text, and last, so it qualifies everything above it rather
+            than being a tick a reader has to interpret. */}
+        <p
+          data-slot="ai-disclosure-provenance-status"
+          data-status={status}
+          className={cn(
+            "mt-3 border-t border-border pt-2",
+            status === "failed" ? "text-destructive" : "text-muted-foreground",
+          )}
+        >
+          {statusText(status, source)}
+        </p>
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+export { disclosureVariants };

package/src/components/ai-disclosure/index.ts

@@ -0,0 +1,9 @@
+export {
+  AIDisclosure,
+  AIDisclosureProvenance,
+  disclosureVariants,
+  type AIDisclosureProps,
+  type AIDisclosureProvenanceProps,
+  type DisclosureKind,
+  type ProvenanceClaim,
+} from "./ai-disclosure";

package/src/components/ai-disclosure/meta.ts

@@ -0,0 +1,23 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "ai-disclosure",
+  title: "AI Disclosure",
+  description: "Tells a reader they are looking at AI, and what is actually known about it.",
+  category: "ai",
+  status: "stable",
+  dependencies: ["class-variance-authority"],
+  registryDependencies: ["popover"],
+  files: ["ai-disclosure.tsx"],
+  a11y:
+    "The text is the disclosure and the icon is decoration, marked aria-hidden — a sparkle alone " +
+    "is a mark a sighted reader may not decode and a screen reader passes over in silence, which " +
+    "is the exact failure this component exists to prevent. Each of the four kinds carries " +
+    "wording of its own, so the distinction between generated, manipulated and human-reviewed " +
+    "survives for anyone who cannot see the styling. The provenance panel states in words " +
+    "whether anyone checked the claims and who, rather than implying it with a tick, and its " +
+    "three states are told apart by their sentences rather than by colour. " +
+    "Scope: this renders the human-visible disclosures of EU AI Act Article 50(1) and 50(4). " +
+    "It cannot satisfy 50(2), which requires machine-readable marking inside the artifact by " +
+    "whoever generated it, and no React component can. Not legal advice.",
+});

package/src/components/ai-response/ai-response.tsx

@@ -50,6 +50,7 @@ export function ResponseCaret({ className, ...props }: ComponentPropsWithRef<"sp
     <span
       data-slot="response-caret"
       aria-hidden="true"
+      data-motion="indicator"
       className={cn(
         "ml-0.5 inline-block h-[1em] w-[2px] translate-y-[0.15em] animate-caret bg-current align-baseline",
         className,

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

@@ -4,6 +4,7 @@ import {
   createContext,
   useContext,
   useMemo,
+  useState,
   type ComponentPropsWithRef,
   type ReactNode,
 } from "react";
@@ -167,10 +168,28 @@ export function StructuredField({ className, name, children, ...props }: Structu
   const state = stateOf(name);
   const raw = value[name];
 
+  // "A token arrived" and "this field is final" are different facts, and in a
+  // streamed object they look identical. The settle makes that distinction
+  // visible — so it plays on the transition into settled, and never on a field
+  // that was already final when the component mounted.
+  //
+  // State adjusted during render rather than tracked in a ref: reading a ref
+  // while rendering is unsafe under concurrent rendering, and an effect would
+  // paint the plain value first and animate a frame later. React re-renders
+  // immediately here and discards the intermediate pass.
+  const [seenState, setSeenState] = useState<FieldState>(state);
+  const [hasSettled, setHasSettled] = useState(false);
+
+  if (seenState !== state) {
+    setSeenState(state);
+    if (state === "settled" && seenState !== "settled") setHasSettled(true);
+  }
+
   return (
     <div
       data-slot="structured-field"
       data-state={state}
+      data-settled={hasSettled || undefined}
       data-field={name}
       className={cn("flex flex-col gap-1", className)}
       {...props}
@@ -195,7 +214,12 @@ export function StructuredField({ className, name, children, ...props }: Structu
             className="block h-4 w-24 animate-pulse-soft rounded bg-muted"
           />
         ) : (
-          (children ?? formatValue(raw, name))
+          <span
+            data-slot="structured-field-value"
+            className={cn(hasSettled && "inline-block animate-settle")}
+          >
+            {children ?? formatValue(raw, name)}
+          </span>
         )}
       </dd>
     </div>

package/src/components/diff-viewer/diff-model.ts

@@ -0,0 +1,256 @@
+import { diffLines, diffWordsWithSpace } from "diff";
+
+/**
+ * Turning two versions of a file into rows a diff can render.
+ *
+ * The algorithm is not the interesting part and is not reimplemented here —
+ * jsdiff does Myers properly, is BSD-licensed, has no dependencies of its own,
+ * and getting an O(ND) diff subtly wrong is a poor use of anybody's afternoon.
+ * What every packaged *viewer* welds on is a styling strategy: emotion in
+ * react-diff-viewer-continued, HTML strings and a stylesheet in diff2html. That
+ * is what cannot be reached by design tokens, and it is why this exists.
+ *
+ * Everything below is pure, so the grouping, the context collapsing and the
+ * word-level pairing can be tested without rendering anything.
+ */
+
+export type RowKind = "context" | "added" | "removed";
+
+export interface WordSegment {
+  text: string;
+  changed: boolean;
+}
+
+export interface DiffRow {
+  kind: RowKind;
+  /** 1-based line number in the original. Absent on an added line. */
+  before?: number;
+  /** 1-based line number in the result. Absent on a removed line. */
+  after?: number;
+  content: string;
+  /**
+   * Word-level split, present only where a removed line pairs with an added
+   * one. Without a pair there is nothing to compare against, and highlighting
+   * the whole line as "changed" would be noise.
+   */
+  segments?: WordSegment[];
+}
+
+export interface DiffHunk {
+  id: string;
+  rows: DiffRow[];
+  /** Context lines hidden before this hunk, if any. */
+  skippedBefore: number;
+}
+
+export interface BuildDiffOptions {
+  /** Unchanged lines kept either side of a change. */
+  context?: number;
+  /**
+   * Compare word by word inside a changed line. Off for very large diffs,
+   * where the extra pass costs more than it explains.
+   */
+  words?: boolean;
+}
+
+function splitLines(text: string): string[] {
+  const lines = text.split("\n");
+  // A trailing newline produces a final empty element that is not a line.
+  if (lines.length > 1 && lines[lines.length - 1] === "") lines.pop();
+  return lines;
+}
+
+/**
+ * Gives both sides a trailing newline before they are compared.
+ *
+ * jsdiff's line tokens carry their own newline, so a final line written as `a`
+ * and one written as `a\n` are different tokens. Appending a line to a file
+ * that did not end in a newline would otherwise be reported as the last line
+ * being removed and re-added — a change the author did not make, sitting on
+ * top of the one they did.
+ */
+function withTrailingNewline(text: string): string {
+  return text.endsWith("\n") ? text : `${text}\n`;
+}
+
+/**
+ * Pairs removed lines with added ones inside a single change block.
+ *
+ * jsdiff reports a change as a run of removals followed by a run of additions.
+ * Comparing the first removal against the first addition is what turns "this
+ * line went away and another arrived" into "this word changed" — but only while
+ * the runs line up. Beyond the shorter run there is no counterpart, and
+ * inventing one produces confident nonsense.
+ */
+function pairWords(removed: DiffRow[], added: DiffRow[]): void {
+  const pairs = Math.min(removed.length, added.length);
+
+  for (let index = 0; index < pairs; index += 1) {
+    const from = removed[index];
+    const to = added[index];
+    if (!from || !to) continue;
+
+    const parts = diffWordsWithSpace(from.content, to.content);
+
+    from.segments = parts
+      .filter((part) => !part.added)
+      .map((part) => ({ text: part.value, changed: Boolean(part.removed) }));
+
+    to.segments = parts
+      .filter((part) => !part.removed)
+      .map((part) => ({ text: part.value, changed: Boolean(part.added) }));
+  }
+}
+
+export function buildDiff(
+  before: string,
+  after: string,
+  options: BuildDiffOptions = {},
+): DiffHunk[] {
+  const { context = 3, words = true } = options;
+
+  const changes = diffLines(withTrailingNewline(before), withTrailingNewline(after));
+  const rows: DiffRow[] = [];
+  let beforeLine = 1;
+  let afterLine = 1;
+
+  // Flat rows first. Grouping into hunks is a separate concern and mixing the
+  // two is how these implementations become unreadable.
+  let pendingRemoved: DiffRow[] = [];
+  let pendingAdded: DiffRow[] = [];
+
+  const flushPair = () => {
+    if (words && pendingRemoved.length > 0 && pendingAdded.length > 0) {
+      pairWords(pendingRemoved, pendingAdded);
+    }
+    pendingRemoved = [];
+    pendingAdded = [];
+  };
+
+  for (const change of changes) {
+    const lines = splitLines(change.value);
+
+    if (change.added) {
+      for (const content of lines) {
+        const row: DiffRow = { kind: "added", after: afterLine, content };
+        afterLine += 1;
+        rows.push(row);
+        pendingAdded.push(row);
+      }
+      continue;
+    }
+
+    if (change.removed) {
+      // A removal run that follows an addition run starts a new pairing.
+      if (pendingAdded.length > 0) flushPair();
+      for (const content of lines) {
+        const row: DiffRow = { kind: "removed", before: beforeLine, content };
+        beforeLine += 1;
+        rows.push(row);
+        pendingRemoved.push(row);
+      }
+      continue;
+    }
+
+    flushPair();
+    for (const content of lines) {
+      rows.push({ kind: "context", before: beforeLine, after: afterLine, content });
+      beforeLine += 1;
+      afterLine += 1;
+    }
+  }
+
+  flushPair();
+
+  return groupIntoHunks(rows, context);
+}
+
+/**
+ * Groups rows into hunks, dropping context beyond `context` lines.
+ *
+ * A file with one changed line is otherwise thousands of rows of identical
+ * text, and the reader has to find the change in it.
+ */
+export function groupIntoHunks(rows: DiffRow[], context: number): DiffHunk[] {
+  const changedIndexes = rows
+    .map((row, index) => (row.kind === "context" ? -1 : index))
+    .filter((index) => index >= 0);
+
+  if (changedIndexes.length === 0) return [];
+
+  // Ranges of rows to keep, then merged where their context overlaps —
+  // otherwise two nearby changes produce two hunks separated by nothing.
+  const ranges: [number, number][] = [];
+  for (const index of changedIndexes) {
+    const start = Math.max(0, index - context);
+    const end = Math.min(rows.length - 1, index + context);
+    const last = ranges[ranges.length - 1];
+    if (last && start <= last[1] + 1) last[1] = Math.max(last[1], end);
+    else ranges.push([start, end]);
+  }
+
+  let previousEnd = -1;
+  return ranges.map(([start, end], index) => {
+    const skippedBefore = start - previousEnd - 1;
+    previousEnd = end;
+    return {
+      id: `hunk-${String(index)}`,
+      rows: rows.slice(start, end + 1),
+      skippedBefore: Math.max(0, skippedBefore),
+    };
+  });
+}
+
+/** Row pairs for a side-by-side view, aligning removals against additions. */
+export function toSplitRows(
+  rows: DiffRow[],
+): { left: DiffRow | null; right: DiffRow | null }[] {
+  const pairs: { left: DiffRow | null; right: DiffRow | null }[] = [];
+  let index = 0;
+
+  while (index < rows.length) {
+    const row = rows[index];
+    if (!row) break;
+
+    if (row.kind === "context") {
+      pairs.push({ left: row, right: row });
+      index += 1;
+      continue;
+    }
+
+    // Take the whole removal run and the whole addition run that follows, then
+    // lay them alongside each other. Emitting them in document order instead
+    // would put every removal above every addition, which is the unified view
+    // wearing a two-column costume.
+    const removed: DiffRow[] = [];
+    while (rows[index]?.kind === "removed") {
+      removed.push(rows[index] as DiffRow);
+      index += 1;
+    }
+    const added: DiffRow[] = [];
+    while (rows[index]?.kind === "added") {
+      added.push(rows[index] as DiffRow);
+      index += 1;
+    }
+
+    const height = Math.max(removed.length, added.length);
+    for (let offset = 0; offset < height; offset += 1) {
+      pairs.push({ left: removed[offset] ?? null, right: added[offset] ?? null });
+    }
+  }
+
+  return pairs;
+}
+
+/** Counts, for a summary that says what the diff does before it is read. */
+export function countChanges(hunks: DiffHunk[]): { added: number; removed: number } {
+  let added = 0;
+  let removed = 0;
+  for (const hunk of hunks) {
+    for (const row of hunk.rows) {
+      if (row.kind === "added") added += 1;
+      if (row.kind === "removed") removed += 1;
+    }
+  }
+  return { added, removed };
+}