@appinternalleads/ui 0.2.0

package/src/widgets/07-FileUpload.tsx

@@ -0,0 +1,449 @@
+import { useEffect, useRef, useState } from 'react';
+import { Box, Icon, Pressable, Text } from '../core';
+import { useDs } from '../tokens';
+import { widget, widgetRadius } from './tokens';
+import { useSurface } from './useSurface';
+import type { Driven } from './driven';
+import { WidgetCard } from './WidgetCard';
+import {
+  useFileUploadEngine, DEFAULT_FILE_UPLOAD_CONFIG,
+  type FileUploadConfig, type FileItem, type FileItemState, type SelectableFile,
+  type UploadOperations,
+} from './fileUploadEngine';
+
+export {
+  useFileUploadEngine, validateFile, createMockUploadOperations, DEFAULT_FILE_UPLOAD_CONFIG,
+  type FileUploadConfig, type FileItem, type FileItemState, type SelectableFile,
+  type UploadOperations, type UploadResult, type UploadProgressEvent,
+} from './fileUploadEngine';
+
+/**
+ * **07 · File Upload** — `FILES` → `FileRef[]` · hue `sky` · **eight states, four of them
+ * failure.**
+ *
+ * > *"The only widget where the user hands over something irreversible at the moment they cannot
+ * > see whether it worked."*
+ *
+ * Two rules from `WIDGET-FLOWS-HANDOFF.md` §3.1 shape everything here:
+ *
+ * **Every state keeps the remove.** A file you cannot remove is a file the user abandons the
+ * whole run over.
+ *
+ * **Silent skipping is the risk.** If 3 of 47 fail and the run carries on, the user believes they
+ * shortlisted 47 people. **Name, count, and offer the retry in one breath** — which is why the
+ * batch summary is a state rather than a toast.
+ *
+ * **Two modes, not one rewritten in place — both real, neither a stand-in for the other:**
+ *
+ * 1. **Driven/controlled** (`files` prop, no `operations`) — unchanged from the original build.
+ *    A host that already owns the whole state machine (e.g. a `question/1`-driven replay, see
+ *    `fromSpec.tsx`) still just hands this widget a `FileRef[]` to draw. Pure render, as before.
+ * 2. **Engine-driven** (`operations` prop present) — this widget now owns validation, the
+ *    upload lifecycle, retry, cancel and race-safety itself, via `fileUploadEngine.ts`.
+ *    **Picking is still the host's job** (`onPick`, a native module or `<input type=file>`);
+ *    everything from "a file was picked" onward is this component's — validation, the upload
+ *    lifecycle, retry, cancel and race-safety, previously all host-owned across this widget family.
+ *
+ * Deliberately **not** built here: the much larger "Upload → Processing → Executing → Result"
+ * agent-run pipeline (parsing, scoring, drafting, a decision deck, backgrounding) documented in
+ * the same source bundle's `Upload Flow.dc.html` — that is a separate, app-level run/canvas
+ * system, not a file-upload component concern.
+ */
+
+export type FileState =
+  | 'selected'   // named back, before the user confirms
+  | 'uploading'
+  | 'uploaded'
+  | 'too-large'
+  | 'wrong-type'
+  | 'failed';
+
+export type FileRef = {
+  n: string;
+  /** Already formatted — `42 KB`. The widget does not own byte formatting. */
+  s: string;
+  ext: string;
+  state?: FileState;
+  /** 0–1. **Held, not reset, on failure** — retry resumes from where it stopped. */
+  progress?: number;
+};
+
+export const FILE_FIXTURES: FileRef[] = [
+  { n: 'candidates-sept.csv', s: '42 KB', ext: 'CSV', state: 'uploaded' },
+  { n: 'role-brief-final.pdf', s: '118 KB', ext: 'PDF', state: 'uploaded' },
+];
+
+/**
+ * **A refusal says what to do, not what went wrong.** *"Export it as a PDF"* is actionable;
+ * *"invalid file type"* leaves the user holding a file and no next step.
+ *
+ * Both size and type are refused **client-side, at pick time** — the handoff is explicit. A file
+ * rejected after a 90-second upload is a wasted 90 seconds and a user who no longer trusts it.
+ */
+const FAILURE_COPY: Record<'too-large' | 'wrong-type' | 'failed', string> = {
+  'too-large': 'Over 10 MB. Try a smaller export.',
+  'wrong-type': 'PDF or DOCX only. Export it as a PDF and drop it again.',
+  failed: 'Upload stopped. Retry picks up where it left off.',
+};
+
+const FAILED: FileState[] = ['too-large', 'wrong-type', 'failed'];
+
+/** Past eight files the list collapses to a count (§3.1). */
+const COLLAPSE_AT = 8;
+
+/** A uniform shape both modes render from — `FileRef` (driven) or `FileItem` (engine) map to
+    this, so `Body`/`FileRow` below have exactly one rendering path, not two. */
+type DisplayFile = {
+  key: string;
+  name: string;
+  sizeLabel: string;
+  ext: string;
+  state: FileState | 'cancelled';
+  progress?: number;
+  errorMessage?: string;
+};
+
+function fromFileRef(f: FileRef): DisplayFile {
+  return {
+    key: f.n, name: f.n, sizeLabel: f.s, ext: f.ext,
+    state: f.state ?? 'uploaded', progress: f.progress,
+    errorMessage: f.state && FAILED.includes(f.state) ? FAILURE_COPY[f.state as 'too-large' | 'wrong-type' | 'failed'] : undefined,
+  };
+}
+
+function fromFileItem(it: FileItem): DisplayFile {
+  return {
+    key: it.localId, name: it.file.name, sizeLabel: it.file.sizeLabel, ext: it.file.ext,
+    state: it.state, progress: it.progress, errorMessage: it.error?.message,
+  };
+}
+
+const isDisplayFailed = (f: DisplayFile) => f.state === 'too-large' || f.state === 'wrong-type' || f.state === 'failed' || f.state === 'cancelled';
+
+export type FileUploadWidgetProps = Driven & {
+  // ── Driven/controlled mode ──────────────────────────────────────────────────────────────
+  files?: FileRef[];
+  max?: number;
+  onAdd?: () => void;
+  onRemove?: (name: string) => void;
+  onRetry?: (name: string) => void;
+  /** State 2 — the user confirms what was named back to them. */
+  onConfirm?: () => void;
+  onCancel?: () => void;
+
+  // ── Engine-driven mode — supply `operations` to opt in ─────────────────────────────────
+  /** The replaceable data-operation boundary (upload). Presence of this prop is what switches
+      the widget from driven/controlled to owning its own lifecycle. */
+  operations?: UploadOperations;
+  /** Validation config (accept/maxSizeBytes/maxFiles). Defaults to the source's own defaults
+      (PDF/DOCX, 10 MB, 10 files) when `operations` is supplied and this is omitted. */
+  config?: FileUploadConfig;
+  /** The host's own picker (native module or `<input type=file>`) — "picking is the host's
+      job" is unchanged; this is the seam. Called when Add is pressed; its resolved files are
+      validated and queued by this widget. */
+  onPick?: () => Promise<SelectableFile[]>;
+};
+
+export function FileUploadWidget(props: FileUploadWidgetProps) {
+  const {
+    operations, config, onPick,
+    files = FILE_FIXTURES, max = 10, onAdd, onRemove, onRetry, onConfirm, onCancel, prompt, onMenu,
+    pill: pillLabel, title: cardTitle, label, hint,
+  } = props;
+
+  if (operations) {
+    return (
+      <EngineBody
+        operations={operations} config={config} onPick={onPick}
+        prompt={prompt} onMenu={onMenu} pill={pillLabel} title={cardTitle} label={label} hint={hint}
+      />
+    );
+  }
+
+  return (
+    <WidgetCard
+      pill={pillLabel ?? 'FILES'}
+      title={cardTitle ?? 'File Upload'}
+      prompt={prompt ?? 'Screen these CVs against the brief I sent yesterday.'}
+      onMenu={onMenu}
+      testID="widget-07">
+      <Body
+        displayFiles={files.map(fromFileRef)} max={max}
+        onAdd={onAdd}
+        onRemove={onRemove}
+        onRetry={onRetry}
+        onConfirm={onConfirm} onCancel={onCancel}
+        label={label} hint={hint}
+      />
+    </WidgetCard>
+  );
+}
+
+/** The engine-driven mode's own top-level component — separated so its hook usage never runs
+    (and never has to be reasoned about) in the far more common driven/controlled path. */
+function EngineBody({
+  operations, config, onPick, prompt, onMenu, pill, title, label, hint,
+}: {
+  operations: UploadOperations; config?: FileUploadConfig; onPick?: () => Promise<SelectableFile[]>;
+  prompt?: string; onMenu?: () => void; pill?: string; title?: string; label?: string; hint?: string;
+}) {
+  const engine = useFileUploadEngine({ config, operations });
+  const max = config?.maxFiles ?? DEFAULT_FILE_UPLOAD_CONFIG.maxFiles;
+
+  const [announcement, setAnnouncement] = useState('');
+  const prevStates = useRef(new Map<string, FileItemState>());
+  useEffect(() => {
+    for (const it of engine.items) {
+      const prev = prevStates.current.get(it.localId);
+      if (prev !== it.state) {
+        if (it.state === 'uploaded') setAnnouncement(`${it.file.name} attached`);
+        else if (it.state === 'failed') setAnnouncement(`${it.file.name}: ${it.error?.message ?? 'upload failed'}`);
+        else if (it.state === 'too-large' || it.state === 'wrong-type') setAnnouncement(`${it.file.name}: ${it.error?.message ?? 'not accepted'}`);
+        else if (it.state === 'cancelled') setAnnouncement(`${it.file.name} cancelled`);
+      }
+      prevStates.current.set(it.localId, it.state);
+    }
+  }, [engine.items]);
+
+  const handleAdd = async () => {
+    if (!onPick) return;
+    const picked = await onPick();
+    if (picked.length > 0) engine.addFiles(picked);
+  };
+
+  return (
+    <WidgetCard
+      pill={pill ?? 'FILES'}
+      title={title ?? 'File Upload'}
+      prompt={prompt ?? 'Screen these CVs against the brief I sent yesterday.'}
+      onMenu={onMenu}
+      testID="widget-07">
+      <Body
+        displayFiles={engine.items.map(fromFileItem)} max={max}
+        onAdd={handleAdd}
+        onRemove={engine.remove}
+        onRetry={engine.retry}
+        onConfirm={engine.confirm}
+        onCancel={engine.cancelSelected}
+        label={label} hint={hint}
+      />
+      <Text accessibilityLiveRegion="polite" style={{ position: 'absolute', width: 1, height: 1, opacity: 0 }}>
+        {announcement}
+      </Text>
+    </WidgetCard>
+  );
+}
+
+function Body({
+  displayFiles, max, onAdd, onRemove, onRetry, onConfirm, onCancel, label, hint,
+}: {
+  displayFiles: DisplayFile[]; max: number;
+  onAdd?: () => void; onRemove?: (key: string) => void; onRetry?: (key: string) => void;
+  onConfirm?: () => void; onCancel?: () => void;
+  /** The dropzone's two lines: what to do, and what is allowed. */
+  label?: string; hint?: string;
+}) {
+  const { colors } = useDs();
+  const surface = useSurface();
+  const [dragOver, setDragOver] = useState(false);
+
+  const failed = displayFiles.filter(isDisplayFailed);
+  const attached = displayFiles.filter(f => !isDisplayFailed(f)).length;
+  const selecting = displayFiles.some(f => f.state === 'selected');
+  const collapsed = displayFiles.length > COLLAPSE_AT;
+
+  /**
+   * **The counter counts what attached, and never contradicts the rows beneath it.**
+   * Universal rule 12. `displayFiles.length` would read "4 files attached" above two rows saying
+   * they did not.
+   */
+  const counter =
+    attached === 0 ? 'Nothing attached yet'
+    : attached === 1 ? `1 file attached · ${max} max`
+    : `${attached} files attached · ${max} max`;
+
+  return (
+    <Box style={{ gap: 12 }}>
+      <Pressable
+        onPress={onAdd}
+        onHoverIn={() => setDragOver(true)}
+        onHoverOut={() => setDragOver(false)}
+        align="center"
+        justify="center"
+        aria-label={label ?? 'Add a file'}
+        style={{
+          gap: 5, paddingVertical: 22, paddingHorizontal: 16,
+          borderRadius: widgetRadius.inset,
+          borderWidth: 1,
+          borderStyle: 'dashed',
+          borderColor: dragOver ? colors.accentFill : colors.hairline,
+          backgroundColor: dragOver ? colors.accentTint : colors.surfaceSunken,
+        }}>
+        <Text color="accentInk" style={{ fontSize: 13.5, lineHeight: 13.5, fontWeight: '600' }}>
+          {label ?? 'Add a file'}
+        </Text>
+        <Text color="textSecondary" style={{ fontSize: 12, lineHeight: 12 }}>
+          {hint ?? 'PDF or DOCX · up to 10 MB'}
+        </Text>
+      </Pressable>
+
+      {collapsed ? (
+        <Box style={{ paddingVertical: 11 }}>
+          <Text color="textSecondary" style={{ fontSize: 13, lineHeight: 13 * 1.25 }}>
+            {`${displayFiles.length} files · ${attached} attached`}
+          </Text>
+        </Box>
+      ) : (
+        <Box>
+          {displayFiles.map((f, i) => (
+            <FileRow
+              key={f.key}
+              file={f}
+              first={i === 0}
+              onRemove={() => onRemove?.(f.key)}
+              onRetry={() => onRetry?.(f.key)}
+            />
+          ))}
+        </Box>
+      )}
+
+      {/**
+        * **State 5 — the batch summary.** Names the count and the failures in one breath, because
+        * a run that carries on quietly leaves the user believing they shortlisted 47 people.
+        */}
+      {failed.length > 0 && !selecting ? (
+        <Box
+          style={{
+            gap: 4, padding: 11, borderRadius: widgetRadius.inset,
+            backgroundColor: colors.surfaceSunken,
+          }}>
+          <Text style={{ fontSize: 13, lineHeight: 13 * 1.3, fontWeight: '600' }}>
+            {`${attached} of ${displayFiles.length} attached`}
+          </Text>
+          <Text color="textSecondary" style={{ fontSize: 12, lineHeight: 12 * 1.4 }}>
+            {`${failed.map(f => f.name).join(', ')} did not.`}
+          </Text>
+        </Box>
+      ) : null}
+
+      {/**
+        * **State 2 — Cancel is weighted equal to Upload.** The handoff says so, and it matters:
+        * the moment before an irreversible handover is the wrong place for a quiet secondary.
+        */}
+      {selecting ? (
+        <Box row style={{ gap: 10 }}>
+          <Pressable
+            onPress={onCancel}
+            flex={1}
+            radius="pill"
+            bg="surfaceSunken"
+            aria-label="Cancel"
+            minHeight={widget.submit.height[surface]}>
+            <Text color="textSecondary" style={{ fontSize: 14.5, fontWeight: '600' }}>Cancel</Text>
+          </Pressable>
+          <Pressable
+            onPress={onConfirm}
+            flex={1}
+            radius="pill"
+            bg="accentFill"
+            aria-label="Upload"
+            minHeight={widget.submit.height[surface]}>
+            <Text style={{ color: colors.accentOnFill, fontSize: 14.5, fontWeight: '600' }}>Upload</Text>
+          </Pressable>
+        </Box>
+      ) : null}
+
+      <Text
+        color="textSecondary"
+        align="center"
+        style={{ fontSize: widget.copy.counter.size[surface], lineHeight: widget.copy.counter.size[surface] }}>
+        {counter}
+      </Text>
+    </Box>
+  );
+}
+
+function FileRow({
+  file, first, onRemove, onRetry,
+}: { file: DisplayFile; first: boolean; onRemove: () => void; onRetry: () => void }) {
+  const { colors } = useDs();
+  const failed = isDisplayFailed(file);
+  const uploading = file.state === 'uploading';
+  const done = file.state === 'uploaded';
+  /** Retry resumes; the bar is not reset, so the held progress must survive the failure. */
+  const held = (file.state === 'failed' || file.state === 'cancelled') && file.progress !== undefined;
+  const errorMessage = file.errorMessage ?? (file.state === 'cancelled' ? 'Cancelled.' : undefined);
+
+  return (
+    <Box
+      style={{
+        minHeight: 52, paddingVertical: 11, paddingHorizontal: 2,
+        borderTopWidth: first ? 0 : 1,
+        borderTopColor: colors.hairline,
+      }}>
+      <Box row align="center" style={{ gap: 11 }}>
+        <Box
+          width={34} height={34} align="center" justify="center"
+          style={{ borderRadius: widgetRadius.inset, backgroundColor: colors.accentTint }}>
+          <Text mono color="accentInk" style={{ fontSize: 10, lineHeight: 10, fontWeight: '600' }}>
+            {file.ext}
+          </Text>
+        </Box>
+
+        <Box flex={1} style={{ gap: 3, minWidth: 0 }}>
+          <Text numberOfLines={1} style={{ fontSize: 13, lineHeight: 13 * 1.25, fontWeight: '600' }}>
+            {file.name}
+          </Text>
+          {failed ? (
+            /* ⚠ Should be `--apricot-deep`. Paper has no equivalent, and `status.running` is a
+               yellow-brown that reads as in-progress — the opposite of a refusal. Using the error
+               ink until that is resolved; see docs/HANDOFF-CONFLICTS.md §1. */
+            <Text color="status.error" style={{ fontSize: 11.5, lineHeight: 11.5 * 1.3 }}>
+              {errorMessage}
+            </Text>
+          ) : (
+            <Text mono color="textSecondary" style={{ fontSize: 11.5, lineHeight: 11.5 }}>
+              {file.sizeLabel}
+            </Text>
+          )}
+        </Box>
+
+        {/* State 4 — the spinner collapses to a mint check. */}
+        {done ? <Icon name="check" size={17} color={colors.status.executed} label="attached" /> : null}
+
+        {file.state === 'failed' || file.state === 'cancelled' ? (
+          <Pressable onPress={onRetry} px="s3" radius="pill" bg="surfaceSunken" aria-label={`Retry ${file.name}`} minHeight={widget.hit}>
+            <Text color="accentInk" style={{ fontSize: 12.5, fontWeight: '600' }}>Retry</Text>
+          </Pressable>
+        ) : null}
+
+        {/* Every state keeps the remove. A file you cannot remove is a run the user abandons. */}
+        <Pressable
+          onPress={onRemove} bg="surfaceSunken" radius="pill"
+          width={30} height={30} minHeight={widget.hit}
+          aria-label="Remove file" style={{ minWidth: widget.hit }}>
+          <Icon name="close" size={13} color={colors.textSecondary} />
+        </Pressable>
+      </Box>
+
+      {uploading || held ? (
+        <Box
+          role="progressbar"
+          aria-label={`${file.name} upload progress`}
+          aria-valuenow={Math.round((file.progress ?? 0) * 100)}
+          aria-valuemin={0}
+          aria-valuemax={100}
+          style={{ height: 3, marginTop: 8, borderRadius: 2, overflow: 'hidden', backgroundColor: colors.surfaceSunken }}>
+          {/* **Never eased.** A determinate bar that eases is lying about throughput (§6). */}
+          <Box
+            style={{
+              height: 3,
+              width: `${Math.round((file.progress ?? 0) * 100)}%`,
+              backgroundColor: held ? colors.textDisabled : colors.accentFill,
+            }}
+          />
+        </Box>
+      ) : null}
+    </Box>
+  );
+}

package/src/widgets/08-Voice.tsx

@@ -0,0 +1,136 @@
+import { useState } from 'react';
+import { Box, MotionView, Pressable, Text, useLoop } from '../core';
+import { useDs } from '../tokens';
+import type { Driven } from './driven';
+import { WidgetCard } from './WidgetCard';
+
+type VoiceState = 'idle' | 'recording' | 'done';
+
+const BARS = 17;
+
+/**
+ * One waveform bar. **Module scope, not defined inside the widget** — a component declared in a
+ * render body is a new type on every render, and React remounts it; that cost a swallowed press
+ * once already in `NumberField`, and here it would restart every bar's loop on each tick.
+ */
+function WaveBar({ i, active }: { i: number; active: boolean }) {
+  const { colors } = useDs();
+  /* The handoff's own arithmetic, kept as arithmetic so the pattern stays irregular. */
+  const height = active ? 10 + ((i * 7) % 19) : 6;
+  /**
+   * `rest: 0.5` parks the bar at the MIDDLE of its cycle, which is `scaleY: 1` — its full
+   * specified height. Parking at either end would show every bar squashed to 35%, so a user with
+   * Reduce Motion on would see a waveform that looks broken rather than one that is simply
+   * still.
+   */
+  const loop = useLoop({
+    duration: (0.7 + (i % 5) * 0.11) * 1000,
+    delay: i * 40,
+    enabled: active,
+    rest: 0.5,
+  });
+  const scaleY = loop.interpolate({ inputRange: [0, 0.5, 1], outputRange: [0.35, 1, 0.35] });
+
+  return (
+    <MotionView
+      style={{
+        width: 3,
+        height,
+        borderRadius: 2,
+        backgroundColor: active ? colors.accentFill : colors.hairlineStrong,
+        transform: [{ scaleY }],
+      }}
+    />
+  );
+}
+
+/**
+ * **08 · Voice Recorder** — `MEDIA` → a `FileRef`.
+ *
+ * **An audio file, not dictation.** This widget produces no transcript, and saying so is part of
+ * the contract: a user who believes they are dictating will speak differently, and will be
+ * surprised by what the run receives.
+ *
+ * The status line is not decoration either. The halo and the moving bars carry "recording" for
+ * everyone who can see them and for nobody else — under Reduce Motion, and to a screen reader,
+ * the words are the whole signal.
+ */
+export function VoiceRecorderWidget({
+  state: state0 = 'idle', seconds = 7, onChange, prompt, onMenu,
+  pill: pillLabel, title: cardTitle, label, hint,
+}: Driven & {
+  state?: VoiceState; seconds?: number;
+  onChange?: (s: VoiceState) => void
+}) {
+  const { colors } = useDs();
+  const [state, setState] = useState<VoiceState>(state0);
+  const recording = state === 'recording';
+
+  const halo = useLoop({ duration: 1400, enabled: recording });
+  const haloScale = halo.interpolate({ inputRange: [0, 1], outputRange: [1, 1.45] });
+  const haloOpacity = halo.interpolate({ inputRange: [0, 1], outputRange: [0.3, 0] });
+
+  const clock = `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, '0')}`;
+  const status =
+    state === 'idle' ? 'Tap to record'
+      : state === 'recording' ? `${clock} · tap to stop`
+        : `${clock} recorded · tap to redo`;
+
+  const advance = () => {
+    const next: VoiceState = state === 'recording' ? 'done' : 'recording';
+    setState(next);
+    onChange?.(next);
+  };
+
+  return (
+    <WidgetCard
+      pill={pillLabel ?? 'MEDIA'}
+      title={cardTitle ?? 'Voice Recorder'}
+      prompt={prompt ?? "I'll just say what I want instead of typing it."}
+      onMenu={onMenu}
+      testID="widget-08">
+      <Box align="center" style={{ gap: 13, paddingVertical: 3 }}>
+        <Box width={62} height={62} align="center" justify="center">
+          {recording ? (
+            <MotionView
+              style={{
+                position: 'absolute',
+                width: 62, height: 62, borderRadius: 31,
+                backgroundColor: colors.accentFill,
+                opacity: haloOpacity,
+                transform: [{ scale: haloScale }],
+              }}
+            />
+          ) : null}
+          <Pressable
+            onPress={advance}
+            radius="pill"
+            width={62}
+            height={62}
+            aria-label="Record"
+            style={{ backgroundColor: recording ? colors.accentPressed : colors.accentFill }}>
+            {/* Circle to square is the universal record/stop pair; no glyph font involved. */}
+            <Box
+              width={recording ? 20 : 24}
+              height={recording ? 20 : 24}
+              style={{
+                borderRadius: recording ? 5 : 12,
+                backgroundColor: colors.accentOnFill,
+              }}
+            />
+          </Pressable>
+        </Box>
+
+        <Box row align="flex-end" height={30} style={{ gap: 3 }}>
+          {Array.from({ length: BARS }, (_, i) => (
+            <WaveBar key={i} i={i} active={recording} />
+          ))}
+        </Box>
+
+        <Text mono color="textSecondary" style={{ fontSize: 12.5, lineHeight: 12.5 }}>
+          {status}
+        </Text>
+      </Box>
+    </WidgetCard>
+  );
+}