@lotics/ui 28.3.1 → 29.3.0

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],
+  );
+}