Blocks / Inline comments

Inline comments

Threads in the margin, each beside the block or text range it is about.

import { InlineComments, inlineCommentAnchorTop, structureRebaseAnchor, structureLayoutThreads } from "@forgeron/ui";
/01 → Default

Launch plan

The new billing page will ship in two phases, the API first and the interface after.

We expect 4 800 accounts to migrate in the first month, with support staffed for the peak.

Rollback is a single switch and is rehearsed the week before.

ship in two phases
  1. Léa MartinNov 17, 15:40

    Can we say which two phases?

  2. Hugo BernardNov 17, 16:05

    Phase one is the API, phase two the UI.

  1. Camille RoyNov 18, 09:12

    Where does this figure come from?

// A document with blocks that carry data-block-id, and the threads in its margin. Click a card to
// bring it to its anchor; select, reply and resolve work on this page's own state.
import { InlineComments, type InlineThread, type MentionOption } from "@forgeron/ui";
import { useState } from "react";

const people: MentionOption[] = [
  { id: "lea", label: "Léa Martin", hint: "Design" },
  { id: "hugo", label: "Hugo Bernard", hint: "Engineering" },
];

const initial: InlineThread[] = [
  {
    id: "t1",
    anchor: { kind: "range", blockId: "b2", start: 12, end: 33, quote: "ship in two phases" },
    status: "open",
    comments: [
      {
        id: "c1",
        author: "Léa Martin",
        at: "Nov 17, 15:40",
        body: "Can we say **which** two phases?",
      },
      {
        id: "c2",
        author: "Hugo Bernard",
        at: "Nov 17, 16:05",
        body: "Phase one is the API, phase two the UI.",
      },
    ],
  },
  {
    id: "t2",
    anchor: { kind: "block", blockId: "b3" },
    status: "open",
    comments: [
      {
        id: "c3",
        author: "Camille Roy",
        at: "Nov 18, 09:12",
        body: "Where does this figure come from?",
      },
    ],
  },
  {
    id: "t3",
    anchor: { kind: "block", blockId: "b1" },
    status: "resolved",
    comments: [{ id: "c4", author: "Léa Martin", at: "Nov 15, 11:00", body: "Typo fixed." }],
  },
];

const text: Record<string, string> = {
  b1: "Launch plan",
  b2: "The new billing page will ship in two phases, the API first and the interface after.",
  b3: "We expect 4 800 accounts to migrate in the first month, with support staffed for the peak.",
  b4: "Rollback is a single switch and is rehearsed the week before.",
};

export default function Default() {
  const [threads, setThreads] = useState(initial);
  const [active, setActive] = useState<string | null>(null);
  const set = (id: string, patch: Partial<InlineThread>) =>
    setThreads((all) => all.map((t) => (t.id === id ? { ...t, ...patch } : t)));
  return (
    <div
      style={{
        display: "grid",
        gridTemplateColumns: "minmax(0,1fr) 280px",
        gap: 24,
        width: "100%",
      }}
    >
      <div
        id="ic-doc"
        style={{ font: "400 14px/22px var(--font-sans)", color: "var(--ink-muted)" }}
      >
        <h3
          data-block-id="b1"
          style={{
            margin: "0 0 16px",
            font: "500 18px/24px var(--font-sans)",
            color: "var(--ink)",
          }}
        >
          {text.b1}
        </h3>
        {(["b2", "b3", "b4"] as const).map((id) => (
          <p
            key={id}
            data-block-id={id}
            style={{
              margin: "0 0 28px",
              outline:
                active && threads.find((t) => t.id === active)?.anchor.blockId === id
                  ? "1px dashed var(--accent)"
                  : "none",
              outlineOffset: 4,
            }}
          >
            {text[id]}
          </p>
        ))}
      </div>
      <InlineComments
        threads={threads}
        anchorsIn="#ic-doc"
        active={active}
        onActiveChange={setActive}
        mentions={people}
        onResolve={(id) => set(id, { status: "resolved" })}
        onReopen={(id) => set(id, { status: "open" })}
        onReply={(id, body) =>
          set(id, {
            comments: [
              ...threads.find((t) => t.id === id)!.comments,
              { id: `c${Date.now()}`, author: "You", at: "Just now", body },
            ],
          })
        }
      />
    </div>
  );
}
/02 → New thread

Rollback is a single switch, rehearsed the week before the launch.

No comments

Select text in the page to start a thread.

// A button stands in for a selection: it gives a draft anchored to a range of the paragraph, and
// the margin opens a box there. The anchor moves with the text through structureRebaseAnchor.
import {
  Button,
  InlineComments,
  structureRebaseAnchor,
  type InlineThread,
  type StructureAnchor,
} from "@forgeron/ui";
import { useState } from "react";

export default function NewThread() {
  const [words, setWords] = useState(
    "Rollback is a single switch, rehearsed the week before the launch.",
  );
  const [threads, setThreads] = useState<InlineThread[]>([]);
  const [draft, setDraft] = useState<StructureAnchor | null>(null);

  const prefix = (text: string) => {
    setWords((w) => text + w);
    // The text was typed at the start: every range of the block moves by its length.
    setThreads((all) =>
      all.map((t) => ({
        ...t,
        anchor:
          structureRebaseAnchor(t.anchor, {
            blockId: "p",
            at: 0,
            remove: 0,
            insert: text.length,
          }) ?? t.anchor,
      })),
    );
  };

  return (
    <div
      style={{
        display: "grid",
        gridTemplateColumns: "minmax(0,1fr) 280px",
        gap: 24,
        width: "100%",
      }}
    >
      <div id="ic-doc2" style={{ display: "grid", gap: 12, alignContent: "start" }}>
        <p
          data-block-id="p"
          style={{ margin: 0, font: "400 14px/22px var(--font-sans)", color: "var(--ink-muted)" }}
        >
          {words}
        </p>
        <div style={{ display: "flex", gap: 8 }}>
          <Button
            size="sm"
            onClick={() =>
              setDraft({
                kind: "range",
                blockId: "p",
                start: words.indexOf("single"),
                end: words.indexOf("single") + 13,
                quote: "single switch",
              })
            }
          >
            Comment on “single switch”
          </Button>
          <Button size="sm" variant="ghost" onClick={() => prefix("Note: ")}>
            Type before it
          </Button>
        </div>
        {threads.map((t) =>
          t.anchor.kind === "range" ? (
            <span
              key={t.id}
              style={{ color: "var(--ink-dim)", font: "400 11px/16px var(--font-mono)" }}
            >
              {t.id}: characters {t.anchor.start} to {t.anchor.end}
            </span>
          ) : null,
        )}
      </div>
      <InlineComments
        threads={threads}
        anchorsIn="#ic-doc2"
        draft={draft}
        onCancelDraft={() => setDraft(null)}
        onCreate={(anchor, body) => {
          setThreads((all) => [
            ...all,
            {
              id: `n${all.length + 1}`,
              anchor,
              status: "open",
              comments: [{ id: `m${all.length + 1}`, author: "You", at: "Just now", body }],
            },
          ]);
          setDraft(null);
        }}
        onResolve={(id) =>
          setThreads((all) => all.map((t) => (t.id === id ? { ...t, status: "resolved" } : t)))
        }
      />
    </div>
  );
}
API → Props
PropTypeDefaultDescription
threadsInlineThread[]—{ id, anchor, status: 'open' | 'resolved', comments: { id, author, avatar?, at, body }[] }. anchor: { kind: 'block', blockId } or { kind: 'range', blockId, start, end, quote? }.
anchorsInstring | RefObject | HTMLElement—The element of the document whose [data-block-id] children are the blocks. The cards sit beside their anchors, and move when the document changes.
measure(anchor) => number | null—Where an anchor is (px from the top of the margin), instead of anchorsIn.
layout"margin" | "stack""margin"Beside the anchors, or one under the other.
filter / defaultFilter / onFilterChange"open" | "resolved" | "all""open"Which threads.
active / defaultActive / onActiveChangestring | null—The thread in front: it stays on its anchor and the others make room.
onReply(threadId, text, mentions) => void—From the box under a thread.
onResolve / onReopen(threadId) => void—The thread's buttons.
draft / onCreate / onCancelDraftStructureAnchor | null; (anchor, text, mentions) => void—A selection to comment on: a card with a box at that place.
mentionsMentionOption[]—The people @ offers in the boxes (RichComposer).
gapnumber8Space between two cards.
classNamestring—Extra classes.