@dowel-ui/react 0.4.0 → 0.7.0

package/src/components/ai-extraction-review/extraction-model.ts

@@ -0,0 +1,159 @@
+/**
+ * The model behind a review of extracted fields: where each value was read
+ * from, what the reviewer decided about it, and how far through the review
+ * they are.
+ *
+ * Pure, so overlap handling and the completion rule are tested without
+ * rendering anything — and so an application can answer "is this review
+ * finished" on the server from the same decisions the component reports,
+ * rather than trusting a flag the client sent.
+ */
+
+export interface SourceSpan {
+  /** Offset into the source text in UTF-16 code units. Inclusive. */
+  start: number;
+  /** Exclusive. */
+  end: number;
+}
+
+export interface ExtractionField {
+  /** Key in the extracted object. */
+  name: string;
+  label: string;
+  /**
+   * What the model extracted. Absent while streaming means it has not arrived;
+   * absent once streaming has ended means the model found nothing.
+   */
+  value?: string;
+  /**
+   * Where in the source the value was read from. Absent means the model
+   * supplied the value without evidence, which the review says outright.
+   */
+  span?: SourceSpan;
+  /** 0 to 1. Shown as a number, never only as a colour. */
+  confidence?: number;
+  /** A textarea instead of a single line. For addresses and descriptions. */
+  multiline?: boolean;
+}
+
+export type FieldDecision =
+  /** The model's value, taken as it was. */
+  | { kind: "accepted"; value: string }
+  /** The reviewer's value, with the model's kept so a record can tell them apart. */
+  | { kind: "corrected"; value: string; proposed: string }
+  /** Wrong and not corrected — the field does not apply, or cannot be known. */
+  | { kind: "rejected" };
+
+/** A run of source text and the fields whose evidence covers it. */
+export interface SourceRun {
+  text: string;
+  /** Field names, in declaration order. Empty for text nobody cites. */
+  fields: string[];
+}
+
+/**
+ * A span brought within the source, or null if nothing of it is.
+ *
+ * Offsets come from a model or an OCR layer and are wrong often enough that
+ * refusing to render on a bad one would leave the whole review blank. A span
+ * past the end is clamped; an inverted or empty one is treated as no evidence,
+ * which is what it is.
+ */
+export function clampSpan(span: SourceSpan, length: number): SourceSpan | null {
+  const start = Math.max(0, Math.min(span.start, length));
+  const end = Math.max(0, Math.min(span.end, length));
+  return end > start ? { start, end } : null;
+}
+
+/** The text a span points at, or an empty string if it points at nothing. */
+export function evidenceOf(source: string, span: SourceSpan | undefined): string {
+  if (!span) return "";
+  const clamped = clampSpan(span, source.length);
+  return clamped ? source.slice(clamped.start, clamped.end) : "";
+}
+
+/** Whether a field's value can be checked against the source at all. */
+export function isSourced(source: string, field: ExtractionField): boolean {
+  return field.span !== undefined && clampSpan(field.span, source.length) !== null;
+}
+
+/**
+ * Cuts the source into runs at every span boundary, so overlapping evidence —
+ * a total that sits inside the line that contains it — renders as nested
+ * coverage rather than as two marks fighting over the same characters.
+ */
+export function segmentSource(source: string, fields: ExtractionField[]): SourceRun[] {
+  const spans = fields.flatMap((field) => {
+    const clamped = field.span ? clampSpan(field.span, source.length) : null;
+    return clamped ? [{ name: field.name, ...clamped }] : [];
+  });
+
+  if (source.length === 0) return [];
+  if (spans.length === 0) return [{ text: source, fields: [] }];
+
+  const cuts = new Set<number>([0, source.length]);
+  for (const span of spans) {
+    cuts.add(span.start);
+    cuts.add(span.end);
+  }
+  const points = [...cuts].sort((a, b) => a - b);
+
+  const runs: SourceRun[] = [];
+  for (let index = 0; index < points.length - 1; index += 1) {
+    const start = points[index] ?? 0;
+    const end = points[index + 1] ?? start;
+    if (end <= start) continue;
+    runs.push({
+      text: source.slice(start, end),
+      fields: spans.filter((span) => span.start <= start && span.end >= end).map((s) => s.name),
+    });
+  }
+  return runs;
+}
+
+export interface ReviewSummary {
+  total: number;
+  reviewed: number;
+  accepted: number;
+  corrected: number;
+  rejected: number;
+  /** Fields with a value the model could not point to in the source. */
+  unsourced: string[];
+  /** Fields still awaiting a decision. */
+  remaining: string[];
+  /** Every field has a decision. The only completion signal worth trusting. */
+  complete: boolean;
+}
+
+export function summarizeReview(
+  source: string,
+  fields: ExtractionField[],
+  decisions: Record<string, FieldDecision> = {},
+): ReviewSummary {
+  const summary: ReviewSummary = {
+    total: fields.length,
+    reviewed: 0,
+    accepted: 0,
+    corrected: 0,
+    rejected: 0,
+    unsourced: [],
+    remaining: [],
+    complete: false,
+  };
+
+  for (const field of fields) {
+    if (field.value !== undefined && !isSourced(source, field)) {
+      summary.unsourced.push(field.name);
+    }
+    const decision = decisions[field.name];
+    if (!decision) {
+      summary.remaining.push(field.name);
+      continue;
+    }
+    summary.reviewed += 1;
+    summary[decision.kind] += 1;
+  }
+
+  summary.complete = fields.length > 0 && summary.remaining.length === 0;
+  return summary;
+}

package/src/components/ai-extraction-review/index.ts

@@ -0,0 +1,13 @@
+export { ExtractionReview, type ExtractionReviewProps } from "./ai-extraction-review";
+export {
+  clampSpan,
+  evidenceOf,
+  isSourced,
+  segmentSource,
+  summarizeReview,
+  type ExtractionField,
+  type FieldDecision,
+  type ReviewSummary,
+  type SourceRun,
+  type SourceSpan,
+} from "./extraction-model";

package/src/components/ai-extraction-review/meta.ts

@@ -0,0 +1,24 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "ai-extraction-review",
+  title: "AI Extraction Review",
+  description:
+    "Check extracted fields against the document they came from, and decide each one.",
+  category: "ai",
+  status: "stable",
+  dependencies: [],
+  registryDependencies: [],
+  files: ["extraction-model.ts", "ai-extraction-review.tsx"],
+  a11y:
+    "Every field quotes its evidence in text under the value, so a reviewer who cannot see the " +
+    "highlight in the source still has what the model read. A value with no evidence is said in " +
+    "words — never left to look like a good one. The source is a focusable named region because " +
+    "it scrolls, and its highlights are mark elements with nothing spliced into the text, since a " +
+    "document read aloud with field names inserted is no longer the document. Focus anywhere in a " +
+    "field brings its evidence into view without moving focus, so a keyboard user is shown the " +
+    "source rather than sent into it. Each control's name carries the field it belongs to, so " +
+    "ten Accept buttons are ten different buttons. Status is a word, outside the label so editing " +
+    "never renames the control, and the running count is a polite live region present from the " +
+    "start. Enter accepts, except while an IME is composing.",
+});

package/src/components/ai-prompt-input/ai-prompt-input.tsx

@@ -222,7 +222,7 @@ export function PromptInputSubmit({
       disabled={disabled}
       onClick={busy ? onStop : undefined}
       className={cn(
-        "ml-auto grid size-8 shrink-0 place-items-center rounded-lg",
+        "ms-auto grid size-8 shrink-0 place-items-center rounded-lg",
         "bg-primary text-primary-foreground transition-colors duration-[var(--duration-fast)]",
         "hover:bg-primary-hover disabled:pointer-events-none disabled:opacity-55",
         focusRing,

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

@@ -98,7 +98,7 @@ export function ReasoningContent({
       )}
       {...props}
     >
-      <div className="mt-2 border-l-2 border-border pl-3 text-sm whitespace-pre-wrap text-muted-foreground">
+      <div className="mt-2 border-s-2 border-border ps-3 text-sm whitespace-pre-wrap text-muted-foreground">
         {children}
       </div>
     </CollapsiblePrimitive.Content>

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

@@ -31,7 +31,7 @@ export function Response({ className, streaming, children, ...props }: ResponseP
         // Minimal prose styling for consumers who pass rendered Markdown.
         "[&_a]:text-primary [&_a]:underline [&_a]:underline-offset-4",
         "[&_code]:rounded [&_code]:bg-muted [&_code]:px-1 [&_code]:py-0.5 [&_code]:font-mono [&_code]:text-[0.9em]",
-        "[&_ol]:my-2 [&_ol]:list-decimal [&_ol]:pl-5 [&_ul]:my-2 [&_ul]:list-disc [&_ul]:pl-5",
+        "[&_ol]:my-2 [&_ol]:list-decimal [&_ol]:ps-5 [&_ul]:my-2 [&_ul]:list-disc [&_ul]:ps-5",
         "[&_p+p]:mt-3",
         className,
       )}
@@ -52,7 +52,7 @@ export function ResponseCaret({ className, ...props }: ComponentPropsWithRef<"sp
       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",
+        "ms-0.5 inline-block h-[1em] w-[2px] translate-y-[0.15em] animate-caret bg-current align-baseline",
         className,
       )}
       {...props}

package/src/components/ai-suggested-value/ai-suggested-value.tsx

@@ -0,0 +1,295 @@
+"use client";
+
+import {
+  cloneElement,
+  isValidElement,
+  useId,
+  useState,
+  type ComponentPropsWithRef,
+  type ReactElement,
+  type ReactNode,
+} from "react";
+
+import { disabledStyles, focusRing } from "@/lib/styles";
+import { cn } from "@/lib/utils";
+
+/**
+ * An AI-proposed value for a form control, offered beside it rather than
+ * written into it.
+ *
+ * Autofill is the most common shape AI takes inside ordinary software —
+ * enrich this contact, fill this form from the upload, guess the category —
+ * and nearly every implementation writes the value straight into the field
+ * as if the person had typed it. Two things go wrong. A plausible, wrong
+ * value rides through on the person's own Submit, because nothing marked it
+ * as needing a look. And once submitted, the record cannot tell a value the
+ * model supplied from one a human typed, which is the one fact an audit later
+ * needs.
+ *
+ * So the suggestion stays pending until it is accepted, and acceptance is
+ * reported rather than performed: the component hands the value to `onAccept`
+ * and never touches the control. That is also what lets it wrap any control —
+ * a select, a date, a number, a combobox — where ghost text can only complete
+ * a string. Afterwards the field says it was filled by AI, says if it was
+ * edited since, and offers to put back what was there.
+ *
+ * Deliberately no "accept all". A button that takes every suggestion at once
+ * is the review deleting itself, and every product that ships one watches its
+ * users press it without reading.
+ */
+
+export interface Suggestion<T = string> {
+  value: T;
+  /** How the value reads — a select's option text, a formatted date. Defaults to the value. */
+  label?: string;
+  /** Where it came from, in the reader's language: "from the invoice header". */
+  source?: string;
+  /** 0 to 1. Shown as a number, never only as a colour. */
+  confidence?: number;
+}
+
+export type SuggestionStatus = "pending" | "accepted" | "dismissed";
+
+export interface SuggestedValueProps<T = string> extends Omit<
+  ComponentPropsWithRef<"div">,
+  "children" | "id" | "aria-describedby" | "aria-invalid"
+> {
+  /** The field, for the buttons' names: "Accept suggestion — Company". */
+  label: string;
+  /** Null or undefined offers nothing. A different suggestion starts pending again. */
+  suggestion?: Suggestion<T> | null;
+  /**
+   * The control's current value. Lets the marker say the fill was edited
+   * since, and lets Undo restore what the field held before.
+   */
+  value?: T;
+  /** Supply to own the status; otherwise it is kept here. */
+  status?: SuggestionStatus;
+  onAccept: (value: T, suggestion: Suggestion<T>) => void;
+  onDismiss?: (suggestion: Suggestion<T>) => void;
+  /** Called with the value the field held before the fill, so it can be put back. */
+  onRevert?: (previous: T | undefined) => void;
+  /** How to compare values. Object.is by default. */
+  equals?: (a: T, b: T) => boolean;
+  /** Confidence below this is called low, in words. */
+  lowConfidenceBelow?: number;
+  /**
+   * Announce a suggestion when it arrives. Off by default: a form that fills
+   * twenty fields at once would narrate all twenty, and the description on
+   * the control already tells a reader when they reach the field.
+   */
+  announce?: boolean;
+  /** The control. Receives the description, and any id or ARIA a FormControl passes down. */
+  children: ReactElement<Record<string, unknown>>;
+  /* Passed through to the control, so this can sit inside a FormControl. */
+  id?: string;
+  "aria-describedby"?: string;
+  "aria-invalid"?: ComponentPropsWithRef<"input">["aria-invalid"];
+}
+
+function defaultLabel(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 (value instanceof Date) return value.toLocaleDateString();
+  return JSON.stringify(value);
+}
+
+function sameSuggestion<T>(
+  a: Suggestion<T> | null | undefined,
+  b: Suggestion<T> | null | undefined,
+  equals: (x: T, y: T) => boolean,
+): boolean {
+  if (!a || !b) return a === b;
+  return equals(a.value, b.value) && a.label === b.label && a.source === b.source;
+}
+
+export function SuggestedValue<T = string>({
+  className,
+  label,
+  suggestion,
+  value,
+  status: controlledStatus,
+  onAccept,
+  onDismiss,
+  onRevert,
+  equals = Object.is,
+  lowConfidenceBelow = 0.7,
+  announce = false,
+  children,
+  id,
+  "aria-describedby": describedByProp,
+  "aria-invalid": ariaInvalid,
+  ...props
+}: SuggestedValueProps<T>) {
+  const descriptionId = useId();
+
+  const [internalStatus, setInternalStatus] = useState<SuggestionStatus>("pending");
+  const [previous, setPrevious] = useState<T | undefined>(undefined);
+
+  // A new suggestion starts pending, whatever happened to the last one.
+  // Compared by content rather than identity, so a parent that rebuilds the
+  // object on every keystroke does not reopen a suggestion already accepted.
+  const [seen, setSeen] = useState(suggestion);
+  if (!sameSuggestion(seen, suggestion, equals)) {
+    setSeen(suggestion);
+    setInternalStatus("pending");
+  }
+
+  const status = controlledStatus ?? internalStatus;
+  const offered = suggestion ?? null;
+  const pending = offered !== null && status === "pending";
+  const accepted = offered !== null && status === "accepted";
+  const edited = accepted && value !== undefined && !equals(value, offered.value);
+
+  const low = offered?.confidence !== undefined && offered.confidence < lowConfidenceBelow;
+  const percent =
+    offered?.confidence === undefined
+      ? null
+      : new Intl.NumberFormat(undefined, { style: "percent", maximumFractionDigits: 0 }).format(
+          offered.confidence,
+        );
+
+  const source = offered?.source ? ` ${offered.source}` : "";
+
+  // What the control's description says. This is how a reader who lands on
+  // the field learns there is a suggestion, without any announcement.
+  let description: ReactNode = null;
+  if (pending) {
+    description = (
+      <>
+        Suggested:{" "}
+        <strong className="font-medium text-foreground">
+          {offered.label ?? defaultLabel(offered.value)}
+        </strong>
+        {source ? `,${source}` : null}
+        {percent !== null ? (
+          <span className={cn(low && "text-warning")}>
+            {low ? `. Low confidence, ${percent} — worth checking` : `. ${percent} confidence`}
+          </span>
+        ) : null}
+      </>
+    );
+  } else if (accepted) {
+    description = edited
+      ? `Filled by AI${source ? `,${source}` : ""}, then edited`
+      : `Filled by AI${source ? `,${source}` : ""}`;
+  }
+
+  // Merged with whatever already describes the control — a FormControl's
+  // description and message, or the child's own — rather than replacing it.
+  const childDescribedBy = isValidElement(children)
+    ? (children.props["aria-describedby"] as string | undefined)
+    : undefined;
+  const describedBy =
+    [childDescribedBy, describedByProp, description !== null ? descriptionId : null]
+      .filter(Boolean)
+      .join(" ") || undefined;
+
+  const control = isValidElement(children)
+    ? cloneElement(children, {
+        id: id ?? children.props.id,
+        "aria-describedby": describedBy,
+        "aria-invalid": ariaInvalid ?? children.props["aria-invalid"],
+      })
+    : children;
+
+  const accept = () => {
+    if (!offered) return;
+    setPrevious(value);
+    setInternalStatus("accepted");
+    onAccept(offered.value, offered);
+  };
+
+  return (
+    <div
+      data-slot="suggested-value"
+      data-status={offered ? status : undefined}
+      data-filled-by={accepted ? "ai" : undefined}
+      data-edited={edited || undefined}
+      className={cn("flex flex-col gap-1.5", className)}
+      {...props}
+    >
+      {control}
+
+      {/* Present from the start and never display:none, so that with `announce`
+          a suggestion arriving after mount is heard — a region that enters the
+          accessibility tree at the same moment as its content announces
+          nothing. Empty, it has no height. */}
+      <div
+        data-slot="suggested-value-row"
+        aria-live={announce ? "polite" : undefined}
+        className={cn(
+          "flex flex-wrap items-center gap-x-3 gap-y-1 text-xs",
+          pending && "rounded-md border border-primary/40 bg-primary/5 px-2.5 py-1.5",
+        )}
+      >
+        {description !== null ? (
+          <p
+            id={descriptionId}
+            data-slot="suggested-value-description"
+            className="m-0 flex-1 text-muted-foreground"
+          >
+            {description}
+          </p>
+        ) : null}
+
+        {pending ? (
+          <span className="flex items-center gap-2">
+            <RowButton
+              variant="primary"
+              aria-label={`Accept suggestion — ${label}`}
+              onClick={accept}
+            >
+              Accept
+            </RowButton>
+            <RowButton
+              aria-label={`Dismiss suggestion — ${label}`}
+              onClick={() => {
+                setInternalStatus("dismissed");
+                onDismiss?.(offered);
+              }}
+            >
+              Dismiss
+            </RowButton>
+          </span>
+        ) : null}
+
+        {accepted && onRevert ? (
+          <RowButton
+            aria-label={`Undo — ${label}`}
+            onClick={() => {
+              setInternalStatus("pending");
+              onRevert(previous);
+            }}
+          >
+            Undo
+          </RowButton>
+        ) : null}
+      </div>
+    </div>
+  );
+}
+
+function RowButton({
+  className,
+  variant = "default",
+  ...props
+}: ComponentPropsWithRef<"button"> & { variant?: "default" | "primary" }) {
+  return (
+    <button
+      type="button"
+      className={cn(
+        "rounded-md border px-2 py-0.5 text-xs font-medium transition-colors",
+        variant === "primary"
+          ? "border-primary bg-primary text-primary-foreground hover:bg-primary-hover"
+          : "border-input bg-background hover:bg-accent hover:text-accent-foreground",
+        focusRing,
+        disabledStyles,
+        className,
+      )}
+      {...props}
+    />
+  );
+}

package/src/components/ai-suggested-value/index.ts

@@ -0,0 +1,6 @@
+export {
+  SuggestedValue,
+  type SuggestedValueProps,
+  type Suggestion,
+  type SuggestionStatus,
+} from "./ai-suggested-value";

package/src/components/ai-suggested-value/meta.ts

@@ -0,0 +1,24 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "ai-suggested-value",
+  title: "AI Suggested Value",
+  description:
+    "An AI-proposed value for any form control, pending until accepted and marked afterwards.",
+  category: "ai",
+  status: "stable",
+  dependencies: [],
+  registryDependencies: [],
+  files: ["ai-suggested-value.tsx"],
+  a11y:
+    "The suggestion is the control's description, so a reader who lands on the field hears it " +
+    "without any announcement — and announcing is opt-in, because a form filling twenty fields at " +
+    "once would narrate all twenty. The row that holds it is rendered from the start and never " +
+    "display:none, so when announcing is on, a suggestion arriving after mount is actually heard. " +
+    "Each button's name carries the field it belongs to, so a page of Accepts is a page of " +
+    "different buttons. Provenance and confidence are words with a number, never a colour. " +
+    "Acceptance is reported, not performed: the control is the consumer's, so its value, its " +
+    "label and its own keyboard behaviour are untouched — there is no shortcut hijacked from a " +
+    "select or a date field. The id and ARIA a FormControl passes down are forwarded to the " +
+    "control, and an existing aria-describedby is merged rather than replaced.",
+});

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

@@ -82,7 +82,7 @@ export function ToolHeader({
     <CollapsiblePrimitive.Trigger
       data-slot="tool-header"
       className={cn(
-        "flex w-full items-center gap-2 px-3 py-2 text-left",
+        "flex w-full items-center gap-2 px-3 py-2 text-start",
         "transition-colors duration-[var(--duration-fast)] hover:bg-accent/50",
         "[&[data-state=open]>svg:last-child]:rotate-180",
         focusRing,
@@ -97,7 +97,7 @@ export function ToolHeader({
       <span
         data-slot="tool-status"
         className={cn(
-          "ml-auto text-xs",
+          "ms-auto text-xs",
           status === "error" ? "text-destructive" : "text-muted-foreground",
         )}
       >