Story-2355: EditableList — the list kind, and Key Instruments as its first consumer

The Brief's Key instruments rail was a wall: Vega listed the documents it found, and counsel could do nothing about it. If the framer missed the supplemental agreement, the missing instrument stayed missing. Worse — a matter with no instruments rendered nothing at all (the block was wrapped in instruments.length > 0 ? … : null), so the first real matter of a new firm showed a rail with a hole in it and no way to fill it.

This Story builds the list kind of the Editable Surface family (EditableList, frozen vocabulary §3) and makes Key instruments its first live consumer: add, edit in place, remove — instantly, with rollback.

The idea in one line

The row IS the value. Each item is an EditableSurface (plain, single-line) — so clicking an instrument drops the caret in it, blur commits it, and clearing its text removes it, because an empty row is no row. Add, edit, and remove all hand the caller the whole next array through one onSave.

The gate that had to pass first

The ticket made the data contract a hard gate: if the functions write path did not accept key_instruments, this Story stops and files the gap. It does accept it.

Two consequences fall straight out of the contract:

• Items persist as plain strings. No contentFormat declaration travels with the write — that map is limited to the four free-prose fields, and sending key_instruments in it is rejected server-side.
• Every action is a full-array commit. There is no per-item endpoint, and the primitive is shaped around that truth instead of pretending otherwise.

The primitive

<EditableList
  items={string[]}                    // the committed items (caller-owned, optimistic)
  onSave={(next: string[]) => void}   // add | edit | remove — ALWAYS the whole next array
  ariaLabel="Key instruments"          // required: editable regions announce themselves
  addLabel={t("addInstrument")}        // the CALLER resolves the i18n key — never a literal inside
  placeholder={t("instrumentPlaceholder")}
  readOnly={false}                     // permission gate: no add, no remove, rows read-only
  itemProvenance={(item, i) => …}     // per-item seam → the shared EditableSurfaceMarker
  itemIcon={<FileText …/>}
/>

Why the add row needed one new prop on EditableSurface

"Click Add, then click again to actually type" is not an affordance, it is a chore. The draft row must land the caret on mount — so EditableSurface gained a single autoFocus prop, forwarded to TipTap's own autofocus option. It is documented as belonging to a surface that only exists because counsel asked to write — never to a surface that is merely displaying a value, which would steal focus on page load.

Optimism: the row lands before the network does

AGENTS.md is blunt about this: a write that waits for the round-trip reads as lag. The Brief's frame edit lives in the TanStack cache (useAppGetMatterBrief), so it takes mechanism 1 — onMutate patches the cached Brief, onError restores the snapshot and toasts, onSettled invalidates to reconcile with server truth.

const edit = useAppEditMatterFrame<{ previous?: MatterBriefView }>({
  mutation: {
    onMutate: async (variables) => {
      await qc.cancelQueries({ queryKey: key });
      const previous = qc.getQueryData<MatterBriefView>(key);
      qc.setQueryData(key, { ...previous, frame: { ...previous.frame,
        frame: { ...previous.frame.frame, ...variables.data.fields },
        contentFormat: { ...previous.frame.contentFormat, ...(variables.data.contentFormat ?? {}) },
      }});
      return { previous };                       // ← the rollback path
    },
    onError: (_e, _v, context) => { qc.setQueryData(key, context.previous); toast.error(t("saveFailed")); },
    onSettled: () => qc.invalidateQueries({ queryKey: key }),
  },
});

Note where this went: on the shared edit mutation, not on a second list-only copy of it. Every frame field routes through that one mutation, so one onMutate makes them all instant — the root-cause fix, and a smaller diff than a bespoke optimistic path per caller. (The prose blocks' components are untouched; they simply inherit the instantness they were already owed. Their contentFormat declaration is carried into the optimistic patch too, so a Markdown field never flashes as literal asterisks in the optimistic window.)

The empty state is the point

Provenance and permission, inherited not reinvented

• Each row's provenance goes through the same EditableSurfaceMarker the rest of the family uses: proposed shows the dotted tag, the passive states are announced to screen readers only.
• A canonical or locked item is not editable (EditableSurface's own rule) and carries no ✕ — you cannot delete your way around a lock.
• readOnly removes the add affordance and every ✕, and leaves the rows plain.

What was verified, and how

Files