@lotics/ui 7.19.3 → 9.0.0

package/src/ledger.tsx

@@ -0,0 +1,220 @@
+import { createContext, useContext, type ReactNode } from "react";
+import { StyleProp, StyleSheet, View, ViewStyle } from "react-native";
+import { colors } from "./colors";
+import { Divider } from "./divider";
+import { Link } from "./link";
+import { Popover, PopoverContent, PopoverTrigger } from "./popover";
+import { PressableHighlight } from "./pressable_highlight";
+import { useLoticsLocale } from "./locale";
+import { Text } from "./text";
+
+// The record-level money list — a compact financial STATEMENT for one record's
+// drawer/section: charge/receipt GROUPS with their sums in the group headers,
+// every figure on ONE right-aligned tabular column, closed by a divider-set
+// emphasized total. A row with `peek` is a door: pressing it floats the fee's
+// PARTICULARS (basis, who charged it, the invoice it landed on) in an anchored
+// popover — the list stays flat and scannable, the depth is on demand. A row
+// with `reference` carries a trailing link instead (an issued invoice, a
+// receipt no.). No bars, no charts — the numbers are the interface.
+//
+//   <Ledger formatValue={formatMoney}>
+//     <LedgerGroup label="Charges" total={total}>
+//       <LedgerRow label="Service fee" value={fee} peek={<FeeParticulars … />} />
+//       <LedgerRow label="Levy" value={levy} reference={{ label: "INV-0414", onPress }} />
+//     </LedgerGroup>
+//     <LedgerGroup label="Received" total={-received}>
+//       <LedgerRow label="Deposit" meta="03/06 · Cash" value={-1_550_000} tone="success" />
+//     </LedgerGroup>
+//     <LedgerTotal label="Outstanding" value={due} tone="danger" zeroLabel="Paid in full" />
+//   </Ledger>
+
+interface LedgerContextValue {
+  format: (n: number) => string;
+}
+
+const LedgerContext = createContext<LedgerContextValue | null>(null);
+
+function useLedger(): LedgerContextValue {
+  const ctx = useContext(LedgerContext);
+  if (!ctx) throw new Error("Ledger components must be used within a Ledger");
+  return ctx;
+}
+
+/** Signed display: negatives render as "− <abs>" (a receipt against charges).
+ *  `n + 0` normalizes -0 (a zero receipts sum passed negated) to plain 0. */
+function signed(format: (n: number) => string, n: number) {
+  return n < 0 ? `− ${format(-n)}` : format(n + 0);
+}
+
+export interface LedgerProps {
+  /** Money formatting shared by every row, sum, and total (e.g. `formatMoney`). */
+  formatValue: (n: number) => string;
+  children: ReactNode;
+  style?: StyleProp<ViewStyle>;
+}
+
+export function Ledger(props: LedgerProps) {
+  const { formatValue, children, style } = props;
+  return (
+    <LedgerContext.Provider value={{ format: formatValue }}>
+      <View style={[styles.ledger, style]}>{children}</View>
+    </LedgerContext.Provider>
+  );
+}
+
+export interface LedgerGroupProps {
+  /** The group name ("Charges", "Received") — xs muted, with the sum opposite. */
+  label: string;
+  /** The group's sum, shown right-aligned in the header. Sign renders as
+   *  "−" (pass receipts negative). Omit to leave the header sumless. */
+  total?: number;
+  children: ReactNode;
+}
+
+/** One side of the ledger — a labelled run of rows with its sum in the header. */
+export function LedgerGroup(props: LedgerGroupProps) {
+  const { label, total, children } = props;
+  const { format } = useLedger();
+  return (
+    <View style={styles.group}>
+      <View style={styles.row}>
+        <Text size="xs" weight="medium" color="muted" style={styles.grow}>
+          {label}
+        </Text>
+        {total != null ? (
+          <Text size="xs" color="muted" tabular>
+            {signed(format, total)}
+          </Text>
+        ) : null}
+      </View>
+      {children}
+    </View>
+  );
+}
+
+export interface LedgerRowProps {
+  /** The line's name — what was charged / received. */
+  label: string;
+  /** Inline context after the label — a date · method, a basis, a period. */
+  meta?: string;
+  /** The amount. Negative renders "− <abs>" (a receipt). */
+  value: number;
+  /** Valence of the amount (a receipt reads success). */
+  tone?: "default" | "success" | "danger";
+  /** The line's PARTICULARS — set it and the whole row becomes a pressable
+   *  door that floats this node in an anchored popover. Put any links (the
+   *  invoice, the tariff) INSIDE the peek: a row is never a button holding
+   *  another button, so `reference` is ignored while `peek` is set. */
+  peek?: ReactNode;
+  /** Peek popover width. Default 300. */
+  peekWidth?: number;
+  /** A trailing reference link (an issued invoice, a receipt no.) for a row
+   *  WITHOUT `peek`. */
+  reference?: { label: string; onPress: () => void };
+  /** Accessible name for a peekable row. Defaults to "<label> details". */
+  accessibilityLabel?: string;
+}
+
+/** One money line. Static by default; a door to its particulars with `peek`. */
+export function LedgerRow(props: LedgerRowProps) {
+  const { label, meta, value, tone = "default", peek, peekWidth = 300, reference, accessibilityLabel } = props;
+  const rowDetails = useLoticsLocale().ledger.rowDetails;
+  const { format } = useLedger();
+  const content = (
+    <>
+      <Text size="sm" numberOfLines={1} style={styles.shrink}>
+        {label}
+      </Text>
+      {meta ? (
+        <Text size="xs" color="muted" numberOfLines={1}>
+          {meta}
+        </Text>
+      ) : null}
+      <View style={styles.grow} />
+      {!peek && reference ? (
+        <Link size="xs" onPress={reference.onPress} accessibilityLabel={reference.label}>
+          {reference.label}
+        </Link>
+      ) : null}
+      <Text size="sm" tabular color={tone === "default" ? undefined : tone}>
+        {signed(format, value)}
+      </Text>
+    </>
+  );
+  if (!peek) {
+    return <View style={styles.row}>{content}</View>;
+  }
+  return (
+    <Popover side="bottom" align="end">
+      <PopoverTrigger>
+        <PressableHighlight
+          focusRing
+          accessibilityRole="button"
+          accessibilityLabel={accessibilityLabel ?? rowDetails(label)}
+          style={(state) => [styles.row, styles.rowPress, state.hovered ? styles.rowHovered : null]}
+        >
+          {content}
+        </PressableHighlight>
+      </PopoverTrigger>
+      <PopoverContent style={{ width: peekWidth }} disableBodyScroll>
+        {peek}
+      </PopoverContent>
+    </Popover>
+  );
+}
+
+export interface LedgerTotalProps {
+  /** The closing question the ledger answers ("Outstanding", "Balance"). */
+  label: string;
+  value: number;
+  /** Valence of the closing figure. */
+  tone?: "default" | "success" | "danger";
+  /** Rendered instead of the figure when `value` is 0 ("Paid in full") — in
+   *  success tone, since a settled ledger is the good outcome. */
+  zeroLabel?: string;
+}
+
+/** The divider-set closing line — the ledger's ONE emphasized number. */
+export function LedgerTotal(props: LedgerTotalProps) {
+  const { label, value, tone = "default", zeroLabel } = props;
+  const { format } = useLedger();
+  const settled = value === 0 && zeroLabel != null;
+  return (
+    <View style={styles.total}>
+      <Divider />
+      <View style={styles.row}>
+        <Text size="sm" weight="semibold" style={styles.grow}>
+          {label}
+        </Text>
+        <Text size="lg" weight="semibold" tabular color={settled ? "success" : tone === "default" ? undefined : tone}>
+          {settled ? zeroLabel : signed(format, value)}
+        </Text>
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  // Outdent by the rows' 8px inset (the ListItem/Timeline technique) so row text +
+  // the money column align with the section heading and the container edges;
+  // the pressable door's wash bleeds into the gutter instead of squeezing text.
+  ledger: { gap: 12, marginHorizontal: -8 },
+  group: { gap: 4 },
+  // EVERY line (group header, rows, the total) shares the 8px text inset, so
+  // labels and the money column sit on one edge whether a row peeks or not —
+  // the pressable door's wash simply fills the same padded box.
+  row: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 10,
+    minHeight: 28,
+    paddingHorizontal: 8,
+  },
+  rowPress: {
+    borderRadius: 8,
+  },
+  rowHovered: { backgroundColor: colors.zinc[50] },
+  grow: { flexGrow: 1, flexShrink: 1 },
+  shrink: { flexShrink: 1 },
+  total: { gap: 6 },
+});

package/src/locale.tsx

@@ -2,10 +2,10 @@ import { createContext, useContext, type ReactNode } from "react";
 import { type PaginationLabels } from "./pagination";
 import { type SortHeaderLabels } from "./sort_header";
 import { type ConfidenceLabels } from "./confidence";
-import { type FindingLabels } from "./finding";
 import { type RemainderMeterLabels } from "./remainder_meter";
 import { type DateRangeFilterFieldLabels } from "./date_range_filter_field";
 import { type GalleryLabels } from "./file_preview_types";
+import { type FindingLabels } from "./finding";
 
 /**
  * The kit's localizable strings, one slice per string-bearing component. A
@@ -36,27 +36,40 @@ export interface LoticsLocale {
   formField: { optional: string };
   /** `Drawer`: the record prev/next + close controls (screen-reader names). */
   drawer: { previous: string; next: string; close: string };
+  /** The `Inline*` editor family: the shared save-error line and the
+   *  text-editor Save/Cancel tooltips. */
+  inline: { saveError: string; save: string; cancel: string };
+  /** `Ledger`: the screen-reader name of a peekable row. */
+  ledger: { rowDetails: (label: string) => string };
+  /** `SectionHeadingTitle`: the info-popover trigger's screen-reader name. */
+  sectionHeading: { info: string };
+  /** `Chip`: the ✕ default name when no `dismissTooltip` is given. */
+  chip: { remove: string };
+  /** `SuggestionChip`: the press target's default name and the ✕ tooltip. */
+  suggestionChip: { add: (label: string) => string; dismiss: string };
   /** `Confidence`: the full level phrase ("High confidence" …). */
   confidence: ConfidenceLabels;
   /** `Finding`: the severity badge word ("Critical" …). */
-  finding: FindingLabels;
   /** `RemainderMeter`: the applied / remaining / over / exact captions. */
   remainderMeter: Required<RemainderMeterLabels>;
   /** `ChangeReview` (+ `ChangeReviewActions`): the review-card chrome — the
    *  Keep/Drop verdicts, Undo, the Applied/Discarded tags, the kept-counter,
    *  the title, and the commit-bar Accept-all / Discard. */
+  finding: FindingLabels;
   changeReview: {
     title: string;
     accept: string;
     reject: string;
     undo: string;
-    applied: string;
-    discarded: string;
     keptCount: (kept: number, total: number) => string;
     acceptAll: string;
     discard: string;
     apply: string;
-    applyKept: string;
+    recommended: string;
+    customValue: string;
+    opAdd: string;
+    opEdit: string;
+    opRemove: string;
   };
   /** `DateRangeFilterField` (and the `DateFilter` panel it wraps): presets,
    *  from/to, the footer Clear/Done, the trigger placeholder, and the time-field
@@ -88,26 +101,33 @@ export const en: LoticsLocale = {
   filterChip: { clear: "Clear" },
   formField: { optional: "Optional" },
   drawer: { previous: "Previous record", next: "Next record", close: "Close" },
+  inline: { saveError: "Couldn't save. Try again.", save: "Save", cancel: "Cancel" },
+  ledger: { rowDetails: (label) => `${label} details` },
+  sectionHeading: { info: "About this data" },
+  chip: { remove: "Remove" },
+  suggestionChip: { add: (label) => `Add: ${label}`, dismiss: "Dismiss suggestion" },
   confidence: { high: "High confidence", medium: "Medium confidence", low: "Low confidence" },
-  finding: { critical: "Critical", warning: "Warning", info: "Note", positive: "On track" },
   remainderMeter: {
     applied: (allocated, total) => `${allocated} of ${total} applied`,
     remaining: (remainder) => `${remainder} unapplied`,
     over: (amount) => `Over by ${amount}`,
     exact: "Fully applied",
   },
+  finding: { critical: "Critical", warning: "Warning", info: "Note", positive: "On track", difference: "Difference" },
   changeReview: {
     title: "Suggested edits",
     accept: "Keep",
     reject: "Drop",
     undo: "Undo",
-    applied: "Applied",
-    discarded: "Discarded",
     keptCount: (kept, total) => `${kept} of ${total} kept`,
-    acceptAll: "Accept all",
+    acceptAll: "Keep all",
     discard: "Discard",
     apply: "Apply",
-    applyKept: "Apply kept",
+    recommended: "AI pick",
+    customValue: "Type another value",
+    opAdd: "Add",
+    opEdit: "Edit",
+    opRemove: "Delete",
   },
   dateRange: {
     year: "Year", month: "Month", day: "Day", hour: "Hour", minute: "Minute", dayPeriod: "AM/PM",
@@ -157,26 +177,33 @@ export const vi: LoticsLocale = {
   filterChip: { clear: "Xóa" },
   formField: { optional: "Tùy chọn" },
   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" },
+  ledger: { rowDetails: (label) => `Chi tiết ${label}` },
+  sectionHeading: { info: "Giải thích dữ liệu" },
+  chip: { remove: "Xóa" },
+  suggestionChip: { add: (label) => `Thêm: ${label}`, dismiss: "Bỏ gợi ý" },
   confidence: { high: "Độ tin cậy cao", medium: "Độ tin cậy trung bình", low: "Độ tin cậy thấp" },
-  finding: { critical: "Nghiêm trọng", warning: "Cảnh báo", info: "Ghi chú", positive: "Đúng tiến độ" },
   remainderMeter: {
     applied: (allocated, total) => `Đã phân bổ ${allocated}/${total}`,
     remaining: (remainder) => `Còn ${remainder}`,
     over: (amount) => `Vượt ${amount}`,
     exact: "Đã phân bổ đủ",
   },
+  finding: { critical: "Nghiêm trọng", warning: "Cảnh báo", info: "Ghi chú", positive: "Đúng tiến độ", difference: "Chênh lệch" },
   changeReview: {
     title: "Đề xuất chỉnh sửa",
     accept: "Giữ",
     reject: "Bỏ",
     undo: "Hoàn tác",
-    applied: "Đã áp dụng",
-    discarded: "Đã bỏ",
-    keptCount: (kept, total) => `Giữ ${kept}/${total}`,
+    keptCount: (kept, total) => `Đã giữ ${kept}/${total}`,
     acceptAll: "Giữ tất cả",
-    discard: "Hủy",
+    discard: "Bỏ hết",
     apply: "Áp dụng",
-    applyKept: "Áp dụng mục đã giữ",
+    recommended: "AI đề xuất",
+    customValue: "Nhập giá trị khác",
+    opAdd: "Thêm",
+    opEdit: "Sửa",
+    opRemove: "Xóa",
   },
   dateRange: {
     year: "Năm", month: "Tháng", day: "Ngày", hour: "Giờ", minute: "Phút", dayPeriod: "SA/CH",

package/src/progress_bar.tsx

@@ -16,6 +16,11 @@ export interface ProgressBarProps {
   format?: ProgressBarFormat;
   color?: string;
   completeColor?: string;
+  /** COMPACT: one row — the track (flex) with a plain sm tabular count beside
+   *  it ("4/5", or "80%" under format="percentage"). For cells, headings, and
+   *  peek triggers where the stacked title-over-track anatomy is too tall and
+   *  a floating caption reads misaligned. `title` is ignored. */
+  compact?: boolean;
 }
 
 /**
@@ -32,11 +37,29 @@ export function ProgressBar(props: ProgressBarProps) {
     format = "percentage",
     color = colors.blue["500"],
     completeColor = colors.green["500"],
+    compact = false,
   } = props;
 
-  const percentage = Math.min(100, Math.max(0, (value / max) * 100));
+  const percentage = max > 0 ? Math.min(100, Math.max(0, (value / max) * 100)) : 0;
   const isComplete = percentage >= 100;
 
+  if (compact) {
+    const label =
+      format === "percentage" ? `${Math.round(percentage)}%` : `${value.toLocaleString("vi-VN")}/${max.toLocaleString("vi-VN")}`;
+    return (
+      <View style={styles.compactRow}>
+        <View style={[styles.track, styles.compactTrack]}>
+          <View style={[styles.fill, { width: `${percentage}%`, backgroundColor: isComplete ? completeColor : color }]} />
+        </View>
+        {format === "none" ? null : (
+          <Text size="sm" tabular color={isComplete ? "success" : "muted"}>
+            {label}
+          </Text>
+        )}
+      </View>
+    );
+  }
+
   const caption =
     format === "fraction"
       ? `${value.toLocaleString("vi-VN")} / ${max.toLocaleString("vi-VN")} · ${Math.round(percentage)}%`
@@ -80,6 +103,14 @@ const styles = StyleSheet.create({
   container: {
     gap: 6,
   },
+  compactRow: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 8,
+  },
+  compactTrack: {
+    flex: 1,
+  },
   header: {
     flexDirection: "row",
     alignItems: "baseline",

package/src/record_summary.tsx

@@ -0,0 +1,101 @@
+import { type ReactNode } from "react";
+import { StyleSheet, View } from "react-native";
+import { Text } from "./text";
+
+export interface RecordSummaryMetric {
+  /** Caption above the number ("Outstanding", "Total value"). */
+  label: string;
+  /** The headline figure — rendered lg semibold tabular. */
+  value: string;
+  /** Valence of the figure (and its note) — the summary's ONE permitted accent. */
+  tone?: "default" | "danger" | "warning" | "success";
+  /** One short qualifier under the number ("Overdue 25 days"). */
+  note?: string;
+}
+
+export interface RecordSummaryProps {
+  /** The record's id/name — xl semibold, tabular so ids align across records. */
+  title: string;
+  /** Heading level of the title (`role="header"` + aria-level). Default 1 —
+   *  the record page's one h1; pass 2 when the band sits inside a surface
+   *  that already owns the h1 (a drawer with its own titled header). */
+  level?: 1 | 2 | 3;
+  /** Identity qualifiers on the title line ("HCM → Hamburg · Export · FCL") —
+   *  sm muted; wraps under the title when narrow. */
+  subtitle?: string;
+  /** A status chip (a `Badge`) or any small node right after the title. */
+  status?: ReactNode;
+  /** ONE headline number with valence — pinned to the summary's top right.
+   *  More than one figure belongs in a KPI strip, not the record header. */
+  metric?: RecordSummaryMetric;
+}
+
+/**
+ * The identity band of a single record's detail screen or drawer: ONE row —
+ * title · subtitle · status chip, with an optional headline metric pinned
+ * right. It exists to stop hand-rolled record headers drifting: mixed type
+ * scales, several competing figures, color noise.
+ *
+ * Color discipline: the header stays neutral; `metric.tone` is the one accent.
+ * The record's FIELDS never live in the header — compose them as
+ * `DetailTable`s in the sections below (`SectionHeading` + `Divider` rhythm) —
+ * see `examples/tpl_record.tsx`.
+ */
+export function RecordSummary(props: RecordSummaryProps) {
+  const { title, subtitle, status, metric, level = 1 } = props;
+  return (
+    <View style={styles.identityRow}>
+        <View style={styles.identity}>
+          <View style={styles.titleRow}>
+            <Text size="xl" weight="semibold" tabular level={level}>
+              {title}
+            </Text>
+            {status ?? null}
+          </View>
+          {subtitle ? (
+            <Text size="sm" color="muted">
+              {subtitle}
+            </Text>
+          ) : null}
+        </View>
+        {metric ? (
+          <View style={styles.metric}>
+            <Text size="xs" color="muted" weight="medium" align="right">
+              {metric.label}
+            </Text>
+            <Text size="lg" weight="semibold" tabular align="right" color={metric.tone === "default" ? undefined : metric.tone}>
+              {metric.value}
+            </Text>
+            {metric.note ? (
+              <Text size="xs" align="right" weight={metric.tone && metric.tone !== "default" ? "medium" : "regular"} color={metric.tone && metric.tone !== "default" ? metric.tone : "muted"}>
+                {metric.note}
+              </Text>
+            ) : null}
+          </View>
+        ) : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  identityRow: {
+    flexDirection: "row",
+    alignItems: "flex-start",
+    gap: 16,
+  },
+  identity: {
+    flex: 1,
+    gap: 2,
+  },
+  titleRow: {
+    flexDirection: "row",
+    alignItems: "center",
+    flexWrap: "wrap",
+    columnGap: 10,
+    rowGap: 4,
+  },
+  metric: {
+    alignItems: "flex-end",
+    gap: 1,
+  },
+});

package/src/section_heading.tsx

@@ -2,6 +2,7 @@ import { View, type StyleProp, type ViewStyle } from "react-native";
 import { Text, type HeadingLevel } from "./text";
 import { Icon, type IconName } from "./icon";
 import { InfoPopover } from "./info_popover";
+import { useLoticsLocale } from "./locale";
 
 // The card-less section header — the bare-canvas sibling of `CardHeader`, built
 // the same compound way. A title (+ optional leading icon / description) on one
@@ -36,7 +37,12 @@ export interface SectionProps {
  *   </Section>
  */
 export function Section(props: SectionProps) {
-  return <View style={[{ gap: 10 }, props.style]}>{props.children}</View>;
+  // gap 12 spaces the heading from its body. Space BETWEEN sections belongs to
+  // the page column: flat record/form pages use `gap: 32` on the content column
+  // with a bare `Divider` BETWEEN sections (never under the heading — the
+  // heading belongs to its content; the hairline separates it from the LAST
+  // section).
+  return <View style={[{ gap: 12 }, props.style]}>{props.children}</View>;
 }
 
 export interface SectionHeadingProps {
@@ -58,26 +64,28 @@ export interface SectionHeadingTitleProps {
   icon?: IconName;
   /** Heading rank. Defaults to 2 — typical for page-level section titles. */
   level?: HeadingLevel;
-  /** Title weight. Defaults to `medium`; `semibold` (matching `CardHeaderTitle`)
-   * for denser surfaces — a side panel, a stacked group list — where `medium`
-   * blends into the body rows. */
+  /** Title weight. Defaults to `semibold` — a section title must separate from
+   * the body rows at a glance (medium blends in; it remains as an opt-down for
+   * a surface where the heading competes with a stronger band above it). */
   weight?: "medium" | "semibold";
   /** An ⓘ popover after the title — a short "what this is / where it came from"
    * gloss, mirroring `CardHeaderTitle`'s `info`. */
   info?: string;
 }
 
-/** The title block — grows to push any sibling actions to the right edge. */
+/** The title block — lg semibold (a section must announce itself; md blends
+ * into control labels) + an optional muted `description` line. Grows to push
+ * any sibling actions to the right edge. */
 export function SectionHeadingTitle(props: SectionHeadingTitleProps) {
-  const { children, description, icon, level = 2, weight = "medium", info } = props;
+  const { children, description, icon, level = 2, weight = "semibold", info } = props;
   return (
     <View style={{ flex: 1, gap: 2 }}>
       <View style={{ flexDirection: "row", alignItems: "center", gap: 6 }}>
         {icon ? <Icon name={icon} size={18} /> : null}
-        <Text level={level} weight={weight} size="md">
+        <Text level={level} weight={weight} size="lg">
           {children}
         </Text>
-        {info ? <InfoPopover text={info} accessibilityLabel="Giải thích dữ liệu" /> : null}
+        {info ? <InfoPopover text={info} accessibilityLabel={useLoticsLocale().sectionHeading.info} /> : null}
       </View>
       {description ? (
         <Text color="zinc-500" size="sm">

package/src/sources.tsx

@@ -16,8 +16,9 @@ export interface SourceRef {
 
 export interface SourcesProps {
   sources: SourceRef[];
-  /** Eyebrow above the chips. Default "Sources". */
-  label?: string;
+  /** Eyebrow above the chips. Default "Sources"; pass `null` for chips only —
+   *  the form used INSIDE a `Change` (a review card's own header/body). */
+  label?: string | null;
   /** Pass to make each chip openable (jump to the record / document / page). The
    *  chips then show a hover state + an open glyph; the host does the navigation. */
   onOpen?: (source: SourceRef) => void;
@@ -45,9 +46,11 @@ export function Sources(props: SourcesProps) {
   if (props.sources.length === 0) return null;
   return (
     <View style={{ gap: 8 }}>
-      <Text size="xs" color="muted" weight="medium">
-        {props.label ?? "Sources"}
-      </Text>
+      {props.label === null ? null : (
+        <Text size="xs" color="muted" weight="medium">
+          {props.label ?? "Sources"}
+        </Text>
+      )}
       <View style={styles.row}>
         {props.sources.map((s) =>
           props.onOpen ? (

package/src/suggestion_chip.tsx

@@ -0,0 +1,47 @@
+import { StyleSheet, View } from "react-native";
+import { Chip } from "./chip";
+import { colors } from "./colors";
+import { Icon } from "./icon";
+import { useLoticsLocale } from "./locale";
+import { Text } from "./text";
+
+export interface SuggestionChipProps {
+  /** The suggested item ("Verify the customer's tax ID"). */
+  label: string;
+  /** Materialize the suggestion. */
+  onAdd: () => void;
+  /** Refuse the suggestion (the ✕). Omit for take-it-or-leave-it pills. */
+  onDismiss?: () => void;
+  /** Accessible name of the press target; default "Add: <label>". */
+  accessibilityLabel?: string;
+  /** The ✕'s name; defaults to the locale's "Dismiss suggestion". */
+  dismissLabel?: string;
+}
+
+/**
+ * A dismissible SUGGESTION pill — an item the record could have but doesn't
+ * yet (a common task, an expected line): a `Chip` whose press MATERIALIZES it
+ * and whose ✕ refuses it. A pill can never be mistaken for the real row it
+ * would become; suggestions never count in any total. Filter out labels the
+ * list already holds before rendering.
+ */
+export function SuggestionChip(props: SuggestionChipProps) {
+  const { label, onAdd, onDismiss, accessibilityLabel, dismissLabel } = props;
+  const labels = useLoticsLocale().suggestionChip;
+  return (
+    <Chip onPress={onAdd} accessibilityLabel={accessibilityLabel ?? labels.add(label)} onDismiss={onDismiss} dismissTooltip={dismissLabel ?? labels.dismiss}>
+      <View style={styles.content}>
+        <Icon name="plus" size={15} color={colors.zinc[500]} />
+        <Text size="sm">{label}</Text>
+      </View>
+    </Chip>
+  );
+}
+
+const styles = StyleSheet.create({
+  content: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 6,
+  },
+});