collaboration — wyrd.component.comment-anchor

CommentAnchor

Compact anchored comment marker that opens an inline threaded discussion surface.

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

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

$schema: https://thewyrdingway.dev/schemas/component-contract.schema.ymlcontractVersion: 0.1.0identity:  name: CommentAnchor  tag: wyrd-comment-anchor  package: wyrd.component.comment-anchor  title: CommentAnchor  summary: Compact anchored comment marker that opens an inline threaded discussion surface.relationships:  related-to:    - quality-parity-and-gatesclassification:  category: collaboration  composition: overlay  interactive: truetarget-strategy:  react: required  flutter: requiredsurface:  properties:    - name: thread-id      type:        kind: string      required: true      serializable: true      summary: Opaque host-supplied thread identifier represented by the marker.    - name: label      type:        kind: string      required: true      serializable: true      summary: Accessible marker label supplied by the host for the anchor target.    - name: comment-count      type:        kind: integer        minimum: 0      required: false      default: 0      serializable: true      summary: Number of comments represented by the marker.    - name: status      type:        kind: enum        values:          - open          - resolved      required: false      default: open      reflects: true      serializable: true      summary: Host-supplied thread status.    - name: is-open      type:        kind: boolean      required: false      controlled: true      reflects: true      serializable: true      summary: Controlled expansion state.    - name: default-open      type:        kind: boolean      required: false      default: false      serializable: true      summary: Initial uncontrolled expansion state.    - name: placement      type:        kind: enum        values:          - inline          - block          - margin      required: false      default: margin      reflects: true      serializable: true      summary: Preferred visual placement for the expanded thread surface.    - 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 for the expanded thread.    - name: reply-value      type:        kind: string      required: false      controlled: true      serializable: true      summary: Controlled reply composer value for the expanded thread.    - 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 in the expanded thread when true.    - name: can-resolve      type:        kind: boolean      required: false      default: true      serializable: true      summary: Shows resolve/reopen affordance in the expanded thread when true.  slots: []  events:    - name: open-change      payload:        thread-id:          kind: string        is-open:          kind: boolean        reason:          kind: enum          values:            - marker            - close-button            - escape            - programmatic      bubbles: true      composed: true      cancelable: false      summary: Emitted when marker expansion changes.    - name: reply-change      payload:        thread-id:          kind: string        value:          kind: string      bubbles: true      composed: true      cancelable: false      summary: Re-emitted from the expanded thread reply composer.    - name: reply-submit      payload:        thread-id:          kind: string        body:          kind: string      bubbles: true      composed: true      cancelable: true      summary: Re-emitted when the expanded thread submits a reply.    - name: resolve      payload:        thread-id:          kind: string      bubbles: true      composed: true      cancelable: true      summary: Re-emitted when the expanded thread requests resolving.    - name: reopen      payload:        thread-id:          kind: string      bubbles: true      composed: true      cancelable: true      summary: Re-emitted when the expanded thread requests reopening.    - 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: closed      source: property      summary: Marker is collapsed.    - name: open      source: property      summary: Expanded thread is visible.    - name: resolved      source: property      summary: Marker represents a resolved thread.  parts:    - name: root      summary: Anchor root.    - name: marker      summary: Compact marker button.    - name: count      summary: Comment count text.    - name: surface      summary: Expanded thread surface.    - name: close      summary: Expanded surface close button.  tokens:    marker-background: color.primary    marker-foreground: color.on-primary    resolved-background: color.surface-container    resolved-foreground: color.on-surface-variant    surface-background: color.surface    surface-foreground: color.on-surface    border-color: color.outline    radius: rounded.md    shadow: shadow.md    padding-x: spacing.sm    padding-y: spacing.xs    gap: spacing.smmessages:  - key: comment-anchor.close    description: Accessible label for closing the expanded anchor thread.  - key: comment-anchor.count-label    description: Text label shown next to the marker comment count.  - key: comment-anchor.marker-label    description: Accessible label for the marker button including host label and comment count.    params:      label: string      count: numberobligations:  accessibility:    role: button    name: Label property and comment count are combined through the localized marker label.    keyboard:      - Tab moves focus to the marker, close button, and expanded thread controls.      - Enter or Space toggles the marker when focused.      - Escape closes the expanded thread and restores focus to the marker.    semantics:      - The marker is a button with aria-expanded reflecting open state.      - The expanded thread is a non-modal inline/anchored surface, not a focus trap.      - The close control is a button named by component-owned localized text.      - The expanded thread preserves CommentThread native list semantics.  behavior:    model: overlay    interactions:      - is-open ?? default-open determines effective expansion state.      - Activating the marker toggles expansion and emits open-change.      - Activating close or pressing Escape closes the thread and emits open-change.      - Expanded thread interactions are re-emitted with thread-id.    hostEffects:      - Dispatch open-change event.      - Dispatch reply, resolve/reopen, and child comment edit/delete events.      - Hosts own anchor positioning context, persistence, identity, permissions, and storage.  conditions:    - rtl    - reduced-motion    - cvd-deuteranopia    - density-compact    - text-expansion  sdui:    status: serializable    serializableProperties:      - thread-id      - label      - comment-count      - status      - is-open      - default-open      - placement      - comments      - reply-value      - default-reply-value      - can-reply      - can-resolve    serializableSlots: []    eventBindings:      - open-change      - reply-change      - reply-submit      - resolve      - reopen      - comment-edit      - comment-delete    notes: CommentAnchor serializes marker state, flat comments, and interaction bindings for embeddable host surfaces. Host-owned persistence and anchor storage are outside the component.examples:  - name: closed    state: closed    properties:      thread-id: thread-route-delay      label: Comments on delay copy      comment-count: 1      status: open      default-open: false      comments:        - id: comment-route-delay-copy          author-id: author-rin          author-name: Rin          timestamp: "2026-07-04T16:15:00.000Z"          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    slots: {}  - name: open    state: open    properties:      thread-id: thread-coordinator-lock      label: Comments on coordinator field      comment-count: 2      status: resolved      default-open: true      placement: margin      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      comment-count: commentCount      is-open: isOpen      default-open: defaultOpen      reply-value: replyValue      default-reply-value: defaultReplyValue      can-reply: canReply      can-resolve: canResolve    events:      open-change: onOpenChange      reply-change: onReplyChange      reply-submit: onReplySubmit      comment-edit: onCommentEdit      comment-delete: onCommentDelete  flutter:    properties:      thread-id: threadId      comment-count: commentCount      is-open: isOpen      default-open: defaultOpen      reply-value: replyValue      default-reply-value: defaultReplyValue      can-reply: canReply      can-resolve: canResolve    events:      open-change: onOpenChange      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.

closed state: closed

Usage

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

<WyrdCommentAnchor threadId="thread-route-delay" label="Comments on delay copy" commentCount={1} status="open" defaultOpen={false} comments={[{"id":"comment-route-delay-copy","author-id":"author-rin","author-name":"Rin","timestamp":"2026-07-04T16:15:00.000Z","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}]} />

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

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdCommentAnchor(
  threadId: 'thread-route-delay',
  label: 'Comments on delay copy',
  commentCount: 1,
  status: 'open',
  defaultOpen: false,
  comments: [{"id":"comment-route-delay-copy","author-id":"author-rin","author-name":"Rin","timestamp":"2026-07-04T16:15:00.000Z","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}],
)

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

open state: open

Usage

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

<WyrdCommentAnchor threadId="thread-coordinator-lock" label="Comments on coordinator field" commentCount={2} status="resolved" defaultOpen placement="margin" 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: onOpenChange, onReplyChange, onReplySubmit, onResolve, onReopen, onCommentEdit, onCommentDelete

import 'package:wyrd_flutter/wyrd_flutter.dart';

WyrdCommentAnchor(
  threadId: 'thread-coordinator-lock',
  label: 'Comments on coordinator field',
  commentCount: 2,
  status: 'resolved',
  defaultOpen: true,
  placement: 'margin',
  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: onOpenChange, onReplyChange, onReplySubmit, onResolve, onReopen, onCommentEdit, onCommentDelete

Properties

Name	Type	Default	Summary
`thread-id`	`string`	`undefined`	Opaque host-supplied thread identifier represented by the marker.
`label`	`string`	`undefined`	Accessible marker label supplied by the host for the anchor target.
`comment-count`	`integer`	`0`	Number of comments represented by the marker.
`status`	`open \| resolved`	`open`	Host-supplied thread status.
`is-open`	`boolean`	`undefined`	Controlled expansion state.
`default-open`	`boolean`	`false`	Initial uncontrolled expansion state.
`placement`	`inline \| block \| margin`	`margin`	Preferred visual placement for the expanded thread surface.
`comments`	`array`		Flat ordered comments for the expanded thread.
`reply-value`	`string`	`undefined`	Controlled reply composer value for the expanded thread.
`default-reply-value`	`string`		Initial uncontrolled reply composer value.
`can-reply`	`boolean`	`true`	Shows the reply composer in the expanded thread when true.
`can-resolve`	`boolean`	`true`	Shows resolve/reopen affordance in the expanded thread when true.

Slots & events

Event	Payload	Summary
`open-change`	`thread-id, is-open, reason`	Emitted when marker expansion changes.
`reply-change`	`thread-id, value`	Re-emitted from the expanded thread reply composer.
`reply-submit`	`thread-id, body`	Re-emitted when the expanded thread submits a reply.
`resolve`	`thread-id`	Re-emitted when the expanded thread requests resolving.
`reopen`	`thread-id`	Re-emitted when the expanded thread requests reopening.
`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
`marker-background`	`color.primary`
`marker-foreground`	`color.on-primary`
`resolved-background`	`color.surface-container`
`resolved-foreground`	`color.on-surface-variant`
`surface-background`	`color.surface`
`surface-foreground`	`color.on-surface`
`border-color`	`color.outline`
`radius`	`rounded.md`
`shadow`	`shadow.md`
`padding-x`	`spacing.sm`
`padding-y`	`spacing.xs`
`gap`	`spacing.sm`

States

State	Source	Summary
`closed`	property	Marker is collapsed.
`open`	property	Expanded thread is visible.
`resolved`	property	Marker represents a resolved thread.

SDUI

Status: serializable. CommentAnchor serializes marker state, flat comments, and interaction bindings for embeddable host surfaces. Host-owned persistence and anchor storage are outside the component.

Serializable	Members
Properties	`thread-id, label, comment-count, status, is-open, default-open, placement, comments, reply-value, default-reply-value, can-reply, can-resolve`
Slots	`—`
Events	`open-change, 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