@fusion.dev/helix-headless 0.1.0 → 0.3.0

package/dist/dialog/root/dialog-root.js

@@ -7,72 +7,10 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { CommandController, customElement, HelixElement, hostAria, MixinControllerOpen, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
-/**
- * @summary A modal window, on the platform's own dialog.
- *
- * @description
- * A real `<dialog>` opened with `showModal()`, not a div with a role and a
- * hand-built trap. The platform gives four things that are each a day's work to
- * reimplement and easy to get subtly wrong: the top layer, so the dialog is
- * above everything regardless of what `z-index` anyone else wrote; a real
- * backdrop; Escape; and inert-behind, so the page underneath is not reachable
- * by pointer, keyboard, or a screen reader's virtual cursor.
- *
- * **`open` drives `showModal()`, and every way it can close comes back through
- * `requestOpen`.** A native dialog can close from three directions: the
- * property, Escape, and a `<form method="dialog">` submit inside it. Left
- * alone, two of those would shut the dialog while the consumer's state still
- * said open, which is the bug that makes a modal impossible to reopen. Escape
- * is intercepted and routed through the request, so `preventDefault()` on the
- * `helix-before-close` refuses it; a close that happens anyway is reflected back.
- *
- * **Nothing here traps focus.** `showModal()` does it, and better: `inert` on
- * the rest of the document is something no JavaScript trap can achieve.
- * `FocusTrapController` stays for the surfaces that are not modal.
- *
- * The regions are bare slots rather than wrappers, for the reason the card's
- * are: an unassigned `<slot>` is `display: contents` and generates no box, so a
- * dialog with no footer has no empty band where one would be.
- *
- * Opened declaratively with the platform's invoker attributes:
- *
- * ```html
- * <helix-button commandfor="confirm" command="--show">Delete…</helix-button>
- * <helix-dialog id="confirm">…</helix-dialog>
- * ```
- *
- * `--show`, `--close` and `--toggle`. Custom commands rather than the built-in
- * `show-modal`, because those are defined against native elements and do
- * nothing when pointed at a custom one.
- *
- * @since 0.1.0
- * @status stable
- * @category overlays
- * @aliases Modal, Lightbox, Sheet
- * @documentation https://helix.fusion.dev/components/dialog
- *
- * @slot - The dialog's content.
- * @slot footer - The actions.
- * @slot header - The title, and anything beside it.
- * @slot icon - A single mark above the title, for a dialog that warns.
- *
- * @event {Event} close - Relayed, because the platform's own does not escape.
- * @event {HelixBeforeCloseEvent} helix-before-close - Fired before it closes, and cancelable.
- * @event {HelixBeforeOpenEvent} helix-before-open - Fired before it opens, and cancelable.
- * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
- *
- * @csspart dialog - The native dialog element.
- */
 let HelixHeadlessDialog = class HelixHeadlessDialog extends MixinControllerOpen(HelixElement) {
     constructor() {
         super(...arguments);
-        /**
-         * Accessible name for the dialog.
-         */
         this.label = '';
-        /* Opened and closed from anywhere on the page, without a line of script:
-           `<helix-button commandfor="…" command="--show">`. See `CommandController`
-           for why this is the platform's invoker rather than a `data-` recipe. */
         this.commands = new CommandController(this, {
             commands: {
                 '--close': () => this.close(),
@@ -80,28 +18,8 @@ let HelixHeadlessDialog = class HelixHeadlessDialog extends MixinControllerOpen(
                 '--toggle': () => this.toggleOpen(),
             },
         });
-        /**
-         * Whether Escape or a press on the backdrop can close it.
-         *
-         * Off for a dialog that must be answered. It does not disable the close
-         * control a consumer slots in: refusing to be dismissed is not the same as
-         * refusing to be closed, and a dialog with no way out at all is a trap.
-         *
-         * A persistent dialog does not ignore that press. It answers it: see
-         * `refuse`, which is the only way a dialog that will not be dismissed can say
-         * so at the moment a reader asks.
-         */
         this.persistent = false;
-        /** What a value set before the element existed is kept in. */
         this.returned = '';
-        /**
-         * Escape, intercepted so it is a request rather than an act.
-         *
-         * The native `cancel` event fires before the dialog closes, so preventing it
-         * leaves the dialog open and lets `requestOpen` decide. Without this a reader
-         * pressing Escape would close a dialog its consumer had said was open, and
-         * the two would disagree until something else moved.
-         */
         this.handleCancel = (event) => {
             event.preventDefault();
             if (this.persistent) {
@@ -109,39 +27,12 @@ let HelixHeadlessDialog = class HelixHeadlessDialog extends MixinControllerOpen(
             }
             this.requestOpen(false);
         };
-        /**
-         * A close that happened anyway, reflected back.
-         *
-         * `<form method="dialog">` closes the dialog directly and there is no event
-         * to prevent. Rather than fight it, the state follows: the dialog is shut, so
-         * saying otherwise would be a lie the next `showModal()` would trip over.
-         */
         this.handleClose = (event) => {
             if (this.open) {
                 this.requestOpen(false);
             }
-            /* And under the platform's own name, from the host. `close` on a `<dialog>`
-               neither bubbles nor is composed, so the one the browser just fired reaches
-               nobody outside this shadow root, which is the same reason `Avatar` relays
-               `load`. Announced after the state has moved, so a consumer binding
-               `onClose` reads a dialog that is already shut.
-        
-               `cancel` is deliberately not relayed. `handleCancel` prevents it so that
-               Escape is a request rather than an act, so the native one never completes:
-               relaying it would announce a dismissal that was refused. */
             this.relayNativeEvent(event);
         };
-        /**
-         * A press on the backdrop, which lands on the dialog element itself.
-         *
-         * **The target alone is not enough here, where it is for `Drawer`.** A modal
-         * `<dialog>` attributes backdrop clicks to itself, which is the usual trick,
-         * and this panel also carries `--dialog-padding` of padding: a press in that
-         * padding has the same target as a press on the backdrop, so the trick alone
-         * closes a dialog when a reader clicks just inside its own edge. The drawer
-         * escapes that because its panel is flush against the window and its content
-         * fills it. So the point is compared against the panel's box.
-         */
         this.handleBackdrop = (event) => {
             const panel = this.dialog;
             if (!panel || event.target !== panel) {
@@ -161,18 +52,6 @@ let HelixHeadlessDialog = class HelixHeadlessDialog extends MixinControllerOpen(
             this.requestOpen(false);
         };
     }
-    /**
-     * What the dialog closed with, the way `<dialog>` reports it.
-     *
-     * **The whole point of a `<dialog>` returning a value is lost behind a shadow
-     * boundary**, which is where this one is: the platform's contract is
-     * `close(value)` then read `returnValue`, and `querySelector` does not reach
-     * the element to do either. A confirmation asking which button was pressed is
-     * the ordinary case.
-     *
-     * Held here as well as on the element, so a value set before the first render
-     * survives to it and a consumer reading one back gets what they wrote.
-     */
     get returnValue() {
         return this.dialog?.returnValue ?? this.returned;
     }
@@ -183,25 +62,12 @@ let HelixHeadlessDialog = class HelixHeadlessDialog extends MixinControllerOpen(
             dialog.returnValue = value;
         }
     }
-    /** The native dialog, or nothing where there is no DOM to hold one. */
     get dialog() {
         return this.renderRoot?.querySelector('dialog') ?? null;
     }
-    /** Moves focus into the dialog and makes the rest of the page inert. */
     show() {
         this.requestOpen(true);
     }
-    /**
-     * Asks to close, which a consumer may refuse.
-     *
-     * Takes what the dialog closed with, the way `<dialog>.close(value)` does, so
-     * the button that dismissed it can say which one it was. Set before the
-     * request rather than after, because a `close` listener reads `returnValue`
-     * and would otherwise read the previous one.
-     *
-     * Not set where the request is refused, since nothing closed and a value
-     * saying it did would outlive the refusal.
-     */
     close(returnValue) {
         const previous = this.returnValue;
         if (returnValue !== undefined) {
@@ -217,78 +83,25 @@ let HelixHeadlessDialog = class HelixHeadlessDialog extends MixinControllerOpen(
     }
     updated(changed) {
         super.updated(changed);
-        /* After render, because the element has to exist to be opened, and only on
-           a difference: `showModal()` on an open dialog throws, and `close()` on a
-           shut one fires a second `close` event. */
         const dialog = this.dialog;
         if (!dialog) {
             return;
         }
         if (this.open && !dialog.open) {
-            /* **After the slotted elements have rendered, or the modal focuses
-               itself.** `showModal()` moves focus to the first focusable descendant,
-               and a custom element that has not rendered its shadow yet has none: the
-               browser falls back to the dialog. Markup never showed this, the parser
-               having upgraded everything before this element's first update, and
-               React does: it creates and connects the dialog before the chat inside
-               it has rendered, so a `default-open` dialog opened with focus on the
-               dialog rather than on the field, measured against the markup twin.
-      
-               Awaited only for children that are Lit elements and only on the way
-               open; a dialog with no such children resolves on the same microtask and
-               is unchanged. */
             void this.openWhenSlotted(dialog);
         }
         else if (!this.open && dialog.open) {
             dialog.close();
         }
     }
-    /** Opens once anything slotted has had its first render. See `updated`. */
     async openWhenSlotted(dialog) {
         await Promise.all([...this.children]
             .map((one) => one.updateComplete)
             .filter((one) => one instanceof Promise));
-        /* Re-checked, because both facts can have moved while that resolved. */
         if (this.open && !dialog.open && this.isConnected) {
             dialog.showModal();
         }
     }
-    /**
-     * Says no to a dismissal, by moving.
-     *
-     * A persistent dialog that ignores a press on the backdrop is
-     * indistinguishable from one that did not notice, and a reader's next move is
-     * to press again harder. A short swell and settle is the smallest thing that
-     * reads as "I heard you, and no": it is the same gesture a native alert makes
-     * on macOS and the one every reader has already been taught.
-     *
-     * An attribute for the length of the animation rather than a class, cleared
-     * on `animationend`, so the styled tier decides what refusing looks like and
-     * this decides only when it happens. Removed first so a second press
-     * restarts it: without that, pressing twice does nothing the second time,
-     * which is the impression the whole thing exists to avoid.
-     *
-     * **`once: true` is not a release when the event cannot arrive.** Under
-     * `prefers-reduced-motion: reduce` the styled tier sets `animation: none`, so
-     * no animation runs, `animationend` never fires, and every refused press left
-     * a listener that could not be removed and an attribute that stayed on. The
-     * controller bounds it to one listener, aborted before the next is added.
-     *
-     * **And the attribute is cleared at once when no animation is running**, asked
-     * of the platform rather than of a media query: this tier does not know what
-     * refusing looks like, and the same silence arrives from a consumer's
-     * stylesheet, from reduced motion, and from no styled tier being loaded at
-     * all.
-     *
-     * **`CSSAnimation` specifically, because `getAnimations` returns transitions
-     * too.** A panel that is still running its entrance transition answers the
-     * bare `length` check with a truthy number while no animation exists to end,
-     * so a refusal landing inside that window took the listener branch and waited
-     * for an `animationend` that was never coming: the attribute stayed on until
-     * the next refused press. That is the same bug this method exists to close,
-     * one window narrower. `getAnimations` flushes pending style itself, so no
-     * reflow is forced for it.
-     */
     refuse() {
         const panel = this.dialog;
         if (!panel) {
@@ -296,8 +109,6 @@ let HelixHeadlessDialog = class HelixHeadlessDialog extends MixinControllerOpen(
         }
         this.refusal?.abort();
         panel.removeAttribute('data-refused');
-        // Read forces the removal to land before the attribute goes back on, or the
-        // two happen in one frame and the animation never restarts.
         void panel.offsetWidth;
         panel.setAttribute('data-refused', '');
         const animating = panel.getAnimations().some((one) => one instanceof CSSAnimation);

package/dist/divider/root/divider-root.js

@@ -7,70 +7,15 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement, slotFilled } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
-/**
- * @summary Separates content into groups with a rule.
- *
- * @description
- * The separator role lives on the rule inside the shadow root rather than on
- * the host. A role does not need to cross the shadow boundary the way an IDREF
- * does, and putting it on the rendered element means the semantics are in the
- * server's markup with no attribute written during a lifecycle the server never
- * runs.
- *
- * Use `orientation="vertical"` between items on one line, such as inside a
- * toolbar. A vertical divider stretches to its flex parent rather than setting
- * a height of its own.
- *
- * @since 0.1.0
- * @status stable
- * @category layout
- * @aliases Separator, Rule
- * @documentation https://helix.fusion.dev/components/divider
- *
- * @slot - Content set into the rule, such as the word between two sections.
- *
- * @csspart content - What is set into it.
- * @csspart line - The rule itself, or each half of it where something is set in.
- */
 let HelixHeadlessDivider = class HelixHeadlessDivider extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * Whether the rule is announced as a separator.
-         *
-         * Off by default, and out of the accessibility tree. Most rules on a page
-         * separate nothing: they underline a heading or close a section that space
-         * had already closed, and announcing every one as a separator is noise a
-         * screen-reader user has to walk past.
-         *
-         * An opt-in, not a `decorative` opt-out, because a boolean attribute cannot
-         * be turned off: `decorative="false"` parses as `true`, which would put the
-         * quiet default out of reach from HTML and leave it settable only as a
-         * property. An opt-in is absent by default, which every reflected property
-         * here has to be.
-         */
         this.announced = false;
     }
-    /**
-     * Marks the middle region when nothing has been set into it.
-     *
-     * A divider with no content has to be one continuous line, and the space
-     * either side of the content is what would break it. `:empty` cannot answer
-     * this and neither can `:host(:has(...))`, which is invalid CSS dropped at
-     * parse time.
-     *
-     * On the region inside the shadow root rather than on the host, because an
-     * attribute written onto the host is a change to markup the consumer rendered.
-     */
     markEmpty() {
         const region = this.renderRoot?.querySelector('[part="content"]');
         const empty = !slotFilled(this.renderRoot?.querySelector('slot'));
         region?.toggleAttribute('data-empty', empty);
-        /* `hidden` beside the mirror, because `data-empty` is a hook the styled
-           sheet reads and this tier has no sheet: an empty region left in the box
-           tree is a gap a consumer cannot close without knowing to look for it. The
-           styled rule stays, because that sheet sets `display` on this part and so
-           outranks the UA one. */
         region?.toggleAttribute('hidden', empty);
     }
     updated(changed) {
@@ -78,22 +23,6 @@ let HelixHeadlessDivider = class HelixHeadlessDivider extends HelixElement {
         this.markEmpty();
     }
     render() {
-        /* Two rules and a slot between them, always.
-         *
-         * `role="presentation"` is the honest default; `announced` is for the rule
-         * that genuinely divides one thing from another rather than just drawing a
-         * line under it.
-         *
-         * **Both halves are always rendered and the semantics stay on the first.**
-         * A rule with nothing set into it is one line with a zero-width slot and a
-         * second line of no length, which costs a reader nothing and costs the
-         * component the branch that would otherwise decide between two markups. It
-         * also means a consumer who slots something in later gets it without the
-         * element re-rendering into a different shape.
-         *
-         * The role is not repeated on the second half. Two separators where a reader
-         * crossed one line is the announcement saying twice what happened once, and
-         * the content between them is not a boundary of its own. */
         return html `<div
       part="line"
       role=${this.announced ? 'separator' : 'presentation'}

package/dist/donut-chart/root/donut-chart-root.js

@@ -8,134 +8,27 @@ import { customElement, drawTooltip, HelixElement, MixinChartSource, seriesIndex
 import { html, nothing, svg } from 'lit';
 import { property } from 'lit/decorators.js';
 import '../../tooltip/index.js';
-/** The drawing's own coordinates, square because the shape has to stay round. */
 const BOX = 100;
 const CENTER = BOX / 2;
-/** The outer edge of the ring, whatever its thickness. */
 const EDGE = 40;
-/**
- * The dash gap, long enough that the pattern cannot repeat.
- *
- * A dash array tiles. Set to `circumference - length` the pattern fills the
- * circle exactly once and is right at rest, and wrong the moment it animates:
- * both numbers interpolate, and while the gap is shorter than the path still to
- * cover, a second and third copy of the slice sweep round the ring and vanish
- * inside one transition. A constant far larger than any circumference has no
- * second tile to draw at any point in the interpolation. It is the number
- * `@starting-style` already uses for the same reason.
- */
 const GAP = 9999;
-/**
- * How much of the radius the ring takes, by name.
- *
- * **The outer edge is fixed and the radius follows the thickness**, which is
- * what makes `none` a pie. The stroke sits astride its own radius, so a ring
- * drawn at a fixed `r` grows outward as well as inward: against a 100 box, a
- * fixed `r=40` has an unstated ceiling at a thickness of 20, and anything past
- * it crosses the view box and is cut with nothing to say so.
- *
- * Derived instead, `r = EDGE - thickness / 2`, the outer edge lands on `EDGE`
- * for every value and the inner edge is `EDGE - thickness`. A pie is where the
- * inner edge reaches the center, which solves to `thickness = EDGE`: the ring
- * is then drawn at `r = EDGE / 2` and its stroke spans the whole radius.
- *
- * `EDGE * 2` was the first answer and is the trap in this arithmetic. It gives
- * `r = 0`, and a circle of radius zero draws nothing at all, so a pie came out
- * as an empty box. The stroke reaches `thickness / 2` either side of `r`, not
- * `thickness`.
- */
 const THICKNESS = {
     large: 8,
     medium: 16,
     none: EDGE,
     small: 26,
 };
-/**
- * @summary Parts of a whole as a ring, read from a table.
- *
- * @description
- * The chart with the narrowest honest use, so the component is narrow too.
- *
- * **It reads one column and treats the rows as the parts.** Every other chart
- * here takes a column per series; a ring has one whole to divide, and a second
- * ring inside the first is two charts sharing a picture in the most literal
- * way. So the first column of numbers is the series and each row is a slice.
- *
- * **It refuses negative values rather than drawing them.** A share of a whole
- * cannot be less than nothing, and an arc for a negative number either runs
- * backwards over its neighbors or is silently dropped. Those rows are skipped
- * and the total is of what is left, which is the only reading that stays true.
- *
- * **The shape is drawn with a dashed stroke, not with arc commands.** One
- * `<circle>` per slice, its dash set to the slice's share of the circumference
- * and its offset to where the slice begins. Arc paths need the sweep flag and a
- * large-arc flag, both of which flip at values a reader never sees coming, and
- * a slice of exactly one whole becomes a path with no length at all.
- *
- * **And it keeps its aspect ratio**, alone among the charts here. The others
- * set `preserveAspectRatio="none"` so one drawing fills any box and rescue
- * their strokes with `vector-effect`; that rescues strokes and not geometry, so
- * a ring drawn the same way is an ellipse in anything but a square.
- *
- * The table is the accessible representation and this drawing is `aria-hidden`.
- *
- * The properties below are written by this component and read by whoever draws
- * it. A consumer sets none of them: they carry a number this element computed
- * and CSS cannot, which is what lets a stylesheet on this tier draw the thing
- * without measuring anything itself.
- *
- * @since 0.1.0
- * @status experimental
- * @category charts
- * @aliases Pie Chart, Ring Chart, Share Chart
- * @documentation https://helix.fusion.dev/components/donut-chart
- *
- * @slot - Goes in the middle of the ring. A total, usually.
- *
- * @csspart center - The middle of the ring, holding whatever is slotted.
- * @csspart mark - The invisible point the tooltip is anchored to.
- * @csspart plot - The drawing.
- * @csspart segment - One slice.
- * @csspart segment-edge - One slice as a closed shape, for a boundary to trace.
- * @csspart tooltip - The bubble, forwarded from `Tooltip`.
- * @csspart tooltip-anchor - The `Tooltip` element itself.
- * @csspart tooltip-cell - One column's name and value inside the tooltip.
- * @csspart tooltip-label - The slice's own name inside the tooltip.
- * @csspart tooltip-name - A column's name inside the tooltip.
- * @csspart tooltip-value - A column's value inside the tooltip.
- * @csspart track - The ring the slices are drawn on.
- *
- * @cssproperty --donut-chart-stroke - How thick the ring is drawn, derived from `hole`.
- */
 let HelixHeadlessDonutChart = class HelixHeadlessDonutChart extends MixinChartSource(HelixElement) {
-    /**
-     * The pointer is not mapped across this one.
-     *
-     * Every other chart lays its readings out left to right, so the nearest is
-     * arithmetic on x. A ring's slices are real elements at every angle, and x
-     * alone would answer with whichever slice shared a horizontal position with
-     * the pointer: at three o'clock and at nine o'clock it would give the same
-     * reading for opposite sides of the chart. So the slices say which one they
-     * are and this only holds the answer.
-     *
-     * Set here rather than in a constructor, and it must not move there: the
-     * analyzer reads `this.pointer.axis = 'none'` in a constructor body as the
-     * declaration of a public field, and fails the build demanding a description
-     * for a member this class does not have.
-     */
     connectedCallback() {
         super.connectedCallback();
         this.pointer.axis = 'none';
     }
-    /** The fraction of the circle the shares are spread over. */
     get span() {
         return this.sweep === 'half' ? 0.5 : 1;
     }
-    /** How thick the ring is drawn, in the drawing's own units. */
     get thickness() {
         return THICKNESS[this.hole ?? 'medium'] ?? THICKNESS.medium ?? 0;
     }
-    /** The ring's radius, which follows its thickness so the outer edge holds. */
     get radius() {
         return EDGE - this.thickness / 2;
     }
@@ -158,24 +51,10 @@ let HelixHeadlessDonutChart = class HelixHeadlessDonutChart extends MixinChartSo
     }
     render() {
         const shares = this.shares;
-        /* No middle where there is no hole. A `center` part over a pie would put
-           slotted content on top of the slices, and a slot nobody can see is worse
-           than one that is not there: a consumer fills it and nothing happens. */
         return html `${this.renderPlot(shares)}
 `;
     }
-    /**
-     * The ring itself, behind a seam the styled tier can move.
-     *
-     * `aria-hidden`, because the table it was read from is the readable version
-     * and a screen reader hearing both hears the same numbers twice.
-     */
     renderPlot(shares) {
-        /* The thickness is declared here, on the box that holds both the ring and
-           the middle, and never on the slices. A custom property inherits down and
-           never sideways, so `[part="center"]` is a sibling of the circles and would
-           only ever read the fallback, sizing the hole as if every ring were the
-           resting thickness. */
         return html `<div
       aria-hidden="true"
       id="helix-chart-plot"
@@ -198,30 +77,15 @@ let HelixHeadlessDonutChart = class HelixHeadlessDonutChart extends MixinChartSo
       ${this.renderTooltip()}
     </div>`;
     }
-    /**
-     * The view box, cropped to what is actually drawn.
-     *
-     * A full turn uses the square. A half arc uses the band from the top of the
-     * ring down to the center line, plus the half stroke its flat ends hang
-     * below that, and cropping to it is the difference between a semi-donut and a
-     * semi-donut with an empty quarter of the box under it. The outer edge is
-     * `EDGE` from the center whatever the thickness, which is what makes this two
-     * numbers rather than a measurement.
-     */
     get frame() {
         if (this.sweep !== 'half') {
             return `0 0 ${BOX} ${BOX}`;
         }
         return `0 ${CENTER - EDGE} ${BOX} ${EDGE + this.thickness / 2}`;
     }
-    /** One slice, as a dash the length of its share. */
     renderSegment(share, index) {
         const circumference = 2 * Math.PI * this.radius;
         const length = share.fraction * circumference * this.span;
-        /* Negative, because `stroke-dashoffset` counts backwards along the path:
-           a positive offset would run the slices anticlockwise from twelve. The
-           rotation that puts zero at the top is the stylesheet's, since it is a
-           fact about how the picture is presented rather than about the numbers. */
         return svg `<circle
       cx=${CENTER}
       cy=${CENTER}
@@ -237,36 +101,6 @@ let HelixHeadlessDonutChart = class HelixHeadlessDonutChart extends MixinChartSo
     />
     ${this.renderEdge(share, index)}`;
     }
-    /**
-     * The same slice again, as a shape with an inside.
-     *
-     * **A stroked arc has no boundary to draw, which is why this exists.** The
-     * segment above is a dash on a circle: the mark *is* the edge, so there is
-     * nothing for an outline to trace and nothing within it to fade. Anything
-     * wanting those two separately needs the slice as a closed path, and this is
-     * it: the outer arc, a step inward, the inner arc back, closed.
-     *
-     * **Rendered always and painted only sometimes**, which is what keeps this on
-     * this tier. Whether a boundary is drawn is a styled question and the answer
-     * lives in a stylesheet; whether the geometry a boundary would need exists at
-     * all is structural, and a component cannot conjure a shape from CSS. So the
-     * path is here for every donut and is `fill: none; stroke: none` until
-     * something asks for it.
-     *
-     * **Not a replacement for the dash.** The dash carries three jobs and only
-     * one of them is the shape: a share growing is a `stroke-dasharray`
-     * interpolating with no reflow, and `@starting-style` on that same property is
-     * the whole reason the ring sweeps in rather than appearing. A `d` cannot do
-     * either. CSS interpolates one only between paths of identical command
-     * structure, and the large-arc flag flips the moment a slice crosses a half
-     * turn, so a growing slice would pop partway through the transition it was
-     * meant to smooth. Both animations stay on the dash and this path follows it.
-     *
-     * The turn to twelve o'clock is arithmetic here rather than the rotation the
-     * stylesheet gives the circles. That rule uses `transform-box: fill-box`, so
-     * it spins each element about its own bounding box, which is the ring's center
-     * for a circle and is not for a sector.
-     */
     renderEdge(share, index) {
         const turn = 2 * Math.PI * this.span;
         const from = share.start * turn - Math.PI / 2;
@@ -275,45 +109,17 @@ let HelixHeadlessDonutChart = class HelixHeadlessDonutChart extends MixinChartSo
         const inner = EDGE - this.thickness;
         const at = (radius, angle) => `${(CENTER + Math.cos(angle) * radius).toFixed(3)} ${(CENTER + Math.sin(angle) * radius).toFixed(3)}`;
         const wide = to - from > Math.PI ? 1 : 0;
-        /* A slice that is the whole ring starts and ends at one point, and an arc
-           between a point and itself draws nothing. Split at the halfway angle so
-           each half is a real arc. */
         const full = to - from >= 2 * Math.PI - 1e-6;
         const mid = from + (to - from) / 2;
         const outward = full
             ? `A ${outer} ${outer} 0 0 1 ${at(outer, mid)} A ${outer} ${outer} 0 0 1 ${at(outer, to)}`
             : `A ${outer} ${outer} 0 ${wide} 1 ${at(outer, to)}`;
-        /* A pie has no inner arc: the radius solves to zero and the two ends meet at
-           the middle, so the step back is a line to the center and not an arc of no
-           size. */
         const homeward = inner <= 0
             ? `L ${CENTER} ${CENTER}`
             : full
                 ? `L ${at(inner, to)} A ${inner} ${inner} 0 0 0 ${at(inner, mid)} A ${inner} ${inner} 0 0 0 ${at(inner, from)}`
                 : `L ${at(inner, to)} A ${inner} ${inner} 0 ${wide} 0 ${at(inner, from)}`;
         const shape = `M ${at(outer, from)} ${outward} ${homeward} Z`;
-        /* **Clipped to itself, because a stroke straddles the line it is drawn on.**
-           Half of it falls outside the wedge: past the fill on both arcs, and across
-           the seam into the neighbor on both radial sides, where that neighbor is
-           drawing the same line from the other direction and the two overlap. Seen
-           as a doubled edge at every join and a halo around the ring.
-    
-           Clipping to the same path keeps the inner half and drops the outer, so an
-           edge stays inside the slice it belongs to and two adjacent edges meet
-           exactly. The clip is the shape itself, so it costs no second geometry and
-           cannot drift from it.
-    
-           Ids are scoped to the shadow root, so an index is enough to keep them
-           apart, and two donuts on a page cannot collide. */
-        /* **`fill="none"` as an attribute, not a rule, because this tier has
-             no rules.** An SVG path fills black by default, and the styled tier's
-             own `fill: none` covers only that tier: everywhere else these closed
-             shapes paint over the ring.
-    
-             A presentation attribute loses to any CSS rule, so the styled tier
-             still decides and a consumer can still fill this if they want one.
-             What it cannot do is fill by accident on the tier whose whole premise
-             is that it ships no CSS. */
         const clip = `helix-donut-edge-${index}`;
         return svg `<clipPath id=${clip}><path d=${shape} /></clipPath>
     <path
@@ -326,37 +132,17 @@ let HelixHeadlessDonutChart = class HelixHeadlessDonutChart extends MixinChartSo
       style="--chart-series: var(--chart-series-${seriesIndex(index)})"
     />`;
     }
-    /**
-     * What a pointer resting on a slice shows.
-     *
-     * Placed in the middle rather than along an axis, a ring having none, and the
-     * middle is where a reader is already looking: the hole usually holds a
-     * total, so a tooltip over it replaces one figure with the one being asked
-     * about rather than covering something else.
-     */
     renderTooltip() {
         const at = this.pointer.at;
         const share = this.shares[at];
         if (!share) {
             return drawTooltip(this.sourceRows, at, this.tag('tooltip'));
         }
-        /* **Outside the ring, on the slice's own bearing**, rather than centered in
-           the hole: centered covers the data on a pie, and in neither shape does it
-           say *which* slice it means. Out here one rule serves both.
-    
-           The mid-angle, less a quarter turn because the ring is rotated to start
-           at twelve o'clock and this arithmetic starts at three. The point is the
-           outer edge, and the box is pushed a little further along the same bearing
-           so its arrow rests on the ring rather than in it. */
         const angle = (share.start + share.fraction / 2) * 2 * Math.PI - Math.PI / 2;
         const edge = EDGE;
         const x = CENTER + Math.cos(angle) * edge;
         const y = CENTER + Math.sin(angle) * edge;
         return drawTooltip(this.sourceRows, at, this.tag('tooltip'), {
-            /* The preferred side from the bearing's dominant axis, and
-               `FloatingController` moves it if that side does not fit. A fixed side
-               cannot express a bearing, so the arrow misses the ring; a preference
-               plus flipping can. */
             placement: Math.abs(Math.cos(angle)) > Math.abs(Math.sin(angle))
                 ? Math.cos(angle) > 0
                     ? 'right'