@gjsify/adwaita-web 0.35.0 → 0.37.0

package/src/elements/adw-shortcut-label.ts

@@ -0,0 +1,138 @@
+// <adw-shortcut-label> — a keyboard shortcut, drawn as keycaps.
+// Attributes: accelerator (`<Control>C`, `<Shift>A Home`, `<Alt>1...9`,
+//   `Control_L&Control_R`, `<Control>C+<Control>X`), disabled-text (the
+//   placeholder shown when `accelerator` is empty).
+// Events: `notify::accelerator`, `notify::disabled-text` (CustomEvent, bubbles),
+//   mirroring the AdwShortcutLabel GObject notify signals.
+//
+// The whole parse — four nesting levels and the fixed keycap order — is
+// `@gjsify/adwaita-core`'s `parseShortcutLabel` (ADR 0004). This element only
+// turns its nodes into DOM, which is the split that keeps a second renderer from
+// re-deriving the grammar and drifting.
+//
+// TEXT, NOT MARKUP. The C builds pango markup: `&lt;` for a literal `<`, and
+// `%s <small><b>%s</b></small>` for the `L`/`R` subscript of a sided modifier
+// (adw-shortcut-label.c:195, :253-266). Core returns `{ label, sideMarker }`
+// instead, so the escaping is `textContent`'s job here and the subscript is a
+// real `<sub>` — nothing parses a markup string back apart.
+//
+// DIRECTION IS READ, NOT ASSUMED. `parse_sequence` picks its arrow from the
+// widget's text direction (:439), so the element resolves its own computed
+// direction at render time rather than defaulting to LTR.
+//
+// Reference: refs/libadwaita/src/adw-shortcut-label.c
+// Reference: refs/libadwaita/src/stylesheet/widgets/_shortcuts-dialog.scss:33-58
+// Copyright (c) GNOME contributors (libadwaita). LGPLv2.1+.
+// Modifications: Implemented as a Web Component for @gjsify/adwaita-web.
+
+import { parseShortcutLabel } from '@gjsify/adwaita-core';
+
+export class AdwShortcutLabel extends HTMLElement {
+    private _initialized = false;
+
+    static get observedAttributes() {
+        return ['accelerator', 'disabled-text'];
+    }
+
+    connectedCallback() {
+        if (!this._initialized) {
+            this._initialized = true;
+            // `GTK_ACCESSIBLE_ROLE_LABEL` (:88). The accessible NAME is set from
+            // the parse below, because the keycaps read as a pile of single
+            // letters otherwise.
+            if (!this.hasAttribute('role')) this.setAttribute('role', 'img');
+        }
+        this._render();
+    }
+
+    attributeChangedCallback(name: string) {
+        if (!this._initialized) return;
+        this._render();
+        this.dispatchEvent(new CustomEvent(`notify::${name}`, { bubbles: true }));
+    }
+
+    get accelerator(): string {
+        return this.getAttribute('accelerator') ?? '';
+    }
+
+    set accelerator(value: string) {
+        this.setAttribute('accelerator', value);
+    }
+
+    get disabledText(): string {
+        return this.getAttribute('disabled-text') ?? '';
+    }
+
+    set disabledText(value: string) {
+        this.setAttribute('disabled-text', value);
+    }
+
+    private _render() {
+        const { nodes, accessibleLabel, error } = parseShortcutLabel(this.accelerator, {
+            disabledText: this.disabledText,
+            direction: this._direction(),
+        });
+
+        this.replaceChildren(...nodes.map((node) => this._nodeElement(node)));
+        this.setAttribute('aria-label', accessibleLabel);
+
+        // `g_warning ("Failed to parse %s, part of accelerator '%s'")` (:532).
+        // The partial render is upstream's too — it keeps what it built.
+        if (error) {
+            console.warn(`adw-shortcut-label: failed to parse ${error}, part of accelerator '${this.accelerator}'`);
+        }
+    }
+
+    /**
+     * The rendered direction, which is what the sequence arrow follows.
+     *
+     * `getComputedStyle` is the only thing that sees an inherited `dir` — the
+     * attribute alone is set on an ancestor most of the time. A detached element
+     * has no computed style to read, so the attribute is the fallback.
+     */
+    private _direction(): 'ltr' | 'rtl' {
+        const computed = this.isConnected ? getComputedStyle(this).direction : '';
+        if (computed === 'rtl' || computed === 'ltr') return computed;
+        return this.closest('[dir="rtl"]') ? 'rtl' : 'ltr';
+    }
+
+    private _nodeElement(node: ReturnType<typeof parseShortcutLabel>['nodes'][number]): HTMLElement {
+        if (node.kind === 'separator' || node.kind === 'disabled') {
+            // `dim_label` (:359-368) — both the separators and the placeholder,
+            // which upstream tells apart only by position (a placeholder is the
+            // only child). The extra class on the placeholder is this port's:
+            // `.dimmed` still applies, and a consumer can now style the
+            // "no shortcut" state without matching on child count.
+            const label = document.createElement('span');
+            label.className = node.kind === 'disabled' ? 'dimmed adw-shortcut-label-disabled' : 'dimmed';
+            label.textContent = node.text;
+            return label;
+        }
+
+        // One combination is one BOX of keycaps, LTR even in an RTL context
+        // (:375-380): the modifier order is a property of the shortcut, not of
+        // the surrounding text.
+        const box = document.createElement('span');
+        box.className = 'adw-shortcut-label-keys';
+        box.setAttribute('dir', 'ltr');
+
+        for (const key of node.keys) {
+            const cap = document.createElement('span');
+            cap.className = 'keycap';
+            cap.textContent = key.label;
+
+            if (key.sideMarker) {
+                const marker = document.createElement('sub');
+                marker.className = 'adw-shortcut-label-side';
+                marker.textContent = key.sideMarker;
+                cap.append(marker);
+            }
+
+            box.append(cap);
+        }
+
+        return box;
+    }
+}
+
+customElements.define('adw-shortcut-label', AdwShortcutLabel);

package/src/elements/adw-sidebar.ts

@@ -7,16 +7,15 @@
 // chevron arrow on each row (the AdwPreferencesPage look the native widget
 // switches to when collapsed).
 //
-// The BEHAVIOUR — the flat index space, the out-of-range rule, which section
-// headers render, the selection-vs-activation split, the filter and the empty
-// state — is HEADLESS and lives in `@gjsify/adwaita-core` (ADR 0004) as
-// {@link SidebarState}; this element only builds DOM for it and re-emits its
-// changes as events. It used to carry its own copy, which clamped an
-// out-of-range `selected` to the LAST row where libadwaita drops the selection
-// entirely, keyed section headers off the DECLARATION index instead of the rows
-// that actually render, and froze the row list after the first connect. The
-// shared vectors in `@gjsify/adwaita-core/conformance` now pin this element to
-// the C source — see `src/adw-sidebar.spec.ts`.
+// The BEHAVIOUR — the flat index space, the out-of-range rule, which section headers
+// render, the selection-vs-activation split, the filter and the empty state — is
+// HEADLESS and lives in `@gjsify/adwaita-core` (ADR 0004) as {@link SidebarState}; this
+// element only builds DOM for it and re-emits its changes as events, pinned to the C
+// source by the shared vectors in `@gjsify/adwaita-core/conformance` (see
+// `src/adw-sidebar.spec.ts`). Three rules a hand-written copy gets wrong: an
+// out-of-range `selected` DROPS the selection rather than clamping to the last row,
+// section headers are keyed off the rows that actually RENDER and not the declaration
+// index, and the row list stays live after the first connect.
 //
 // Sub-elements (declared as children, consumed at connect time — mirrors
 // adw-tab-page in adw-tab-view):
@@ -59,12 +58,10 @@ import {
 
 import { createAdwIcon } from './adw-icon.js';
 
-// The sidebar consumes its declared children and drops them from the tree, so a
-// later `setAttribute` on one cannot find its sidebar with `closest()`. These
-// keep the link — the web stand-in for the `g_object_bind_property` /
-// `notify::icon-name` bindings that keep a live AdwSidebarItem's labels in sync
-// (adw-sidebar.c:1393-1421). Before this, `observedAttributes` was declared on
-// both child elements and no `attributeChangedCallback` existed to answer it.
+// The sidebar consumes its declared children and drops them from the tree, so a later
+// `setAttribute` on one cannot find its sidebar with `closest()`. These keep the link —
+// the web stand-in for the `g_object_bind_property` / `notify::icon-name` bindings that
+// keep a live AdwSidebarItem's labels in sync.
 const itemBindings = new WeakMap<AdwSidebarItem, { sidebar: AdwSidebar; spec: AdwSidebarItemSpec }>();
 const sectionBindings = new WeakMap<AdwSidebarSection, { sidebar: AdwSidebar; spec: AdwSidebarSectionSpec }>();
 
@@ -116,7 +113,6 @@ export class AdwSidebar extends HTMLElement {
         return ['mode', 'selected'];
     }
 
-    /** Zero-based flat index of the selected item, or -1 for no selection. */
     get selected(): number {
         return this._state.selected;
     }
@@ -130,7 +126,6 @@ export class AdwSidebar extends HTMLElement {
         return this._state.selectedItem;
     }
 
-    /** 'sidebar' (flat navigation list) or 'page' (boxed lists). */
     get mode(): 'sidebar' | 'page' {
         return this._state.mode;
     }
@@ -171,10 +166,10 @@ export class AdwSidebar extends HTMLElement {
         // asked to hear about, and `setSections` runs the 0 → n auto-select.
         this._state.setSections(this._readDeclaredSections());
         this._state.setMode(this._readModeAttr());
-        // A declared `selected` wins over that auto-select. libadwaita would let
-        // the auto-select clobber a builder-set property (items arrive after
-        // properties, and items_changed_cb then selects 0); for a declarative
-        // element the authored attribute has to survive its own children.
+        // A declared `selected` wins over that auto-select. libadwaita lets the
+        // auto-select clobber a builder-set property (items arrive after properties, and
+        // `items_changed_cb` then selects 0); for a declarative element the authored
+        // attribute has to survive its own children.
         if (this.hasAttribute('selected')) this._state.setSelected(this._readSelectedAttr());
 
         this._state.subscribe((change) => this._onSelectionChanged(change));
@@ -190,8 +185,8 @@ export class AdwSidebar extends HTMLElement {
 
         if (name === 'selected') {
             this._state.setSelected(this._readSelectedAttr());
-            // Normalise even when nothing moved, so `selected="5"` on a 3-item
-            // sidebar does not keep claiming 5 while the property reads -1.
+            // Normalise even when nothing moved, so `selected="5"` on a 3-item sidebar
+            // does not keep claiming 5 while the property reads -1.
             this._reflectSelected();
             return;
         }
@@ -202,9 +197,9 @@ export class AdwSidebar extends HTMLElement {
     }
 
     /**
-     * Re-derive after a declared `<adw-sidebar-item>` / `<adw-sidebar-section>`
-     * attribute changed. The item model keeps its shape, so the selection cannot
-     * move — exactly like the GObject property bindings this stands in for.
+     * Re-derive after a declared `<adw-sidebar-item>` / `<adw-sidebar-section>` attribute
+     * changed. The item model keeps its shape, so the selection cannot move — exactly
+     * like the GObject property bindings this stands in for.
      */
     refresh(): void {
         if (!this._initialized) return;
@@ -212,7 +207,6 @@ export class AdwSidebar extends HTMLElement {
         this._rebuild();
     }
 
-    /** Snapshot the declared children into specs, and bind them for live updates. */
     private _readDeclaredSections(): AdwSidebarSectionSpec[] {
         const sections: AdwSidebarSectionSpec[] = [];
 
@@ -245,8 +239,8 @@ export class AdwSidebar extends HTMLElement {
 
     /**
      * `parseFloat`, not `parseInt`: the core rejects a fractional position, and
-     * truncating `"1.5"` to row 1 here would hide that from it. An unparseable
-     * value is NaN, which the core turns into "no selection".
+     * truncating `"1.5"` to row 1 here would hide that from it. An unparseable value is
+     * NaN, which the core turns into "no selection".
      */
     private _readSelectedAttr(): number {
         return Number.parseFloat(this.getAttribute('selected') ?? '');
@@ -269,13 +263,11 @@ export class AdwSidebar extends HTMLElement {
         );
     }
 
-    /** Click handler — the core applies the selection, then `activated` fires. */
     private _activate(index: number): void {
         if (!this._state.activate(index).activated) return;
         this.dispatchEvent(new CustomEvent('activated', { bubbles: true, detail: { index } }));
     }
 
-    /** Rebuild the rendered rows + headers from the core's derived model. */
     private _rebuild(): void {
         const headers = new Map<number, SidebarHeaderSpec>();
         for (const header of this._state.headers) headers.set(header.sectionIndex, header);
@@ -335,9 +327,9 @@ export class AdwSidebar extends HTMLElement {
         row.type = 'button';
         row.className = 'adw-sidebar-item';
         row.setAttribute('role', 'option');
-        // `visible` / `enabled` are bound to the row's `visible` / `sensitive`
-        // in create_row (adw-sidebar.c:1382-1383): the row still EXISTS and still
-        // owns its flat index, it just does not show or respond.
+        // `visible` / `enabled` are bound to the row's `visible` / `sensitive` in
+        // `create_row`: the row still EXISTS and still owns its flat index, it just does
+        // not show or respond.
         row.hidden = item.visible === false;
         row.disabled = item.enabled === false;
 
@@ -362,8 +354,8 @@ export class AdwSidebar extends HTMLElement {
 
         row.appendChild(textEl);
 
-        // Page mode adds a trailing chevron on every row, the way the
-        // boxed-list AdwActionRow carries a `go-next-symbolic` arrow.
+        // Page mode adds a trailing chevron on every row, the way the boxed-list
+        // AdwActionRow carries a `go-next-symbolic` arrow.
         row.appendChild(createAdwIcon('go-next', 'adw-sidebar-item-arrow'));
 
         row.addEventListener('click', () => this._activate(flat.index));
@@ -379,8 +371,8 @@ export class AdwSidebar extends HTMLElement {
 
     private _applySelection(): void {
         const selected = this._state.selected;
-        // Page mode tracks the selection but never paints it (adw-sidebar.c:2948-2951):
-        // its rows are plain boxed-list AdwActionRows with no selected state.
+        // Page mode tracks the selection but never paints it: its rows are plain
+        // boxed-list AdwActionRows with no selected state.
         const paint = this._state.selectionVisible;
 
         this._rows.forEach((row, position) => {

package/src/elements/adw-spin-row.ts

@@ -1,15 +1,10 @@
-// <adw-spin-row> — Row with a title/subtitle and a numeric spin control (+/− buttons).
-// Attributes: title, subtitle, min, max, step, value
-// Events: notify::value (CustomEvent, mirrors GJS GObject signal naming)
+// <adw-spin-row> — row with a title/subtitle and a numeric spin control (+/− buttons).
 //
-// The ADJUSTMENT state machine (value/min/max/step plus the clamp-on-every-
-// mutation and the change detection) is HEADLESS and lives in
-// `@gjsify/adwaita-core` (ADR 0004) as {@link SpinState}; this element composes it
-// and keeps only the DOM render half — the −/input/+ control, the step-precision
-// display (the `Adw.SpinRow:digits` concern, which belongs to the widget, not to
-// the adjustment) and the `notify::value` event.
-// `@gjsify/adwaita-nativescript` composes the same state machine, so both ports
-// share one behaviour.
+// The ADJUSTMENT state machine (value/min/max/step plus the clamp-on-every-mutation and
+// the change detection) is HEADLESS and lives in `@gjsify/adwaita-core` (ADR 0004) as
+// {@link SpinState}; this element keeps only the DOM half — the −/input/+ control, the
+// step-precision display (the `Adw.SpinRow:digits` concern, which belongs to the widget
+// rather than to the adjustment) and the `notify::value` event.
 //
 // Adapted from Adwaita Web UI Framework (https://github.com/mclellac/adwaita-web).
 // Copyright (c) 2025 csm. MIT License.
@@ -61,7 +56,6 @@ export class AdwSpinRow extends HTMLElement {
         this._subtitleEl.className = 'adw-row-subtitle';
         text.append(this._titleEl, this._subtitleEl);
 
-        // Spin control container
         const control = document.createElement('div');
         control.className = 'adw-spin-control';
 
@@ -123,8 +117,7 @@ export class AdwSpinRow extends HTMLElement {
     }
 
     private _renderText() {
-        // The `string_is_not_empty` label rule, from core — this block was one of
-        // six hand-rolled copies, all of which omitted the TITLE half.
+        // The `string_is_not_empty` label rule, from core — it hides the TITLE too.
         const labels = deriveRowLabels({
             title: this.getAttribute('title'),
             subtitle: this.getAttribute('subtitle'),

package/src/elements/adw-spinner.ts

@@ -1,27 +1,21 @@
 // <adw-spinner> — A continuously-spinning loading indicator.
 // Attributes: size (px; the BOX, floored at the measured minimum 16).
 //
-// THE BOX AND THE RING ARE DIFFERENT THINGS. `adw_spinner_measure`
-// (adw-spinner.c:78-81) reports MIN_SIZE as both minimum and natural and has no
-// upper bound — `MAX_SIZE` at :15 is defined and never referenced — while
-// `adw_spinner_snapshot` (:95-99) hands the widget's real width and height to
-// the paintable, which caps only `radius` (adw-spinner-paintable.c:343) and
-// still centres on the box (:349-351). So `size="200"` occupies 200px of layout
-// and draws a 64px ring in the middle. This element used to BE the ring, which
-// is why its suite asserted the opposite of the core's `SPINNER_SIZE_VECTORS`.
+// THE BOX AND THE RING ARE DIFFERENT THINGS. `adw_spinner_measure` reports MIN_SIZE as
+// both minimum and natural and has no upper bound, while `adw_spinner_snapshot` hands
+// the widget's real size to the paintable, which caps only `radius` and still centres on
+// the box. So `size="200"` occupies 200px of layout and draws a 64px ring in the middle.
 //
-// THE ARC IS NOT A ROTATING QUARTER-CIRCLE. It extends, overlaps, contracts and
-// idles on an ease-in-out-sine while the figure turns; the arithmetic is
-// `@gjsify/adwaita-core`'s `spinnerArc`, shared with the vectors that judge it.
-// Expressing that needs a per-frame value, so this element draws an SVG arc and
-// advances it from one module-level ticker — not one timer per spinner. CSS
-// keyframes cannot express it: a `border-top-color` chase is a fixed 90 degrees,
-// which is what this element drew for its whole life.
+// THE ARC IS NOT A ROTATING QUARTER-CIRCLE. It extends, overlaps, contracts and idles on
+// an ease-in-out-sine while the figure turns; the arithmetic is `@gjsify/adwaita-core`'s
+// `spinnerArc`, shared with the vectors that judge it. That needs a per-frame value, so
+// this element draws an SVG arc and advances it from one module-level ticker. CSS
+// keyframes cannot express it — a `border-top-color` chase is a fixed 90 degrees.
 //
-// IT KEEPS SPINNING UNDER REDUCED MOTION. `adw_spinner_paintable_set_widget`
-// calls `adw_animation_set_follow_enable_animations_setting (…, FALSE)` (:537)
-// — deliberately, because a frozen busy indicator reads as a hang. The old
-// `@media (prefers-reduced-motion: reduce) { animation: none }` did exactly that.
+// IT KEEPS SPINNING UNDER REDUCED MOTION, deliberately: a frozen busy indicator reads as
+// a hang, which is why `adw_spinner_paintable_set_widget` calls
+// `adw_animation_set_follow_enable_animations_setting (…, FALSE)`. Do not reintroduce a
+// `@media (prefers-reduced-motion: reduce) { animation: none }` rule for it.
 //
 // Reference: refs/libadwaita/src/adw-spinner.c (MIN_SIZE, adw_spinner_measure, the a11y role)
 // Reference: refs/libadwaita/src/adw-spinner-paintable.c (the animation + geometry)
@@ -42,10 +36,9 @@ const SVG_NS = 'http://www.w3.org/2000/svg';
 /**
  * Every mapped spinner, driven by ONE `requestAnimationFrame` loop.
  *
- * The C animates per widget off the frame clock, which costs nothing extra
- * because the clock is already ticking. A browser has no such clock, so the
- * equivalent is one shared rAF: N spinners on a page must not mean N loops, and
- * the loop must not exist at all while none are mapped.
+ * The C animates per widget off the frame clock, which costs nothing extra because the
+ * clock is already ticking. A browser has no such clock, so the equivalent is one shared
+ * rAF: N spinners must not mean N loops, and the loop must not exist while none are mapped.
  */
 const mapped = new Set<AdwSpinner>();
 let frameHandle = 0;
@@ -76,8 +69,8 @@ export class AdwSpinner extends HTMLElement {
 
     connectedCallback() {
         this._build();
-        // `widget_map_cb` (adw-spinner-paintable.c:181-185) plays the animation
-        // on MAP, not on construction: an off-screen spinner burns nothing.
+        // `widget_map_cb` plays the animation on MAP, not on construction: an off-screen
+        // spinner burns nothing.
         mapped.add(this);
         this._origin = null;
         startTicking();
@@ -92,11 +85,9 @@ export class AdwSpinner extends HTMLElement {
     }
 
     /**
-     * Draw the frame for `now`, in `requestAnimationFrame` timebase.
-     *
-     * Public because the shared ticker is a module-level function rather than a
-     * method — and because a test needs to place the spinner at a known moment
-     * without waiting for real frames.
+     * Draw the frame for `now`, in `requestAnimationFrame` timebase. Public because the
+     * shared ticker is a module-level function, and because a test needs to place the
+     * spinner at a known moment without waiting for real frames.
      */
     drawAt(now: number): void {
         if (this._origin === null) this._origin = now;
@@ -107,19 +98,18 @@ export class AdwSpinner extends HTMLElement {
         if (this._svg) return;
         const svg = document.createElementNS(SVG_NS, 'svg');
         svg.setAttribute('fill', 'none');
-        // The ring is decorative; the ROLE is on the host, per adw-spinner.c:124.
+        // The ring is decorative; the ROLE is on the host.
         svg.setAttribute('aria-hidden', 'true');
 
         const track = document.createElementNS(SVG_NS, 'circle');
         track.setAttribute('stroke', 'currentColor');
-        // `CIRCLE_OPACITY` of the WIDGET's colour (adw-spinner-paintable.c:367-369),
-        // not a hardcoded grey — so the track follows the text colour everywhere.
+        // C's `CIRCLE_OPACITY` of the WIDGET's colour, not a hardcoded grey, so the track
+        // follows the text colour everywhere.
         track.setAttribute('stroke-opacity', String(ADW_SPINNER_TRACK_OPACITY));
 
         const arc = document.createElementNS(SVG_NS, 'circle');
         arc.setAttribute('stroke', 'currentColor');
-        // `GSK_LINE_CAP_ROUND` (adw-spinner-paintable.c:354). The port's
-        // `border-top-color` ends were square-cut, visible from 48px up.
+        // C's `GSK_LINE_CAP_ROUND`; square-cut ends are visible from 48px up.
         arc.setAttribute('stroke-linecap', 'round');
 
         svg.append(track, arc);
@@ -128,9 +118,8 @@ export class AdwSpinner extends HTMLElement {
         this._arc = arc;
         this.replaceChildren(svg);
 
-        // `gtk_widget_class_set_accessible_role (…, PROGRESS_BAR)` (adw-spinner.c:124)
-        // and `GTK_ACCESSIBLE_STATE_BUSY, TRUE` (:139-141). A repo-wide grep for
-        // either found ZERO hits before this: screen readers announced nothing.
+        // C's `gtk_widget_class_set_accessible_role (…, PROGRESS_BAR)` plus
+        // `GTK_ACCESSIBLE_STATE_BUSY, TRUE`; without both, screen readers announce nothing.
         this.setAttribute('role', 'progressbar');
         this.setAttribute('aria-busy', 'true');
 
@@ -154,8 +143,7 @@ export class AdwSpinner extends HTMLElement {
         svg.setAttribute('height', String(diameter));
         svg.setAttribute('viewBox', `0 0 ${diameter} ${diameter}`);
 
-        // The stroke is centred on the path, so the circle sits half a stroke in
-        // — `radius - line_width / 2` (adw-spinner-paintable.c:364).
+        // The stroke is centred on the path, so the circle sits half a stroke in.
         const radius = (diameter - lineWidth) / 2;
         this._radius = radius;
         this._circumference = 2 * Math.PI * radius;
@@ -180,9 +168,9 @@ export class AdwSpinner extends HTMLElement {
         const { end, length } = spinnerArc(progress);
         const drawn = length * this._radius;
         arc.setAttribute('stroke-dasharray', `${drawn} ${Math.max(this._circumference - drawn, 0)}`);
-        // An SVG circle's path starts at 3 o'clock and runs clockwise, which is
-        // the same origin and direction the C's angles use — so a radian is a
-        // path distance and the dash only has to be shifted to `end`.
+        // An SVG circle's path starts at 3 o'clock and runs clockwise, the same origin and
+        // direction as the C's angles, so a radian is a path distance and the dash only
+        // has to be shifted to `end`.
         arc.setAttribute('stroke-dashoffset', String(-end * this._radius));
     }
 }