@lotics/ui 28.3.1 → 29.2.0

package/src/file_thumbnail.tsx

@@ -21,6 +21,7 @@ import {
   Linking,
 } from "react-native";
 import { isImageMimeType, isVideoMimeType, isAudioMimeType } from "./mime";
+import { DiffMark, type DiffKind } from "./diff_mark";
 
 export const THUMBNAIL_SIZE = 96;
 export const COMPACT_THUMBNAIL_SIZE = 32;
@@ -86,14 +87,67 @@ interface FileThumbnailProps {
   /** Accessible name for the tile — what pressing it DOES, when the raw filename isn't
    *  the useful name ("Xem chứng từ"). Defaults to `file.filename`. */
   accessibilityLabel?: string;
+  /**
+   * WHAT A PROPOSAL DOES TO THIS TILE — a corner mark for a document set under
+   * review, rendered as a grid rather than as a list.
+   *
+   * Top-LEFT because it is the one corner nothing else claims (remove sits
+   * top-right, selection bottom-right, the uploading scrim covers everything),
+   * and because it puts the mark where the row list already puts it.
+   *
+   * The disc rides a white RING: a tile's ground is an arbitrary photo, and a
+   * pale tint over a pale scan is not a mark, it is a smudge. `removed`
+   * additionally fades the tile BODY — the grid's way of saying a document is
+   * on its way off the record — while the mark itself stays at full strength,
+   * since a faded mark is the exact smudge the ring exists to prevent.
+   *
+   * Ignored on a COMPACT tile (≤ 32px): a 22px disc on a 32px tile is not a
+   * corner mark, it is the tile. A compact strip lives inside a row, and that
+   * row is where its change belongs.
+   *
+   * A grid expresses MEMBERSHIP (this document is arriving, that one is going)
+   * and expresses PAIRING badly: a 96px tile has nowhere to say which file a
+   * replacement supersedes. Use `FileRow` for a set where things are being
+   * replaced rather than added and removed.
+   */
+  diff?: DiffKind;
 }
 
+/**
+ * The tile's diff mark — the same disc the rows use, on a white RING.
+ *
+ * The ring rather than the disc alone because a tile's ground is an arbitrary
+ * photo, and a pale tint over a pale scan is a smudge. It is circular rather
+ * than a rounded square: two shapes for one mark is exactly the inconsistency
+ * the disc exists to end.
+ */
+function DiffCorner({ kind }: { kind: DiffKind }) {
+  if (kind === "unchanged") return null;
+  return (
+    <View style={diffCornerStyles.chip} pointerEvents="none">
+      <DiffMark kind={kind} />
+    </View>
+  );
+}
+
+const diffCornerStyles = StyleSheet.create({
+  chip: {
+    position: "absolute",
+    top: 4,
+    left: 4,
+    zIndex: 2,
+    backgroundColor: colors.white,
+    borderRadius: 999,
+    padding: 2,
+  },
+});
+
 /**
  * Displays a file as a square thumbnail.
  * Works with any file source via DisplayFile interface.
  */
 export function FileThumbnail(props: FileThumbnailProps) {
-  const { file, size, onPress, onLongPress, onRemove, selected, uploading, isTemplate, disablePress } = props;
+  const { file, size, onPress, onLongPress, onRemove, selected, uploading, isTemplate, disablePress, diff } = props;
   const accessibilityLabel = props.accessibilityLabel ?? file.filename;
   // A tile with no `onPress` still OPENS the file — a useful default for a bare
   // thumbnail in a list or a gallery. But a caller that said `disablePress`
@@ -106,13 +160,34 @@ export function FileThumbnail(props: FileThumbnailProps) {
   const rootStyle =
     size !== undefined ? { width: size, height: size } : { width: "100%" as const, aspectRatio: 1 };
 
+  // A tile ≤ 32px is a badge in a strip, not a card: a 22px mark would swallow
+  // it. The row or cell holding the strip carries the change instead.
+  const compact = size !== undefined && size <= COMPACT_THUMBNAIL_SIZE;
+  const mark = diff === undefined || compact ? null : <DiffCorner kind={diff} />;
+
+  /**
+   * A document on its way OFF the record reads as leaving, and the fade says
+   * that across the whole tile — which is what a grid is scanned by.
+   *
+   * It wraps the BODY rather than the root on purpose. `opacity` cascades to
+   * the entire subtree, so on the root it faded the corner mark too, at exactly
+   * the moment the mark has the most to say. That is also the dimming
+   * `DiffMark`'s ink was darkened for; putting the mark inside it would have
+   * spent that margin for nothing.
+   */
+  const body = (node: React.ReactNode) =>
+    diff === "removed" ? <View style={styles.fadedBody}>{node}</View> : node;
+
   if (isImageMimeType(file.mimeType)) {
     return (
       <View style={rootStyle}>
-        <ImageThumbnail file={file} size={size} accessibilityLabel={accessibilityLabel} onPress={press} onLongPress={onLongPress} />
+        {body(
+          <ImageThumbnail file={file} size={size} accessibilityLabel={accessibilityLabel} onPress={press} onLongPress={onLongPress} />,
+        )}
         {uploading && <UploadingOverlay size={size} />}
         {onRemove && <RemoveButton onPress={onRemove} />}
         {selected !== undefined && <SelectionOverlay selected={selected} />}
+        {mark}
       </View>
     );
   }
@@ -122,46 +197,52 @@ export function FileThumbnail(props: FileThumbnailProps) {
   if (size !== undefined && size <= COMPACT_THUMBNAIL_SIZE && mediaIcon === undefined) {
     return (
       <View style={rootStyle}>
-        <DocumentBadge
-          mimeType={file.mimeType}
-          size={size}
-          isTemplate={isTemplate}
-          accessibilityLabel={accessibilityLabel}
-          onPress={pressOrOpen}
-          onLongPress={onLongPress}
-        />
+        {body(
+          <DocumentBadge
+            mimeType={file.mimeType}
+            size={size}
+            isTemplate={isTemplate}
+            accessibilityLabel={accessibilityLabel}
+            onPress={pressOrOpen}
+            onLongPress={onLongPress}
+          />,
+        )}
         {uploading && <UploadingOverlay size={size} />}
         {onRemove && <RemoveButton onPress={onRemove} />}
+        {mark}
       </View>
     );
   }
 
   return (
     <View style={rootStyle}>
-      {mediaIcon !== undefined ? (
-        <MediaCard
-          mimeType={file.mimeType}
-          filename={file.filename}
-          icon={mediaIcon}
-          size={size}
-          accessibilityLabel={accessibilityLabel}
-          onPress={pressOrOpen}
-          onLongPress={onLongPress}
-        />
-      ) : (
-        <DocumentCard
-          mimeType={file.mimeType}
-          filename={file.filename}
-          size={size}
-          isTemplate={isTemplate}
-          accessibilityLabel={accessibilityLabel}
-          onPress={pressOrOpen}
-          onLongPress={onLongPress}
-        />
+      {body(
+        mediaIcon !== undefined ? (
+          <MediaCard
+            mimeType={file.mimeType}
+            filename={file.filename}
+            icon={mediaIcon}
+            size={size}
+            accessibilityLabel={accessibilityLabel}
+            onPress={pressOrOpen}
+            onLongPress={onLongPress}
+          />
+        ) : (
+          <DocumentCard
+            mimeType={file.mimeType}
+            filename={file.filename}
+            size={size}
+            isTemplate={isTemplate}
+            accessibilityLabel={accessibilityLabel}
+            onPress={pressOrOpen}
+            onLongPress={onLongPress}
+          />
+        ),
       )}
       {uploading && <UploadingOverlay size={size} />}
       {onRemove && <RemoveButton onPress={onRemove} />}
       {selected !== undefined && <SelectionOverlay selected={selected} />}
+      {mark}
     </View>
   );
 }
@@ -456,6 +537,8 @@ function SelectionOverlay({ selected }: { selected: boolean }) {
 // =============================================================================
 
 const styles = StyleSheet.create({
+  // Fills the tile so the fade covers the whole body and nothing reflows.
+  fadedBody: { width: "100%", height: "100%", opacity: 0.45 },
   documentCard: {
     borderRadius: 10,
     backgroundColor: colors.white,

package/src/file_thumbnail_grid.tsx

@@ -15,6 +15,7 @@ import { View, Pressable, StyleSheet, type ViewStyle } from "react-native";
 import { Text } from "./text";
 import { colors } from "./colors";
 import { FileThumbnail, type DisplayFile, THUMBNAIL_SIZE, COMPACT_THUMBNAIL_SIZE } from "./file_thumbnail";
+import { type DiffKind } from "./diff_mark";
 import { FOCUS_RING } from "./control_surface";
 import { useFocusRing } from "./use_focus_ring";
 
@@ -171,12 +172,22 @@ export interface FileThumbnailGridProps {
   disablePress?: boolean;
   /** Selected file IDs — renders a selection overlay on those thumbnails. */
   selectedIds?: ReadonlySet<string>;
+  /**
+   * What a proposal does to each file, keyed by id — a corner mark on the tile
+   * and a fade on anything being removed. Keyed the same way `selectedIds` is,
+   * so a grid under review is the SAME grid with one more map passed in.
+   *
+   * A grid says MEMBERSHIP well and PAIRING badly: there is nowhere on a 96px
+   * tile to name the file a replacement supersedes. A set where documents are
+   * being replaced rather than added and removed wants `FileRow`.
+   */
+  diffs?: ReadonlyMap<string, DiffKind>;
   onFilePress?: (file: DisplayFile) => void;
   onRemove?: (id: string) => void;
 }
 
 export function FileThumbnailGrid(props: FileThumbnailGridProps) {
-  const { files, selectedIds, onFilePress, onRemove, disablePress, ...layout } = props;
+  const { files, selectedIds, diffs, onFilePress, onRemove, disablePress, ...layout } = props;
   return (
     <ThumbnailGrid
       {...layout}
@@ -187,6 +198,7 @@ export function FileThumbnailGrid(props: FileThumbnailGridProps) {
         <FileThumbnail
           file={file}
           size={size}
+          diff={diffs?.get(file.id)}
           onPress={disablePress || !onFilePress ? undefined : () => onFilePress(file)}
           // Withholding `onPress` is NOT enough: a tile with none falls back to
           // opening the file, so it stays a button and a tab stop. The prop has

package/src/finding.tsx

@@ -47,9 +47,8 @@ export interface FindingProps {
  * 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.
+ * records; it decides nothing itself. Stack several most-severe first,
+ * separated by a `Divider`.
  */
 export function Finding(props: FindingProps) {
   const words = useLoticsLocale().finding;

package/src/inline_slot.tsx

@@ -0,0 +1,58 @@
+import { StyleSheet, View, type StyleProp, type ViewStyle } from "react-native";
+import { type ReactNode } from "react";
+import { CONTROL_RADIUS } from "./control_surface";
+import { INLINE_CONTROL_HEIGHT } from "./inline_edit";
+
+export interface InlineSlotProps {
+  /** Whatever sits in the value column — a `DiffValue`, a chip, a pair. */
+  children: ReactNode;
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * ANY node placed on the INLINE-CONTROL GRID — the box an `Inline*` editor
+ * draws, minus the editor.
+ *
+ * A record's value column mixes editors with things that are not editors: a
+ * computed total, a synced value, a proposed change. The editors are 40px tall
+ * with 8px of horizontal padding inside a 1px border, and their text therefore
+ * sits 9px in from the cell edge and centred in a 40px band. Anything rendered
+ * raw beside them starts at the cell edge, 20px tall, at the top — so the value
+ * column quietly acquires TWO left edges and two baselines, and `DetailRow`'s
+ * label (which pads down to meet a control) agrees with one kind of row and not
+ * the other.
+ *
+ * That is not a cosmetic drift. The column is the only thing telling a reader
+ * these values belong to one record, and it stops reading as a column.
+ *
+ * `InlineStatic` is the STRING case of this and composes it. Reach for the slot
+ * directly when the value is a node — which a review surface always is, since a
+ * proposed value is a `DiffValue` sitting where its editor would be.
+ *
+ * NOT for a table cell: a `Table` sets its own row rhythm, and a 40px control
+ * band inside one only makes the rows taller.
+ */
+export function InlineSlot({ children, style }: InlineSlotProps) {
+  return <View style={[styles.box, style]}>{children}</View>;
+}
+
+const styles = StyleSheet.create({
+  // Matches `inline_edit`'s view box exactly (height, radius, padding, 1px
+  // transparent border) so the content's baseline aligns with the editors —
+  // minus the FocusRingPressable, so it never reads as an interactive control.
+  box: {
+    minHeight: INLINE_CONTROL_HEIGHT,
+    borderRadius: CONTROL_RADIUS,
+    borderWidth: 1,
+    borderColor: "transparent",
+    paddingHorizontal: 8,
+    // The editors' vertical padding too, not just the horizontal. A single line
+    // hides its absence — the box is `minHeight` 40 and the text is ~20, so both
+    // sides land on 40 whether or not this exists — but an auto-growing input
+    // sizes itself to content PLUS its padding and border, so from the SECOND
+    // line on, a value without this sits ~14px shorter than the input that
+    // replaces it. Matching by coincidence at one line is not matching.
+    paddingVertical: 8,
+    justifyContent: "center",
+  },
+});

package/src/inline_static.tsx

@@ -1,8 +1,8 @@
-import { StyleSheet, View } from "react-native";
+import { StyleSheet } from "react-native";
 import { Text } from "./text";
 import { colors } from "./colors";
-import { CONTROL_RADIUS } from "./control_surface";
-import { INLINE_CONTROL_HEIGHT, inlineValueTextStyle } from "./inline_edit";
+import { inlineValueTextStyle } from "./inline_edit";
+import { InlineSlot } from "./inline_slot";
 
 export interface InlineStaticProps {
   /** The value to show. Empty → `placeholder` (default "—"). */
@@ -45,7 +45,7 @@ export function InlineStatic(props: InlineStaticProps) {
   const isEmpty = value.length === 0;
   const display = isEmpty ? (placeholder ?? "—") : value;
   return (
-    <View style={styles.box}>
+    <InlineSlot>
       <Text
         numberOfLines={multiline ? undefined : 1}
         tabular={tabular}
@@ -56,28 +56,10 @@ export function InlineStatic(props: InlineStaticProps) {
       >
         {display}
       </Text>
-    </View>
+    </InlineSlot>
   );
 }
 
 const styles = StyleSheet.create({
-  // Matches `inline_edit`'s view box exactly (height, radius, padding, 1px
-  // transparent border) so the value's baseline aligns with the editors — minus
-  // the FocusRingPressable, so it never reads as an interactive control.
-  box: {
-    minHeight: INLINE_CONTROL_HEIGHT,
-    borderRadius: CONTROL_RADIUS,
-    borderWidth: 1,
-    borderColor: "transparent",
-    paddingHorizontal: 8,
-    // The editors' vertical padding too, not just the horizontal. A single line
-    // hides its absence — the box is `minHeight` 40 and the text is ~20, so both
-    // sides land on 40 whether or not this exists — but an auto-growing input
-    // sizes itself to content PLUS its padding and border, so from the SECOND
-    // line on, a value without this sits ~14px shorter than the input that
-    // replaces it. Matching by coincidence at one line is not matching.
-    paddingVertical: 8,
-    justifyContent: "center",
-  },
   placeholder: { color: colors.zinc[400] },
 });

package/src/locale.tsx

@@ -94,27 +94,17 @@ export interface LoticsLocale {
   suggestionChip: { add: (label: string) => string; dismiss: string };
   /** `Confidence`: the full level phrase ("High confidence" …). */
   confidence: ConfidenceLabels;
-  /** `Finding`: the severity badge word ("Critical" …). */
   /** `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`: the severity words + the comparison delta caption. */
   finding: FindingLabels;
-  changeReview: {
-    title: string;
-    accept: string;
-    reject: string;
-    undo: string;
-    keptCount: (kept: number, total: number) => string;
-    acceptAll: string;
-    discard: string;
-    apply: string;
-    recommended: string;
-    customValue: string;
-    opAdd: string;
-    opEdit: string;
-    opRemove: string;
+  /** `DiffMark`: what a proposal does to a row — the accessible word each mark
+   *  announces, since the meaning may never rest on colour alone. */
+  diff: {
+    added: string;
+    changed: string;
+    removed: string;
+    unchanged: string;
   };
   /** `DateRangeFilterField` (and the `DateFilter` panel it wraps): presets,
    *  from/to, the footer Clear/Done, the trigger placeholder, and the time-field
@@ -273,20 +263,11 @@ export const en: LoticsLocale = {
     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",
-    keptCount: (kept, total) => `${kept} of ${total} kept`,
-    acceptAll: "Keep all",
-    discard: "Discard",
-    apply: "Apply",
-    recommended: "AI pick",
-    customValue: "Type another value",
-    opAdd: "Add",
-    opEdit: "Edit",
-    opRemove: "Delete",
+  diff: {
+    added: "Added",
+    changed: "Changed",
+    removed: "Removed",
+    unchanged: "Unchanged",
   },
   dateRange: {
     year: "Year", month: "Month", day: "Day", hour: "Hour", minute: "Minute", dayPeriod: "AM/PM",
@@ -437,20 +418,11 @@ export const vi: LoticsLocale = {
     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",
-    keptCount: (kept, total) => `Đã giữ ${kept}/${total}`,
-    acceptAll: "Giữ tất cả",
-    discard: "Bỏ hết",
-    apply: "Áp dụng",
-    recommended: "AI đề xuất",
-    customValue: "Nhập giá trị khác",
-    opAdd: "Thêm",
-    opEdit: "Sửa",
-    opRemove: "Xóa",
+  diff: {
+    added: "Thêm mới",
+    changed: "Thay đổi",
+    removed: "Xóa",
+    unchanged: "Giữ nguyên",
   },
   dateRange: {
     year: "Năm", month: "Tháng", day: "Ngày", hour: "Giờ", minute: "Phút", dayPeriod: "SA/CH",

package/src/result_header.tsx

@@ -5,7 +5,7 @@ import { Icon, type IconName } from "./icon";
 import { Text, type HeadingLevel } from "./text";
 
 /**
- * Result header — the strip that opens the POST-SAVE RECEIPT. `ChangeReview` gates a proposal
+ * Result header — the strip that opens the POST-SAVE RECEIPT. A review surface gates a proposal
  * BEFORE it applies; this header opens the receipt for what a save-direct run
  * ALREADY CREATED. The receipt states the outcome and routes — it never edits
  * (correction happens through the record's ordinary verbs, on the record):

package/src/use_change_set.ts

@@ -0,0 +1,115 @@
+import { useCallback, useMemo, useState } from "react";
+
+export type ChangeDecision = "pending" | "accepted" | "rejected";
+
+/**
+ * THE REVIEW BOOKKEEPING, WITHOUT A SURFACE.
+ *
+ * Keeping which proposals are in and which are out is genuinely fiddly — the
+ * counter, keep-all, undo, the commit gate — and genuinely the same every time.
+ * What is NOT the same every time is where any of it renders. So this is a hook:
+ * the host gets the state machine and draws whatever its screen needs, instead
+ * of adopting a container to get the arithmetic.
+ *
+ * Decisions are stored as OVERRIDES against a default, never seeded from `ids`
+ * into state. Seeding would need an effect to keep in step, and `ids` is
+ * typically a `useMemo` over query rows — a new array every render, so the
+ * effect fires every render and sets state every time. (That exact loop has bit
+ * this codebase before: `Maximum update depth exceeded` in a settle drawer that
+ * seeded "everything ticked" from its rows.) Storing the exceptions makes the
+ * selection derived: nothing to seed, nothing to re-sync, and ids that come and
+ * go simply pick up the default.
+ */
+export interface ChangeSet<Id extends string = string> {
+  status: (id: Id) => ChangeDecision;
+  accept: (id: Id) => void;
+  reject: (id: Id) => void;
+  /** Back to the default — the Undo on a decided row. */
+  undo: (id: Id) => void;
+  acceptAll: () => void;
+  rejectAll: () => void;
+  /** Every id back to the default. */
+  reset: () => void;
+  accepted: readonly Id[];
+  rejected: readonly Id[];
+  pending: readonly Id[];
+  keptCount: number;
+  total: number;
+  /** Nothing is left undecided — the usual gate on a commit button. */
+  settled: boolean;
+}
+
+export interface UseChangeSetOptions {
+  /**
+   * What an untouched proposal counts as. Default `accepted`: the operator
+   * drops the exceptions rather than approving each of eight identical lines,
+   * which is the difference between a review and a second round of data entry.
+   * Use `pending` when each change genuinely deserves its own verdict — and
+   * gate the commit on `settled`.
+   */
+  initial?: ChangeDecision;
+}
+
+export function useChangeSet<Id extends string = string>(
+  ids: readonly Id[],
+  options?: UseChangeSetOptions,
+): ChangeSet<Id> {
+  const initial = options?.initial ?? "accepted";
+  const [overrides, setOverrides] = useState<ReadonlyMap<Id, ChangeDecision>>(new Map());
+
+  const set = useCallback((id: Id, decision: ChangeDecision) => {
+    setOverrides((prev) => {
+      const next = new Map(prev);
+      next.set(id, decision);
+      return next;
+    });
+  }, []);
+
+  const undo = useCallback((id: Id) => {
+    setOverrides((prev) => {
+      if (!prev.has(id)) return prev;
+      const next = new Map(prev);
+      next.delete(id);
+      return next;
+    });
+  }, []);
+
+  const all = useCallback(
+    (decision: ChangeDecision) => setOverrides(new Map(ids.map((id) => [id, decision]))),
+    [ids],
+  );
+
+  const status = useCallback((id: Id) => overrides.get(id) ?? initial, [overrides, initial]);
+
+  const groups = useMemo(() => {
+    const accepted: Id[] = [];
+    const rejected: Id[] = [];
+    const pending: Id[] = [];
+    for (const id of ids) {
+      const s = overrides.get(id) ?? initial;
+      if (s === "accepted") accepted.push(id);
+      else if (s === "rejected") rejected.push(id);
+      else pending.push(id);
+    }
+    return { accepted, rejected, pending };
+  }, [ids, overrides, initial]);
+
+  return useMemo(
+    () => ({
+      status,
+      accept: (id: Id) => set(id, "accepted"),
+      reject: (id: Id) => set(id, "rejected"),
+      undo,
+      acceptAll: () => all("accepted"),
+      rejectAll: () => all("rejected"),
+      reset: () => setOverrides(new Map()),
+      accepted: groups.accepted,
+      rejected: groups.rejected,
+      pending: groups.pending,
+      keptCount: groups.accepted.length,
+      total: ids.length,
+      settled: groups.pending.length === 0,
+    }),
+    [status, set, undo, all, groups, ids.length],
+  );
+}