collaboration — wyrd.component.comment-thread

CommentThread

Threaded review discussion with flat host-supplied comments, reply submission, and resolve/reopen events.

Install @wyrd-company/react or the Flutter package and use it directly — your DESIGN.md does the styling.

catalog/contracts/comment-thread.yml source of truth · verbatim

$schema: https://thewyrdingway.dev/schemas/component-contract.schema.ymlcontractVersion: 0.1.0identity:  name: CommentThread  tag: wyrd-comment-thread  package: wyrd.component.comment-thread  title: CommentThread  summary: Threaded review discussion with flat host-supplied comments, reply submission, and resolve/reopen events.relationships:  related-to:    - quality-parity-and-gatesclassification:  category: collaboration  composition: collection  interactive: truetarget-strategy:  react: required  flutter: requiredsurface:  properties:    - name: thread-id      type:        kind: string      required: true      serializable: true      summary: Opaque host-supplied thread identifier.    - name: status      type:        kind: enum        values:          - open          - resolved      required: false      default: open      reflects: true      serializable: true      summary: Host-supplied thread status.    - name: comments      type:        kind: array        item:          kind: object          fields:            id:              kind: string            author-id:              kind: string            author-name:              kind: string            timestamp:              kind: string            timestamp-label:              kind: string            body-format:              kind: enum              values:                - plain-text            body:              kind: string            decision:              kind: enum              values:                - none                - approve                - request-changes                - comment                - suggestion            edited:              kind: boolean            can-edit:              kind: boolean            can-delete:              kind: boolean      required: false      default: []      serializable: true      summary: Flat ordered comments in display order, structurally mirroring the comment contract.    - name: reply-value      type:        kind: string      required: false      controlled: true      serializable: true      summary: Controlled reply composer value.    - name: default-reply-value      type:        kind: string      required: false      default: ""      serializable: true      summary: Initial uncontrolled reply composer value.    - name: can-reply      type:        kind: boolean      required: false      default: true      serializable: true      summary: Shows the reply composer when true.    - name: can-resolve      type:        kind: boolean      required: false      default: true      serializable: true      summary: Shows resolve/reopen affordance when true.  slots: []  events:    - name: reply-change      payload:        thread-id:          kind: string        value:          kind: string      bubbles: true      composed: true      cancelable: false      summary: Emitted when the reply composer value changes.    - name: reply-submit      payload:        thread-id:          kind: string        body:          kind: string      bubbles: true      composed: true      cancelable: true      summary: Emitted when the user submits a non-empty reply.    - name: resolve      payload:        thread-id:          kind: string      bubbles: true      composed: true      cancelable: true      summary: Emitted when the user requests resolving an open thread.    - name: reopen      payload:        thread-id:          kind: string      bubbles: true      composed: true      cancelable: true      summary: Emitted when the user requests reopening a resolved thread.    - name: comment-edit      payload:        thread-id:          kind: string        comment-id:          kind: string      bubbles: true      composed: true      cancelable: true      summary: Re-emitted when a child comment edit affordance is activated.    - name: comment-delete      payload:        thread-id:          kind: string        comment-id:          kind: string      bubbles: true      composed: true      cancelable: true      summary: Re-emitted when a child comment delete affordance is activated.  states:    - name: open      source: property      summary: Thread is open.    - name: resolved      source: property      summary: Thread is resolved.    - name: replying      source: interaction      summary: Reply composer has focus or content.  parts:    - name: root      summary: Thread root.    - name: header      summary: Status and resolve/reopen action row.    - name: status      summary: Thread status text.    - name: list      summary: Comment list/feed.    - name: item      summary: Comment list item.    - name: composer      summary: Reply composer region.    - name: reply-input      summary: Reply text input.    - name: reply-submit      summary: Reply submit button.    - name: status-action      summary: Resolve/reopen button.  tokens:    background: color.surface    foreground: color.on-surface    muted: color.on-surface-variant    border-color: color.outline    composer-background: color.surface-container    action-background: color.primary    action-foreground: color.on-primary    radius: rounded.md    padding-x: spacing.md    padding-y: spacing.md    gap: spacing.smmessages:  - key: comment-thread.reply    description: Label for the reply composer.  - key: comment-thread.reply-placeholder    description: Placeholder text for the reply composer.  - key: comment-thread.submit-reply    description: Button label for submitting a reply.  - key: comment-thread.resolve    description: Button label for resolving an open thread.  - key: comment-thread.reopen    description: Button label for reopening a resolved thread.  - key: comment-thread.status.open    description: Status label for an open thread.  - key: comment-thread.status.resolved    description: Status label for a resolved thread.obligations:  accessibility:    role: list    name: Thread id and status identify the comment thread; hosts may wrap with a stronger label when needed.    keyboard:      - Tab moves through resolve/reopen action, child comment actions, reply input, and submit button.      - Enter or Space activates focused buttons.      - The reply input accepts normal multiline text entry.    semantics:      - Web projections render thread comments as a native list of article-like comment items.      - Resolve/reopen and reply submit controls are buttons named by component-owned localized messages.      - Reply input is labelled by the component-owned reply message.      - Empty reply submissions are ignored locally and do not dispatch reply-submit.  behavior:    model: collection    interactions:      - Comments render in host-supplied order.      - reply-value ?? default-reply-value determines the effective composer text.      - Editing the composer emits reply-change with thread-id and value.      - Submitting non-empty composer text emits reply-submit with thread-id and body.      - Resolve emits resolve for open threads; reopen emits reopen for resolved threads.      - Child comment edit/delete actions are re-emitted with thread-id and comment-id.    hostEffects:      - Dispatch reply-change event.      - Dispatch reply-submit event.      - Dispatch resolve or reopen event.      - Dispatch child comment edit/delete events.      - Hosts own persistence, identity, permissions, thread status transitions, and reply clearing.  conditions:    - rtl    - reduced-motion    - cvd-deuteranopia    - density-compact    - text-expansion  sdui:    status: serializable    serializableProperties:      - thread-id      - status      - comments      - reply-value      - default-reply-value      - can-reply      - can-resolve    serializableSlots: []    eventBindings:      - reply-change      - reply-submit      - resolve      - reopen      - comment-edit      - comment-delete    notes: CommentThread serializes flat comments and interaction bindings. It does not own workflow state, identity, or persistence.examples:  - name: open    state: open    properties:      thread-id: thread-route-delay      status: open      comments:        - id: comment-route-delay-copy          author-id: author-rin          author-name: Rin          timestamp: "2026-07-04T16:15:00.000Z"          timestamp-label: Today at 4:15 PM          body-format: plain-text          body: Delay copy should identify the affected service window before dispatch signs off.          decision: request-changes          edited: false          can-edit: false          can-delete: false      default-reply-value: ""    slots: {}  - name: resolved    state: resolved    properties:      thread-id: thread-coordinator-lock      status: resolved      comments:        - id: comment-coordinator-lock          author-id: author-mara          author-name: Mara          timestamp: "2026-07-04T16:20:00.000Z"          body-format: plain-text          body: Locked coordinator field matches this scenario.          decision: approve          edited: true          can-edit: true          can-delete: false    slots: {}overrides:  react:    properties:      thread-id: threadId      reply-value: replyValue      default-reply-value: defaultReplyValue      can-reply: canReply      can-resolve: canResolve    events:      reply-change: onReplyChange      reply-submit: onReplySubmit      comment-edit: onCommentEdit      comment-delete: onCommentDelete  flutter:    properties:      thread-id: threadId      reply-value: replyValue      default-reply-value: defaultReplyValue      can-reply: canReply      can-resolve: canResolve    events:      reply-change: onReplyChange      reply-submit: onReplySubmit      comment-edit: onCommentEdit      comment-delete: onCommentDelete

Examples

Generated from the contract's examples block. Previews are the published @wyrd-company/react component, themed by the brand's role tokens — flip the site's light/dark toggle and they follow.

Code target React Flutter Applies to every example on component pages.

open state: open

Usage

import { WyrdCommentThread } from "@wyrd-company/react";

<WyrdCommentThread threadId="thread-route-delay" status="open" comments={[{"id":"comment-route-delay-copy","author-id":"author-rin","author-name":"Rin","timestamp":"2026-07-04T16:15:00.000Z","timestamp-label":"Today at 4:15 PM","body-format":"plain-text","body":"Delay copy should identify the affected service window before dispatch signs off.","decision":"request-changes","edited":false,"can-edit":false,"can-delete":false}]} defaultReplyValue="" />

// events: onReplyChange, onReplySubmit, onResolve, onReopen, onCommentEdit, onCommentDelete

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdCommentThread(
  threadId: 'thread-route-delay',
  status: 'open',
  comments: [{"id":"comment-route-delay-copy","author-id":"author-rin","author-name":"Rin","timestamp":"2026-07-04T16:15:00.000Z","timestamp-label":"Today at 4:15 PM","body-format":"plain-text","body":"Delay copy should identify the affected service window before dispatch signs off.","decision":"request-changes","edited":false,"can-edit":false,"can-delete":false}],
  defaultReplyValue: '',
)

// events: onReplyChange, onReplySubmit, onResolve, onReopen, onCommentEdit, onCommentDelete

resolved state: resolved

Usage

import { WyrdCommentThread } from "@wyrd-company/react";

<WyrdCommentThread threadId="thread-coordinator-lock" status="resolved" comments={[{"id":"comment-coordinator-lock","author-id":"author-mara","author-name":"Mara","timestamp":"2026-07-04T16:20:00.000Z","body-format":"plain-text","body":"Locked coordinator field matches this scenario.","decision":"approve","edited":true,"can-edit":true,"can-delete":false}]} />

// events: onReplyChange, onReplySubmit, onResolve, onReopen, onCommentEdit, onCommentDelete

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdCommentThread(
  threadId: 'thread-coordinator-lock',
  status: 'resolved',
  comments: [{"id":"comment-coordinator-lock","author-id":"author-mara","author-name":"Mara","timestamp":"2026-07-04T16:20:00.000Z","body-format":"plain-text","body":"Locked coordinator field matches this scenario.","decision":"approve","edited":true,"can-edit":true,"can-delete":false}],
)

// events: onReplyChange, onReplySubmit, onResolve, onReopen, onCommentEdit, onCommentDelete

Properties

Name	Type	Default	Summary
`thread-id`	`string`	`undefined`	Opaque host-supplied thread identifier.
`status`	`open \| resolved`	`open`	Host-supplied thread status.
`comments`	`array`		Flat ordered comments in display order, structurally mirroring the comment contract.
`reply-value`	`string`	`undefined`	Controlled reply composer value.
`default-reply-value`	`string`		Initial uncontrolled reply composer value.
`can-reply`	`boolean`	`true`	Shows the reply composer when true.
`can-resolve`	`boolean`	`true`	Shows resolve/reopen affordance when true.

Slots & events

Event	Payload	Summary
`reply-change`	`thread-id, value`	Emitted when the reply composer value changes.
`reply-submit`	`thread-id, body`	Emitted when the user submits a non-empty reply.
`resolve`	`thread-id`	Emitted when the user requests resolving an open thread.
`reopen`	`thread-id`	Emitted when the user requests reopening a resolved thread.
`comment-edit`	`thread-id, comment-id`	Re-emitted when a child comment edit affordance is activated.
`comment-delete`	`thread-id, comment-id`	Re-emitted when a child comment delete affordance is activated.

Tokens

The contract's token bindings. Open the shared contextual sidebar from any example; primary swatches reflect the color you pick there. Error swatches show the active preset's values; editing any knob switches to custom and resets error to TWW · Ink.

Binding	Token
`background`	`color.surface`
`foreground`	`color.on-surface`
`muted`	`color.on-surface-variant`
`border-color`	`color.outline`
`composer-background`	`color.surface-container`
`action-background`	`color.primary`
`action-foreground`	`color.on-primary`
`radius`	`rounded.md`
`padding-x`	`spacing.md`
`padding-y`	`spacing.md`
`gap`	`spacing.sm`

States

State	Source	Summary
`open`	property	Thread is open.
`resolved`	property	Thread is resolved.
`replying`	interaction	Reply composer has focus or content.

SDUI

Status: serializable. CommentThread serializes flat comments and interaction bindings. It does not own workflow state, identity, or persistence.

Serializable	Members
Properties	`thread-id, status, comments, reply-value, default-reply-value, can-reply, can-resolve`
Slots	`—`
Events	`reply-change, reply-submit, resolve, reopen, comment-edit, comment-delete`

  The Wyrding Way — a contract-first design system. © Wyrd Company 
   Pipeline demo
 Choose an example to inspect its pipeline context.
 Explore the shape of a brand's pipeline input: presets and knobs regenerate the illustrative excerpt below — not a compilable DESIGN.md (see the format reference). Primary swatches update live; accent, shape, density, and ground are excerpt-only; error swatches are preset-derived until any edit switches to custom (TWW · Ink errors). Component previews use the published brand package and the site's light/dark toggle.
 
  Start from
       
 * homages — shown for range, not affiliation.
 
  Tokens
 Primary updates live swatches. Accent, shape, density, and ground appear in the excerpt only. Error swatches follow the preset until you edit a knob — then they reset to TWW · Ink.
  color.primary   #26221A    color.accent   #9C7C14    rounded.md   2px    density   1.0×    ground     
 
   DESIGN.md excerpt illustrative