@fusion.dev/helix-headless 0.1.0 → 0.3.0

package/dist/badge/root/badge-root.js

@@ -7,56 +7,15 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
-/**
- * @summary Attaches a count or a presence mark to another element.
- *
- * @description
- * Wraps whatever it decorates and pins the indicator to its corner, so the
- * thing being counted stays the thing in the layout: a badge is an annotation,
- * not a container that happens to hold an icon.
- *
- * The indicator says how many, and none is none. A `value` that reads as zero
- * shows no mark at all, an absent one shows a bare dot, and any other value
- * shows the value. `max` caps the top: past it the indicator reads `{max}+`
- * rather than growing to fit, since a corner mark that widens with its value
- * pushes the layout around.
- *
- * **A dot needs a label.** Without one it is a colored circle that announces
- * nothing, which tells a sighted reader there is something new and tells
- * everyone else there is not. The label is required in that form, and the
- * indicator is hidden from assistive technology when a number already says it.
- *
- * @since 0.1.0
- * @status stable
- * @category markers
- * @aliases Count, Indicator, Pip
- * @documentation https://helix.fusion.dev/components/badge
- *
- * @slot - The element being decorated.
- *
- * @csspart indicator - The count, or the dot when there is no value.
- */
 let HelixHeadlessBadge = class HelixHeadlessBadge extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * Accessible name.
-         *
-         * Required for a dot, which has no text to read.
-         */
         this.label = '';
-        /**
-         * The count or short text to show.
-         *
-         * Absent shows a dot, zero shows nothing.
-         */
         this.value = '';
     }
-    /** Whether the value counts nothing, in which case there is no mark. */
     get blank() {
         return this.value.trim() !== '' && Number(this.value) === 0;
     }
-    /** What the indicator reads, once the cap has been applied. */
     get text() {
         const count = Number(this.value);
         if (this.max !== undefined && Number.isFinite(count) && count > this.max) {
@@ -67,33 +26,7 @@ let HelixHeadlessBadge = class HelixHeadlessBadge extends HelixElement {
     render() {
         const blank = this.blank;
         const text = this.text;
-        /* A mark with text is content and is announced; a dot is decoration and is
-           not.
-         *
-         * It must not ask for a `label` as well, or a badge showing a count and no
-         * label is `aria-hidden` and the number it exists to show reaches nobody
-         * using a screen reader. The number is its own name where none is given,
-         * which is why `aria-label` is conditional on the label rather than on this:
-         * a `4` announces as "4" from the text, and `label="4 unread"` says the
-         * better thing.
-         *
-         * A dot with no label still says nothing, which is the deliberate half: a
-         * dot means "something here" and cannot say what, so naming it is the
-         * consumer's to do and silence is better than "badge". */
         const announced = !blank && (text !== '' || this.label !== '');
-        // The indicator holds the text and nothing else, so an absent value leaves
-        // it empty and `[part="indicator"]:empty` is what draws the dot. Lit's
-        // marker comments do not affect `:empty`, but a whitespace text node does,
-        // which is why the tags close the way they do.
-        //
-        // It stays mounted when there is nothing to show, so the styled tier can
-        // transition it out rather than having it vanish between frames. Both
-        // markers are on the shadow content, not the host, so they cost no
-        // attribute a consumer's server markup would have to match.
-        //
-        // `single` is what lets a one-character mark be a circle. Whether the text
-        // fits inside the square is a fact about the string, and CSS cannot count
-        // characters.
         return html `<slot></slot>
       <span
         part="indicator"

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

@@ -8,102 +8,26 @@ import { customElement, drawTooltip, extent, HelixElement, linear, linePath, Mix
 import { html, nothing, svg } from 'lit';
 import { property } from 'lit/decorators.js';
 import '../../tooltip/index.js';
-/** The drawing's own coordinates. Height only: the width is the element's. */
 const HEIGHT = 100;
-/**
- * @summary Categories as columns, read from a table.
- *
- * @description
- * Two decisions are made here rather than left to a consumer.
- *
- * **It measures from zero and there is no property to change that.** A bar's
- * length *is* its value, so a baseline anywhere else makes the lengths
- * proportional to nothing. A reader who wants the differences between values
- * rather than the values should be drawing a line, which claims only a shape.
- *
- * **The labels are HTML beside the drawing rather than `<text>` inside it.** An
- * `<svg>` that fills its box scales everything in it, including type: the same
- * `font-size` comes out at 10px in a narrow chart and 43px in a wide one, and
- * there is no non-scaling-font to answer it the way `vector-effect` answers
- * strokes. So the columns are drawn and the words are written around them.
- *
- * The table is the accessible representation and this drawing is `aria-hidden`.
- * A reader who wants the numbers gets the numbers, not a described picture of
- * them.
- *
- * The custom 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.
- *
- * @since 0.1.0
- * @status experimental
- * @category charts
- * @aliases Column Chart, Categorical Chart
- * @documentation https://helix.fusion.dev/components/bar-chart
- *
- * @csspart axis - One scale's numbers, drawn only when `secondary` splits them.
- * @csspart band - The slot the pointer is resting in.
- * @csspart bar - One column.
- * @csspart bar-wash-end - The far stop of a bar's gradient, where one is used.
- * @csspart bar-wash-start - The stop of a bar's gradient at its base.
- * @csspart baseline - The rule the columns stand on.
- * @csspart gridline - One rule across the plot, under `gridlines`.
- * @csspart group - One category's columns, together.
- * @csspart label - One category's name.
- * @csspart labels - The row of category names.
- * @csspart line - A series drawn as a line rather than as columns, under `lines`.
- * @csspart mark - The invisible point the tooltip is anchored to.
- * @csspart plot - The drawing.
- * @csspart svg - The drawing surface the bars and lines sit on.
- * @csspart tick - One number on an axis.
- * @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 reading'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.
- *
- * @cssproperty --bar-chart-axis - The color of a single-series axis, taken from that series.
- * @cssproperty --bar-chart-secondary - The color of the secondary axis when one series owns it. It resolves a `--helix-color-series-*` token, so on the headless tier alone it names something that is not there. #138.
- * @cssproperty --chart-bar-wash - The gradient a bar would take, named per bar so the
- *   styled tier can point `fill` at it. Drawn whatever the treatment and used only where
- *   `wash="gradient"` asks for it.
- */
 let HelixHeadlessBarChart = class HelixHeadlessBarChart extends MixinChartSource(HelixElement) {
-    /** The series names on the second scale, lowercased and trimmed. */
     get scaled() {
         return new Set((this.secondary ?? '')
             .split(/\s+/)
             .map((name) => name.trim().toLowerCase())
             .filter(Boolean));
     }
-    /** The series names drawn as a line, lowercased and trimmed for matching. */
     get lined() {
         return new Set((this.lines ?? '')
             .split(/\s+/)
             .map((name) => name.trim().toLowerCase())
             .filter(Boolean));
     }
-    /** Whether the levels are ruled, which is every value but `category`. */
     get rulesValue() {
         return this.gridlines !== undefined && this.gridlines !== 'category';
     }
-    /** Whether each category is ruled, which only two values ask for. */
     get rulesCategory() {
         return this.gridlines === 'both' || this.gridlines === 'category';
     }
-    /**
-     * Tells the pointer which way the categories run.
-     *
-     * In `willUpdate` because `direction` is a property a consumer can change at
-     * any time, and the controller resolves a reading from whichever axis it was
-     * last told about: set once at connect, a chart turned sideways after that
-     * goes on reading x and answers with the same row wherever the pointer goes.
-     *
-     * `willUpdate` and not `updated`, because SSR calls the first and not the
-     * second, and a value the server and the client disagree about is worse than
-     * one neither has.
-     */
     willUpdate(changed) {
         super.willUpdate(changed);
         this.pointer.axis = this.direction === 'horizontal' ? 'block' : 'inline';
@@ -114,33 +38,14 @@ let HelixHeadlessBarChart = class HelixHeadlessBarChart extends MixinChartSource
         if (categories.length === 0) {
             return html `<div id="helix-chart-plot" part="plot"></div>`;
         }
-        /* Zero at both ends, so a series that goes negative gets a baseline inside
-           the box and its columns hang below it. `extent` over every series at once
-           rather than per series, because two series drawn to different scales are
-           two charts sharing a picture. */
         const scaled = this.scaled;
         const own = (one) => scaled.has(one.name.trim().toLowerCase());
-        /* Two extents where a series asked for its own, and the primary is taken
-           over the series that did *not*: measuring the primary over everything
-           would stretch it to hold numbers no column is drawn against, which is the
-           one thing splitting the axes was meant to stop. Empty on either side
-           falls back to the whole set, so `secondary` naming a column that is not
-           there leaves a chart rather than a blank. */
         const values = series.flatMap((one) => one.points.map((point) => point.value));
         const on = (which) => {
             const found = series.filter(which).flatMap((one) => one.points.map((point) => point.value));
             return found.length > 0 ? found : values.length > 0 ? values : [0];
         };
         const [low, high] = extent(scaled.size === 0 ? on(() => true) : on((one) => !own(one)));
-        /* **The range is inverted for columns and not for bars**, which is the
-           whole of what makes the two directions different arithmetic rather than
-           one drawing turned on its side. SVG counts down from the top, so a column
-           growing upward needs `[HEIGHT, 0]`; a bar growing rightward is already
-           going the way x counts, so it takes `[0, HEIGHT]`.
-         *
-         * Reusing the inverted scale for both puts the longest bar at x=0 and every
-           shorter one hard against the right edge, growing away from the baseline
-           instead of out of it. */
         const domain = [Math.min(0, low), Math.max(0, high)];
         const range = this.direction === 'horizontal' ? [0, HEIGHT] : [HEIGHT, 0];
         const y = linear(domain, range);
@@ -149,88 +54,28 @@ let HelixHeadlessBarChart = class HelixHeadlessBarChart extends MixinChartSource
         const [second, top] = extent(scaled.size > 0 ? on(own) : [0]);
         const other = [Math.min(0, second), Math.max(0, top)];
         const z = scaled.size > 0 ? linear(other, range) : undefined;
-        /* Widest number on either scale, in characters, so the axis column is the
-           size of its own contents.
-         *
-         * The ticks are absolutely positioned, which is what puts each one on the
-         * level it names and also what stops any of them contributing a width: an
-         * axis of six numbers laid out that way is an empty box. The count is known
-         * here and unknowable to a selector, so it is written as a length and the
-           stylesheet reads it. */
         const widest = z === undefined
             ? 0
             : Math.max(...[...ticks(domain), ...ticks(other)].map((level) => level.toLocaleString().length));
-        /* The second axis wears its series' color when exactly one series is on it,
-           which is the case worth helping and the only one a single color can
-           describe honestly: with two sharing it, painting the axis either of their
-           colors says it belongs to that one.
-         *
-           **Written onto the axis and not onto the plot.** The axis is the plot's
-           sibling, being a column of the host grid, and a custom property inherits
-           down and never sideways: written onto the plot, both axes come out the
-           neutral. */
         const lone = series.filter(own);
         const tint = lone.length === 1 && lone[0] !== undefined
             ? `--bar-chart-secondary: var(--chart-series-${seriesIndex(series.indexOf(lone[0]))})`
             : undefined;
         return html `${z === undefined ? nothing : this.renderAxis(y, domain, 'primary', sideways, widest)}${this.renderPlot(series, categories, y, domain, floor, z)}${z === undefined ? nothing : this.renderAxis(z, other, 'secondary', sideways, widest, tint)}${this.renderLabels(categories)}`;
     }
-    /**
-     * The columns themselves, 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(series, categories, y, domain, floor, z) {
         const sideways = this.direction === 'horizontal';
         const slot = 100 / categories.length;
-        /* Split first, because the columns share the slot between themselves and a
-           line takes none of it. Sized by every series instead, a chart of two
-           columns and one line draws both columns two thirds as wide and leaves a
-           third of every slot empty, for a mark that is not in the slot at all. */
         const lined = this.lined;
-        /* Kept with the index it has among *all* the series, because a column needs
-           two different numbers and they stopped being the same the moment one
-           series could be a line. `depth` is its place in the slot, so the columns
-           stand shoulder to shoulder with no gap where a line was; `tone` is its
-           place in the palette, so it keeps the color the legend gives it.
-         *
-           Passing the first for both moves a series into its neighbor's color as
-           well as its slot: with `Target` drawn as a line, a chart of four series
-           paints three columns in the first three colors and the line in the third
-           one as well. */
         const scaled = this.scaled;
         const own = (one) => scaled.has(one.name.trim().toLowerCase());
-        /* The scale a series is measured against, resolved once per series rather
-           than per point. `z` is absent unless `secondary` named something, so the
-           ordinary chart takes exactly the path it took before this existed. */
         const against = (one) => z !== undefined && own(one) ? z : y;
         const columns = series
             .map((one, index) => ({ one, tone: index }))
             .filter(({ one }) => !lined.has(one.name.trim().toLowerCase()));
-        /* **The stride is what the columns share and the thickness is what they
-           draw.** Back to back, two columns meet on one coordinate and each one's
-           edge is the other's: an outlined chart then shows a single line between
-           them rather than two, and a bar looks as though it were missing a side.
-           A gap is also just the right way to draw a group, which is why the split
-           stays whether anything is outlined or not.
-    
-           Centered in the stride rather than flush against it, so the gap between two
-           columns is the same size everywhere and the group sits where it did. One
-           series has no neighbor to be separated from and keeps the full stride. */
         const stride = (slot * 0.72) / Math.max(columns.length, 1);
         const gap = columns.length > 1 ? stride * 0.08 : 0;
         const thickness = stride - gap;
-        /* **The geometry is computed for the axis it is drawn on, not rotated onto
-           it.** Turning the whole plot with `rotate: 90deg` is the shorter CSS and
-           does not work: a rotation is about the element's own center, so the
-           drawing leaves its grid cell entirely while the labels, which are a
-           separate row, stay where they were. What that produces is one column
-           floating beside a list of names.
-         *
-         * Swapping the two axes here costs one branch and keeps every other fact
-         * about the chart the same. `value` runs along x when the bars are
-         * sideways and along y otherwise; `category` takes the other one. */
         const bar = (value, index, depth, tone, scale) => {
             const at = scale(value);
             const along = Math.min(floor, at);
@@ -266,18 +111,7 @@ let HelixHeadlessBarChart = class HelixHeadlessBarChart extends MixinChartSource
         viewBox="0 0 100 ${HEIGHT}"
         xmlns="http://www.w3.org/2000/svg"
       >
-        ${
-        /* **One gradient per series, rendered whether or not anything points
-           at it.** A `<defs>` entry draws nothing on its own, and this tier's
-           business is elements while which fill a bar takes is the styled
-           tier's: `wash="gradient"` there switches `fill` to
-           `--chart-bar-wash` and this is what it would find.
-
-           Colored through the series property rather than an attribute, so
-           the stops read a token this tier never names. The id resolves
-           within the shadow root, so two charts on a page carrying the same
-           ids stay independent. */
-        svg `<defs>
+        ${svg `<defs>
             ${series.map((_, index) => svg `<linearGradient
                 id="helix-bar-wash-${seriesIndex(index)}"
                 style="--chart-series: var(--chart-series-${seriesIndex(index)})"
@@ -295,52 +129,16 @@ let HelixHeadlessBarChart = class HelixHeadlessBarChart extends MixinChartSource
             ? svg `<line part="baseline" x1=${floor} x2=${floor} y1="0" y2="100" />`
             : svg `<line part="baseline" x1="0" x2="100" y1=${floor} y2=${floor} />`}
         ${this.renderBand(categories.length, sideways)}
-        ${categories.map((_, index) => 
-        /* The group the tooltip is about says so, and the stylesheet fades
-           the rest. A tooltip over a chart of five categories otherwise
-           makes a reader match its heading against the row of names to find
-           out which columns it means. */
-        svg `<g data-active=${this.pointer.at === index ? '' : nothing} part="group">
+        ${categories.map((_, index) => svg `<g data-active=${this.pointer.at === index ? '' : nothing} part="group">
               ${columns.map(({ one, tone }, depth) => bar(one.points[index]?.value ?? 0, index, depth, tone, against(one)))}
             </g>`)}
-        ${
-        /* After the groups, so a line is never drawn under the columns it is
-           meant to be read against. Outside them too: a group is one
-           category and a line crosses all of them, so it belongs to the plot
-           rather than to any one slot. */
-        series.map((one) => lined.has(one.name.trim().toLowerCase())
+        ${series.map((one) => lined.has(one.name.trim().toLowerCase())
             ? this.renderLine(one, series.indexOf(one), slot, against(one), sideways)
             : nothing)}
       </svg>
       ${this.renderTooltip()}
     </div>`;
     }
-    /**
-     * The numbers along one scale, drawn only where there are two of them.
-     *
-     * **A chart with one scale renders no axis, on purpose.** Columns measured
-     * against each other need no numbers to be compared, and a row of them beside
-     * a small chart is furniture that makes the drawing smaller for no reading a
-     * reader was going to do. With two scales that argument inverts: a reader
-     * cannot tell there are two, cannot tell which series is on which, and cannot
-     * recover either from the picture. So this appears with `secondary` and never
-     * without it.
-     *
-     * **Beside the plot and not inside it.** Inside, the numbers are drawn over
-     * the drawing, and a horizontal chart shows it immediately: its value axis
-     * runs along the bottom, which is where the last row of bars is. The vertical
-     * case has the same fault and enough slack to hide it. The plot is also the
-     * pointer's catchment and the tooltip's containing block, both measured from
-     * its box, so padding it to make room would move every reading half an axis
-     * to the right.
-     *
-     * A column of the host grid instead, which the stylesheet grows only when
-     * `secondary` is set. That is what the property reflects for.
-     *
-     * The primary hugs the edge the drawing starts at and the secondary the edge
-     * it ends at: down the two sides for columns, along the bottom and top for
-     * bars, which is where each axis is when the chart is turned.
-     */
     renderAxis(scale, domain, which, sideways, widest, tint) {
         const sizing = sideways ? undefined : `--bar-chart-axis: ${widest}ch`;
         return html `<div
@@ -356,25 +154,10 @@ let HelixHeadlessBarChart = class HelixHeadlessBarChart extends MixinChartSource
           >`)}
     </div>`;
     }
-    /**
-     * The grid, behind everything, or nothing at all.
-     *
-     * Across the measured axis, which turns with `direction`: a rule belongs to
-     * the axis the bars are measured on and not the one they are arranged on, so
-     * columns get horizontal rules and rows get vertical ones. Getting that
-     * backwards draws a grid that divides the categories, which are already
-     * divided by being separate bars.
-     *
-     * Drawn before the baseline, so where a gridline and zero coincide the
-     * baseline is what shows: zero is a fact about the data and a gridline is a
-     * ruler.
-     */
     renderGridlines(y, domain, sideways, count) {
         if (this.gridlines === undefined) {
             return nothing;
         }
-        /* Through the middle of each group, which is where the column stands, and
-           not on the boundary between two of them. */
         const slot = 100 / Math.max(count, 1);
         const categories = this.rulesCategory
             ? Array.from({ length: count }, (_, index) => (index + 0.5) * slot).map((at) => sideways
@@ -388,20 +171,6 @@ let HelixHeadlessBarChart = class HelixHeadlessBarChart extends MixinChartSource
             : [];
         return svg `${categories}${levels}`;
     }
-    /**
-     * The slot the pointer is resting in, drawn behind the columns.
-     *
-     * **The honest version of the fade.** A group under the pointer already sets
-     * `data-active` and the stylesheet dims the others, which says which group is
-     * meant by making four of five quieter: it reads as the chart losing
-     * confidence rather than as one column being pointed at. A band says the same
-     * thing by lighting the region the pointer is actually in, and the region is
-     * the whole slot, because that is the catchment the pointer resolves against.
-     *
-     * Both are kept. The fade separates the active group from its neighbors and
-     * the band says where the neighborhood is, and on a chart of two categories
-     * the fade alone is ambiguous about which half is lit.
-     */
     renderBand(count, sideways) {
         const at = this.pointer.at;
         if (at < 0 || count === 0) {
@@ -417,31 +186,12 @@ let HelixHeadlessBarChart = class HelixHeadlessBarChart extends MixinChartSource
       ${categories.map((one) => html `<span part="label">${one}</span>`)}
     </div>`;
     }
-    /**
-     * One series drawn as a line across the categories, behind a seam.
-     *
-     * Through the middle of each slot, which is where the group stands, so a
-     * point sits over its own columns rather than over the gap between two of
-     * them. The same arithmetic the category gridlines use, and for the same
-     * reason: the reading is the thing, the boundary is only where the pointer
-     * changes its mind.
-     *
-     * `data-series` keeps the index the series has among *all* of them, not among
-     * the lines, so the color a line takes is the color the legend gives it and
-     * moving a column between marks does not repaint the chart.
-     */
     renderLine(one, depth, slot, y, sideways) {
         const points = one.points.map((point, index) => {
             const across = index * slot + slot / 2;
             const along = y(point.value);
             return sideways ? [along, across] : [across, along];
         });
-        /* Straight between the category centers, and no `curve` property to change
-           it. A bar chart's other axis is categorical: there is nothing between
-           Gateway and Billing, so a curve through them draws values at positions
-           that do not exist and bulges past the readings on the way. `LineChart`
-           offers the choice because its axis is continuous and the shape between
-           two readings is a claim somebody may legitimately want to make. */
         return svg `<path
       d=${linePath(points, 'straight')}
       data-series=${seriesIndex(depth)}
@@ -449,22 +199,12 @@ let HelixHeadlessBarChart = class HelixHeadlessBarChart extends MixinChartSource
       style="--chart-series: var(--chart-series-${seriesIndex(depth)})"
     />`;
     }
-    /**
-     * What a pointer resting on a reading shows.
-     *
-     * A seam over `drawTooltip`, which holds the markup every chart shares. The
-     * usual reason to override is arrangement: every cell of the row is already
-     * there, including the columns nothing was plotted from.
-     */
     renderTooltip() {
         const at = this.pointer.at;
         const series = this.series;
         if (at < 0 || series.length === 0) {
             return drawTooltip(this.sourceRows, at, this.tag('tooltip'));
         }
-        /* Off the far end of the tallest bar in the group, so the box never covers
-           the columns it is describing. Horizontal bars grow rightward, so the far
-           end is along x and the arrow hangs off the box's start edge. */
         const values = series.map((one) => one.points[at]?.value ?? 0);
         const all = series.flatMap((one) => one.points.map((point) => point.value));
         const [low, high] = extent(all.length > 0 ? all : [0]);

package/dist/blockquote/root/blockquote-root.js

@@ -7,58 +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 A passage set off from the prose around it.
- *
- * @description
- * Renders a real `<blockquote>` with a `<footer>` for the attribution, which is
- * the structure the HTML spec describes for exactly this: the attribution is
- * about the quotation rather than part of it, and putting it inside the quoted
- * text claims the source said their own name.
- *
- * A quotation run inside a sentence is a `Quote`, which is a different element
- * because it is a different job.
- *
- * @since 0.1.0
- * @status stable
- * @category typography
- * @aliases Pullquote, Citation, Excerpt
- * @documentation https://helix.fusion.dev/components/blockquote
- *
- * @slot - The quoted passage.
- * @slot attribution - Who said it, and where.
- *
- * @csspart attribution - The footer carrying the source.
- * @csspart blockquote - The quotation.
- */
 let HelixHeadlessBlockquote = class HelixHeadlessBlockquote extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * URL identifying where the passage came from.
-         */
         this.cite = '';
     }
-    /**
-     * Says on the footer whether there is an attribution in it.
-     *
-     * A `<footer>` with nothing in it is still a block in the quote's flow and
-     * still takes the container's gap, so every blockquote written without an
-     * attribution reserved a full space below itself. There is no selector that
-     * can ask, `slot:empty` being about a slot's fallback rather than its
-     * assigned nodes, so the component asks and says so on the footer inside this
-     * shadow root: an attribute on the host is a change to markup the consumer
-     * rendered, which React reports on hydration.
-     */
     markEmpty() {
         const footer = this.renderRoot?.querySelector('[part="attribution"]');
         const empty = !slotFilled(this.renderRoot?.querySelector('slot[name="attribution"]'));
         footer?.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. */
         footer?.toggleAttribute('hidden', empty);
     }
     updated(changed) {
@@ -66,9 +23,6 @@ let HelixHeadlessBlockquote = class HelixHeadlessBlockquote extends HelixElement
         this.markEmpty();
     }
     render() {
-        // The footer is a bare slot inside a real `<footer>`: the element is the
-        // semantics and cannot be omitted, while an unfilled slot inside it is
-        // `display: contents` and generates no box.
         return html `<blockquote part="blockquote" cite=${this.cite || nothing}>
       <slot></slot>
       <footer part="attribution"><slot name="attribution"></slot></footer>

package/dist/breadcrumbs/breadcrumb/breadcrumb.js

@@ -9,85 +9,18 @@ import { caretRight } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
-/**
- * @summary One step in a breadcrumb trail.
- *
- * @description
- * Contributes the separator, the list-item role, and the link itself where one
- * is wanted.
- *
- * **`href` makes the crumb the link.** A router cannot reach an anchor inside a
- * shadow root, and the consumer restores the soft navigation by intercepting the
- * click on the way out, which is what `Tree.Item` and `List.Item` both do. What
- * the anchor buys is the whole crumb as a target, Enter, middle click, the
- * status bar, and a trail that works before any JavaScript runs.
- *
- * **And the parent needs it.** A trail that collapses has to rebuild its hidden
- * crumbs somewhere else, which means reading each one's destination. From a
- * property that is a read; from a consumer's slotted markup it is a hunt for an
- * anchor and a guess about which element is the link.
- *
- * A crumb with no `href` is unchanged: the consumer slots whatever they like,
- * including their own anchor, and this renders a plain `<span>` around it.
- *
- * Each item renders its own separator and hides it with `:host(:first-child)`,
- * so the trail needs no index and no coordination from the parent. `:host()`
- * takes a structural pseudo-class, unlike `:has()`, which it rejects.
- *
- * The current page is text, not a link. Linking a page to itself is a known
- * screen-reader annoyance, and `aria-current="page"` on the host is what
- * conveys position.
- *
- * @since 0.1.0
- * @status stable
- * @aliases Crumb
- * @documentation https://helix.fusion.dev/components/breadcrumbs
- *
- * @slot - The step's label. Without an `href` this may be the consumer's own
- * anchor, styled with `data-link="quiet"`, since a slotted anchor belongs to the
- * outer tree and cannot be reached from this component's styles.
- * @slot end - After it, for a count or a mark.
- * @slot separator - Replaces the chevron shown before this item.
- * @slot start - Before the label, for an icon.
- *
- * @csspart link - The crumb itself, which is an `<a>` where `href` is set.
- * @csspart separator - The separator preceding the item.
- * @csspart separator-mark - The glyph between this crumb and the next, where none is slotted.
- */
 let HelixHeadlessBreadcrumb = class HelixHeadlessBreadcrumb extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * Whether this item is the page the reader is on.
-         */
         this.current = false;
-        /**
-         * What the link declares about where it goes.
-         *
-         * The consumer's decision.
-         */
         this.rel = '';
-        /**
-         * Where the link opens, for the rare crumb that leaves the site.
-         */
         this.target = '';
     }
     willUpdate(changed) {
         super.willUpdate(changed);
-        // On the host, because the item is an `<ol>` child in the flat tree and the
-        // role has to be there for the list to have items. In `willUpdate` rather
-        // than `connectedCallback`, which the server never calls.
         hostAria(this.internals, { role: 'listitem' });
         this.internals.ariaCurrent = this.current ? 'page' : null;
     }
-    /**
-     * The mark between one crumb and the next.
-     *
-     * The chevron is the slot's own fallback, so replacing it is a matter of
-     * filling the slot and costs the consumer no way to opt out of the default.
-     * The seam answers the other half: a tier drawing its own separator gets it
-     * without reimplementing the crumb, its link and its current-page branch.
-     */
     renderSeparator() {
         return html `<slot name="separator"
       ><svg part="separator-mark" fill="currentColor" viewBox=${caretRight.viewBox}>
@@ -96,12 +29,7 @@ let HelixHeadlessBreadcrumb = class HelixHeadlessBreadcrumb extends HelixElement
     >`;
     }
     render() {
-        /* The label and whatever flanks it, which is the same content whether or
-           not it is a link. Built once so the two branches below cannot drift. */
         const label = html `<slot name="start"></slot><slot></slot><slot name="end"></slot>`;
-        /* The current page is text, not a link, whatever it was given, so `current`
-           wins over `href` rather than the two contradicting each other in the
-           markup. */
         const linked = (this.href ?? '') !== '' && !this.current;
         return html `<span part="separator" aria-hidden="true"
         >${this.renderSeparator()}</span