@lotics/ui 13.9.0 → 14.0.0

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/json_panel.tsx

@@ -1,4 +1,4 @@
-import { Platform, StyleSheet, View } from "react-native";
+import { Platform, ScrollView, StyleSheet, View } from "react-native";
 import { Text } from "./text";
 import { colors } from "./colors";
 
@@ -15,18 +15,22 @@ export function JsonPanel(props: JsonPanelProps) {
         {title}
       </Text>
       <View style={styles.body}>
-        <Text
-          size="xs"
-          style={{
-            fontFamily:
-              Platform.OS === "web"
-                ? "ui-monospace, SFMono-Regular, Menlo, monospace"
-                : "monospace",
-            lineHeight: 18,
-          }}
-        >
-          {value}
-        </Text>
+        {/* A real dump can be tens of KB (a streamed tool input) — the panel caps
+            its height and scrolls inside, so it can never blow a feed open. */}
+        <ScrollView style={styles.scroll} contentContainerStyle={styles.content} nestedScrollEnabled>
+          <Text
+            size="xs"
+            style={{
+              fontFamily:
+                Platform.OS === "web"
+                  ? "ui-monospace, SFMono-Regular, Menlo, monospace"
+                  : "monospace",
+              lineHeight: 18,
+            }}
+          >
+            {value}
+          </Text>
+        </ScrollView>
       </View>
     </View>
   );
@@ -50,6 +54,14 @@ const styles = StyleSheet.create({
     borderColor: colors.zinc[200],
     borderRadius: 8,
     backgroundColor: colors.white,
+    // The ScrollView owns the padding (content inset scrolls with the text); the
+    // frame just clips so the scrollbar respects the rounded corners.
+    overflow: "hidden",
+  },
+  scroll: {
+    maxHeight: 240,
+  },
+  content: {
     paddingHorizontal: 10,
     paddingVertical: 8,
   },

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/primitives_purity.test.ts

@@ -21,18 +21,31 @@ import * as path from "node:path";
  * import `./markdown`. So it's allowed — the guards below remain for the
  * genuine context couplings.
  *
+ * The ONE allowed `ai` coupling: the `AgentRun` family renders the ai-sdk
+ * `UIMessage.parts` shape directly — that IS its contract (both chat and app
+ * agents emit it), so there is no bespoke transcript type to keep in sync.
+ * `agent_transform.ts` (the single place that folds parts into the render
+ * timeline) `import type`s from `ai` — erased at runtime, so no `ai` enters any
+ * consumer's bundle. That file alone is exempt from the `ai`-package guard; every
+ * other primitive stays ai-free, and the `@ai-sdk/*` runtime packages are never
+ * allowed anywhere.
+ *
  * The boundary is enforced by this test — without it primitives drift
  * back into the parent app's contexts over months.
  */
 
+const AI_PACKAGE_PATTERN = /from\s+["']ai["']/;
 const FORBIDDEN_PATTERNS = [
   /from\s+["']posthog-js/,
   /from\s+["']@lingui\//,
   /from\s+["']@ai-sdk\//,
-  /from\s+["']ai["']/,
+  AI_PACKAGE_PATTERN,
   /from\s+["']@lotics\/shared/,
 ];
 
+// The sole file permitted to `import type` from the `ai` package (see above).
+const AI_PACKAGE_ALLOWED = new Set(["agent_transform.ts"]);
+
 const SRC_DIR = path.resolve(__dirname);
 
 function listTopLevelSourceFiles(): string[] {
@@ -49,6 +62,7 @@ describe("packages/ui primitives — purity", () => {
     for (const file of listTopLevelSourceFiles()) {
       const src = fs.readFileSync(file, "utf-8");
       for (const pattern of FORBIDDEN_PATTERNS) {
+        if (pattern === AI_PACKAGE_PATTERN && AI_PACKAGE_ALLOWED.has(path.basename(file))) continue;
         if (pattern.test(src)) {
           violations.push(`${path.basename(file)} matches ${pattern}`);
         }

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,