@dowel-ui/react 0.4.0 → 0.5.0

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/confirm-typed/confirm-typed.tsx

@@ -0,0 +1,191 @@
+"use client";
+
+import {
+  useId,
+  useRef,
+  useState,
+  type ComponentPropsWithRef,
+  type KeyboardEvent,
+  type ReactNode,
+} from "react";
+
+import { Button } from "@/components/button";
+import { Input } from "@/components/input";
+import { cn } from "@/lib/utils";
+
+/**
+ * Type the name to confirm.
+ *
+ * The GitHub pattern for deleting a repository, and the one every product
+ * copies for the action that cannot be undone: the name of the thing has to
+ * pass through the reader's fingers before the button works. Trivial to
+ * build, absent from every component library, and usually built wrong in
+ * the one place it matters — what happens when the text does not match.
+ * The common version disables the button and says nothing, so a keyboard
+ * or screen reader user presses it, or presses Enter, and nothing happens
+ * at all.
+ *
+ * Here a mismatch is a thing that is said. The button stays reachable and
+ * pressing it, or Enter, before the text matches announces what was
+ * expected and marks the field invalid. The moment the text matches, that
+ * is announced too, once, so a reader knows the action has become
+ * available without watching the button change colour.
+ *
+ * Pasting is allowed. Blocking it is a popular piece of friction, and it
+ * punishes exactly the people who cannot type a long name easily — switch
+ * users, voice users, anyone with a tremor — while stopping nobody who can
+ * select-all and copy. The name is on screen either way; the point is that
+ * it passed through the reader's attention, not their keyboard.
+ */
+
+export interface ConfirmTypedProps extends Omit<ComponentPropsWithRef<"div">, "children"> {
+  /** The text that must be typed, exactly. */
+  expected: string;
+  /** What confirming does, as the button reads: "Delete project". */
+  action: string;
+  onConfirm: () => void;
+  /** While the action runs. The button stays focusable and says so. */
+  pending?: boolean;
+  /** Match regardless of case. Off by default: a name is a name. */
+  caseSensitive?: boolean;
+  variant?: "destructive" | "primary";
+  /** The typed text. Controlled, if you want it. */
+  value?: string;
+  onValueChange?: (value: string) => void;
+  /** The consequence, in a sentence or two, before the field. */
+  children?: ReactNode;
+}
+
+export function ConfirmTyped({
+  className,
+  expected,
+  action,
+  onConfirm,
+  pending = false,
+  caseSensitive = true,
+  variant = "destructive",
+  value: valueProp,
+  onValueChange,
+  children,
+  ...props
+}: ConfirmTypedProps) {
+  const id = useId();
+  const inputRef = useRef<HTMLInputElement>(null);
+
+  const [uncontrolled, setUncontrolled] = useState("");
+  const value = valueProp ?? uncontrolled;
+
+  const [attempted, setAttempted] = useState(false);
+  const [announcement, setAnnouncement] = useState("");
+
+  // Surrounding whitespace never decides it: a trailing space is not a
+  // different name, and a reader cannot see it to know why it failed.
+  const normalise = (text: string) => (caseSensitive ? text.trim() : text.trim().toLowerCase());
+  const matched = value.length > 0 && normalise(value) === normalise(expected);
+
+  // Announce the match once, on the transition. Adjusted during render so the
+  // announcement lands in the same commit as the state it describes.
+  const [wasMatched, setWasMatched] = useState(matched);
+  if (wasMatched !== matched) {
+    setWasMatched(matched);
+    if (matched) {
+      setAnnouncement(`Matches. ${action} is available.`);
+      setAttempted(false);
+    }
+  }
+
+  const setValue = (next: string) => {
+    setUncontrolled(next);
+    onValueChange?.(next);
+  };
+
+  const attempt = () => {
+    if (pending) return;
+    if (matched) {
+      onConfirm();
+      return;
+    }
+    // Said, not swallowed. A press that does nothing tells a keyboard user
+    // nothing; this one tells them what was expected.
+    setAttempted(true);
+    setAnnouncement(`Does not match. Type ${expected} exactly.`);
+    inputRef.current?.focus();
+  };
+
+  const onKeyDown = (event: KeyboardEvent<HTMLInputElement>) => {
+    if (event.key !== "Enter" || event.nativeEvent.isComposing) return;
+    event.preventDefault();
+    attempt();
+  };
+
+  const mismatch = attempted && !matched;
+  const hint = matched
+    ? "Matches."
+    : mismatch
+      ? `Does not match. Type ${expected} exactly.`
+      : caseSensitive
+        ? "Type it exactly as shown."
+        : "Type it as shown. Case does not matter.";
+
+  return (
+    <div
+      data-slot="confirm-typed"
+      data-state={matched ? "matched" : mismatch ? "mismatched" : "idle"}
+      className={cn("flex flex-col gap-2", className)}
+      {...props}
+    >
+      {children}
+
+      <label htmlFor={`${id}-input`} className="text-sm">
+        To confirm, type{" "}
+        <strong className="rounded bg-muted px-1 py-0.5 font-mono text-xs font-medium select-all">
+          {expected}
+        </strong>
+      </label>
+
+      <Input
+        ref={inputRef}
+        id={`${id}-input`}
+        value={value}
+        autoComplete="off"
+        autoCapitalize="off"
+        spellCheck={false}
+        aria-describedby={`${id}-hint`}
+        aria-invalid={mismatch || undefined}
+        onChange={(event) => {
+          setValue(event.target.value);
+        }}
+        onKeyDown={onKeyDown}
+      />
+
+      <p
+        id={`${id}-hint`}
+        data-slot="confirm-typed-hint"
+        className={cn(
+          "text-xs",
+          mismatch ? "text-destructive" : matched ? "text-success" : "text-muted-foreground",
+        )}
+      >
+        {hint}
+      </p>
+
+      {/* Present from the first render, so the first announcement is heard. */}
+      <span role="status" aria-live="polite" className="sr-only">
+        {announcement}
+      </span>
+
+      <Button
+        variant={variant}
+        loading={pending}
+        data-ready={matched || undefined}
+        aria-describedby={matched ? undefined : `${id}-hint`}
+        // Dimmed rather than disabled while the text does not match: it stays
+        // reachable, and pressing it says why nothing happened.
+        className={cn("self-start", !matched && !pending && "opacity-55")}
+        onClick={attempt}
+      >
+        {pending ? `${action}…` : action}
+      </Button>
+    </div>
+  );
+}

package/src/components/confirm-typed/index.ts

@@ -0,0 +1 @@
+export { ConfirmTyped, type ConfirmTypedProps } from "./confirm-typed";

package/src/components/confirm-typed/meta.ts

@@ -0,0 +1,22 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "confirm-typed",
+  title: "Confirm Typed",
+  description: "Type the name to confirm — and be told, not ignored, when it does not match.",
+  category: "form",
+  status: "stable",
+  dependencies: [],
+  registryDependencies: ["button", "input"],
+  files: ["confirm-typed.tsx"],
+  a11y:
+    "The button stays reachable while the text does not match, dimmed rather than disabled, and " +
+    "pressing it or Enter announces what was expected, marks the field invalid and returns focus " +
+    "to it — the common version disables the button and says nothing, so a keyboard user cannot " +
+    "tell whether anything happened. The match is announced once, on the transition, naming the " +
+    "action that became available, so nobody has to watch the button change colour. Typing " +
+    "itself stays silent, because a verdict on every keystroke is noise. The hint is the field's " +
+    "description and the button's, and the status region exists from the first render so the " +
+    "first announcement is heard. Pasting is allowed: blocking it punishes people who cannot " +
+    "type a long name easily and stops nobody who can select-all and copy.",
+});