Skip to content

Annotated document

An edited text shown as original, edit or every change, beside a rail of notes that light passages.

<div class="cap-annotated" data-cap="annotated" id="ad-edited">
  <fieldset class="cap-seg cap-annotated-view">
    <legend class="cap-sr-only">Markup view</legend>
    <div class="cap-seg-options">
      <label><input type="radio" name="ad-view" value="original" /> Original</label>
      <label><input type="radio" name="ad-view" value="edited" checked /> Simple markup</label>
      <label><input type="radio" name="ad-view" value="all" /> All markup</label>
    </div>
  </fieldset>
  <div class="cap-annotated-layout">
    <div class="cap-annotated-doc" role="region" aria-label="Document" tabindex="0">
      <h3>Release notes</h3>
      <p>
        <mark data-note="n1" data-tone="info">This release <del>makes a lot of improvements to</del><ins>speeds up</ins> the export</mark>, which now finishes in
        under a minute for most accounts. <ins>Exports you saved before the upgrade stay where they were.</ins>
      </p>
      <p>
        The retention window is <mark data-note="n2" data-tone="ok"><del>about a month</del><ins>30 days</ins></mark>. After it ends, logs are deleted and
        cannot be restored, <mark data-note="n3" data-tone="crit">so export anything you need to keep</mark>.
      </p>
      <p>Questions go to <mark data-note="n2" data-tone="ok">the address on the account</mark>.</p>
    </div>
    <ul class="cap-annotated-notes" aria-label="Notes">
      <li>
        <button type="button" class="cap-annotated-note" data-note="n1" data-tone="info">
          <span class="cap-annotated-note-icon" aria-hidden="true">E</span>
          <span class="cap-annotated-note-kind">Editorial</span>
          <span class="cap-annotated-note-text">Say what got better, not that something did.</span>
        </button>
      </li>
      <li>
        <button type="button" class="cap-annotated-note" data-note="n2" data-tone="ok">
          <span class="cap-annotated-note-icon" aria-hidden="true">P</span>
          <span class="cap-annotated-note-kind">Precision</span>
          <span class="cap-annotated-note-text">Give the exact window, and say where questions go.</span>
        </button>
      </li>
      <li>
        <button type="button" class="cap-annotated-note" data-note="n3" data-tone="crit">
          <span class="cap-annotated-note-icon" aria-hidden="true">R</span>
          <span class="cap-annotated-note-kind">Risk</span>
          <span class="cap-annotated-note-text">A deletion that cannot be undone needs its warning in the same sentence.</span>
        </button>
      </li>
    </ul>
  </div>
</div>

Installation

// package.json: "capsomer": "github:DrDustinEdwards/capsomer#v0.152.2"
import "capsomer/tokens.css";
import "capsomer/base.css";
import "capsomer/annotated-document.css";
import { enhance } from "capsomer/behavior/annotated-document";

enhance();

Usage

<div class="cap-annotated" data-cap="annotated">
  <fieldset class="cap-seg cap-annotated-view">
    <legend class="cap-sr-only">Markup view</legend>
    <div class="cap-seg-options">
      <label><input type="radio" name="view" value="original" /> Original</label>
      <label><input type="radio" name="view" value="edited" checked /> Simple markup</label>
      <label><input type="radio" name="view" value="all" /> All markup</label>
    </div>
  </fieldset>
  <div class="cap-annotated-layout">
    <div class="cap-annotated-doc" role="region" aria-label="Document" tabindex="0">
      <p><mark data-note="n1" data-tone="info"><del>about a month</del><ins>30 days</ins></mark></p>
    </div>
    <ul class="cap-annotated-notes" aria-label="Notes">
      <li>
        <button type="button" class="cap-annotated-note" data-note="n1" data-tone="info">
          <span class="cap-annotated-note-icon" aria-hidden="true">E</span>
          <span class="cap-annotated-note-kind">Editorial</span>
          <span class="cap-annotated-note-text">Give the exact window.</span>
        </button>
      </li>
    </ul>
  </div>
</div>

Examples

Every change marked

<div class="cap-annotated" data-cap="annotated" id="ad-all">
  <fieldset class="cap-seg cap-annotated-view">
    <legend class="cap-sr-only">Markup view</legend>
    <div class="cap-seg-options">
      <label><input type="radio" name="ad-view-2" value="original" /> Original</label>
      <label><input type="radio" name="ad-view-2" value="edited" /> Simple markup</label>
      <label><input type="radio" name="ad-view-2" value="all" checked /> All markup</label>
    </div>
  </fieldset>
  <div class="cap-annotated-layout">
    <div class="cap-annotated-doc" role="region" aria-label="Document, every change" tabindex="0">
      <p>The retention window is <mark data-note="m1" data-tone="ok"><del>about a month</del><ins>30 days</ins></mark>.</p>
    </div>
    <ul class="cap-annotated-notes" aria-label="Notes, every change">
      <li>
        <button type="button" class="cap-annotated-note" data-note="m1" data-tone="ok">
          <span class="cap-annotated-note-kind">Precision</span>
          <span class="cap-annotated-note-text">Give the exact window.</span>
        </button>
      </li>
    </ul>
  </div>
</div>

Kinds in their tones, the control centered, no notes in the original

<div class="cap-annotated" data-cap="annotated" data-hide-notes="original" data-view-align="center" data-kind="tone" id="ad-tone">
  <fieldset class="cap-seg cap-annotated-view">
    <legend class="cap-sr-only">Markup view</legend>
    <div class="cap-seg-options">
      <label><input type="radio" name="ad-view-3" value="original" checked /> Original</label>
      <label><input type="radio" name="ad-view-3" value="edited" /> Simple markup</label>
      <label><input type="radio" name="ad-view-3" value="all" /> All markup</label>
    </div>
  </fieldset>
  <div class="cap-annotated-layout">
    <div class="cap-annotated-doc" role="region" aria-label="Document, in tones" tabindex="0">
      <p>Files are kept for <mark data-note="t1" data-tone="warn"><del>a while</del><ins>30 days</ins></mark> and then deleted.</p>
    </div>
    <ul class="cap-annotated-notes" aria-label="Notes, in tones">
      <li>
        <button type="button" class="cap-annotated-note" data-note="t1" data-tone="warn">
          <span class="cap-annotated-note-icon" aria-hidden="true">E</span>
          <span class="cap-annotated-note-kind">Editorial</span>
          <span class="cap-annotated-note-text">Say how long.</span>
        </button>
      </li>
    </ul>
  </div>
</div>

API reference

AnnotatedDocument

PropTypeRequiredDoes
childrenReactNodeYesThe document: prose with ins, del and <mark data-note="…" data-tone="…"> passages.
notesAnnotatedNote[]Yes
namestringThe radios' name. Default: one made up, so two documents on a page do not share a group.
labelstring
views{ original: string; edited: string; all: string }
view"original" | "edited" | "all"The view shown first.
docLabelstring
notesLabelstring
hideNotesInOriginalbooleanThe original shows the text alone, with no notes beside it.
viewAlign"center" | "end"The view control's place over the document. Omitted: the start.
kind"tone""tone": each note's kind and icon take its tone's color. Omitted: the kind muted, the icon on a tint.

Functions

FunctionSignatureDoes
bring(box: HTMLElement, target: HTMLElement, margin: number): voidScrolls box (a scroll container) so target sits near its top, without moving the page.
enhance(root?: ParentNode): () => void

CSS variables

VariableDefault
--cap-annotated-h32rem
--cap-annotated-softvar(--accent-soft)
--cap-annotated-tonevar(--accent)

Parts and data attributes

ClassIs
.cap-annotatedthe root
.cap-annotated-doca part
.cap-annotated-layouta part
.cap-annotated-notea part
.cap-annotated-note-icona part
.cap-annotated-note-kinda part
.cap-annotated-note-texta part
.cap-annotated-notesa part
.cap-annotated-viewa part
AttributeValues
data-hide-notesoriginal
data-kindtone
data-litpresent or absent
data-tonecrit info ok warn
data-view-aligncenter end
StateRead from
:checkedthe platform
:focus-visiblethe platform
:hoverthe platform
[aria-pressed="true"]an attribute

Accessibility

KeyDoes
Arrow keysChange the view
TabInto the document (to scroll it), then from note to note
Enter, Space on a noteLight its passages, or turn it off
  • Passages are a tinted ground with a tone underline, and a ring when lit, not color alone; forced colors: Mark and Highlight.
  • Insertions in the marked view are underlined and deletions struck through, as well as colored.