web/src/customer-grid/SwipeView.tsx

// ---------------------------------------------------------------------------
// customer-grid / SwipeView.tsx
// ⭐ WAVE-27 item 8 (owner ruling R2, contract C3) — the SWIPE deck.
//
// One record at a time, decided left or right into two options of ONE
// single-select. R2 fixes the shape and it is narrow on purpose:
//   · SINGLE-SELECT ONLY, one field, two of its options. No checkbox binding.
//   · the deck holds only the records whose bound field is EMPTY — a record
//     that already has a value has been decided, and re-asking is not triage.
//   · a swipe writes through the NORMAL cell door (`onSwipe`, which the host
//     maps to the same `patchAndRecord` a kanban card move uses), so undo,
//     echo-suppression and the permission wall all hold without being
//     re-implemented here.
//
// Honesty rules carried from the other modes:
//   · nothing is silently hidden — the deck states what is left, and the
//     empty state names the bound field rather than saying "all done".
//   · a lost binding is SHOWN, never repaired by guessing. `_clean_display`
//     validates that `fieldKey` names a field the table HAS and stops there;
//     it cannot know the field is still a select, or that the two options are
//     still in its vocabulary (its docstring draws that line explicitly). So
//     those three losses land here, and each one says what happened and
//     re-opens the picker — the `viewModes.tsx:190-194` rule, which exists
//     because the wave-7 trap was a picker silently falling back to its first
//     option.
// ---------------------------------------------------------------------------

import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import { choiceOptions } from "./types";
import type { CustomerDoc, DisplaySpec, Field, Row, Viewer } from "./types";
// ⚠ `SurfaceScope` is `apiBridge`'s (a TYPE-only import, so nothing of that module is
//   loaded here) — the same import `RecordComments` takes for the same prop.
import type { SurfaceScope } from "./apiBridge";
import RecordComments from "./RecordComments";
import { Documents } from "./Documents";
import { formatDisplay } from "./cells";
import { actionHref } from "./display";
import { optionTint } from "./choiceColors";
import { ModeIcon } from "./icons";
// ⭐ W29-T73 — the line its three siblings all have, and the one this file shipped without.
// `SwipeView.css` had ZERO references anywhere in `src/`, so T26's two new sections rendered
// unstyled while `.cg-swipe-card` (which lives in `index.css`) kept the card looking right —
// a partially-styled surface reads as a design choice, which is why nobody reported it and no
// gate could see it: a side-effect import references no symbol ([[artifact-with-no-importer]]).
import "./SwipeView.css";

export type SwipeSpec = NonNullable<DisplaySpec["swipe"]>;

/** The three ways a stored binding can rot that the host cannot see (see the header note). */
type BindingFault =
  | { kind: "unbound" }
  | { kind: "field-gone"; fieldKey: string }
  | { kind: "not-select"; field: Field }
  | { kind: "option-gone"; field: Field; missing: string[] };

function readBinding(spec: SwipeSpec | undefined, fieldByKey: Map<string, Field>):
  { ok: true; field: Field; spec: SwipeSpec } | { ok: false; fault: BindingFault } {
  if (!spec) return { ok: false, fault: { kind: "unbound" } };
  const field = fieldByKey.get(spec.fieldKey);
  if (!field) return { ok: false, fault: { kind: "field-gone", fieldKey: spec.fieldKey } };
  // R2 — SINGLE-select only. `multiselect` is deliberately not accepted: its cell holds a SET,
  // so "write this option" would mean append-or-replace, and a triage gesture that sometimes
  // adds and sometimes overwrites is two gestures wearing one button.
  if (field.type !== "select") return { ok: false, fault: { kind: "not-select", field } };
  const options = choiceOptions(field);
  const has = new Set(options.map((o) => o.toLowerCase()));
  const missing = [spec.leftOption, spec.rightOption].filter((o) => !has.has(o.toLowerCase()));
  if (missing.length) return { ok: false, fault: { kind: "option-gone", field, missing } };
  return { ok: true, field, spec };
}

/** The bound cell is EMPTY — the one predicate that decides deck membership (R2). */
const isUndecided = (row: Row, key: string): boolean =>
  String(row[key] ?? "").trim() === "";

export function SwipeView({

  rows,

  fields,

  fieldByKey,

  spec,

  cardKeys,

  detailKeys,

  scope,

  viewer,

  docs,

  docPayload,

  onDocAdd,

  onDocFetch,

  onDocDelete,

  titleKey,

  canWrite,

  readOnlyReason,

  canBind,

  onSpec,

  onSwipe,

  onOpen,

}: {

  /** DISTINCT data rows from the full pipeline, overlay edits layered — the kanban's contract.

   *  The deck re-derives from these, so a written record leaves it as soon as the optimistic

   *  patch lands; there is no local cursor to drift out of step with the data. */

  rows: Row[];

  /** Every field, for the picker's field list. */

  fields: Field[];

  fieldByKey: Map<string, Field>;

  /** The stored binding, or undefined for a deck nobody has configured yet. */

  spec: SwipeSpec | undefined;

  /** The handful of visible fields the card lists under its title. */

  cardKeys: string[];

  titleKey: string;

  /** May this viewer write the BOUND field's value? (the kanban's `canMove`) */

  canWrite: boolean;

  /** Stated when the deck cannot be decided — permissions, or a computed column. */

  readOnlyReason: string | null;

  /** May this viewer change what the deck is bound TO? A VIEW-config act, so it is the

   *  view-editing permission and NOT `canWrite` — conflating the two is

   *  [[schema-role-is-not-a-value-wall]]. REQUIRED, because a picker that silently does

   *  nothing is worse than no picker ([[wrong-parent-not-broken-control]]). */

  canBind: boolean;

  /** `undefined` DELETES the binding — absent is the honest unconfigured state, and storing a

   *  half-binding is what `cleanDisplay` drops on both engines (the `kanbanClamp` law). */

  onSpec: (next: SwipeSpec | undefined) => void;

  onSwipe: (pid: number, value: string) => void;

  onOpen: (pid: number) => void;

  /**

   * ⭐⭐ WAVE-29 T26 (owner R9) — WHAT MAKES THE CARD A RECORD RATHER THAN A SUMMARY.

   *

   * R9: *"the swipe CARD itself renders the record detail inline — fields, comments and

   * attachments — so a reviewer decides without leaving the deck."* Everything below is that,

   * and every one of them is OPTIONAL for one reason: this deck runs on hosts that supply

   * different amounts. A card must render with none of them rather than throw — the standalone

   * embed has no `scope`, and a deployment with no document storage serves no handlers.

   */

  /** Every field the VIEW shows, in its order — not the three-key card summary. */

  detailKeys?: string[];

  /** The surface these records live on. Comments are keyed by it; absent ⇒ no comments section,

   *  which is the pre-existing precondition `RecordDetail` already carries. */

  scope?: SurfaceScope;

  viewer?: Viewer;

  /** This record's attachments, and the plumbing. Handlers absent ⇒ the section is not rendered

   *  at all, exactly as `RecordDetail` decides it (a dead upload control is a promise the app

   *  cannot keep). */

  /** Keyed by pid, because a deck shows many records — `RecordDetail` takes ONE record's list

   *  and that shape cannot serve a deck. */

  docs?: Record<string, CustomerDoc[]>;

  docPayload?: { pid: number; docId: string; name: string; mime: string; data_b64: string };

  /** ⚠ EVERY HANDLER TAKES THE PID, unlike `RecordDetail`'s, whose host closes over the ONE

   *  open record. A deck paints many records at once, so a handler bound to a single pid would

   *  attach every reviewer's upload to whichever card happened to be open. */

  onDocAdd?: (

    pid: number,

    file: { name: string; mime: string; size: number; data_b64: string }

  ) => void;

  onDocFetch?: (pid: number, docId: string) => void;

  onDocDelete?: (pid: number, docId: string) => void;

}) {
  // "Later" — session-only, never stored. A deck with no way past a record you cannot decide
  // blocks on that record forever, so this is navigation WITHIN the deck rather than a third
  // gesture: it writes nothing, survives no reload, and the count is disclosed in the empty
  // state rather than quietly shrinking the deck (rule 8b).
  const [later, setLater] = useState<Set<number>>(new Set());
  const deckRef = useRef<HTMLDivElement>(null);

  const binding = useMemo(() => readBinding(spec, fieldByKey), [spec, fieldByKey]);
  const boundKey = binding.ok ? binding.field.key : null;

  const undecided = useMemo(
    () => (boundKey ? rows.filter((r) => isUndecided(r, boundKey)) : []),
    [rows, boundKey]
  );
  const deck = useMemo(() => undecided.filter((r) => !later.has(r.pid)), [undecided, later]);
  const card = deck[0];

  // A record decided elsewhere (the grid, another user's echo) must not stay "later" forever —
  // otherwise the disclosed skip count drifts away from what is actually on the deck.
  useEffect(() => {
    setLater((prev) => {
      if (prev.size === 0) return prev;
      const live = new Set(undecided.map((r) => r.pid));
      const next = new Set([...prev].filter((pid) => live.has(pid)));
      return next.size === prev.size ? prev : next;
    });
  }, [undecided]);

  const decide = useCallback(
    (value: string) => {
      if (!card || !canWrite) return;
      onSwipe(card.pid, value);
    },
    [card, canWrite, onSwipe]
  );

  // ← / → decide, and they are the SAME two actions the buttons are rather than a second code
  // path: the whole point of the mode is that one hand can clear a queue.
  useEffect(() => {
    if (!binding.ok || !canWrite || !card) return;
    const onKey = (e: KeyboardEvent) => {
      if (e.key !== "ArrowLeft" && e.key !== "ArrowRight") return;
      const el = document.activeElement as HTMLElement | null;
      // Never steal an arrow key from a text field or a native control the user is inside.
      if (el && (el.tagName === "INPUT" || el.tagName === "SELECT" || el.tagName === "TEXTAREA"))
        return;
      if (!deckRef.current?.contains(el ?? null) && el !== document.body) return;
      e.preventDefault();
      decide(e.key === "ArrowLeft" ? binding.spec.leftOption : binding.spec.rightOption);
    };
    window.addEventListener("keydown", onKey);
    return () => window.removeEventListener("keydown", onKey);
  }, [binding, canWrite, card, decide]);

  if (!binding.ok) {
    return (
      <div className="cg-swipe" ref={deckRef}>

        <SwipeBinder

          fault={binding.fault}

          fields={fields}

          fieldByKey={fieldByKey}

          spec={spec}

          canBind={canBind}

          onSpec={onSpec}

        />

      </div>
    );
  }

  const { field } = binding;
  const leftTint = optionTint(field, binding.spec.leftOption);
  const rightTint = optionTint(field, binding.spec.rightOption);

  return (
    <div className="cg-swipe" ref={deckRef} tabIndex={-1}>

      <div className="cg-swipe-bar">

        <span className="cg-swipe-bound">

          <ModeIcon mode="swipe" />

          Sorting into <strong>{field.label}</strong>

        </span>

        <span className="cg-swipe-left">

          {deck.length.toLocaleString()} {deck.length === 1 ? "record" : "records"} to sort

        </span>

        {canBind && (

          <button

            type="button"

            className="cg-link-btn"

            onClick={() => onSpec(undefined)}

            title="Choose a different field or different options for this deck"

          >

            Change

          </button>

        )}

      </div>

      {readOnlyReason && <div className="cg-kb-note">{readOnlyReason}</div>}

      {card ? (

        <div className="cg-swipe-deck">

          <button

            type="button"

            className="cg-swipe-side cg-swipe-side--left"

            disabled={!canWrite}

            style={leftTint ? { background: leftTint.bg, color: leftTint.fg } : undefined}

            onClick={() => decide(binding.spec.leftOption)}

            title={`Set ${field.label} to ${binding.spec.leftOption} (left arrow key)`}

          >

            <span aria-hidden className="cg-swipe-arrow">

              <svg width="16" height="16" viewBox="0 0 16 16">

                <path

                  d="M11 3.2 6.2 8l4.8 4.8"

                  fill="none"

                  stroke="currentColor"

                  strokeWidth="1.6"

                  strokeLinecap="round"

                  strokeLinejoin="round"

                />

              </svg>

            </span>

            {binding.spec.leftOption}

          </button>

          <article

            className="cg-swipe-card"

            role="button"

            tabIndex={0}

            onClick={() => onOpen(card.pid)}

            onKeyDown={(e) => {

              if (e.key !== "Enter" && e.key !== " ") return;

              e.preventDefault();

              onOpen(card.pid);

            }}

          >

            <h3 className="cg-swipe-title">{String(card[titleKey] ?? "")}</h3>

            <div className="cg-swipe-cells">

              {/* ⭐ WAVE-29 T26 (R9) — the RECORD's visible fields, not the three-key summary the

                  kanban card lends. `detailKeys` falls back to `cardKeys` so a host that has not

                  been widened yet renders exactly what it rendered before. */}

              {(detailKeys && detailKeys.length ? detailKeys : cardKeys).map((k) => {

                const f = fieldByKey.get(k);

                if (!f) return null;

                const text = formatDisplay(f, card[k]);

                if (!text) return null;

                // A url cell is a LINK here too (wave-26 item 11), through `display.ts`'s one

                // scheme guard — and every gesture that reaches it must be stopped from also

                // reaching the card, which is a button (the kanban card's note, same trap).

                const href = actionHref(f, card[k]);

                return (

                  <div key={k} className="cg-swipe-cell">

                    <span className="cg-lv-k">{f.label}</span>

                    {href ? (

                      <a

                        className="cg-lv-v"

                        href={href}

                        target="_blank"

                        rel="noopener noreferrer"

                        title={text}

                        onClick={(e) => e.stopPropagation()}

                        onKeyDown={(e) => e.stopPropagation()}

                      >

                        {text}

                      </a>

                    ) : (

                      <span className="cg-lv-v">{text}</span>

                    )}

                  </div>

                );

              })}

            </div>

            {/* ⭐ R9's other two thirds. Both stop their own events: the card is a `role="button"`

                that opens the record, and a click on a comment box or an upload control must not

                also open the modal it exists to make unnecessary (the kanban card's link trap,

                one surface over). */}

            {onDocAdd && onDocFetch && onDocDelete && (

              <div

                className="cg-swipe-docs"

                onClick={(e) => e.stopPropagation()}

                onKeyDown={(e) => e.stopPropagation()}

                role="presentation"

              >

                <Documents

                  pid={Number(card.pid)}

                  docs={docs?.[String(card.pid)] ?? []}

                  docPayload={docPayload}

                  onAdd={(file) => onDocAdd(card.pid, file)}

                  onFetch={(docId) => onDocFetch(card.pid, docId)}

                  onDelete={(docId) => onDocDelete(card.pid, docId)}

                />

              </div>

            )}

            {scope != null && (

              <div

                className="cg-swipe-comments"

                onClick={(e) => e.stopPropagation()}

                onKeyDown={(e) => e.stopPropagation()}

                role="presentation"

              >

                {/* ⚠ KEYED ON scope+pid, the same key `RecordDetail` uses: without it React

                    reuses the mounted instance across a card change and paints one record's

                    comments under another's name until the fetch returns. */}

                <RecordComments

                  key={`${scope}:${Number(card.pid)}`}

                  scope={scope}

                  pid={Number(card.pid)}

                  viewer={viewer}

                />

              </div>

            )}

            {canWrite && (

              <button

                type="button"

                className="cg-link-btn cg-swipe-later"

                onClick={(e) => {

                  e.stopPropagation();

                  setLater((prev) => new Set(prev).add(card.pid));

                }}

              >

                Decide later

              </button>

            )}

          </article>

          <button

            type="button"

            className="cg-swipe-side cg-swipe-side--right"

            disabled={!canWrite}

            style={rightTint ? { background: rightTint.bg, color: rightTint.fg } : undefined}

            onClick={() => decide(binding.spec.rightOption)}

            title={`Set ${field.label} to ${binding.spec.rightOption} (right arrow key)`}

          >

            {binding.spec.rightOption}

            <span aria-hidden className="cg-swipe-arrow">

              <svg width="16" height="16" viewBox="0 0 16 16">

                <path

                  d="M5 3.2 9.8 8 5 12.8"

                  fill="none"

                  stroke="currentColor"

                  strokeWidth="1.6"

                  strokeLinecap="round"

                  strokeLinejoin="round"

                />

              </svg>

            </span>

          </button>

        </div>

      ) : (

        // The empty state NAMES the bound field (C3), because "nothing to sort" is ambiguous

        // between "the deck is finished" and "the filter hid everything", and the two want

        // different next actions. `later` is disclosed rather than quietly subtracted.

        <div className="cg-mode-empty cg-swipe-empty">

          {later.size > 0 ? (

            <>

              <p>

                {later.size.toLocaleString()}{" "}

                {later.size === 1 ? "record is" : "records are"} set aside for later. Nothing else

                in this view is missing a <strong>{field.label}</strong>.

              </p>

              <button type="button" className="cg-btn" onClick={() => setLater(new Set())}>

                Bring them back

              </button>

            </>

          ) : (

            <p>

              Every record in this view already has a <strong>{field.label}</strong>. Widen the

              view's filters to sort more.

            </p>

          )}

        </div>
      )}
    </div>
  );
}

/**

 * The binding picker: field + two options. It is also the surface every LOST binding lands on,

 * with the loss stated above it — one place that answers "what is this deck for", rather than an

 * error screen beside a separate setup screen.

 */
function SwipeBinder({

  fault,

  fields,

  fieldByKey,

  spec,

  canBind,

  onSpec,

}: {

  fault: BindingFault;

  fields: Field[];

  fieldByKey: Map<string, Field>;

  spec: SwipeSpec | undefined;

  canBind: boolean;

  onSpec: (next: SwipeSpec | undefined) => void;

}) {
  const selects = useMemo(
    () => fields.filter((f) => f.type === "select" && choiceOptions(f).length >= 2),
    [fields]
  );
  const [fieldKey, setFieldKey] = useState<string>(() => {
    if (spec && fieldByKey.get(spec.fieldKey)?.type === "select") return spec.fieldKey;
    return selects[0]?.key ?? "";
  });
  const chosen = fieldByKey.get(fieldKey);
  const options = useMemo(() => (chosen ? choiceOptions(chosen) : []), [chosen]);
  const [left, setLeft] = useState<string>("");
  const [right, setRight] = useState<string>("");

  // The two option selects follow the FIELD. Kept in an effect rather than derived so the user's
  // pick survives re-renders, and reset whenever the field changes — carrying an option from the
  // previous field would offer a value the new field cannot hold.
  useEffect(() => {
    setLeft(options[0] ?? "");
    setRight(options.find((o) => o !== options[0]) ?? "");
  }, [options]);

  const message = ((): string => {
    switch (fault.kind) {
      case "field-gone":
        return "The field this deck sorted into has been deleted. Pick another one.";
      case "not-select":
        return `“${fault.field.label}” is no longer a single-select, so it has no options to`
          + " sort into. Pick another field.";
      case "option-gone":
        return `${fault.missing.map((m) => `“${m}”`).join(" and ")} ${

          fault.missing.length === 1 ? "is" : "are"

        } no longer ${fault.missing.length === 1 ? "an option" : "options"} on “${

          fault.field.label

        }”. Pick the sides again.`;
      default:
        return "Sort records one at a time into two options of a single-select field.";
    }
  })();

  if (!canBind) {
    return (
      <div className="cg-mode-empty">

        <p>{message}</p>

        <p>Its creator or an admin can set this view up.</p>

      </div>
    );
  }
  if (selects.length === 0) {
    // Honest and specific: the mode is not broken, the TABLE has nothing to bind to. Naming the
    // requirement is what turns a dead end into a next action.
    return (
      <div className="cg-mode-empty">

        <p>

          A swipe deck sorts into a single-select field with at least two options. This database

          does not have one yet — add a single-select column, then come back.

        </p>

      </div>
    );
  }
  const ready = !!chosen && !!left && !!right && left.toLowerCase() !== right.toLowerCase();
  return (
    <div className="cg-swipe-setup">

      <p className="cg-swipe-setup-note">{message}</p>

      <label className="cg-swipe-setup-row">

        <span>Sort into</span>

        <select

          className="cg-select"

          value={fieldKey}

          onChange={(e) => setFieldKey(e.target.value)}

        >

          {/* Every option carries an explicit `value`: a <select> whose value names nothing

              renders its FIRST option and reports a choice the user never made

              ([[cg-condition-builder-items]]). */}

          {selects.map((f) => (

            <option key={f.key} value={f.key}>

              {f.label}

            </option>

          ))}

        </select>

      </label>

      <div className="cg-swipe-setup-sides">

        <label className="cg-swipe-setup-row">

          <span>Swipe left</span>

          <select className="cg-select" value={left} onChange={(e) => setLeft(e.target.value)}>

            {options.map((o) => (

              <option key={o} value={o}>

                {o}

              </option>

            ))}

          </select>

        </label>

        <label className="cg-swipe-setup-row">

          <span>Swipe right</span>

          <select className="cg-select" value={right} onChange={(e) => setRight(e.target.value)}>

            {options.map((o) => (

              <option key={o} value={o}>

                {o}

              </option>

            ))}

          </select>

        </label>

      </div>

      {!ready && left && right && (

        // Stated, not silently refused: both engines DROP a binding whose sides are the same

        // option, so a Save that looked like it worked would simply not persist.

        <p className="cg-swipe-setup-warn">

          The two sides must be different options — otherwise both gestures do the same thing.

        </p>

      )}

      <button

        type="button"

        className="cg-btn cg-btn--primary"

        disabled={!ready}

        onClick={() =>

          chosen && onSpec({ fieldKey: chosen.key, leftOption: left, rightOption: right })

        }

      >

        Start sorting

      </button>

    </div>

  );

}



export default SwipeView;