@dowel-ui/react 0.1.1 → 0.3.0

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

@@ -0,0 +1,268 @@
+"use client";
+
+import {
+  createContext,
+  useContext,
+  useMemo,
+  useState,
+  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];
+
+  // "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}
+    >
+      <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"
+          />
+        ) : (
+          <span
+            data-slot="structured-field-value"
+            className={cn(hasSettled && "inline-block animate-settle")}
+          >
+            {children ?? formatValue(raw, name)}
+          </span>
+        )}
+      </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/file-upload/file-upload.tsx

@@ -0,0 +1,322 @@
+"use client";
+
+import {
+  useId,
+  useRef,
+  useState,
+  type ComponentPropsWithRef,
+  type DragEvent,
+  type ReactNode,
+} from "react";
+
+import { disabledStyles, focusRing } from "@/lib/styles";
+import { cn } from "@/lib/utils";
+
+import { formatBytes, type QueuedFile, type UploadStatus } from "./upload-queue";
+
+/**
+ * The visible half of uploading. The queue is in `upload-queue.ts` and is the
+ * part worth owning.
+ *
+ * There is no dropzone pattern in the WAI-ARIA APG, and inventing one is the
+ * usual failure: a `div` with `role="button"`, a keydown handler, and a file
+ * picker that keyboard users can never reach. So the control here is a real
+ * `<input type="file">` with a real `<label>`. That is already operable by
+ * keyboard, already announces itself, already opens the picker on Enter and
+ * Space, and needs nothing added. Drag and drop is layered on top as a pointer
+ * convenience, and every drop can also be done from the input.
+ */
+
+const STATUS_LABEL: Record<UploadStatus, string> = {
+  queued: "Waiting",
+  uploading: "Uploading",
+  done: "Uploaded",
+  failed: "Failed",
+  cancelled: "Cancelled",
+};
+
+export interface FileUploadProps extends Omit<ComponentPropsWithRef<"div">, "onDrop"> {
+  /** Names the control. */
+  label: string;
+  onFiles: (files: File[]) => void;
+  accept?: string;
+  multiple?: boolean;
+  disabled?: boolean;
+  /** Shown under the prompt: accepted types, size limit. */
+  hint?: ReactNode;
+  children?: ReactNode;
+}
+
+export function FileUpload({
+  className,
+  label,
+  onFiles,
+  accept,
+  multiple = true,
+  disabled = false,
+  hint,
+  children,
+  ...props
+}: FileUploadProps) {
+  const inputId = useId();
+  const hintId = useId();
+  const [dragging, setDragging] = useState(false);
+  const depth = useRef(0);
+
+  function handleDrop(event: DragEvent<HTMLDivElement>) {
+    event.preventDefault();
+    depth.current = 0;
+    setDragging(false);
+    if (disabled) return;
+
+    const dropped = [...event.dataTransfer.files];
+    if (dropped.length > 0) onFiles(multiple ? dropped : dropped.slice(0, 1));
+  }
+
+  return (
+    <div data-slot="file-upload" className={cn("flex flex-col gap-3", className)} {...props}>
+      {/* dragenter/dragleave fire for every child element, so a plain boolean
+          flickers as the pointer crosses the prompt text. Counting depth is
+          what makes the highlight steady. */}
+      <div
+        data-slot="file-upload-dropzone"
+        data-dragging={dragging || undefined}
+        onDragEnter={(event) => {
+          event.preventDefault();
+          depth.current += 1;
+          if (!disabled) setDragging(true);
+        }}
+        onDragLeave={() => {
+          depth.current -= 1;
+          if (depth.current <= 0) setDragging(false);
+        }}
+        onDragOver={(event) => {
+          event.preventDefault();
+        }}
+        onDrop={handleDrop}
+        className={cn(
+          "rounded-lg border border-dashed border-border-strong bg-muted/30 px-4 py-6 text-center",
+          "transition-colors duration-[var(--duration-fast)]",
+          dragging && "border-primary bg-primary/5",
+          disabled && "pointer-events-none opacity-55",
+        )}
+      >
+        {/* The label is the control. Clicking it opens the picker, Enter and
+            Space activate it, and assistive technology already describes it. */}
+        <label
+          htmlFor={inputId}
+          className={cn(
+            "inline-flex cursor-pointer flex-col items-center gap-1 rounded-md px-2 py-1 text-sm",
+            "focus-within:ring-2 focus-within:ring-ring/55",
+          )}
+        >
+          <span className="font-medium">{label}</span>
+          <span className="text-xs text-muted-foreground">
+            Drop {multiple ? "files" : "a file"} here, or choose from your device
+          </span>
+          <input
+            id={inputId}
+            type="file"
+            accept={accept}
+            multiple={multiple}
+            disabled={disabled}
+            aria-describedby={hint ? hintId : undefined}
+            onChange={(event) => {
+              const chosen = [...(event.target.files ?? [])];
+              if (chosen.length > 0) onFiles(chosen);
+              // Reset, so choosing the same file twice fires change twice.
+              event.target.value = "";
+            }}
+            className="sr-only"
+          />
+        </label>
+
+        {hint ? (
+          <p id={hintId} className="mt-2 text-xs text-muted-foreground">
+            {hint}
+          </p>
+        ) : null}
+      </div>
+
+      {children}
+    </div>
+  );
+}
+
+export interface FileUploadListProps extends ComponentPropsWithRef<"ul"> {
+  files: QueuedFile[];
+  onCancel?: (id: string) => void;
+  onRetry?: (id: string) => void;
+  onRemove?: (id: string) => void;
+}
+
+export function FileUploadList({
+  className,
+  files,
+  onCancel,
+  onRetry,
+  onRemove,
+  ...props
+}: FileUploadListProps) {
+  if (files.length === 0) return null;
+
+  return (
+    <ul
+      data-slot="file-upload-list"
+      className={cn("flex list-none flex-col gap-2", className)}
+      {...props}
+    >
+      {files.map((entry) => (
+        <FileUploadItem
+          key={entry.id}
+          entry={entry}
+          onCancel={onCancel}
+          onRetry={onRetry}
+          onRemove={onRemove}
+        />
+      ))}
+    </ul>
+  );
+}
+
+export interface FileUploadItemProps extends Omit<ComponentPropsWithRef<"li">, "children"> {
+  entry: QueuedFile;
+  onCancel?: (id: string) => void;
+  onRetry?: (id: string) => void;
+  onRemove?: (id: string) => void;
+}
+
+export function FileUploadItem({
+  className,
+  entry,
+  onCancel,
+  onRetry,
+  onRemove,
+  ...props
+}: FileUploadItemProps) {
+  const { id, file, status, progress, error } = entry;
+  const percent = progress === null ? null : Math.round(progress * 100);
+
+  return (
+    <li
+      data-slot="file-upload-item"
+      data-status={status}
+      className={cn(
+        "flex items-center gap-3 rounded-lg border px-3 py-2 text-sm",
+        status === "failed"
+          ? "border-destructive/40 bg-destructive/5"
+          : "border-border bg-card",
+        className,
+      )}
+      {...props}
+    >
+      <div className="flex min-w-0 flex-1 flex-col gap-1">
+        <div className="flex items-baseline justify-between gap-2">
+          <span className="truncate font-medium">{file.name}</span>
+          <span className="shrink-0 text-xs text-muted-foreground tabular-nums">
+            {formatBytes(file.size)}
+          </span>
+        </div>
+
+        {/* Status in words, always. A bar at 60% with a red tint does not say
+            whether it is uploading, stalled or failed. */}
+        <p
+          className={cn(
+            "text-xs",
+            status === "failed" ? "text-destructive" : "text-muted-foreground",
+          )}
+        >
+          {STATUS_LABEL[status]}
+          {status === "uploading" && percent !== null ? ` · ${String(percent)}%` : null}
+          {error ? ` · ${error}` : null}
+        </p>
+
+        {status === "uploading" ? (
+          <div
+            role="progressbar"
+            aria-label={`Uploading ${file.name}`}
+            aria-valuenow={percent ?? undefined}
+            aria-valuemin={0}
+            aria-valuemax={100}
+            className="h-1 w-full overflow-hidden rounded-full bg-muted"
+          >
+            <div
+              data-slot="file-upload-progress"
+              className="h-full rounded-full bg-primary transition-[width] duration-[var(--duration-normal)] ease-[var(--ease-out-quint)]"
+              style={{ width: `${String(percent ?? 0)}%` }}
+            />
+          </div>
+        ) : null}
+      </div>
+
+      <div className="flex shrink-0 items-center gap-1">
+        {status === "uploading" && onCancel ? (
+          <ItemButton onClick={() => onCancel(id)}>Cancel</ItemButton>
+        ) : null}
+        {(status === "failed" || status === "cancelled") && onRetry ? (
+          <ItemButton onClick={() => onRetry(id)}>Retry</ItemButton>
+        ) : null}
+        {onRemove ? (
+          <ItemButton onClick={() => onRemove(id)} aria-label={`Remove ${file.name}`}>
+            Remove
+          </ItemButton>
+        ) : null}
+      </div>
+    </li>
+  );
+}
+
+function ItemButton({ className, ...props }: ComponentPropsWithRef<"button">) {
+  return (
+    <button
+      type="button"
+      className={cn(
+        "rounded-md border border-input bg-background px-2 py-0.5 text-xs font-medium",
+        "transition-colors hover:bg-accent hover:text-accent-foreground",
+        focusRing,
+        disabledStyles,
+        className,
+      )}
+      {...props}
+    />
+  );
+}
+
+/**
+ * One sentence covering the whole queue, announced politely.
+ *
+ * Per-file live regions would talk over each other the moment two uploads run
+ * at once; one summary of the set is readable where six competing ones are not.
+ */
+export function FileUploadStatus({
+  className,
+  stats,
+  ...props
+}: ComponentPropsWithRef<"p"> & {
+  stats: { total: number; active: number; done: number; failed: number };
+}) {
+  const { total, active, done, failed } = stats;
+
+  // Progress through the set, not a count of what happens to be in flight.
+  // "3 of 5 uploading" is wrong the moment a concurrency limit holds two back,
+  // and it never tells the reader how much of the job is left.
+  const message =
+    total === 0
+      ? ""
+      : active > 0
+        ? `${String(done)} of ${String(total)} uploaded`
+        : failed > 0
+          ? `${String(done)} uploaded, ${String(failed)} failed`
+          : `${String(done)} uploaded`;
+
+  return (
+    <p
+      data-slot="file-upload-status"
+      aria-live="polite"
+      className={cn("text-xs text-muted-foreground", className)}
+      {...props}
+    >
+      {message}
+    </p>
+  );
+}

package/src/components/file-upload/index.ts

@@ -0,0 +1,20 @@
+export {
+  FileUpload,
+  FileUploadItem,
+  FileUploadList,
+  FileUploadStatus,
+  type FileUploadItemProps,
+  type FileUploadListProps,
+  type FileUploadProps,
+} from "./file-upload";
+export {
+  formatBytes,
+  matchesAccept,
+  useUploadQueue,
+  xhrUpload,
+  type QueuedFile,
+  type UploadContext,
+  type UploadFn,
+  type UploadQueueOptions,
+  type UploadStatus,
+} from "./upload-queue";

package/src/components/file-upload/meta.ts

@@ -0,0 +1,21 @@
+import { defineMeta } from "@/registry/schema";
+
+export const meta = defineMeta({
+  name: "file-upload",
+  title: "File Upload",
+  description: "A dropzone over a real file input, plus the upload queue nobody ships.",
+  category: "form",
+  status: "stable",
+  dependencies: [],
+  registryDependencies: [],
+  files: ["upload-queue.ts", "file-upload.tsx"],
+  a11y:
+    "The APG has no dropzone pattern, and inventing one is the usual failure — a div with " +
+    'role="button", a keydown handler, and a picker keyboard users never reach. The control here ' +
+    "is a real input[type=file] with a real label, which is already operable, already announced, " +
+    "and opens the picker on Enter and Space with nothing added. Drag and drop is a pointer " +
+    "convenience layered on top; every drop can also be done from the input. Each uploading file " +
+    "gets a progressbar named after it, status is always stated in words as well as drawn, and " +
+    "one polite live region summarises the whole queue rather than six per-file regions talking " +
+    "over each other.",
+});