@lotics/ui 7.19.2 → 8.0.0

package/src/composer.tsx

@@ -2,6 +2,7 @@ import React, { type ReactNode, type Ref, useCallback, useEffect, useState } fro
 import { View, TextInput as RNTextInput, ScrollView, StyleSheet, type TextInputProps } from "react-native";
 import { IconButton } from "./icon_button";
 import { colors } from "./colors";
+import { Text } from "./text";
 import { fontFamilyRegular, getInputTextStyle } from "./text_utils";
 import { useAutoGrowHeight } from "./use_auto_grow_height";
 
@@ -189,7 +190,6 @@ export function Composer(props: ComposerProps) {
         autoFocus={autoFocus}
         onChangeText={handleChangeText}
         onSubmitEditing={handleSend}
-        placeholder={placeholder}
         placeholderTextColor={colors.zinc[500]}
         value={text}
         onFocus={() => setFocused(true)}
@@ -208,6 +208,15 @@ export function Composer(props: ComposerProps) {
           spreadInputProps?.style,
         ]}
       />
+      {/* The placeholder is OURS, not the textarea's: a long hint must never
+          wrap into clipped lines inside the pill — one line, ellipsized. */}
+      {emptyText && placeholder ? (
+        <View pointerEvents="none" style={[styles.placeholderOverlay, expanded ? styles.placeholderOverlayExpanded : { paddingHorizontal: 10 }]}>
+          <Text size="sm" numberOfLines={1} style={{ color: colors.zinc[500], letterSpacing: -0.4 }}>
+            {placeholder}
+          </Text>
+        </View>
+      ) : null}
     </View>
   );
 
@@ -314,6 +323,18 @@ const styles = StyleSheet.create({
   field: {
     flex: 1,
   },
+  placeholderOverlay: {
+    position: "absolute",
+    left: 0,
+    right: 0,
+    top: 0,
+    bottom: 0,
+    justifyContent: "center",
+  },
+  placeholderOverlayExpanded: {
+    justifyContent: "flex-start",
+    paddingTop: 2,
+  },
   textInput: {
     flex: 1,
     fontFamily: fontFamilyRegular,

package/src/confidence.tsx

@@ -36,7 +36,7 @@ export function levelFromScore(score: number): ConfidenceLevel {
  * How sure the AI is — a calibrated high / medium / low read as a 3-tick meter
  * (emerald / amber / zinc) beside the level word. The fill count and the colour
  * both carry the level. The human weights an AI proposal or estimate by it. Pair
- * with `ReviewCard` or `ChangeReview`.
+ * with `ChangeReview`.
  */
 export function Confidence(props: ConfidenceProps) {
   const level = props.level ?? (props.score != null ? levelFromScore(props.score) : "medium");

package/src/control_surface.ts

@@ -39,20 +39,6 @@ export const CONTROL_TRANSITION = {
   transitionDuration: "0.12s",
 };
 
-/** THE review-card surface — the bordered white card every "AI proposes, you
- *  decide" surface wears (`ReviewCard`, and the whole-set `ChangeReview`), so the
- *  review family reads as ONE contract instead of look-alikes drifting apart. One
- *  definition; each adds its own header / body / footer on top.
- *  `reviewResolvedStyle` is the settled wash once decided. */
-export const reviewCardStyle: ViewStyle = {
-  borderWidth: 1,
-  borderColor: colors.border,
-  backgroundColor: colors.white,
-  borderRadius: 12,
-  padding: 16,
-  gap: 12,
-};
-export const reviewResolvedStyle: ViewStyle = { backgroundColor: colors.zinc[50] };
 
 /**
  * THE pill-surface contract — the single definition of the bordered, white,

package/src/finding.tsx

@@ -1,110 +1,142 @@
-import { StyleSheet, View } from "react-native";
-import { colors, solid, type ColorName } from "./colors";
-import { Text } from "./text";
+import { StyleSheet, View, type StyleProp, type ViewStyle } from "react-native";
+import { type ReactNode } from "react";
 import { Badge } from "./badge";
-import { Button } from "./button";
+import { Text } from "./text";
 import { Sources, type SourceRef } from "./sources";
 import { useLoticsLocale } from "./locale";
+import { colors, type ColorName } from "./colors";
 
 export type FindingSeverity = "critical" | "warning" | "info" | "positive";
 
+/** The localized strings — the `finding` LoticsLocale slice. */
+export type FindingLabels = Record<FindingSeverity, string> & {
+  /** The delta row's label in `FindingComparison`. */
+  difference: string;
+};
+
+const SEVERITY_COLOR: Record<FindingSeverity, ColorName> = {
+  critical: "red",
+  warning: "amber",
+  info: "zinc",
+  positive: "emerald",
+};
+
 export interface FindingProps {
-  severity?: FindingSeverity;
-  /** Translated severity words. Defaults resolve through the locale ("Critical" …). */
-  labels?: Partial<FindingLabels>;
-  /** The headline — what the agent found. */
+  /** Ranked severity — the dot badge + its localized word. */
+  severity: FindingSeverity;
+  /** What the agent found — one line. */
   title: string;
-  /** One or two lines explaining it. */
+  /** The explanation under the title. */
   detail?: string;
-  /** A headline figure tied to the finding (a value, a delta, a count), shown in
-   *  the header row in the severity colour. */
+  /** The emphasized MEASURE of the finding ("−40 pcs") — prominent in the
+   *  body (lg, semibold), never a side note. */
   metric?: string;
-  /** A short caption beside the metric giving it context ("exposure", "overdue",
-   *  "vs target"). */
+  /** What the metric compares ("invoice vs packing list"). */
   metricCaption?: string;
-  /** Provenance — the records / documents the finding rests on. */
+  /** Provenance — the one `Sources` idiom, chips at the bottom. */
   sources?: SourceRef[];
-  onOpenSource?: (s: SourceRef) => void;
-  /** The single action the finding suggests. */
-  action?: { label: string; onPress: () => void };
+  onOpenSource?: (source: SourceRef) => void;
+  /** Compose anything extra between the body and the sources — a band pair,
+   *  an action row, a custom block. */
+  children?: ReactNode;
+  style?: StyleProp<ViewStyle>;
 }
 
-// Severity reads through a coloured dot badge + the order it's stacked in (most
-// severe first): red critical, amber warning, blue note, emerald on-track. The
-// metric takes the same colour. Words resolve prop → locale → English default.
-export type FindingLabels = Record<FindingSeverity, string>;
-const SEV_COLOR: Record<FindingSeverity, ColorName> = {
-  critical: "red",
-  warning: "amber",
-  info: "blue",
-  positive: "emerald",
-};
-
 /**
- * One ranked insight from an AI briefing / audit / anomaly scan — a severity dot
- * badge and a headline figure share the top row, the headline + explanation read
- * below, then provenance and the single action it suggests. Severity reads
- * through the coloured badge + metric and the stacking order (most severe first).
- * Unlike `Callout` (a flat inline status), a Finding is ranked, sourced, and
- * carries its own next action.
+ * One ranked insight from an AI check — a cross-check discrepancy, an audit
+ * observation, a briefing item. Good defaults (severity word · title · detail
+ * · the PROMINENT metric · `Sources` chips) with a `children` slot for any
+ * extra composition. Display-only: a finding informs the verdict the host
+ * records; it decides nothing itself. Stack several most-severe first —
+ * inside a `ChangeReview` wrap each in a display-only `Change` (the family's
+ * dividers apply); standalone, separate them yourself.
  */
 export function Finding(props: FindingProps) {
-  const severity = props.severity ?? "info";
-  const words = { ...useLoticsLocale().finding, ...props.labels };
-  const sev = { word: words[severity], color: SEV_COLOR[severity] };
+  const words = useLoticsLocale().finding;
   return (
-    <View style={styles.card}>
-      <View style={styles.header}>
-        <Badge variant="dot" color={sev.color} label={sev.word} />
-        <View style={{ flex: 1 }} />
-        {props.metric ? (
-          <View style={styles.metric}>
-            <Text size="lg" weight="semibold" tabular style={{ color: solid(sev.color), letterSpacing: -0.3 }}>
-              {props.metric}
-            </Text>
-            {props.metricCaption ? (
-              <Text size="xs" color="muted">
-                {props.metricCaption}
-              </Text>
-            ) : null}
-          </View>
-        ) : null}
-      </View>
-
-      <View style={styles.body}>
-        <Text size="md" weight="semibold" numberOfLines={2}>
-          {props.title}
+    <View style={[styles.root, props.style]}>
+      <Badge variant="dot" color={SEVERITY_COLOR[props.severity]} label={words[props.severity]} />
+      <Text size="sm" weight="medium">
+        {props.title}
+      </Text>
+      {props.detail ? (
+        <Text size="sm" color="muted">
+          {props.detail}
         </Text>
-        {props.detail ? (
-          <Text size="sm" color="muted">
-            {props.detail}
+      ) : null}
+      {props.metric ? (
+        <View style={styles.metricBlock}>
+          <Text size="lg" weight="semibold" tabular>
+            {props.metric}
           </Text>
-        ) : null}
-      </View>
-
+          {props.metricCaption ? (
+            <Text size="xs" color="muted">
+              {props.metricCaption}
+            </Text>
+          ) : null}
+        </View>
+      ) : null}
+      {props.children}
       {props.sources && props.sources.length > 0 ? (
-        <Sources sources={props.sources} onOpen={props.onOpenSource} />
+        <Sources label={null} sources={props.sources} onOpen={props.onOpenSource} />
       ) : null}
-      {props.action ? (
-        <View style={styles.actionRow}>
-          <Button title={props.action.label} color="secondary" onPress={props.action.onPress} />
+    </View>
+  );
+}
+
+export interface FindingComparisonProps {
+  /** The disagreeing sides — each value with where it came from
+   *  ("invoice.pdf" · "480 pcs"). Two or more. */
+  values: { label: string; value: string }[];
+  /** The computed difference, EMPHASIZED ("−40 pcs"). */
+  delta?: string;
+  /** Label for the delta row. Defaults to the localized "Difference". */
+  deltaLabel?: string;
+}
+
+/**
+ * The expected-vs-actual body of a `Finding` — each side a labeled row
+ * (source · value), a hairline, then the DELTA emphasized. Compose it as the
+ * finding's children; it replaces ad-hoc metric text for any
+ * one-value-disagrees insight (quantities, totals, dates).
+ */
+export function FindingComparison(props: FindingComparisonProps) {
+  const words = useLoticsLocale().finding;
+  return (
+    <View style={styles.comparison}>
+      {props.values.map((v, i) => (
+        <View key={`${v.label}-${i}`} style={styles.comparisonRow}>
+          <Text size="sm" color="muted" style={styles.comparisonLabel} numberOfLines={1}>
+            {v.label}
+          </Text>
+          <Text size="sm" weight="semibold" tabular numberOfLines={1} style={{ flexShrink: 1 }}>
+            {v.value}
+          </Text>
         </View>
+      ))}
+      {props.delta ? (
+        <>
+          <View style={styles.comparisonRule} />
+          <View style={styles.comparisonRow}>
+            <Text size="sm" color="muted" style={styles.comparisonLabel} numberOfLines={1}>
+              {props.deltaLabel ?? words.difference}
+            </Text>
+            <Text size="lg" weight="semibold" tabular>
+              {props.delta}
+            </Text>
+          </View>
+        </>
       ) : null}
     </View>
   );
 }
 
 const styles = StyleSheet.create({
-  card: {
-    borderWidth: 1,
-    borderColor: colors.border,
-    backgroundColor: colors.white,
-    borderRadius: 12,
-    padding: 16,
-    gap: 12,
-  },
-  header: { flexDirection: "row", alignItems: "center", gap: 12 },
-  metric: { flexDirection: "row", alignItems: "baseline", gap: 5 },
-  body: { gap: 6 },
-  actionRow: { flexDirection: "row", justifyContent: "flex-end" },
+  root: { gap: 6, alignItems: "flex-start" },
+  metricBlock: { gap: 1, paddingVertical: 2 },
+  comparison: { gap: 6, paddingVertical: 4, alignSelf: "stretch", maxWidth: 420 },
+  comparisonRow: { flexDirection: "row", alignItems: "baseline", gap: 12 },
+  comparisonLabel: { width: 130 },
+  comparisonRule: { height: 1, backgroundColor: colors.zinc[100] },
 });
+

package/src/floating_action_bar.tsx

@@ -31,7 +31,7 @@ export function FloatingActionBar(props: FloatingActionBarProps) {
     <View pointerEvents="box-none" style={styles.wrap}>
       <Card style={styles.bar}>
         <Text size="sm" weight="semibold" tabular>{`${count} ${label}`}</Text>
-        <Button title={clearLabel} color="secondary" onPress={onClear} />
+        <Button title={clearLabel} color="muted" onPress={onClear} />
         {children}
       </Card>
     </View>

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
@@ -39,24 +39,26 @@ export interface LoticsLocale {
   /** `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
@@ -89,25 +91,27 @@ export const en: LoticsLocale = {
   formField: { optional: "Optional" },
   drawer: { previous: "Previous record", next: "Next record", close: "Close" },
   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",
@@ -158,25 +162,27 @@ export const vi: LoticsLocale = {
   formField: { optional: "Tùy chọn" },
   drawer: { previous: "Bản ghi trước", next: "Bản ghi sau", close: "Đóng" },
   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/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/use_option_list.test.ts

@@ -190,4 +190,43 @@ describe("useOptionList", () => {
     });
     expect(view.result.current.rows.map((r) => r.option.value)).toEqual(["z"]);
   });
+
+  it("controlled server-filtered mode browses recents on an empty query", () => {
+    const recentOptions = [
+      { value: "r1", label: "Recent one" },
+      { value: "r2", label: "Recent two" },
+    ];
+    // A server search has nothing for an empty term — recents are the idle list.
+    const params: UseOptionListParams<string, false> = {
+      options: [],
+      search: { mode: "controlled", query: "", serverFiltered: true },
+      recentOptions,
+    };
+    const view = renderHook((p: UseOptionListParams<string, false>) => useOptionList(p), {
+      initialProps: params,
+    });
+    expect(view.result.current.searching).toBe(false);
+    expect(view.result.current.rows.map((r) => r.option.value)).toEqual(["r1", "r2"]);
+    // Typing hands the list back to the server's results.
+    view.rerender({
+      ...params,
+      options: [{ value: "z", label: "Zucchini" }],
+      search: { mode: "controlled", query: "zu", serverFiltered: true },
+    });
+    expect(view.result.current.rows.map((r) => r.option.value)).toEqual(["z"]);
+  });
+
+  it("an empty controlled query without recents browses the full option set", () => {
+    // The `recentOptions ?? options` idle contract — a consumer that supplies
+    // browse options (server or local) and no recents keeps its full list.
+    for (const serverFiltered of [true, false]) {
+      const view = renderHook((p: UseOptionListParams<string, false>) => useOptionList(p), {
+        initialProps: {
+          options: OPTS,
+          search: { mode: "controlled" as const, query: "", serverFiltered },
+        },
+      });
+      expect(view.result.current.rows.map((r) => r.option.value)).toEqual(["a", "b", "c"]);
+    }
+  });
 });

package/src/use_option_list.ts

@@ -172,12 +172,15 @@ export function useOptionList<T extends string, MULTI extends boolean = false, D
     [options],
   );
   const filtered = useMemo(() => {
-    if (searchMode === "none" || serverFiltered) return cleanOptions;
+    if (searchMode === "none") return cleanOptions;
     if (!searching) {
       // Empty query: a controlled (Combobox) field browses recents, else its full
-      // local set; an internal field shows everything.
+      // local set; an internal field shows everything. This must precede the
+      // server-filtered short-circuit — a server search returns nothing for an
+      // empty term, so recents are the only idle content it has.
       return searchMode === "controlled" ? (recentOptions ?? cleanOptions) : cleanOptions;
     }
+    if (serverFiltered) return cleanOptions;
     const q = normalizeForSearch(query);
     return cleanOptions.filter((o) => normalizeForSearch(o.label ?? o.value).includes(q));
   }, [searchMode, serverFiltered, searching, cleanOptions, recentOptions, query]);