Skip to content

Anchor bar

"On this page": sticky links to a long view's sections, the current one marked.

<nav class="cap-anchors" aria-label="Link states" id="anchor-states">
  <span class="cap-anchors-label" aria-hidden="true">On this page</span>
  <ul class="cap-anchors-list">
    <li><a href="#s-links">Rest</a></li>
    <li><a href="#s-links" aria-current="location">Current</a></li>
    <li><a href="#s-links">Hover</a></li>
    <li><a href="#s-links">Pressed</a></li>
  </ul>
</nav>
<nav class="cap-anchors" aria-label="Link states, comfortable" data-density="comfortable">
  <span class="cap-anchors-label" aria-hidden="true">On this page</span>
  <ul class="cap-anchors-list">
    <li><a href="#s-links">Rest</a></li>
    <li><a href="#s-links" aria-current="location">Current</a></li>
  </ul>
</nav>

Installation

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

enhance();

Usage

<nav class="cap-anchors" aria-label="On this page" data-cap="anchor-bar">
  <span class="cap-anchors-label" aria-hidden="true">On this page</span>
  <ul class="cap-anchors-list">
    <li><a href="#what-it-checks">What it checks</a></li>
    <li><a href="#thresholds">Thresholds</a></li>
    <li><a href="#when-it-alerts">When it alerts</a></li>
  </ul>
</nav>
...
<h2 id="what-it-checks">What it checks</h2>

Examples

At the top of a long page

<main class="specimen-page" tabindex="-1">
  <article data-context="prose">
    <h1>How the watcher decides a site is down</h1>
    <nav class="cap-anchors" aria-label="On this page" data-cap="anchor-bar">
      <span class="cap-anchors-label" aria-hidden="true">On this page</span>
      <ul class="cap-anchors-list">
        <li><a href="#what-it-checks">What it checks</a></li>
        <li><a href="#thresholds">Thresholds</a></li>
        <li><a href="#when-it-alerts">When it alerts</a></li>
        <li><a href="#what-it-keeps">What it keeps</a></li>
      </ul>
    </nav>
    <section>
      <h2 id="what-it-checks">What it checks</h2>
      <p>Every five minutes the watcher asks each site for its health route, a small address that answers with the commit the site is running and whether its database and its queue respond. A site with no health route is asked for its home page instead, and a 200 from there counts as alive and nothing more: it says the server answered, not that the site works.</p>
      <p>Each check records the status code, how long the answer took, and the commit it reported. The watcher runs from one region, so a slow answer can mean a slow site or a slow path between the two. It does not try to tell those apart on one check; the thresholds below look at several in a row before they say anything.</p>
      <p>Checks that time out after ten seconds are recorded as no answer, which is a state of its own and not a zero. A chart of response times leaves a gap there, hatched, so a quiet line is never mistaken for a fast one.</p>
      <p>The watcher also reads each site's deploys from its platform, so a failure that starts a few minutes after a deploy is shown beside that deploy, with a link to roll it back.</p>
    </section>
    <section>
      <h2 id="thresholds">Thresholds</h2>
      <p>One failed check is not an outage. Networks drop packets and platforms restart workers, and a person woken for each of those would soon stop reading the alerts. A site is marked degraded after two failed checks in a row, or when its median response time over the last hour is more than three times its median over the last week.</p>
      <p>A site is marked down after three failed checks in a row, which is ten to fifteen minutes depending on where in the cycle the trouble began. That delay is the price of not crying wolf, and the page says so: the time shown is when the first of the three failed, not when the third did.</p>
      <p>Thresholds are the same for every site on purpose. A site that needs a different one is a site whose health route is measuring the wrong thing, and the fix belongs there.</p>
      <p>Usage against a platform's free limits has its own thresholds: a warning at three quarters used, or sooner when the day's projection runs out before the reset, and critical at nine tenths.</p>
    </section>
    <section>
      <h2 id="when-it-alerts">When it alerts</h2>
      <p>A site going down sends one message, and a site coming back sends one more. Nothing repeats while the state holds, because a repeated alert says nothing new and teaches its reader to ignore the channel it arrives on.</p>
      <p>Degraded sends nothing on its own. It shows on the overview, worst first, with its reason in plain words, and turns into an alert only if it becomes down. Notices, such as a dependency with an update waiting, never alert and are collapsed under one row until someone opens them.</p>
      <p>Every alert names the site, what failed, when it started, and the one thing to do first, which is usually to open the site's detail and read the last three checks. An alert that cannot say what to do next is a bug in the alert.</p>
      <p>Alerts stop at night only for warnings. A site that is down is down at any hour, and the person it wakes chose that when they added it.</p>
    </section>
    <section>
      <h2 id="what-it-keeps">What it keeps</h2>
      <p>Each check is kept for seven days, which is enough to see a pattern across a week and short enough that the store stays inside the free tier. A day's checks are then folded into one row per site: how many answered, the median and the slowest response, and the commits seen.</p>
      <p>Folded rows are kept for a year. They draw the uptime strip on each site's page, one slot per day, with days the watcher itself was not running drawn hatched and labeled as no data rather than as up.</p>
      <p>Nothing the watcher keeps identifies a visitor. It asks its own questions of each site and records the answers; it never reads a site's logs or its visitors' requests.</p>
      <p>The record of each change a person makes through the Portal, a resumed job or a revoked key, is kept separately and for good, under that person's name.</p>
    </section>
  </article>
</main>

Scrolled into the third section

<main class="specimen-page" tabindex="-1">
  <article data-context="prose">
    <h1>How the watcher decides a site is down</h1>
    <nav class="cap-anchors" aria-label="On this page" data-cap="anchor-bar">
      <span class="cap-anchors-label" aria-hidden="true">On this page</span>
      <ul class="cap-anchors-list">
        <li><a href="#what-it-checks">What it checks</a></li>
        <li><a href="#thresholds">Thresholds</a></li>
        <li><a href="#when-it-alerts">When it alerts</a></li>
        <li><a href="#what-it-keeps">What it keeps</a></li>
      </ul>
    </nav>
    <section>
      <h2 id="what-it-checks">What it checks</h2>
      <p>Every five minutes the watcher asks each site for its health route, a small address that answers with the commit the site is running and whether its database and its queue respond. A site with no health route is asked for its home page instead, and a 200 from there counts as alive and nothing more: it says the server answered, not that the site works.</p>
      <p>Each check records the status code, how long the answer took, and the commit it reported. The watcher runs from one region, so a slow answer can mean a slow site or a slow path between the two. It does not try to tell those apart on one check; the thresholds below look at several in a row before they say anything.</p>
      <p>Checks that time out after ten seconds are recorded as no answer, which is a state of its own and not a zero. A chart of response times leaves a gap there, hatched, so a quiet line is never mistaken for a fast one.</p>
      <p>The watcher also reads each site's deploys from its platform, so a failure that starts a few minutes after a deploy is shown beside that deploy, with a link to roll it back.</p>
    </section>
    <section>
      <h2 id="thresholds">Thresholds</h2>
      <p>One failed check is not an outage. Networks drop packets and platforms restart workers, and a person woken for each of those would soon stop reading the alerts. A site is marked degraded after two failed checks in a row, or when its median response time over the last hour is more than three times its median over the last week.</p>
      <p>A site is marked down after three failed checks in a row, which is ten to fifteen minutes depending on where in the cycle the trouble began. That delay is the price of not crying wolf, and the page says so: the time shown is when the first of the three failed, not when the third did.</p>
      <p>Thresholds are the same for every site on purpose. A site that needs a different one is a site whose health route is measuring the wrong thing, and the fix belongs there.</p>
      <p>Usage against a platform's free limits has its own thresholds: a warning at three quarters used, or sooner when the day's projection runs out before the reset, and critical at nine tenths.</p>
    </section>
    <section>
      <h2 id="when-it-alerts">When it alerts</h2>
      <p>A site going down sends one message, and a site coming back sends one more. Nothing repeats while the state holds, because a repeated alert says nothing new and teaches its reader to ignore the channel it arrives on.</p>
      <p>Degraded sends nothing on its own. It shows on the overview, worst first, with its reason in plain words, and turns into an alert only if it becomes down. Notices, such as a dependency with an update waiting, never alert and are collapsed under one row until someone opens them.</p>
      <p>Every alert names the site, what failed, when it started, and the one thing to do first, which is usually to open the site's detail and read the last three checks. An alert that cannot say what to do next is a bug in the alert.</p>
      <p>Alerts stop at night only for warnings. A site that is down is down at any hour, and the person it wakes chose that when they added it.</p>
    </section>
    <section>
      <h2 id="what-it-keeps">What it keeps</h2>
      <p>Each check is kept for seven days, which is enough to see a pattern across a week and short enough that the store stays inside the free tier. A day's checks are then folded into one row per site: how many answered, the median and the slowest response, and the commits seen.</p>
      <p>Folded rows are kept for a year. They draw the uptime strip on each site's page, one slot per day, with days the watcher itself was not running drawn hatched and labeled as no data rather than as up.</p>
      <p>Nothing the watcher keeps identifies a visitor. It asks its own questions of each site and records the answers; it never reads a site's logs or its visitors' requests.</p>
      <p>The record of each change a person makes through the Portal, a resumed job or a revoked key, is kept separately and for good, under that person's name.</p>
    </section>
  </article>
</main>

Blocks marked data-section, a bar built from them

<main class="specimen-page" tabindex="-1">
  <h1>Overview</h1>
  <nav class="cap-anchors" aria-label="On this page" data-cap="anchor-bar"></nav>
  <section id="usage" data-section="Usage">
    <h2>Usage against free limits</h2>
    <p>Worker requests: 61,400 of 100,000 today.</p>
  </section>
  <section id="sites" data-section="Sites">
    <h2>Sites</h2>
    <p>Six sites, all up.</p>
  </section>
  <section id="deploys" data-section="Deploys">
    <h2>Deploys and downtime, 7 days</h2>
    <p>Two deploys this week, no downtime.</p>
  </section>
</main>

A short page: the bar does not show

<main class="specimen-page" tabindex="-1">
  <article data-context="prose">
    <h1>Adding a site</h1>
    <nav class="cap-anchors" aria-label="On this page" data-cap="anchor-bar">
      <span class="cap-anchors-label" aria-hidden="true">On this page</span>
      <ul class="cap-anchors-list">
        <li><a href="#before">Before you start</a></li>
        <li><a href="#steps">Steps</a></li>
      </ul>
    </nav>
    <section>
      <h2 id="before">Before you start</h2>
      <p>The site needs a health route that answers with its commit.</p>
    </section>
    <section>
      <h2 id="steps">Steps</h2>
      <p>Add its address in Settings. Its checks start on the next pass.</p>
    </section>
  </article>
</main>

Vertical, beside the sections

<main class="specimen-page" tabindex="-1">
  <div class="anchor-vertical-demo">
    <nav class="cap-anchors" aria-label="Sections" data-cap="anchor-bar" data-orientation="vertical" data-always>
      <span class="cap-anchors-label" aria-hidden="true">Sections</span>
      <ul class="cap-anchors-list">
        <li><a href="#vx-checks">What it checks</a></li>
        <li><a href="#vx-thresholds">Thresholds</a></li>
        <li><a href="#vx-alerts">When it alerts</a></li>
        <li><a href="#vx-keeps">What it keeps</a></li>
      </ul>
    </nav>
    <article data-context="prose">
      <section>
        <h2 id="vx-checks">What it checks</h2>
        <p>Each check runs every five minutes against example.com, example.org and example.net. A failing check is tried again twice before it counts.</p>
        <p>Field notes, the annual report and the release notes are checked for links and headings on every save.</p>
        <p>A check that fails three times in a row opens an incident and tells the owner by email.</p>
        <p>Every result is kept for 90 days, then summarized by day.</p>
      </section>
      <section>
        <h2 id="vx-thresholds">Thresholds</h2>
        <p>Each check runs every five minutes against example.com, example.org and example.net. A failing check is tried again twice before it counts.</p>
        <p>Field notes, the annual report and the release notes are checked for links and headings on every save.</p>
        <p>A check that fails three times in a row opens an incident and tells the owner by email.</p>
        <p>Every result is kept for 90 days, then summarized by day.</p>
      </section>
      <section>
        <h2 id="vx-alerts">When it alerts</h2>
        <p>Each check runs every five minutes against example.com, example.org and example.net. A failing check is tried again twice before it counts.</p>
        <p>Field notes, the annual report and the release notes are checked for links and headings on every save.</p>
        <p>A check that fails three times in a row opens an incident and tells the owner by email.</p>
        <p>Every result is kept for 90 days, then summarized by day.</p>
      </section>
      <section>
        <h2 id="vx-keeps">What it keeps</h2>
        <p>Each check runs every five minutes against example.com, example.org and example.net. A failing check is tried again twice before it counts.</p>
        <p>Field notes, the annual report and the release notes are checked for links and headings on every save.</p>
        <p>A check that fails three times in a row opens an incident and tells the owner by email.</p>
        <p>Every result is kept for 90 days, then summarized by day.</p>
      </section>
    </article>
  </div>
</main>

API reference

AnchorBar

PropTypeRequiredDoes
sectionsArray<{ id: string; label: string }>The view's sections, in order; each id is the id of the block or h2 it links to. Left out, the bar finds them itself, as the behavior module does: the [data-section][id] blocks of its main (else its h2[id] headings), kept in step as they come and go.
alwaysbooleanShow the bar even when the view is short or has fewer than three sections.
labelstring
orientation"horizontal" | "vertical""vertical": a list down a side column, sticky beside the sections (a long page's section nav).

Functions

FunctionSignatureDoes
scrollParent(el: Element | null | undefined): HTMLElement | nullThe nearest ancestor that scrolls, or null for the window.
sectionsIn(scope: ParentNode): HTMLElement[]What the bar links to: the blocks of the page marked data-section with an id (a panel: its data-section is the link's name), or, when there are none, its h2 headings that have one. A block inside another block is not an entry: the bar names the outer sections only (the Portal's Health holds whole panels inside its sections).
sectionLabel(section: HTMLElement): string
meetsRule(headings: Element[], scroller: HTMLElement | null, barHeight?: number): booleanThe rule: three or more sections, and a view taller than two screens. The bar's own height does not count (barHeight), or showing it could tip the rule it was shown by.
currentSection(headings: HTMLElement[], scroller: HTMLElement | null, line?: number): HTMLElement | nullThe current section: the last heading above a line 35% down the view, or the last heading once the view is scrolled to its end.
watchSections(headings: HTMLElement[], onChange: (id: string | null) => void, scroller?: HTMLElement | null): () => voidCalls onChange with the current section's id whenever it changes. Returns a function that stops watching.
goToSection(heading: HTMLElement, opts?: { push?: boolean | undefined; }): voidScrolls a section to the top, under the bar, moves focus to it, and replaces the address's hash (a click on an in-page link is not a place to go Back to). push: true adds an entry.
measureBar(nav: HTMLElement, scroller: HTMLElement | null): voidTells the page how tall the bar is, so a section scrolled to sits below it. A vertical bar sits beside the sections, not over them, so it takes no room at their top.
markSections(headings: HTMLElement[]): voidMarks the sections the bar links to, so each stops below the bar when scrolled to.
enhance(root?: ParentNode): () => voidAttaches to every [data-cap="anchor-bar"] under root. A bar with an empty list is filled from the sections in its scope (data-cap-scope, or its main) and kept in step with them. Returns a function that detaches them.

CSS variables

VariableDefault
--cap-anchors-hvar(--space-8)

Parts and data attributes

ClassIs
.cap-anchorsthe root
.cap-anchors-labela part
.cap-anchors-lista part
AttributeValues
data-cap-anchorpresent or absent
data-orientationvertical
StateRead from
:activethe platform
:focus-visiblethe platform
:hoverthe platform
[aria-current="location"]an attribute

Accessibility

KeyDoes
TabReaches each link in turn
Enter on a linkScrolls to the section and moves focus to its heading
  • A nav named "On this page"; the visible label beside the links is aria-hidden because it repeats that name.
  • aria-current="location" tells a screen reader which link is the section being read.
  • Smooth scrolling only under prefers-reduced-motion: no-preference.