@startsimpli/ui 0.4.142 → 0.4.144

package/src/components/track-changes/types.ts

@@ -0,0 +1,451 @@
+/**
+ * @startsimpli/ui/track-changes — the shapes the track-changes editor surface
+ * reads and the one call it writes (bd startsim-sjuai; design startsim-xyn25).
+ *
+ * THE FIELD STAYS A PLAIN STRING. Suggestions and comments are separate server
+ * rows anchored to character offsets of that string at a known version, and
+ * blame is derived server-side from the revision chain. The editor renders all
+ * three as DECORATIONS over the stored string and never writes a mark into it.
+ *
+ * STRUCTURAL ON PURPOSE, like `history/types.ts`: packages/ui imports no API
+ * client. The consuming app injects its own authed client
+ * ({@link TrackChangesClient}). Both spellings of every key are declared
+ * because the shared API client camelCases responses recursively; the
+ * normalizers in `normalize.ts` read either.
+ *
+ * ── OFFSET UNITS ────────────────────────────────────────────────────────────
+ * The server is Python, so its string offsets count CODE POINTS. The editor is
+ * JavaScript, so its offsets count UTF-16 CODE UNITS. They differ by one for
+ * every character outside the Basic Multilingual Plane before the offset, and
+ * LinkedIn posts are full of emoji. `offset_unit` on a response says which unit
+ * it uses; absent means `code_point`. The normalizers convert at the boundary,
+ * so everything past them is UTF-16.
+ *
+ * ── STATUS OF THESE SHAPES ──────────────────────────────────────────────────
+ * All three follow the FINAL contracts: blame start-simpli-api #507
+ * (startsim-gulrr), suggestions and comments #508 (startsim-txfrl,
+ * startsim-a76zp). Every response declares `offset_unit: "utf16"` and the
+ * `version` its positions were mapped to; suggestions and comments carry a
+ * nested `author` and a `position {state, from, to, version}` (null when not
+ * placed); blame spans carry flat actor columns, and an unknown span carries
+ * `via: "unknown"`, a `reason` code and a `detail` sentence. Older spellings
+ * the normalizer still reads are kept only so a camelising client works.
+ */
+import type { ActorKind, ActorKindSource } from '../ActorIdentity';
+
+export type { ActorKind, ActorKindSource };
+
+/** Which unit a response's offsets count. */
+export type OffsetUnit = 'code_point' | 'utf16';
+
+/** The actor columns every annotation and blame span carries, both spellings. */
+export interface WireActor {
+  actor_sub?: string | null;
+  actorSub?: string | null;
+  actor_label?: string | null;
+  actorLabel?: string | null;
+  actor_kind?: ActorKind | string | null;
+  actorKind?: ActorKind | string | null;
+  actor_kind_source?: ActorKindSource | string | null;
+  actorKindSource?: ActorKindSource | string | null;
+}
+
+/** The nested actor object the suggestion and comment routes answer with
+ *  (start-simpli-api RED branch feat/tc-suggestions-comments): `author`,
+ *  `resolution.by`. */
+export interface WireAuthor {
+  sub?: string | null;
+  label?: string | null;
+  kind?: ActorKind | string | null;
+  kind_source?: ActorKindSource | string | null;
+  kindSource?: ActorKindSource | string | null;
+}
+
+/** Where the server mapped an anchor to on read: current-version offsets and
+ *  the mapping's outcome. `from`/`to` are `null` when orphaned. */
+export interface PositionWire {
+  from?: number | null;
+  to?: number | null;
+  state?: AnchorState | string | null;
+  /** The record version the position was mapped to. */
+  version?: number | null;
+}
+
+/** An actor after normalization. `label` may be `''` (a service token can carry
+ *  no email); `kind` is three-state and `unknown` is calm, not a defect. */
+export interface TrackActor {
+  sub: string;
+  label: string;
+  kind: ActorKind;
+  kindSource?: ActorKindSource;
+}
+
+/* -------------------------------------------------------------------------- */
+/*  BLAME  GET /api/v1/entities/<id>/blame/?field=<f>   (startsim-gulrr)      */
+/* -------------------------------------------------------------------------- */
+
+/** How a span's text got there. `restore` credits the restorer; an accepted
+ *  suggestion credits its AUTHOR, with `accepted_by` the acceptor; `unknown`
+ *  spans carry a `reason` and no actor at all. */
+export type BlameVia = 'edit' | 'accepted_suggestion' | 'restore' | 'unknown';
+
+/** Why nobody can be credited with a span. */
+export type BlameReason = 'before_history' | 'truncated' | 'values_omitted' | 'chain_break' | 'unrecorded_change';
+
+/**
+ * One span of GET /api/v1/entities/<id>/blame/?field=<f> (start-simpli-api
+ * #507, final contract in startsim-gulrr). Spans are contiguous, non-empty,
+ * in order and cover the whole text. Author columns are FLAT on a known span;
+ * an unknown span has none of them.
+ */
+export interface BlameSpanWire extends WireActor {
+  from: number;
+  to: number;
+  via?: BlameVia | string | null;
+  /** `null` on an unknown span that no revision touched. */
+  version?: number | null;
+  at?: string | null;
+  /** accepted_suggestion only: the ACCEPTOR, with actor_* keys. */
+  accepted_by?: WireActor | null;
+  acceptedBy?: WireActor | null;
+  suggestion_id?: string | null;
+  set_id?: string | null;
+  /** restore only. */
+  restored_from?: number | null;
+  restoredFrom?: number | null;
+  /** unknown only. */
+  reason?: BlameReason | string | null;
+  /** unknown only: a readable sentence. */
+  detail?: string | null;
+}
+
+export interface BlameResponseWire {
+  entity_id?: string;
+  field?: string;
+  /** The record's current version; the spans describe its text. */
+  version?: number | null;
+  /** Always "utf16" on this route. */
+  offset_unit?: OffsetUnit | null;
+  offsetUnit?: OffsetUnit | null;
+  /** UTF-16 length of the current text. */
+  length?: number | null;
+  /** False when the type's history is off: then `spans` is null and
+   *  `detail` says why. */
+  recorded?: boolean | null;
+  history?: { enabled?: boolean; declared_by?: string } | null;
+  trail_starts?: { version?: number; at?: string; from_creation?: boolean } | null;
+  spans?: BlameSpanWire[] | null;
+  detail?: string | null;
+}
+
+/* -------------------------------------------------------------------------- */
+/*  SUGGESTIONS  GET/POST /api/v1/entities/<id>/suggestions/  (startsim-txfrl) */
+/* -------------------------------------------------------------------------- */
+
+export type SuggestionStatus = 'open' | 'accepted' | 'rejected' | 'withdrawn' | 'superseded';
+
+/** Where an anchor landed after the server mapped it to the current version
+ *  (design section c). An orphaned anchor is NEVER painted at a guessed place. */
+export type AnchorState = 'mapped' | 'reanchored' | 'orphaned';
+
+export interface AnchorWire {
+  from: number;
+  to: number;
+  quote?: string | null;
+  prefix?: string | null;
+  suffix?: string | null;
+}
+
+export interface SuggestionWire extends WireActor {
+  id: string;
+  /** The author, as the RED contract nests it. Flat actor columns are read
+   *  as a fallback. */
+  author?: WireAuthor | null;
+  /** The anchor mapped to the CURRENT version, with its state. Preferred
+   *  over every other spelling below. */
+  position?: PositionWire | null;
+  set_id?: string | null;
+  setId?: string | null;
+  field?: string | null;
+  base_version?: number | null;
+  baseVersion?: number | null;
+  /** The anchor as PROPOSED, against `base_version`. */
+  anchor?: AnchorWire | null;
+  /** ASSUMED: the anchor mapped to the CURRENT version on read. Also read:
+   *  `current`, `mappedAnchor`. When absent, `anchor` is taken to already be
+   *  in current-version offsets. */
+  mapped_anchor?: AnchorWire | null;
+  mappedAnchor?: AnchorWire | null;
+  current?: AnchorWire | null;
+  replacement?: string | null;
+  /** The fold of the suggestion's events. Absent means `open`. */
+  status?: SuggestionStatus | string | null;
+  /** ASSUMED name. Also read: `anchorStatus`, `anchor_state`, `mapping`. */
+  anchor_status?: AnchorState | string | null;
+  anchorStatus?: AnchorState | string | null;
+  created_at?: string | null;
+  createdAt?: string | null;
+  /** How a closed suggestion was closed: who, when, and (accepted) the
+   *  revision it produced. Null while open. */
+  resolution?: ResolutionWire | null;
+}
+
+export interface ResolutionWire {
+  action?: string | null;
+  by?: WireAuthor | null;
+  at?: string | null;
+  reason?: string | null;
+  revision?: number | null;
+}
+
+export interface SuggestionPageWire {
+  version?: number | null;
+  next?: string | null;
+  next_cursor?: string | null;
+  nextCursor?: string | null;
+  results?: SuggestionWire[] | null;
+  offset_unit?: OffsetUnit | null;
+  offsetUnit?: OffsetUnit | null;
+}
+
+/** The suggesting-mode post (design section d): the WHOLE proposed text; the
+ *  server hunks it with the shared word diff and supersedes this author's own
+ *  still-open set. */
+export interface ProposeRequest {
+  field: string;
+  base_version: number;
+  proposed: string;
+}
+
+/* -------------------------------------------------------------------------- */
+/*  COMMENTS  GET /api/v1/entities/<id>/comments/?field=<f>  (startsim-a76zp) */
+/* -------------------------------------------------------------------------- */
+
+export interface CommentWire extends WireActor {
+  id: string;
+  thread_id?: string | null;
+  author?: WireAuthor | null;
+  edited_at?: string | null;
+  editedAt?: string | null;
+  /** Mentioned subs. Shown in-app only; nothing is emailed (Quinn). */
+  mentions?: string[] | null;
+  body?: string | null;
+  created_at?: string | null;
+  createdAt?: string | null;
+  /** Tombstoned: the fact of the comment stays, the body is gone. */
+  deleted?: boolean | null;
+}
+
+export interface CommentThreadWire extends WireActor {
+  /** Also read: `id`. */
+  thread_id?: string | null;
+  threadId?: string | null;
+  id?: string | null;
+  field?: string | null;
+  anchor?: AnchorWire | null;
+  mapped_anchor?: AnchorWire | null;
+  mappedAnchor?: AnchorWire | null;
+  current?: AnchorWire | null;
+  anchor_status?: AnchorState | string | null;
+  anchorStatus?: AnchorState | string | null;
+  position?: PositionWire | null;
+  author?: WireAuthor | null;
+  /** `open` | `resolved`. `resolved: true` also read. */
+  status?: string | null;
+  resolution?: ResolutionWire | null;
+  base_version?: number | null;
+  created_at?: string | null;
+  resolved?: boolean | null;
+  comments?: CommentWire[] | null;
+  /** The body withheld by the per-field read gate. */
+  redacted?: boolean | null;
+}
+
+export interface CommentPageWire {
+  version?: number | null;
+  next?: string | null;
+  next_cursor?: string | null;
+  nextCursor?: string | null;
+  results?: CommentThreadWire[] | null;
+  offset_unit?: OffsetUnit | null;
+  offsetUnit?: OffsetUnit | null;
+}
+
+/* -------------------------------------------------------------------------- */
+/*  THE INJECTED CLIENT                                                       */
+/* -------------------------------------------------------------------------- */
+
+/**
+ * What the editor surface needs from the server, and nothing it does not.
+ * The consuming app binds the record id:
+ *
+ * ```ts
+ * const client: TrackChangesClient = {
+ *   blame: (q) => api.entities.blame(id, q),
+ *   listSuggestions: (q) => api.entities.suggestions(id, q),
+ *   listComments: (q) => api.entities.comments(id, q),
+ *   propose: (body) => api.entities.propose(id, body),
+ * };
+ * ```
+ *
+ * Every read is optional so a host can mount the editor before a route ships.
+ * Accept, reject, reply and resolve are the rail's (startsim-whwxd.3), which
+ * extends this interface rather than declaring a second one.
+ *
+ * A 404 from any read means the caller may not read the record or the field.
+ * The editor says so; it never treats it as "no annotations".
+ */
+export interface TrackChangesClient {
+  blame?: (query: { field: string }) => Promise<BlameResponseWire>;
+  /** Keyset-paginated: the hook passes `cursor` (the previous page's
+   *  `next_cursor`) until there is none, because a proposal supersedes ALL of
+   *  the author's open suggestions and the editor must know every one. */
+  listSuggestions?: (query: { field: string; cursor?: string }) => Promise<SuggestionPageWire | SuggestionWire[]>;
+  /** `status: 'all'` is what the rail asks for, so resolved threads stay
+   *  readable (and reopenable) in its resolved list. */
+  listComments?: (query: { field: string; cursor?: string; status?: 'open' | 'resolved' | 'all' }) => Promise<CommentPageWire | CommentThreadWire[]>;
+  propose?: (body: ProposeRequest) => Promise<unknown>;
+
+  /* ---- the rail's writes (startsim-whwxd.3). Each is optional, like the reads:
+   * a host that has not bound one simply does not get that control. ---- */
+
+  /** POST suggestions/accept/ {ids, expected_version}. One revision per
+   *  suggestion, document order, all or nothing. Resolves the RECORD (the
+   *  record serializer's body) plus `accepted`; the host must adopt its
+   *  `version`, or its own next save 412s against this accept. */
+  accept?: (req: AcceptRequest) => Promise<AcceptResponseWire>;
+  /** POST suggestions/reject/ {ids, reason?}. The record does not move. */
+  reject?: (req: { ids: string[]; reason?: string }) => Promise<unknown>;
+  /** POST suggestions/<id>/withdraw/. Author only. */
+  withdraw?: (id: string) => Promise<unknown>;
+  /** POST comments/ — a span, field or record comment. */
+  comment?: (req: CommentRequest) => Promise<CommentThreadWire>;
+  /** POST comments/<thread_id>/replies/. */
+  reply?: (threadId: string, req: { body: string; mentions?: string[] }) => Promise<CommentWire>;
+  /** POST comments/<thread_id>/resolve/ */
+  resolveThread?: (threadId: string) => Promise<unknown>;
+  /** POST comments/<thread_id>/reopen/ */
+  reopenThread?: (threadId: string) => Promise<unknown>;
+  /** GET /api/v1/org/roster/ — the colleagues a comment may @mention. In-app
+   *  only: the server sends nothing to anyone mentioned (Quinn, 2026-10-07). */
+  roster?: (query: { cursor?: string }) => Promise<RosterPageWire>;
+}
+
+export interface AcceptRequest {
+  ids: string[];
+  /** The version the reviewer is looking at. REQUIRED by the route (428
+   *  without it, 412 when stale). */
+  expectedVersion: number;
+}
+
+/** The accept answer: the record body, plus what was accepted. */
+export interface AcceptResponseWire {
+  id?: string | number;
+  version?: number | null;
+  data?: Record<string, unknown>;
+  accepted?: { suggestions?: string[]; revisions?: number[] } | null;
+  [key: string]: unknown;
+}
+
+export interface CommentRequest {
+  body: string;
+  /** Omitted: a whole-record comment. */
+  field?: string;
+  /** A span comment: both offsets, UTF-16 at `base_version`. */
+  from?: number;
+  to?: number;
+  base_version?: number;
+  mentions?: string[];
+}
+
+export interface RosterEntryWire {
+  sub?: string | null;
+  label?: string | null;
+}
+
+export interface RosterPageWire {
+  next?: string | null;
+  next_cursor?: string | null;
+  nextCursor?: string | null;
+  results?: RosterEntryWire[] | null;
+}
+
+/** A colleague who can be @mentioned. */
+export interface RosterMember {
+  sub: string;
+  label: string;
+}
+
+/* -------------------------------------------------------------------------- */
+/*  NORMALIZED SHAPES (UTF-16 offsets into the stored string)                 */
+/* -------------------------------------------------------------------------- */
+
+export interface BlameSpan {
+  /** Stable within one response: `blame:<from>`. */
+  id: string;
+  from: number;
+  to: number;
+  /** `null` for an unknown span. */
+  author: TrackActor | null;
+  /** Set when nobody can be credited: the sentence a reader is shown. */
+  unknownReason: string | null;
+  /** The machine-readable reason code of an unknown span. */
+  reason: BlameReason | null;
+  version: number | null;
+  at: string | null;
+  via: BlameVia | null;
+  acceptedBy: TrackActor | null;
+  restoredFrom: number | null;
+}
+
+export interface Suggestion {
+  id: string;
+  setId: string | null;
+  from: number;
+  to: number;
+  /** The text the suggestion replaces (empty for a pure insert). */
+  quote: string;
+  /** The text it proposes (empty for a pure delete). */
+  replacement: string;
+  status: SuggestionStatus;
+  anchorState: AnchorState;
+  author: TrackActor;
+  createdAt: string | null;
+}
+
+export interface TrackComment {
+  id: string;
+  body: string | null;
+  deleted: boolean;
+  author: TrackActor;
+  createdAt: string | null;
+  /** Mentioned subs; shown in-app only. */
+  mentions: string[];
+  editedAt: string | null;
+}
+
+export interface CommentThread {
+  id: string;
+  /** The field the thread is on; `null` for a whole-record comment. */
+  field: string | null;
+  /** Who resolved or reopened it last, and when. */
+  resolution: { action: string; by: TrackActor; at: string | null } | null;
+  /** `null` for a whole-record or whole-field comment. */
+  from: number | null;
+  to: number | null;
+  quote: string;
+  anchorState: AnchorState;
+  resolved: boolean;
+  redacted: boolean;
+  comments: TrackComment[];
+}
+
+/** What a selection becomes when a host anchors a comment to it. UTF-16
+ *  offsets; convert with `toServerOffsets` before posting. */
+export interface SelectionAnchor {
+  from: number;
+  to: number;
+  quote: string;
+  prefix: string;
+  suffix: string;
+}