@lovett/ui 0.0.11 → 0.2.0

package/src/thread/types.ts

@@ -0,0 +1,232 @@
+/**
+ * Thread primitive — the data shapes.
+ *
+ * ADR-147 T3. This module is deliberately entity-agnostic: it knows nothing
+ * about tasks, boards, posts, brands, or the wire. It takes already-shaped
+ * data and reports intent through callbacks. The `entity_type` registry that
+ * makes threads safe (ADR-147 D2) lives server-side; nothing here is an
+ * authorization boundary and nothing here should ever be treated as one.
+ *
+ * Timestamps are integer epoch MILLISECONDS. The D1 schema stores epoch
+ * seconds (ADR-147 D16); converting at the API seam is T4's job, not this
+ * layer's — a component that guesses at units is a component that renders
+ * "56 years ago" the first time someone changes the column.
+ */
+
+import type { MentionTargetType } from './comment-body'
+
+/**
+ * ADR-147 D8 — reactions are a bounded set of glyph KEYS, never emoji and
+ * never a free string. The bound is what makes the column enumerable, the
+ * rendering consistent across platforms, and the no-emoji rule enforceable.
+ */
+export const THREAD_REACTION_KEYS = [
+  'up',
+  'heart',
+  'celebrate',
+  'eyes',
+  'check',
+  'question',
+] as const
+
+export type ThreadReactionKey = (typeof THREAD_REACTION_KEYS)[number]
+
+/** One reaction row as the API groups it: key, tally, and the viewer's own state. */
+export interface ThreadReactionCount {
+  readonly key: ThreadReactionKey
+  readonly count: number
+  readonly viewerReacted: boolean
+}
+
+/**
+ * ADR-147 D17 — optimistic send is a first-class state, not a nicety.
+ * A comment silently lost to a bad connection is the worst thing this surface
+ * can do to someone, and it is the most likely.
+ */
+export type CommentDeliveryState = 'sent' | 'pending' | 'failed'
+
+/**
+ * ADR-147 D5 — every field here can be absent. `users.name` / `given_name` /
+ * `family_name` are nullable by standing policy (do not fabricate a display
+ * name), `author_id` is ON DELETE SET NULL, and no avatar column is populated
+ * yet. The display fallback lives in the component (D6), never in the data.
+ */
+export interface ThreadAuthor {
+  readonly id?: string | null | undefined
+  readonly name?: string | null | undefined
+  /** Used as the display fallback when `name` is absent — D5's "only an email" case. */
+  readonly email?: string | null | undefined
+  /** May 404 or be blocked. The avatar keeps its initial behind the photo (D14). */
+  readonly avatarUrl?: string | null | undefined
+  /** Identity colour as DATA (D6). Omitted falls back to Avatar's documented hash. */
+  readonly tint?: string | null | undefined
+  /** A short role chip beside the name, e.g. "Client". */
+  readonly role?: string | null | undefined
+}
+
+/**
+ * `gif` joined `image` and `file` with ADR-151 D4.
+ *
+ * It is its own kind rather than a flavour of `image` because it identifies a
+ * Giphy reference whose stored rendition is an mp4. That is what lets its
+ * renderer genuinely pause on the first frame. Uploaded GIFs deliberately stay
+ * `image` and are distinguished by `mime: 'image/gif'`; their renderer swaps a
+ * captured canvas still for the live image under reduced motion.
+ */
+export type ThreadAttachmentKind = 'image' | 'gif' | 'file'
+
+/**
+ * ADR-147 D9. `aspectRatio` is captured at attach time so the thread reserves
+ * the image slot before it loads — the layout-stability rule. An attachment
+ * without one gets a declared 16/10 box rather than a collapsing one.
+ */
+export interface ThreadAttachment {
+  readonly id: string
+  readonly kind: ThreadAttachmentKind
+  readonly name: string
+  readonly url?: string | undefined
+  readonly mime?: string | undefined
+  readonly sizeBytes?: number | undefined
+  readonly aspectRatio?: number | undefined
+}
+
+/**
+ * One unfurled link card on one comment (ADR-150 D8).
+ *
+ * This is the WIRE shape, and it is deliberately narrower than the cache row
+ * behind it. `thread_link_previews` also carries `status` (`ok` / `failed` /
+ * `blocked`) and internal failure codes; a thread read returns only `ok`,
+ * unhidden rows, so neither ever crosses the wire. A client cannot tell a
+ * blocked URL from one nobody has fetched yet, which is the intent.
+ *
+ * `title` is NOT nullable, unlike everything else here: D5 makes a non-empty
+ * title the condition for writing an `ok` row at all, so a card without one
+ * does not exist. `domain` is derived by the WORKER from the URL that was
+ * actually fetched — never from `og:site_name`, which the target page chooses.
+ *
+ * `href` is per-OCCURRENCE and keeps its fragment, so clicking the card lands
+ * on the anchor the person meant; the cache is keyed on a canonical fetch URL
+ * with the fragment removed, because a fragment is never sent to an origin.
+ *
+ * `canHide` reflects "the viewer authored this comment" for rendering only. It
+ * is never an authorization decision — D7 re-checks authorship server-side on
+ * every hide, and a flipped flag earns a 404.
+ */
+export interface ThreadLinkPreview {
+  /** SHA-256 of the canonical fetch URL, 64 lowercase hex characters. */
+  readonly urlHash: string
+  /** The normalized href for THIS occurrence, fragment included. */
+  readonly href: string
+  readonly title: string
+  /** Worker-derived display host. Not `og:site_name`. */
+  readonly domain: string
+  readonly description?: string | null | undefined
+  readonly imageUrl?: string | null | undefined
+  readonly siteName?: string | null | undefined
+  /**
+   * `og:image:width / og:image:height`, already clamped to `0.1..10` by the
+   * worker (ADR-150 D4). Absent means the card declares a 16:9 slot — the point
+   * being that it declares SOMETHING before the image loads, and keeps it if
+   * the image never does.
+   */
+  readonly imageAspect?: number | null | undefined
+  readonly canHide: boolean
+}
+
+/** -1 | 0 | 1. The community/roadmap variant (D8) — never combined with reactions. */
+export type ThreadVote = -1 | 0 | 1
+
+export interface ThreadComment {
+  readonly id: string
+  /** Absent or null = a root comment. */
+  readonly parentId?: string | null | undefined
+  /** Null = the author record is gone (D5). Renders degraded, never crashes. */
+  readonly author?: ThreadAuthor | null | undefined
+  /** Markdown. Rendered through MarkdownRenderer's component map; NEVER rehype-raw (D7). */
+  readonly bodyMd: string
+  readonly createdAt: number
+  /** Set = "· edited" (D15). No edit history in v1. */
+  readonly editedAt?: number | null | undefined
+  /** Set = tombstone (D4). The row still renders and KEEPS its subtree. */
+  readonly deletedAt?: number | null | undefined
+  /**
+   * TRUE = the tombstone above was made by somebody OTHER than the author
+   * (FU-0031, FU-0032). Meaningless without `deletedAt`, and read nowhere else.
+   *
+   * One boolean rather than a `deletedBy` author, and that is a decision, not
+   * a shortcut: the wire deliberately never carries who removed a comment, so
+   * a field that could hold a name would be a field somebody eventually fills.
+   * A boolean cannot leak an identity it does not have.
+   *
+   * OPTIONAL, and absent means `[deleted]` — the render every host on 0.1.0
+   * already gets. A host with no moderation concept never sets it and never
+   * sees a word change.
+   */
+  readonly moderated?: boolean | undefined
+  readonly reactions?: readonly ThreadReactionCount[] | undefined
+  readonly attachments?: readonly ThreadAttachment[] | undefined
+  /**
+   * At most three (ADR-150 D1), already ordered by the worker and already
+   * filtered to visible, successful rows. Absent is the normal state for a
+   * comment with no links — and also what a fail-soft preview read returns
+   * (D10), which is why an empty list can never be distinguished from an error
+   * and neither one is allowed to break the comment.
+   */
+  readonly linkPreviews?: readonly ThreadLinkPreview[] | undefined
+  /** Vote variant only (D8). */
+  readonly score?: number | undefined
+  /** Vote variant only (D8). Lifted to props — never local state (correction 3). */
+  readonly viewerVote?: ThreadVote | undefined
+  /** Pinned / "top comment". Sorts first under `top`. */
+  readonly pinned?: boolean | undefined
+  /** Defaults to 'sent' when absent. */
+  readonly state?: CommentDeliveryState | undefined
+  /** Shown beside the retry on a failed send. */
+  readonly errorText?: string | undefined
+}
+
+/**
+ * A comment placed in the reply tree.
+ *
+ * `depth` is the TRUE stored depth (D3: "depth is stored true and rendered
+ * capped"). The render cap is a display concern and lives in the hook.
+ *
+ * `orphanedParentId` is the D4 distinction: non-null means this reply named a
+ * parent that is ABSENT from the list it was built from — "not fetched", not
+ * "deleted". A deleted parent is a tombstone row that is still present, so its
+ * children stay nested under it and this stays null.
+ */
+export interface CommentNode extends ThreadComment {
+  readonly replies: readonly CommentNode[]
+  readonly depth: number
+  readonly orphanedParentId: string | null
+}
+
+export type ThreadSort = 'top' | 'new'
+
+/**
+ * Reactions and votes are never both on one comment (D8): reactions are
+ * acknowledgement, votes are ranking. The headless layer exposes both and the
+ * surface picks exactly one. Task threads take reactions; community and
+ * roadmap take votes.
+ */
+export type ThreadEngagement = 'reactions' | 'votes' | 'none'
+
+/**
+ * One row the `@` picker may offer (ADR-149 D6).
+ *
+ * It lives here, beside the other data shapes, rather than in the rich
+ * composer, for one structural reason: the package barrel must stay free of
+ * TipTap so a thread LIST never pays for ProseMirror (ADR-148 D5), and a host
+ * needs this type to write its `mentionItems` callback.
+ *
+ * The picker is a CONVENIENCE, never a permission boundary. The host filters a
+ * list it already had; the server still parses `body_md` at write time and
+ * re-checks every mention it extracts, exactly as it does for one typed by
+ * hand or pasted (ADR-147 D11, restated in ADR-149 D6).
+ */
+export interface MentionSuggestionItem {
+  readonly id: string
+  readonly label: string
+  readonly type: MentionTargetType
+}