@appinternalleads/ui 0.2.0

package/src/widgets/22-26-Progress.tsx

@@ -0,0 +1,301 @@
+import { Arc, Box, Icon, MotionView, Text, useLoop } from '../core';
+import { useDs } from '../tokens';
+import { CounterLine, StatTile } from './parts';
+import { widget } from './tokens';
+import { WidgetCard } from './WidgetCard';
+
+/**
+ * **Group G — the run reporting on itself.** All five return nothing.
+ *
+ * The rule that governs the group: *"a step with no way to say no is a readout with a button on
+ * it."* If a progress card needs an action, the step attaches one explicitly — none of these
+ * five grows a button on its own, because a cancel that appears because a bar is slow is a cancel
+ * nobody planned for.
+ */
+
+/**
+ * **22 · Tick Bar** — determinate, countable.
+ *
+ * Use it when the unit is countable and **the count is the useful number**. Twenty-four ticks say
+ * "twenty-four CVs" in a way `46%` never does, and the two tiles give the fraction both halves.
+ */
+export function TickBarWidget({
+  done = 11, total = 24, remaining = 'about 40 seconds left', prompt, onMenu,
+}: {
+  done?: number; total?: number; remaining?: string; prompt?: string; onMenu?: () => void;
+}) {
+  const { colors } = useDs();
+  return (
+    <WidgetCard
+      pill="WORKING"
+      title="Tick Bar"
+      prompt={prompt ?? 'Screen all 24 CVs.'}
+      onMenu={onMenu}
+      testID="widget-22">
+      <Box style={{ gap: 13 }}>
+        <Box row style={{ gap: widget.stat.gap }}>
+          <StatTile live value={String(done)} label="Screened" />
+          <StatTile value={String(total)} label="Total in batch" />
+        </Box>
+        <Box row style={{ gap: 3 }}>
+          {Array.from({ length: total }, (_, i) => (
+            <Box
+              key={i}
+              flex={1}
+              height={8}
+              style={{
+                borderRadius: 2,
+                backgroundColor: i < done ? colors.accentFill : colors.surfaceSunken,
+              }}
+            />
+          ))}
+        </Box>
+        <CounterLine>{`${done} of ${total} · ${remaining}`}</CounterLine>
+      </Box>
+    </WidgetCard>
+  );
+}
+
+/**
+ * **23 · Linear Bar** — determinate, timed.
+ *
+ * **A determinate bar is never eased.** Width changes are linear or stepped and match real
+ * throughput; easing one makes it accelerate toward the end, which is a claim about the work
+ * rather than a flourish. The shimmer moves across the fill, not the fill's edge — motion that
+ * says *still running* without saying anything about speed.
+ */
+export function LinearBarWidget({
+  pct = 68, title = 'Assembling sections', prompt, onMenu,
+}: { pct?: number; title?: string; prompt?: string; onMenu?: () => void }) {
+  const { colors } = useDs();
+  const shimmer = useLoop({ duration: 1600 });
+  const translateX = shimmer.interpolate({ inputRange: [0, 1], outputRange: [-120, 320] });
+
+  return (
+    <WidgetCard
+      pill="WORKING"
+      title="Linear Bar"
+      prompt={prompt ?? 'Pull the full report together.'}
+      onMenu={onMenu}
+      testID="widget-23">
+      <Box style={{ gap: 11 }}>
+        <Box row align="center">
+          <Box flex={1}>
+            <Text style={{ fontSize: 15, lineHeight: 15 * 1.2, fontWeight: '600' }}>{title}</Text>
+          </Box>
+          <Text mono numeric color="textSecondary" style={{ fontSize: 12.5, lineHeight: 12.5 }}>
+            {`${pct}%`}
+          </Text>
+        </Box>
+        <Box
+          height={8}
+          radius="pill"
+          style={{ backgroundColor: colors.surfaceSunken, overflow: 'hidden' }}>
+          <Box
+            height={8}
+            radius="pill"
+            style={{ width: `${pct}%`, backgroundColor: colors.accentFill, overflow: 'hidden' }}>
+            <MotionView
+              style={{
+                position: 'absolute', top: 0, bottom: 0, width: 90,
+                backgroundColor: colors.accentPressed,
+                opacity: 0.55,
+                transform: [{ translateX }],
+              }}
+            />
+          </Box>
+        </Box>
+        <Text color="textSecondary" style={{ fontSize: 12.5, lineHeight: 12.5 * 1.5 }}>
+          Never eased. A determinate bar that eases is lying about throughput.
+        </Text>
+      </Box>
+    </WidgetCard>
+  );
+}
+
+/**
+ * **24 · Ring** — determinate, compact. For a card that already has a headline of its own.
+ */
+export function RingWidget({
+  pct = 42, title = 'Syncing your ATS',
+  body = 'Reading roles, candidates and stage history. Nothing is written back until it finishes.',
+  prompt, onMenu,
+}: { pct?: number; title?: string; body?: string; prompt?: string; onMenu?: () => void }) {
+  const { colors } = useDs();
+  const size = 82;
+
+  return (
+    <WidgetCard
+      pill="WORKING"
+      title="Ring"
+      prompt={prompt ?? 'How far through is the sync?'}
+      onMenu={onMenu}
+      testID="widget-24">
+      <Box row align="center" style={{ gap: 15 }}>
+        <Box width={size} height={size}>
+          <Arc
+            size={size}
+            thickness={11}
+            segments={[
+              { sweep: pct * 3.6, color: colors.accentFill },
+              { sweep: 360 - pct * 3.6, color: colors.surfaceSunken },
+            ]}
+            testID="w24-ring"
+          />
+          <Box
+            align="center"
+            justify="center"
+            style={{ position: 'absolute', top: 0, left: 0, right: 0, bottom: 0 }}>
+            <Text
+              numeric
+              style={{ fontSize: 15, lineHeight: 15, fontWeight: '600', color: colors.accentInk }}>
+              {`${pct}%`}
+            </Text>
+          </Box>
+        </Box>
+        <Box flex={1} style={{ gap: 6 }}>
+          <Text style={{ fontSize: 14.5, lineHeight: 14.5 * 1.25, fontWeight: '600' }}>{title}</Text>
+          <Text color="textSecondary" style={{ fontSize: 12.5, lineHeight: 12.5 * 1.5 }}>{body}</Text>
+        </Box>
+      </Box>
+    </WidgetCard>
+  );
+}
+
+export type Stage = { label: string; state: 'done' | 'now' | 'wait'; meta: string };
+
+export const SYNC_STAGES: Stage[] = [
+  { label: 'Read the brief', state: 'done', meta: '0:04' },
+  { label: 'Screen 24 CVs', state: 'done', meta: '1:12' },
+  { label: 'Score and rank', state: 'now', meta: 'running' },
+  { label: 'Draft outreach', state: 'wait', meta: '—' },
+];
+
+/**
+ * **25 · Stepped** — determinate, named stages. Use it when the stages have names worth reading.
+ *
+ * ⚠ **The done marker is `status.executed` `#2F6B4F`, not the pale mint tint.** A white tick on
+ * `#DCF0E4` fails contrast outright — that pale value is a background, and the handoff calls it
+ * out as the mistake most likely to be made here.
+ */
+export function SteppedWidget({
+  stages = SYNC_STAGES, prompt, onMenu,
+}: { stages?: Stage[]; prompt?: string; onMenu?: () => void }) {
+  const { colors } = useDs();
+
+  return (
+    <WidgetCard
+      pill="WORKING"
+      title="Stepped"
+      prompt={prompt ?? 'Where are you up to?'}
+      onMenu={onMenu}
+      rows
+      testID="widget-25">
+      <Box>
+        {stages.map((s, i) => (
+          <Box
+            key={s.label}
+            row
+            align="center"
+            style={{
+              minHeight: 50, paddingVertical: 10, paddingHorizontal: 2, gap: 11,
+              borderTopWidth: i === 0 ? 0 : 1, borderTopColor: colors.hairline,
+            }}>
+            <Box
+              width={24}
+              height={24}
+              radius="pill"
+              align="center"
+              justify="center"
+              style={{
+                borderWidth: 2,
+                borderColor:
+                  s.state === 'done' ? colors.status.executed
+                    : s.state === 'now' ? colors.accentFill
+                      : colors.hairlineStrong,
+                backgroundColor:
+                  s.state === 'done' ? colors.status.executed
+                    : s.state === 'now' ? colors.accentTint
+                      : undefined,
+              }}>
+              {s.state === 'done' ? <Icon name="tick" size={11} color={colors.accentOnFill} /> : null}
+            </Box>
+            <Box flex={1}>
+              <Text
+                color={s.state === 'wait' ? 'textSecondary' : 'textPrimary'}
+                style={{
+                  fontSize: 13.5,
+                  lineHeight: 13.5 * 1.35,
+                  fontWeight: s.state === 'wait' ? '400' : '600',
+                }}>
+                {s.label}
+              </Text>
+            </Box>
+            <Text mono color="textSecondary" style={{ fontSize: 11.5, lineHeight: 11.5 }}>
+              {s.meta}
+            </Text>
+          </Box>
+        ))}
+      </Box>
+    </WidgetCard>
+  );
+}
+
+/**
+ * **26 · Indeterminate** — unknown duration.
+ *
+ * **No percentage, because there isn't one.** A fabricated number is worse than none: it sets an
+ * expectation the run cannot keep. The card names what it is waiting on instead, which is the
+ * only honest thing it knows.
+ */
+export function IndeterminateWidget({
+  title = 'Waiting on LinkedIn',
+  note = "Their page is slow right now. I'll keep the run open and pick up as soon as it answers.",
+  prompt, onMenu,
+}: { title?: string; note?: string; prompt?: string; onMenu?: () => void }) {
+  const { colors } = useDs();
+  const spin = useLoop({ duration: 900 });
+  const rotate = spin.interpolate({ inputRange: [0, 1], outputRange: ['0deg', '360deg'] });
+  const slide = useLoop({ duration: 1500 });
+  const left = slide.interpolate({ inputRange: [0, 1], outputRange: ['-40%', '102%'] });
+
+  return (
+    <WidgetCard
+      pill="WORKING"
+      title="Indeterminate"
+      prompt={prompt ?? 'Check whether this person is still open to a move.'}
+      onMenu={onMenu}
+      testID="widget-26">
+      <Box style={{ gap: 13 }}>
+        <Box row align="center" style={{ gap: 11 }}>
+          <MotionView
+            style={{
+              width: 26, height: 26, borderRadius: 13,
+              borderWidth: 2.5,
+              borderColor: colors.surfaceSunken,
+              borderTopColor: colors.accentFill,
+              transform: [{ rotate }],
+            }}
+          />
+          <Box flex={1}>
+            <Text style={{ fontSize: 14.5, lineHeight: 14.5 * 1.25, fontWeight: '600' }}>{title}</Text>
+          </Box>
+        </Box>
+        <Box
+          height={8}
+          radius="pill"
+          style={{ backgroundColor: colors.surfaceSunken, overflow: 'hidden' }}>
+          <MotionView
+            style={{
+              position: 'absolute', top: 0, bottom: 0, width: '38%',
+              borderRadius: 999,
+              backgroundColor: colors.accentFill,
+              left,
+            }}
+          />
+        </Box>
+        <Text color="textSecondary" style={{ fontSize: 12.5, lineHeight: 12.5 * 1.5 }}>{note}</Text>
+      </Box>
+    </WidgetCard>
+  );
+}

package/src/widgets/WidgetCard.tsx

@@ -0,0 +1,178 @@
+import type { ReactNode } from 'react';
+import { Box, Pressable, Text } from '../core';
+import { useDs } from '../tokens';
+import { widget } from './tokens';
+import { SurfaceProvider, useMeasuredSurface, useSurface } from './useSurface';
+
+/**
+ * **The shell all 26 widgets wear.** Handoff §1, and the first thing built — *"nothing else can
+ * be judged until this is right."*
+ *
+ * ```
+ * ┌─ prompt bubble ────────────────────┐   the user's message, above the card
+ * └────────────────────────────────────┘
+ * ┌─ card ─────────────────────────────┐
+ * │ [PILL]  Title…              ( ⋮ )  │   header
+ * ├────────────────────────────────────┤   1px hairline, full bleed
+ * │ body                               │
+ * └────────────────────────────────────┘
+ * ```
+ *
+ * The point of one shell is that **an ask and an answer are the same object in the thread.** A
+ * question that looked different from its own answer would read as two events rather than one.
+ *
+ * Colour and type are paper's; every geometry value is the handoff's. See
+ * `docs/HANDOFF-CONFLICTS.md` for each substitution.
+ */
+
+/** The user's message, above the card. Left-aligned, and never full width. */
+export function PromptBubble({ children }: { children: string }) {
+  const surface = useSurface();
+  const pad = surface === 'web' ? widget.prompt.padWeb : widget.prompt.padMobile;
+  const copy = widget.copy.body;
+  return (
+    <Box
+      alignSelf="flex-start"
+      bg="surface1"
+      lift={1}
+      radius="card"
+      style={{
+        paddingVertical: pad.y,
+        paddingHorizontal: pad.x,
+        maxWidth: widget.prompt.maxWidth[surface],
+      }}>
+      <Text style={{ fontSize: copy.size[surface], lineHeight: copy.size[surface] * copy.lh[surface] }}>
+        {children}
+      </Text>
+    </Box>
+  );
+}
+
+/**
+ * The category pill.
+ *
+ * **Verbatim and not paraphrasable** — `TEXT`, `CHOICE`, `FILE`. It carries the category so the
+ * title is free to clip, which is why truncation below is intentional rather than a fallback.
+ */
+export function CategoryPill({ children }: { children: string }) {
+  const surface = useSurface();
+  const p = widget.pill;
+  return (
+    <Box
+      bg="accentTint"
+      radius="pill"
+      style={{ paddingVertical: p.padY[surface], paddingHorizontal: p.padX[surface] }}>
+      <Text
+        color="accentInk"
+        uppercase
+        style={{
+          fontSize: p.size[surface],
+          lineHeight: p.size[surface],
+          fontWeight: '600',
+          letterSpacing: p.size[surface] * p.tracking,
+        }}>
+        {children}
+      </Text>
+    </Box>
+  );
+}
+
+export type WidgetCardProps = {
+  /** The category. Verbatim from the widget's spec. */
+  pill: string;
+  title: string;
+  /** The user's message that produced this ask. Omitted for an unprompted card. */
+  prompt?: string;
+  onMenu?: () => void;
+  children?: ReactNode;
+  /** A body of rows pads differently — rows carry their own vertical padding (§1). */
+  rows?: boolean;
+  /**
+   * **The run has stopped on this card.** Level 1 is replaced by the accent ring, which is the
+   * only place in the family a card's elevation carries meaning rather than depth: blocked and
+   * offered must never look alike (§3, widget 06).
+   */
+  blocked?: boolean;
+  testID?: string;
+};
+
+export function WidgetCard({
+  pill, title, prompt, onMenu, children, rows = false, blocked = false, testID,
+}: WidgetCardProps) {
+  const { colors } = useDs();
+  const { surface, onLayout } = useMeasuredSurface();
+  const h = surface === 'web' ? widget.header.padWeb : widget.header.padMobile;
+  const body = rows
+    ? { paddingTop: widget.body.padRows.top, paddingHorizontal: widget.body.padRows.x, paddingBottom: widget.body.padRows.bottom }
+    : { padding: widget.body.pad[surface] };
+
+  return (
+    <SurfaceProvider surface={surface}>
+      <Box
+        onLayout={onLayout}
+        style={{ gap: widget.card.gapToPrompt[surface] }}
+        testID={testID}>
+        {prompt ? <PromptBubble>{prompt}</PromptBubble> : null}
+
+        <Box
+          bg="surface1"
+          lift={1}
+          radius="card"
+          alignSelf="flex-start"
+          style={{
+            /* `overflow: hidden` so the hairline and body reach the card's edges. */
+            overflow: 'hidden',
+            width: '100%',
+            maxWidth: surface === 'web' ? widget.card.webMaxWidth : undefined,
+            boxShadow: blocked
+              ? `0 0 0 3px ${colors.accentTint}, 0 6px 18px -10px ${colors.accentFill}`
+              : undefined,
+          }}>
+          <Box
+            row
+            align="center"
+            style={{
+              gap: widget.header.gap[surface],
+              paddingTop: h.top, paddingRight: h.right, paddingBottom: h.bottom, paddingLeft: h.left,
+            }}>
+            <CategoryPill>{pill}</CategoryPill>
+            {/* Truncation is intentional: the pill carries the category, so the title may clip. */}
+            <Box flex={1} style={{ minWidth: 0 }}>
+              <Text
+                numberOfLines={1}
+                style={{
+                  fontSize: widget.title.size[surface],
+                  lineHeight: widget.title.size[surface] * widget.title.lineHeight,
+                  fontWeight: '600',
+                }}>
+                {title}
+              </Text>
+            </Box>
+            <Pressable
+              onPress={onMenu}
+              bg="surfaceSunken"
+              radius="pill"
+              aria-label="Card options"
+              width={widget.menu.size[surface]}
+              height={widget.menu.size[surface]}
+              /* 34px is the drawn circle; the 44 floor is the touchable box around it. */
+              minHeight={widget.hit}
+              style={{ minWidth: widget.hit }}>
+              <Text
+                mono
+                color="textSecondary"
+                style={{ fontSize: widget.menu.glyph[surface], lineHeight: widget.menu.glyph[surface], fontWeight: '600' }}>
+                ⋮
+              </Text>
+            </Pressable>
+          </Box>
+
+          {/* A 1px view rather than a border-bottom on the header, so it survives padding changes. */}
+          <Box style={{ height: widget.hairline, backgroundColor: colors.hairline }} />
+
+          <Box style={{ ...body, gap: widget.body.gap.min }}>{children}</Box>
+        </Box>
+      </Box>
+    </SurfaceProvider>
+  );
+}

package/src/widgets/WidgetInput.tsx

@@ -0,0 +1,75 @@
+import { useState } from 'react';
+import { TextInput } from 'react-native';
+import { useDs } from '../tokens';
+import { widget, widgetRadius } from './tokens';
+import { useSurface } from './useSurface';
+
+/**
+ * The text input every widget in this family uses.
+ *
+ * **⚠ Not `core/Input`, and the difference is a real conflict.** Paper's rule is *"a field is a
+ * hole in the paper, not an object on it"* — it never lifts, it has no border, and focus darkens
+ * the hairline because **there is no colour focus ring anywhere in that system**.
+ *
+ * The handoff specifies the opposite: a 1px solid border, and on focus `border-color → --coral`
+ * plus a 3px coral ring. That is a structural disagreement rather than a palette one, so it
+ * cannot be rethemed away.
+ *
+ * Followed as specified, in paper's accent. Logged in `docs/HANDOFF-CONFLICTS.md` §6 — **if this
+ * surface ever sits beside a paper form, the two fields will not look like the same system.**
+ */
+export function WidgetInput({
+  value, onChangeText, placeholder, shape = 'rect', invalid, multiline, minHeight,
+  onBlur, ariaLabel, testID,
+}: {
+  value: string;
+  onChangeText: (t: string) => void;
+  placeholder?: string;
+  /** `pill` is the search shape; `rect` is everything else. */
+  shape?: 'rect' | 'pill';
+  invalid?: boolean;
+  multiline?: boolean;
+  minHeight?: number;
+  onBlur?: () => void;
+  ariaLabel?: string;
+  testID?: string;
+}) {
+  const { colors, fonts } = useDs();
+  const surface = useSurface();
+  const [focused, setFocused] = useState(false);
+  const size = widget.copy.body.size[surface];
+
+  return (
+    <TextInput
+      testID={testID}
+      value={value}
+      onChangeText={onChangeText}
+      onFocus={() => setFocused(true)}
+      onBlur={() => {
+        setFocused(false);
+        onBlur?.();
+      }}
+      placeholder={placeholder}
+      placeholderTextColor={colors.textTertiary}
+      multiline={multiline}
+      aria-label={ariaLabel}
+      aria-invalid={invalid}
+      style={{
+        height: multiline ? undefined : widget.field.height[surface],
+        minHeight,
+        paddingHorizontal: shape === 'pill' ? widget.field.padPill : widget.field.padRect,
+        paddingVertical: multiline ? 12 : 0,
+        borderRadius: shape === 'pill' ? 999 : widgetRadius.inset,
+        borderWidth: 1,
+        borderColor: invalid ? colors.status.error : focused ? colors.accentFill : colors.hairline,
+        backgroundColor: colors.surface1,
+        color: colors.textPrimary,
+        fontFamily: fonts.sans,
+        fontSize: size,
+        textAlignVertical: multiline ? 'top' : 'center',
+        /* The handoff's focus ring. Paper has none anywhere — see the conflict note above. */
+        boxShadow: focused ? `0 0 0 3px ${colors.accentTint}` : undefined,
+      }}
+    />
+  );
+}

package/src/widgets/driven.ts

@@ -0,0 +1,60 @@
+/**
+ * **What every widget accepts when it is driven from JSON rather than from a fixture.**
+ *
+ * The 26 were built from the handoff, so each one carries its own pill, title and specimen copy —
+ * that is what made them reviewable against the design. Driven from a `question/1` block, all
+ * three come from the spec instead, and the built-in values become defaults.
+ *
+ * **`prompt` is not in the block** (decision Q12b). The user's own message belongs to the
+ * transcript the app already holds; a question that carried a copy of it would have two sources
+ * for one sentence and no rule for which wins.
+ */
+export type Driven = {
+  /** The category chip. From the field's type when driven; the handoff's word otherwise. */
+  pill?: string;
+  /** The card's heading. The field's `label` when driven. */
+  title?: string;
+  /**
+   * The in-body field label, where the widget has one.
+   *
+   * **`''` means "the header already says it".** Driven from a spec the card's title and a form
+   * label are the same string — the first spec-driven render printed *Candidate name* twice, once
+   * as the heading and once above the input. `undefined` keeps the widget's own default; `''`
+   * removes the line entirely, which is what a spec-driven card wants for a form label and
+   * emphatically not what it wants for a stat tile's caption, where the label is the number's
+   * unit and dropping it leaves a bare figure.
+   */
+  label?: string;
+  /** The line under the control. A field's `hint`, already templated. */
+  hint?: string;
+  /** The user's message, supplied by the app. */
+  prompt?: string;
+  onMenu?: () => void;
+};
+
+/**
+ * **An option as a widget draws it.**
+ *
+ * The same shape `question/1` uses, minus the parts only the schema cares about. A bare string is
+ * still accepted everywhere — it is its own value and its own label, which is the only difference
+ * between the two forms and the reason the fixtures stay readable.
+ */
+import { isEscapeWording } from '../fields/types';
+
+export type WidgetOption = {
+  value: string;
+  label: string;
+  /** The run's reasoning. Drawn by every control that has room for it. */
+  note?: string;
+  /** The way out. Renders muted until picked, so it reads as an escape, not a candidate. */
+  escape?: boolean;
+};
+
+export type WidgetOptionEntry = string | WidgetOption;
+
+export const toWidgetOption = (o: WidgetOptionEntry): WidgetOption =>
+  typeof o === 'string'
+    /* The long-standing wording is still recognised, so a plain `string[]` keeps its escape.
+       The predicate is `fields/types.ts`'s, not a second copy — having two was the bug. */
+    ? { value: o, label: o, escape: isEscapeWording(o) }
+    : { ...o, escape: o.escape ?? isEscapeWording(o.label) };