@startsimpli/ui 0.4.135 → 0.4.136

package/src/components/history/types.ts

@@ -0,0 +1,167 @@
+/**
+ * @startsimpli/ui/history — the shapes the shared record history panel renders
+ * (bd startsim-g4rwo; trail bd startsim-o1qib).
+ *
+ * Structural on purpose, exactly like `activity/types.ts`: packages/ui imports
+ * no API client, so these mirror one `/api/v1/entities/<id>/revisions/` row
+ * without depending on @startsimpli/api. The consuming app injects its own
+ * authed client (see {@link RevisionClient}).
+ *
+ * ── THE SPELLING TRAP, AND WHY EVERY KEY HERE IS OPTIONAL TWICE ─────────────
+ *
+ * The wire is snake_case. The shared API client
+ * (`packages/api/src/utils/case-transform.ts`) camelCases every response key
+ * RECURSIVELY and has no preserve list, so an app that fetches this route
+ * through `FetchWrapper` receives `actorKind`, `createdAt`, `redactedFields`
+ * and `valuesOmitted`. Both spellings are therefore declared and
+ * {@link normalizeRevision} reads either, because a panel that renders blank
+ * actors against a camelising client — and correctly against a raw one — is a
+ * bug nobody would find twice.
+ *
+ * WHAT THAT TRANSFORM BREAKS AND THIS MODULE CANNOT FIX: the keys INSIDE
+ * `metadata.changed` are the tenant's own declared attribute names, so a
+ * camelising client renames `team_verdict` to `teamVerdict` and there is no
+ * safe inverse — `snake_to_camel` is not injective, and guessing one would
+ * print a field name the tenant never declared. So field names are rendered
+ * EXACTLY as received and never re-cased. A consumer that wants the declared
+ * spellings must fetch this route without the case transform; one that cannot
+ * should pass `fieldLabel` to map them. Stated here rather than discovered
+ * later, because the same transform already corrupted declared names once.
+ */
+
+/**
+ * The actor vocabulary lives on `ActorIdentity`, which is the component that
+ * RENDERS it, and is re-exported here so a consumer of this module needs one
+ * import rather than two. Declared once (rule #1): a second union would be a
+ * second place for "person | machine | unknown" to drift, and the three-state
+ * shape is the one thing in this epic that must not.
+ */
+import type { ActorKind, ActorKindSource } from '../ActorIdentity';
+
+export type { ActorKind, ActorKindSource };
+
+/** `deleted` is declared server-side and not yet written — bd startsim-jkkn7.6. */
+export type RevisionAction = 'created' | 'updated' | 'deleted';
+
+/** Which endpoint wrote. `server` is a management command or a worker — a real
+ *  write that must not claim to be an endpoint. */
+export type RevisionSource = 'create' | 'patch' | 'put' | 'upsert' | 'server';
+
+/** `none` always, today; `matched` arrives with the conditional write
+ *  (bd startsim-3c2wc). */
+export type RevisionPrecondition = 'none' | 'matched';
+
+/**
+ * One `metadata.changed` entry, straight off the wire.
+ *
+ * THE ABSENCE OF A SIDE IS THE PAYLOAD, which is why neither key is nullable
+ * rather than optional-and-nullable:
+ *
+ * - a field the write CREATED has `after` and NO `before` key;
+ * - a field the write DELETED has `before` and NO `after` key — the server
+ *   never writes `after: null`, because a key a person deleted is a different
+ *   fact from a key set to `null`, and `null` IS a legal stored value;
+ * - a field the read gate WITHHELD is `{}` and the row's `redacted_fields`
+ *   names it;
+ * - a row over the byte cap has `{}` for EVERY field and
+ *   `metadata.values_omitted` set.
+ *
+ * So `'after' in entry` is the only correct test and `entry.after === undefined`
+ * is wrong. {@link normalizeFieldChange} is the one place that does it.
+ */
+export interface RevisionFieldChange {
+  before?: unknown;
+  after?: unknown;
+  /** The value was too large to store. WHEN THIS IS TRUE A MISSING SIDE SAYS
+   *  NOTHING — it was dropped, not deleted — so the delete inference above is
+   *  invalid and a diff over this entry would show a deletion that never
+   *  happened. */
+  truncated?: boolean;
+}
+
+export interface RevisionMetadata {
+  /** ALWAYS PRESENT, possibly `{}`. Keyed by the tenant's declared attribute
+   *  names — see the spelling trap in this module's header. */
+  changed?: Record<string, RevisionFieldChange>;
+  /** Present only when the name COLUMN moved. Namespaced away from `changed`
+   *  because a tenant may declare a data key literally called "name". */
+  name?: RevisionFieldChange;
+  /** Fields `human_edits.guard_machine_write` HELD BACK. A row carrying these
+   *  is a machine ATTEMPT, not a change, and its `changed` is `{}` — which is
+   *  correct, not a bug. */
+  preserved?: string[];
+  /** What an upsert CLAIMED it was re-authoring. The one override that
+   *  legitimately destroys a person's text, so it is shown. */
+  regenerate?: string[];
+  /** The whole row exceeded the row cap: every field is still NAMED in
+   *  `changed`, every value is `{}`. */
+  values_omitted?: boolean;
+  /** Camelised alias — see the header. */
+  valuesOmitted?: boolean;
+}
+
+/** One row of the append-only revision trail. Only `id` and `version` are
+ *  relied on; everything else is treated as optional so a row from a tenant
+ *  running an older build still renders. */
+export interface EntityRevision {
+  id: string;
+  /** 1-based, GAPLESS 1..N per entity, DB-unique. A hole is a provably lost
+   *  revision — which is what the unique constraint exists to make visible. */
+  version: number;
+  action?: RevisionAction | string;
+  source?: RevisionSource | string;
+  precondition?: RevisionPrecondition | string;
+  created_at?: string | null;
+  createdAt?: string | null;
+  /** May be `""`. */
+  actor_sub?: string | null;
+  actorSub?: string | null;
+  /** The actor's email, denormalised at write time. For a machine this is
+   *  often not an address at all (`svc:n8n-ogmc`). */
+  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;
+  metadata?: RevisionMetadata | null;
+  /** PRESENT ONLY when the per-field gate withheld something on this row. */
+  redacted_fields?: string[] | null;
+  redactedFields?: string[] | null;
+}
+
+/** The DRF envelope. `redacted_fields` is the server's roll-up of every row on
+ *  this page (`apps/api/pagination.py`), present only when something really
+ *  was held back. */
+export interface RevisionPage {
+  count?: number;
+  next?: string | null;
+  previous?: string | null;
+  results?: EntityRevision[];
+  redacted_fields?: string[] | null;
+  redactedFields?: string[] | null;
+}
+
+/** Narrowing the panel asks for. Server-side paginated (repo rule 8) — the
+ *  route caps `page_size` at 200 and 400s a parameter it does not recognise,
+ *  so this stays deliberately minimal. */
+export interface RevisionQuery {
+  page?: number;
+  pageSize?: number;
+  // Index signature so this satisfies an API client's query-params type; the
+  // injected client is the app's own.
+  [key: string]: unknown;
+}
+
+/**
+ * The one call the panel needs. The consuming app injects its authed client
+ * (`{ list: (p) => api.entities.revisions(id, p) }`), which is what keeps
+ * @startsimpli/api out of packages/ui and the app wrapper under ten lines.
+ *
+ * A 404 from this route means the caller may not read the PARENT record — the
+ * route is nested and an unreadable row is simply absent. The panel surfaces
+ * that as "you cannot see this record's history", never as an empty trail.
+ */
+export interface RevisionClient {
+  list: (query: RevisionQuery) => Promise<RevisionPage>;
+}

package/src/components/index.ts

@@ -155,7 +155,13 @@ export * from './calendar'
 // display name is never printed alone as if it were an identity
 // (startsim-768w.19.8.1).
 export { ActorIdentity, actorInitials, actorLabel, actorHandle } from './ActorIdentity'
-export type { ActorIdentityProps, ActorIdentityValue } from './ActorIdentity'
+export { actorKindTitle } from './ActorIdentity'
+export type {
+  ActorIdentityProps,
+  ActorIdentityValue,
+  ActorKind,
+  ActorKindSource,
+} from './ActorIdentity'
 
 // Activity components (timeline, quick log, log dialog)
 export { ActivityTimeline, dayHeading } from './ActivityTimeline'
@@ -168,6 +174,10 @@ export type {
 // The shared, filterable activity feed: filter bar + page-level composer over
 // any append-only event stream (startsim-768w.19.5).
 export * from './activity'
+
+// The shared record history panel: who changed which field, from what, to
+// what, and whether a machine did it (bd startsim-g4rwo).
+export * from './history'
 export { QuickLogButtons } from './QuickLogButtons'
 export type { QuickLogButtonsProps, QuickLogAction } from './QuickLogButtons'
 export { LogActivityDialog } from './LogActivityDialog'