@lotics/ui 13.9.0 → 13.10.0

package/docs/ai_patterns.md

@@ -243,15 +243,23 @@ plain `useState` (controlled `status` everywhere); the family owns the mechanics
 Undo, the counter, Keep-all, apply gating). Never apply a field with no value — gate unresolved
 conflicts (`keepDisabled`, `applyDisabled`). Editing IS the review.
 
-## Ask back — `Clarify`
+## Ask back — `Clarify` / `ClarifyWizard`
 
 `Clarify` (`@lotics/ui/clarify`): when the agent is unsure, it asks a question with quick-reply
-options and PAUSES, instead of guessing wrong. Human-in-the-loop input mid-run: `question`,
-`options` (`{ label, value, description? }` — a `ChoiceList`), `onAnswer(value)` resumes the run,
-and the controlled `answer` keeps the pick switchable until committed.
-
-**Limitation:** the "Question" eyebrow above the prompt is currently hardcoded English (no label
-prop, not on the locale provider).
+options and PAUSES, instead of guessing wrong. Human-in-the-loop input mid-run: `question` (the
+prompt, rendered as-is — no eyebrow chrome), `options` (`{ label, value, description }` — every
+answer carries a REQUIRED one-line description so the human picks without re-deriving it from the
+question; a `ChoiceList`), `onAnswer(value)` resumes the run, the controlled `answer` keeps the pick
+switchable until committed. **`allowCustom`** adds an always-visible, borderless, auto-growing multiline field below the
+options — typing it IS the selection; its text becomes the value (any value not matching an option
+reads as the custom answer).
+
+`ClarifyWizard` (`@lotics/ui/clarify_wizard`): a SEQUENCE of clarify questions worked one at a time —
+Back / Next / Cancel / Submit (Next/Submit primary), the step position an eyebrow ("1 / 3") above the
+question — no progress bar. Each step is a `Clarify`; advance only once the
+current question is answered; `onSubmit` gives one `{ value, custom }` per question (aligned by index,
+`custom` true when the answer came from "Other…"), `onCancel` dismisses. All navigation chrome is
+locale-wired (the `clarify` slice). The multi-question form of the ask-back.
 
 ## Provenance — `Sources`
 

package/docs/catalog.md

@@ -980,11 +980,19 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `ChangeRecord` (THE item card: registers like a Change; tone wash + localized op word;
   verb level follows the decision level) · `ChangeBand` (the raw ± band) ·
   `ChangeValueInput` (the diff-at-rest editor); the `changeReview` locale slice.
-- **`clarify`** — `Clarify`: the agent asks back — a borderless block (question + a
-  `ChoiceList`), no card wrapper.
+- **`clarify`** — `Clarify` + `ClarifyOption`: the agent asks back — a borderless block
+  (the question text + a `ChoiceList`, no card wrapper; an optional muted `eyebrow` sits tight above
+  the question — e.g. a wizard's "1 / 3"). `ClarifyOption` requires
+  `{ value, label, description }` — the description is MANDATORY (every answer explains itself).
+  `allowCustom` adds an always-visible borderless multiline custom-answer field below the options.
+- **`clarify_wizard`** — `ClarifyWizard` + `ClarifyWizardQuestion`/`ClarifyWizardAnswer`: a SEQUENCE
+  of `Clarify` questions with Back/Next/Cancel/Submit + a `n / total` position indicator; advance
+  only when the current is answered, `onSubmit` returns one `{ value, custom }` per question.
+  Navigation chrome is locale-wired (the `clarify` locale slice).
 - **`choice_list`** — `ChoiceList` + `ChoiceOption`: selectable answer options as
   divider-separated rows (no bordered cards) with a per-row focus ring + hover wash; the
-  agent's quick-reply surface.
+  agent's quick-reply surface. `allowCustom` appends an always-visible borderless multiline field whose
+  text IS the value (a value not in `options` reads as the custom answer).
 - **`sources`** — `Sources` + `SourceRef`/`SourceKind` (record | document | table | web |
   knowledge): provenance chips, per-kind glyphs.
 - **`finding`** — `Finding` + `FindingComparison` + `FindingSeverity`/`FindingLabels`: one

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "13.9.0",
+  "version": "13.10.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -89,6 +89,7 @@
     "./change_review": "./src/change_review.tsx",
     "./finding": "./src/finding.tsx",
     "./clarify": "./src/clarify.tsx",
+    "./clarify_wizard": "./src/clarify_wizard.tsx",
     "./choice_list": "./src/choice_list.tsx",
     "./sources": "./src/sources.tsx",
     "./icon": "./src/icon.tsx",

package/src/choice_list.tsx

@@ -1,10 +1,22 @@
-import { Pressable, View } from "react-native";
+import { useState } from "react";
+import { Pressable, TextInput, View } from "react-native";
 import { colors } from "./colors";
 import { Text } from "./text";
 import { Icon } from "./icon";
 import { Divider } from "./divider";
-import { useFocusRing } from "./use_focus_ring";
-import { FOCUS_RING } from "./control_surface";
+import { composeHandler, useFocusRing } from "./use_focus_ring";
+import { useHover } from "./use_hover";
+import { CONTROL_RADIUS, FOCUS_RING } from "./control_surface";
+import { useAutoGrowHeight } from "./use_auto_grow_height";
+import { fontFamilyMedium, getInputTextStyle } from "./text_utils";
+import { useLoticsLocale } from "./locale";
+
+// A typed custom answer must read exactly like a picked option's LABEL (`Text
+// size="sm" weight="medium"`). Its SIZE stays on the input contract (getInputTextStyle:
+// 14 on desktop = the sm label, 16 on mobile to defeat iOS-Safari focus-zoom — and the
+// size useAutoGrowHeight is tuned to); this override only aligns the family, tracking,
+// and colour to the label, which is where an unstyled input actually diverges from it.
+const ANSWER_LABEL_FONT = { fontFamily: fontFamilyMedium, letterSpacing: -0.4, color: colors.zinc[900] } as const;
 
 export interface ChoiceOption {
   label: string;
@@ -15,25 +27,33 @@ export interface ChoiceOption {
 
 export interface ChoiceListProps {
   options: ChoiceOption[];
-  /** The chosen value. */
+  /** The chosen value — an option's `value`, or (with `allowCustom`) the free
+   *  TEXT of an "Other" answer. `undefined` = nothing chosen. */
   value?: string;
   onSelect: (value: string) => void;
+  /** Show an always-visible inline free-text field at the bottom for a custom
+   *  answer — typing it IS the selection. Its text IS the value (any `value` not
+   *  matching an option reads as the custom answer, so the caller distinguishes a
+   *  custom answer by "not in `options`"). */
+  allowCustom?: boolean;
 }
 
 /** One selectable option — a role-less-free `Pressable` (its own accessible name
  *  + selected state), hover wash + focus ring, no border. */
-function ChoiceRow({ option, selected, onSelect }: { option: ChoiceOption; selected: boolean; onSelect: (value: string) => void }) {
+function ChoiceRow({ option, selected, onSelect }: { option: ChoiceOption; selected: boolean; onSelect: () => void }) {
   const { focusVisible, focusProps } = useFocusRing();
   return (
     <Pressable
       accessibilityRole="button"
       accessibilityLabel={option.label}
       accessibilityState={{ selected }}
-      onPress={() => onSelect(option.value)}
+      onPress={onSelect}
       {...focusProps}
       style={({ hovered, pressed }) => [
-        { flexDirection: "row", alignItems: "center", gap: 12, paddingVertical: 14, paddingHorizontal: 6, borderRadius: 8 },
-        hovered || pressed ? { backgroundColor: colors.zinc[50] } : null,
+        { flexDirection: "row", alignItems: "center", gap: 12, paddingVertical: 14, paddingHorizontal: 8, borderRadius: CONTROL_RADIUS },
+        // Selected reads as a persistent tint (zinc-100); an unselected row only
+        // washes on hover (zinc-50). The check below reserves its slot always.
+        selected ? { backgroundColor: colors.zinc[100] } : hovered || pressed ? { backgroundColor: colors.zinc[50] } : null,
         focusVisible ? { boxShadow: FOCUS_RING } : null,
       ]}
     >
@@ -47,28 +67,97 @@ function ChoiceRow({ option, selected, onSelect }: { option: ChoiceOption; selec
           </Text>
         ) : null}
       </View>
-      {selected ? <Icon name="check" size={17} color={colors.zinc[900]} /> : null}
+      <View style={{ width: 17, alignItems: "center" }}>
+        {selected ? <Icon name="check" size={17} color={colors.zinc[900]} /> : null}
+      </View>
     </Pressable>
   );
 }
 
+/** The custom-answer row — the SAME box as a `ChoiceRow` (padding · radius · hover
+ *  wash · focus ring), but holding an always-editable, auto-growing multiline input
+ *  instead of a pressable label. Typing it IS the selection; focusing it re-selects a
+ *  parked draft (`onFocus`). */
+function CustomAnswerRow({ value, selected, onChangeText, onFocus, placeholder }: { value: string; selected: boolean; onChangeText: (text: string) => void; onFocus: () => void; placeholder: string }) {
+  const { hovered, hoverProps } = useHover();
+  const { focusVisible, focusProps } = useFocusRing({ always: true });
+  const grow = useAutoGrowHeight({ minLines: 1 });
+  return (
+    <View
+      {...(hoverProps as object)}
+      style={[
+        { paddingVertical: 14, paddingHorizontal: 8, borderRadius: CONTROL_RADIUS },
+        // Same states as an option row: a filled custom answer reads as selected
+        // (zinc-100); otherwise it washes on hover (zinc-50).
+        selected ? { backgroundColor: colors.zinc[100] } : hovered ? { backgroundColor: colors.zinc[50] } : null,
+        focusVisible ? { boxShadow: FOCUS_RING } : null,
+      ]}
+    >
+      <TextInput
+        ref={grow.inputRef}
+        multiline
+        value={value}
+        onChangeText={(text) => { onChangeText(text); grow.measure(); }}
+        onFocus={composeHandler(onFocus, focusProps.onFocus)}
+        onBlur={focusProps.onBlur}
+        onContentSizeChange={grow.onContentSizeChange}
+        scrollEnabled={grow.scrollEnabled}
+        placeholder={placeholder}
+        placeholderTextColor={colors.zinc[400]}
+        // Bare input: the row owns padding + hover + focus ring, so it strips its own
+        // padding and browser outline and just grows with the text. Input-contract size +
+        // the option-label family/tracking/colour, so a typed answer reads like a picked one.
+        style={[getInputTextStyle(), ANSWER_LABEL_FONT, { height: grow.containerHeight, padding: 0, outlineStyle: "none" as unknown as "solid" }]}
+      />
+    </View>
+  );
+}
+
 /**
  * A vertical set of selectable answer options — divider-separated rows (no
  * bordered cards), each with its own focus ring + hover wash, single-select and
  * freely switchable (pick a different option any time). The chosen row shows a
- * check. The agent's quick-reply surface (`Clarify` uses it) and any "pick one"
- * question.
+ * check. With `allowCustom`, an always-visible inline free-text field at the
+ * bottom captures a custom answer (typing it IS the selection). The agent's
+ * quick-reply surface (`Clarify` / `ClarifyWizard` use it) and any "pick one" question.
  */
 export function ChoiceList(props: ChoiceListProps) {
-  const { options, value, onSelect } = props;
+  const { options, value, onSelect, allowCustom } = props;
+  const labels = useLoticsLocale().clarify;
+  // A value that matches no option IS a custom answer (its own text, or "" right
+  // after focusing an empty custom row).
+  const isCustomValue = (v: string | undefined): v is string => !!allowCustom && typeof v === "string" && !options.some((o) => o.value === v);
+  // The custom TEXT is a draft that outlives selection: picking an option deselects
+  // the custom row but must KEEP its text so the human can return to it. The single
+  // `value` can't hold both a picked option and the parked text, so the draft is
+  // local — seeded from `value` when this row mounts already custom-selected.
+  const [customDraft, setCustomDraft] = useState(() => (isCustomValue(value) ? value : ""));
+  const customSelected = isCustomValue(value);
   return (
     <View>
       {options.map((o, i) => (
         <View key={o.value}>
-          {i > 0 ? <Divider /> : null}
-          <ChoiceRow option={o} selected={value === o.value} onSelect={onSelect} />
+          {/* The hairline carries vertical padding so each row's rounded hover/selected
+              fill has air on both sides of it (a flush divider would pinch the corners). */}
+          {i > 0 ? <Divider paddingVertical={6} /> : null}
+          <ChoiceRow option={o} selected={value === o.value} onSelect={() => onSelect(o.value)} />
         </View>
       ))}
+      {allowCustom ? (
+        <View>
+          {options.length > 0 ? <Divider paddingVertical={6} /> : null}
+          {/* The custom answer is an ALWAYS-visible inline row (no press-to-reveal). Its
+              text persists (customDraft) across option switches; typing selects it, and
+              focusing a non-empty parked draft re-selects it without retyping. */}
+          <CustomAnswerRow
+            value={customDraft}
+            selected={customSelected && customDraft.length > 0}
+            onChangeText={(text) => { setCustomDraft(text); onSelect(text); }}
+            onFocus={() => { if (customDraft.length > 0 && !customSelected) onSelect(customDraft); }}
+            placeholder={labels.otherPlaceholder}
+          />
+        </View>
+      ) : null}
     </View>
   );
 }

package/src/clarify.tsx

@@ -1,38 +1,54 @@
 import { View } from "react-native";
 import { Text } from "./text";
-import { ChoiceList, type ChoiceOption } from "./choice_list";
+import { ChoiceList } from "./choice_list";
 
-export type ClarifyOption = ChoiceOption;
+export interface ClarifyOption {
+  value: string;
+  label: string;
+  /** REQUIRED for a clarify answer: the one-line "what this choice means" so the
+   *  human can pick without re-deriving it from the question. */
+  description: string;
+}
 
 export interface ClarifyProps {
   /** The agent's question — what it needs settled to proceed. */
   question: string;
+  /** A muted eyebrow rendered tight above the question — e.g. a wizard's "1 / 3". */
+  eyebrow?: string;
   options: ClarifyOption[];
   onAnswer: (value: string) => void;
-  /** The chosen option's VALUE — the picked choice shows selected; it stays
-   *  switchable so the human can change their mind. */
+  /** The chosen option's VALUE — or, with `allowCustom`, a custom answer's free
+   *  text. The picked choice shows selected; switchable so the human can change. */
   answer?: string;
+  /** Offer an "Other…" free-text row below the options. */
+  allowCustom?: boolean;
 }
 
 /**
- * The agent asks BACK — a question with selectable answer options the human picks
- * before the run continues, freely switchable until committed. A borderless block
- * (no card): the question, then divider-separated option rows (`ChoiceList`).
- * Human-in-the-loop input: when the agent is unsure, it clarifies instead of
- * guessing wrong. Pair with `AgentRun` / `AgentProgress`.
+ * The agent asks BACK — a question with selectable answer options (each carrying
+ * a one-line description) the human picks before the run continues, freely
+ * switchable until committed. A borderless block (no card): the question text,
+ * then divider-separated option rows (`ChoiceList`); `allowCustom` adds an
+ * "Other…" free-text row. For a SEQUENCE of questions with Back/Next/Submit
+ * navigation, use `ClarifyWizard`. Human-in-the-loop: when unsure, the agent
+ * clarifies instead of guessing wrong. Pair with `AgentRun` / `AgentProgress`.
  */
 export function Clarify(props: ClarifyProps) {
   return (
-    <View style={{ gap: 14 }}>
-      <View style={{ gap: 4 }}>
-        <Text size="xs" color="muted" weight="medium">
-          Question
-        </Text>
+    <View style={{ gap: 12 }}>
+      {/* paddingHorizontal 8 aligns the eyebrow + question with the option/answer
+          text, which sits on the `ChoiceList` rows' 8px inset (CONTROL_RADIUS grid). */}
+      <View style={{ gap: 4, paddingHorizontal: 8 }}>
+        {props.eyebrow ? (
+          <Text size="xs" color="muted" weight="medium">
+            {props.eyebrow}
+          </Text>
+        ) : null}
         <Text size="sm" weight="medium">
           {props.question}
         </Text>
       </View>
-      <ChoiceList options={props.options} value={props.answer} onSelect={props.onAnswer} />
+      <ChoiceList options={props.options} value={props.answer} onSelect={props.onAnswer} allowCustom={props.allowCustom} />
     </View>
   );
 }

package/src/clarify_wizard.tsx

@@ -0,0 +1,84 @@
+import { useState } from "react";
+import { View } from "react-native";
+import { Button } from "./button";
+import { Clarify, type ClarifyOption } from "./clarify";
+import { useLoticsLocale } from "./locale";
+
+export interface ClarifyWizardQuestion {
+  question: string;
+  answers: ClarifyOption[];
+  /** Offer an "Other…" free-text answer for this question. */
+  allowCustom?: boolean;
+}
+
+export interface ClarifyWizardAnswer {
+  /** The chosen option's value, or the custom free text. */
+  value: string;
+  /** True when the value came from the "Other…" row (not one of the options). */
+  custom: boolean;
+}
+
+export interface ClarifyWizardProps {
+  questions: ClarifyWizardQuestion[];
+  /** Fires when every question is answered and the human submits — one answer
+   *  per question, aligned by index. */
+  onSubmit: (answers: ClarifyWizardAnswer[]) => void;
+  onCancel: () => void;
+}
+
+/**
+ * A SEQUENCE of `Clarify` questions the human works through one at a time —
+ * Back / Next / Cancel / Submit with a position indicator. Each step reuses
+ * `Clarify` (question + described answers + optional "Other…"). You can only
+ * advance once the current question is answered; Submit fires when the last is.
+ * The multi-question form of the agent's ask-back; single questions use `Clarify`.
+ */
+export function ClarifyWizard(props: ClarifyWizardProps) {
+  const { questions, onSubmit, onCancel } = props;
+  const labels = useLoticsLocale().clarify;
+  const [index, setIndex] = useState(0);
+  const [answers, setAnswers] = useState<(string | undefined)[]>(() => questions.map(() => undefined));
+
+  const total = questions.length;
+  const q = questions[index];
+  const current = answers[index];
+  // Answered = a non-empty string: an option value, or filled custom text ("" is
+  // "Other" picked but not yet typed — not answered).
+  const answered = typeof current === "string" && current.length > 0;
+  const isLast = index === total - 1;
+
+  const setAnswer = (v: string) =>
+    setAnswers((prev) => {
+      const next = [...prev];
+      next[index] = v;
+      return next;
+    });
+
+  const submit = () =>
+    onSubmit(
+      questions.map((question, i) => {
+        const value = answers[i] ?? "";
+        return { value, custom: !question.answers.some((a) => a.value === value) };
+      }),
+    );
+
+  return (
+    <View style={{ gap: 16 }}>
+      {/* The step position is an eyebrow above the question (no progress bar); the
+          footer aligns to the same 8px inset as the question and answers. Keyed by
+          index so each step's custom-answer draft is its own (no bleed across steps). */}
+      <Clarify key={index} eyebrow={`${index + 1} / ${total}`} question={q.question} options={q.answers} answer={current} onAnswer={setAnswer} allowCustom={q.allowCustom} />
+      <View style={{ flexDirection: "row", alignItems: "center", justifyContent: "space-between", gap: 8, paddingHorizontal: 8 }}>
+        <Button title={labels.cancel} color="muted" onPress={onCancel} />
+        <View style={{ flexDirection: "row", gap: 8 }}>
+          {index > 0 ? <Button title={labels.back} color="secondary" onPress={() => setIndex(index - 1)} /> : null}
+          {isLast ? (
+            <Button title={labels.submit} color="primary" onPress={submit} disabled={!answered} />
+          ) : (
+            <Button title={labels.next} color="primary" onPress={() => setIndex(index + 1)} disabled={!answered} />
+          )}
+        </View>
+      </View>
+    </View>
+  );
+}

package/src/locale.tsx

@@ -57,6 +57,8 @@ export interface LoticsLocale {
   /** The `Inline*` editor family: the shared save-error line and the
    *  text-editor Save/Cancel tooltips. */
   inline: { saveError: string; save: string; cancel: string };
+  /** `ChoiceList` custom-answer placeholder + `ClarifyWizard` navigation chrome. */
+  clarify: { otherPlaceholder: string; back: string; next: string; cancel: string; submit: string };
   /** `Ledger`: the screen-reader name of a peekable row. */
   ledger: { rowDetails: (label: string) => string };
   /** `SectionHeadingTitle`: the info-popover trigger's screen-reader name. */
@@ -159,6 +161,7 @@ export const en: LoticsLocale = {
   dangerZone: { title: "Danger zone" },
   drawer: { previous: "Previous record", next: "Next record", close: "Close" },
   inline: { saveError: "Couldn't save. Try again.", save: "Save", cancel: "Cancel" },
+  clarify: { otherPlaceholder: "Or type your own answer…", back: "Back", next: "Next", cancel: "Cancel", submit: "Submit" },
   ledger: { rowDetails: (label) => `${label} details` },
   sectionHeading: { info: "About this data" },
   chip: { remove: "Remove" },
@@ -254,6 +257,7 @@ export const vi: LoticsLocale = {
   dangerZone: { title: "Vùng nguy hiểm" },
   drawer: { previous: "Bản ghi trước", next: "Bản ghi sau", close: "Đóng" },
   inline: { saveError: "Không lưu được. Thử lại.", save: "Lưu", cancel: "Hủy" },
+  clarify: { otherPlaceholder: "Hoặc nhập câu trả lời khác…", back: "Quay lại", next: "Tiếp", cancel: "Hủy", submit: "Gửi" },
   ledger: { rowDetails: (label) => `Chi tiết ${label}` },
   sectionHeading: { info: "Giải thích dữ liệu" },
   chip: { remove: "Xóa" },

package/src/table.tsx

@@ -315,7 +315,11 @@ const styles = StyleSheet.create({
   // Divider-separated.
   headerBand: {
     paddingHorizontal: ROW_GUTTER,
-    paddingVertical: 10,
+    // NO top padding (GAP-85): a Table is borderless, so its container ALWAYS owns
+    // the top spacing (a Section's gap, a Card's padding, any `gap` above). A band
+    // paddingTop would stack on that and double-gap the column header; the bottom
+    // padding is the band's own — it spaces the header off the hairline below.
+    paddingBottom: 10,
     flexDirection: "row",
     alignItems: "center",
     gap: COLUMN_GAP,