@fusion.dev/helix-headless 0.104.1 → 0.106.0

package/dist/map/terrain/map-terrain.d.ts

@@ -0,0 +1,68 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { nothing, type PropertyValues } from 'lit';
+/** How an elevation tile stores its heights in its colors. */
+export type MapTerrainEncoding = 'mapbox' | 'terrarium';
+/**
+ * @summary Hills and mountains on a map, shaded and raised in 3D.
+ *
+ * @description
+ * `connectMap` shades the land by its slopes, from elevation tiles, so hills
+ * and valleys show on a flat map. Set `raised` to raise the ground to its real
+ * height as well, and tilt the map to see it. Routes, areas, and buildings lie
+ * on the raised ground.
+ *
+ * Set `src` to an elevation tile URL with `{z}`, `{x}`, and `{y}` in it, and
+ * `encoding` to how its tiles store heights: `terrarium`, the default, or
+ * `mapbox`. Set `max-zoom` to the deepest zoom the provider has tiles for.
+ * Put the provider's credit in `attribution`.
+ *
+ * MapLibre draws the terrain. Leaflet draws maps flat, so a Leaflet map shows
+ * none. The frame lists the layer by its `label` for screen readers.
+ *
+ * @since 0.105.0
+ * @status experimental
+ * @category media
+ * @aliases Terrain, Hillshade, Elevation, Relief
+ * @documentation https://fusion.dev/helix/components/map
+ *
+ * @event {HelixMapPartChangeEvent} helix-map-part-change - The tiles, how the ground is raised, or the layer's name or colors changed. Used by `connectMap`; pages do not need to listen for it.
+ */
+export declare class HelixHeadlessMapTerrain extends HelixElement {
+    /** The elevation provider's credit, shown in the frame's footer. Links in it stay links. */
+    attribution?: string;
+    /** More about the terrain. Read after the label in the frame's list. */
+    description?: string;
+    /** How the tiles store heights in their colors: `terrarium` or `mapbox`. */
+    encoding: MapTerrainEncoding;
+    /** How many times its real height the ground is raised, where `raised` is set. */
+    exaggeration: number;
+    /**
+     * A name this layer shares with other layers, such as a route and its
+     * dotted legs. The layers menu shows layers in the same group as one entry,
+     * named by the first of them, and its checkbox shows or hides them all.
+     */
+    group?: string;
+    /** Marks this as a layer for the frame and the connector, whatever its tag. */
+    readonly isMapLayer = true;
+    /** @internal Which kind of layer, which is how the connector draws it. */
+    readonly layerKind: 'terrain';
+    /** The layer's name in the frame's list. */
+    label: string;
+    /**
+     * The deepest zoom the provider has tiles for. The map enlarges those tiles
+     * at deeper zooms, where it would otherwise ask for tiles that do not exist.
+     */
+    maxZoom?: number;
+    /** Raises the ground to its real height in 3D. Tilt the map to see it. */
+    raised: boolean;
+    /** One elevation tile URL with `{z}`, `{x}`, and `{y}` in it. */
+    src?: string;
+    /** Tells the frame and the connector the layer changed. */
+    protected updated(changed: PropertyValues): void;
+    protected render(): typeof nothing;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-map-terrain': HelixHeadlessMapTerrain;
+    }
+}

package/dist/map/terrain/map-terrain.js

@@ -0,0 +1,58 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { customElement, HelixElement, HelixMapPartChangeEvent } from '@fusion.dev/helix-core';
+import { nothing } from 'lit';
+import { property } from 'lit/decorators.js';
+let HelixHeadlessMapTerrain = class HelixHeadlessMapTerrain extends HelixElement {
+    constructor() {
+        super(...arguments);
+        this.encoding = 'terrarium';
+        this.exaggeration = 1;
+        this.isMapLayer = true;
+        this.layerKind = 'terrain';
+        this.label = 'Terrain';
+        this.raised = false;
+    }
+    updated(changed) {
+        super.updated(changed);
+        this.dispatchEvent(new HelixMapPartChangeEvent({ kind: 'layer' }));
+    }
+    render() {
+        return nothing;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessMapTerrain.prototype, "attribution", void 0);
+__decorate([
+    property()
+], HelixHeadlessMapTerrain.prototype, "description", void 0);
+__decorate([
+    property()
+], HelixHeadlessMapTerrain.prototype, "encoding", void 0);
+__decorate([
+    property({ type: Number })
+], HelixHeadlessMapTerrain.prototype, "exaggeration", void 0);
+__decorate([
+    property()
+], HelixHeadlessMapTerrain.prototype, "group", void 0);
+__decorate([
+    property()
+], HelixHeadlessMapTerrain.prototype, "label", void 0);
+__decorate([
+    property({ attribute: 'max-zoom', type: Number })
+], HelixHeadlessMapTerrain.prototype, "maxZoom", void 0);
+__decorate([
+    property({ type: Boolean })
+], HelixHeadlessMapTerrain.prototype, "raised", void 0);
+__decorate([
+    property()
+], HelixHeadlessMapTerrain.prototype, "src", void 0);
+HelixHeadlessMapTerrain = __decorate([
+    customElement('helix-headless-map-terrain')
+], HelixHeadlessMapTerrain);
+export { HelixHeadlessMapTerrain };

package/dist/megamenu/root/megamenu-root.d.ts

@@ -2,23 +2,23 @@ import { HelixElement, PopoverController } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessMegamenu_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
 /**
- * @summary A section of a navigation that opens a panel of destinations.
+ * @summary A section of a navigation with a trigger that opens a panel of links.
  *
  * @description
- * **A disclosure, not a menu, and that is the whole design.** `role="menu"` and
- * `menuitem` are for an application's commands: they take over the arrow keys,
- * announce "menu" to a reader who asked for navigation, and put every link
- * inside a role that is not a link. This is a button that shows and hides a
- * region of the consumer's own anchors, which leaves a middle click, a modified
- * click and the status bar working. `Menu` remains right for a row of commands.
+ * A disclosure: a button that shows and hides a region of your own links. It
+ * does not use `role="menu"` or `menuitem`, which are for application commands.
+ * Those roles take over the arrow keys, announce "menu" to someone looking for
+ * navigation, and put every link inside a role that is not a link. As a
+ * disclosure, middle clicks, modified clicks, and the status bar keep working.
+ * Use `Menu` for a row of commands.
  *
- * **It renders no links.** A router renders its own anchor and cannot render
- * one inside this shadow root, so the panel is a slot and what goes in it is
- * the lists and headings the consumer wrote.
+ * It renders no links. A router renders its own anchors and cannot render them
+ * inside this shadow root, so the panel is a slot for the lists and headings
+ * you write.
  *
- * **It opens on hover, and a press is always the fallback.** `open-on` says
- * which, and hover is the resting value because a nav bar is where a reader
- * expects to sweep along a row and see each section.
+ * It opens on hover by default, and a press always opens it too. `open-on` sets
+ * which. Hover is the default because in a navigation bar people expect to move
+ * along the row and see each section.
  *
  * @since 0.1.0
  * @status stable
@@ -26,24 +26,25 @@ declare const HelixHeadlessMegamenu_base: (new (...args: any[]) => import("@fusi
  * @aliases Mega menu, Flyout, Nav panel
  * @documentation https://fusion.dev/helix/components/megamenu
  *
- * @slot - The panel's contents: the consumer's own lists and headings.
- * @slot trigger - The control that opens it. Falls back to a button named by `label`.
+ * @slot - The panel's contents, such as your own lists of links and their headings.
+ * @slot trigger - The control that opens the panel. When it is empty, a button named by `label` is shown.
  *
- * @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`.
+ * @event {HelixBeforeCloseEvent} helix-before-close - The panel is about to close. Cancelable.
+ * @event {HelixBeforeOpenEvent} helix-before-open - The panel is about to open. Cancelable.
+ * @event {Event} toggle - The panel opened or closed. Carries `newState` and `oldState`.
  *
- * @csspart surface - The floating panel, which is what opens.
- * @csspart trigger - The default trigger, where none was slotted.
+ * @csspart surface - The floating panel that opens.
+ * @csspart trigger - The default trigger button, shown when the `trigger` slot is empty.
  *
  * @cssproperty --megamenu-top - Where the panel starts, measured from the bar above it.
  *
- * @cssstate narrow - While the page is under `band-below`, so the panel is a band whether or not one was asked for.
- * @cssstate open - While the panel is open, which is when the trigger reads as current.
+ * @cssstate narrow - The page is narrower than `band-below`, so the panel is shown as a band whatever its variant.
+ * @cssstate open - The panel is open, and the trigger is shown as current.
  */
 export declare class HelixHeadlessMegamenu extends HelixHeadlessMegamenu_base {
     /**
-     * The width, in pixels, under which a card becomes a band. Zero never does.
+     * The page width, in pixels, below which a card panel is shown as a band. At
+     * zero, it never is.
      *
      * A card is a panel hung off one word, and there is no room to hang anything
      * off a word on a phone: the columns do not shrink past
@@ -69,11 +70,12 @@ export declare class HelixHeadlessMegamenu extends HelixHeadlessMegamenu_base {
      */
     bandBelow: number;
     /**
-     * The section's name, which names the default trigger and the panel.
+     * The section's name, used for the default trigger and the panel.
      */
     label: string;
     /**
-     * Whether hovering the trigger opens the panel, or only a press does.
+     * Whether hovering over the trigger opens the panel (`hover`), or only a press
+     * does (`click`).
      *
      * A press always works. This says whether a mouse also opens it by resting on
      * the trigger, and it is the default because that is what a navigation bar

package/dist/menu/item/menu-item.d.ts

@@ -4,21 +4,19 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
  * @summary One row in a menu: a command, a choice, or a way into a submenu.
  *
  * @description
- * Three shapes, one element, because a reader moving down a menu with the
- * arrow keys does not care which kind each row is and neither should the
- * markup. What it is follows from what it was given: something slotted into
- * `submenu` makes it a way in, `checked` makes it a choice, and neither makes
- * it a command.
+ * One element covers three kinds of row, and what you give it decides which:
+ * - Content in the `submenu` slot makes the row open a submenu page.
+ * - `checked` makes the row a choice.
+ * - With neither, the row is a command.
  *
- * **The role follows the shape.** A row that can be ticked is
- * `menuitemcheckbox` and carries `aria-checked`, because a reader is told "one
- * of these is on" rather than "here is a button"; `exclusive` makes it
- * `menuitemradio`, for a set where only one can be. A row that opens a page
- * keeps `menuitem` and says `aria-haspopup`, since the page it opens is a menu.
+ * The role follows the kind. A row with `checked` is `menuitemcheckbox` with
+ * `aria-checked`, and `exclusive` makes it `menuitemradio`, for a set where
+ * only one can be on. A row that opens a page keeps `menuitem` and sets
+ * `aria-haspopup`.
  *
- * Whether it is on the page showing is set by the menu as a property, never as
- * an attribute: an attribute written onto a consumer's element after it
- * upgrades is a hydration mismatch waiting to happen.
+ * The menu sets whether the row's page is showing as a property, never as an
+ * attribute. An attribute written onto your element after it upgrades causes a
+ * hydration mismatch.
  *
  * @since 0.1.0
  * @status stable
@@ -26,15 +24,15 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
  * @documentation https://fusion.dev/helix/components/menu
  *
  * @slot - The label.
- * @slot start - Before the label. A mark about the row.
- * @slot submenu - Rows this one opens, which makes it a way in.
+ * @slot start - Content before the label, such as an icon.
+ * @slot submenu - The rows of a submenu that this row opens.
  *
- * @event {HelixSelectEvent} helix-select - Fired when the row is chosen. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixSelectEvent} helix-select - The row was chosen. Cancelable: cancel it to keep the menu open.
  *
  * @csspart item - The row, which is an `<a>` where `href` is set.
- * @csspart mark - The trailing mark: a tick when checked, a caret when it opens
- * a page. One column, because a row is never both.
- * @csspart start - The leading column, which is a slot and is always there.
+ * @csspart mark - The trailing mark: a check mark when the row is checked, or a caret
+ * when it opens a submenu. A row never shows both, so they share one column.
+ * @csspart start - The leading column that holds the `start` slot. It is always rendered.
  */
 export declare class HelixHeadlessMenuItem extends HelixElement {
     /**
@@ -50,15 +48,15 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      */
     checkable: boolean;
     /**
-     * Whether the row is ticked.
+     * Whether the row is checked.
      */
     checked: boolean;
     /**
-     * Whether the row can be chosen.
+     * Whether the row is disabled, so it cannot be chosen.
      */
     disabled: boolean;
     /**
-     * Whether the link saves the file rather than opening it.
+     * Whether the link downloads the file when the row is chosen.
      *
      * Only meaningful beside an `href`, and only for a file served from this
      * origin: the attribute is ignored cross-origin, which is the browser's rule
@@ -66,7 +64,7 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      */
     download: boolean;
     /**
-     * Whether only one row of the set it belongs to can be on.
+     * Whether only one row in its set can be checked at a time.
      *
      * Announcement and nothing else, the way `checkable` is: this element applies
      * no choice and polices no group, so what it does is tell a reader which kind
@@ -79,7 +77,7 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      */
     exclusive: boolean;
     /**
-     * Where the row goes, which makes it a real link.
+     * The URL the row links to. Setting it renders the row as a link.
      *
      * **The row itself becomes an `<a>`, and the role goes with it.** A
      * `menuitem` cannot contain a link: measured in Chromium, an anchor inside
@@ -100,7 +98,7 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      */
     href: string;
     /**
-     * Whether this row is on the page currently showing.
+     * Whether the row is on the menu page that is showing.
      *
      * Set by the menu, and a property rather than an attribute for that reason.
      * Public because the menu has to reach it, and not something a consumer
@@ -108,7 +106,7 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      */
     onPage: boolean;
     /**
-     * The relationship, which `target="_blank"` should always set.
+     * The link's `rel`. Set it whenever you set `target="_blank"`.
      */
     rel: string;
     /**
@@ -123,11 +121,11 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      */
     showingSubmenu: boolean;
     /**
-     * Where the link opens, for the rows that should leave the page.
+     * Where the link opens, for rows that should open outside the current page.
      */
     target: string;
     /**
-     * What this row stands for, carried in the event when it is chosen.
+     * The row's value, sent in `helix-select` when the row is chosen.
      */
     value: string;
     /**
@@ -217,16 +215,17 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      */
     focus(): void;
     /**
-     * `NavigableItem`, so the arrow keys can be the shared controller's business.
+     * Moves focus to the row. Part of `NavigableItem`, which the shared keyboard
+     * controller uses for the arrow keys.
      *
      * `focus()` above already puts focus on the control inside the row rather than
      * on the row, which is the whole of what moving here means.
      */
     focusItem(): void;
-    /** Chooses the row, which is the same act as pressing it. */
+    /** Chooses the row, the same as pressing it. */
     select(): void;
     /**
-     * Whether this is the row the set is on, which in a menu is where focus is.
+     * Whether the row has focus, which is what selected means in a menu.
      *
      * A radio group's selection is an answer it holds; a menu has no answer, only
      * a row the reader has walked to, so focus is the whole of what "the current

package/dist/menu/root/menu-root.d.ts

@@ -2,25 +2,21 @@ import { HelixElement, KeyboardNavigationController, type Placement } from '@fus
 import { type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessMenu_base: (new (...args: any[]) => import("@fusion.dev/helix-core").CollectionElement) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
 /**
- * @summary A menu of commands, opened from a trigger.
+ * @summary A menu of commands that opens from a trigger.
  *
  * @description
- * The trigger is slotted and stays the consumer's own element, the same way the
- * tooltip takes one. The surface is rendered here, in the top layer through the
- * popover API, so it clears any ancestor with `overflow: hidden` without a
- * `z-index` anywhere.
+ * The trigger is slotted and stays your own element, as with the tooltip. The
+ * menu renders its surface in the top layer with the popover API, so an
+ * ancestor with `overflow: hidden` does not clip it and it needs no `z-index`.
  *
- * **It drills down rather than flying out.** A submenu replaces what is on
- * screen and a back row returns, instead of opening a second panel beside the
- * first. Panels beside panels need a diagonal path a pointer has to travel
- * without straying, they run off the edge of a narrow window, and on a touch
- * screen there is no hover to open them with at all. One panel that changes
- * what it holds has none of those problems and reads the same on a phone.
+ * Submenus drill down. A submenu replaces the panel's content, and a back row
+ * returns to the previous page. One panel avoids the diagonal pointer path that
+ * side-by-side panels need, stays inside a narrow window, and works on touch
+ * screens, which have no hover.
  *
- * The open page is held here rather than in each item, because only one page
- * shows at a time and something has to know which. Items are told by property,
- * not by attribute: an attribute written onto a consumer's element after it
- * upgrades is a hydration mismatch waiting to happen.
+ * The root holds which page is open, because only one page shows at a time. It
+ * sets this on items as a property, never as an attribute. An attribute written
+ * onto your element after it upgrades causes a hydration mismatch.
  *
  * @since 0.1.0
  * @status stable
@@ -29,30 +25,30 @@ declare const HelixHeadlessMenu_base: (new (...args: any[]) => import("@fusion.d
  * @documentation https://fusion.dev/helix/components/menu
  *
  * @slot - The items.
- * @slot trigger - What opens it.
+ * @slot trigger - The control that opens the menu.
  *
- * @event {HelixBeforeCloseEvent} helix-before-close - Fired before it closes, and cancelable.
- * @event {HelixBeforeOpenEvent} helix-before-open - Fired before it opens, and cancelable.
- * @event {HelixSelectEvent} helix-select - Fired when an item is chosen. Cancelable: refusing it takes the decision and nothing moves.
- * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
+ * @event {HelixBeforeCloseEvent} helix-before-close - The menu is about to close. Cancelable: cancel it to keep it open.
+ * @event {HelixBeforeOpenEvent} helix-before-open - The menu is about to open. Cancelable: cancel it to keep it closed.
+ * @event {HelixSelectEvent} helix-select - An item was chosen. Cancelable: cancel it to keep the menu open.
+ * @event {Event} toggle - The menu opened or closed. The event carries `newState` and `oldState`.
  *
  * @csspart back - The control that returns from a submenu.
  * @csspart back-mark - The glyph on the back control of a submenu.
- * @csspart empty - Shown when there are no items to show.
+ * @csspart empty - The text shown when the menu has no items.
  * @csspart header - The bar above a submenu, holding the way back and its name.
- * @csspart live - The empty and loading lines again, in a region a screen reader hears when they change. Visually hidden in the styled tier.
- * @csspart loading - Shown while the items are still on their way.
+ * @csspart live - A live region that repeats the empty and loading text, so screen readers announce it when it changes. Visually hidden in the styled tier.
+ * @csspart loading - The text shown while the items are loading.
  * @csspart surface - The floating panel the menu is drawn on.
  * @csspart title - The name of the submenu that is showing.
  *
- * @cssstate drilled - While a submenu's page is showing rather than the menu's own, so what is not a row can leave with the page it was on.
- * @cssstate mark - While a row on the page showing can be ticked or leads to a page, so the trailing column is held open for every row.
+ * @cssstate drilled - A submenu's page is showing, so content that is not a row can hide with the top page.
+ * @cssstate mark - A row on the current page has a checkbox or a link, so every row keeps the trailing column.
  * @cssstate open - While the menu is open.
- * @cssstate start - While a row on the page showing has something in its leading column, so that column is held open for every row.
+ * @cssstate start - A row on the current page has content in its leading column, so every row keeps that column.
  */
 export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
     /**
-     * What the row returning from a submenu reads.
+     * The text of the row that returns from a submenu.
      */
     backLabel: string;
     /**
@@ -64,7 +60,7 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
      */
     offset: number;
     /**
-     * Preferred side.
+     * The side the menu opens on, when there is room.
      *
      * It moves if that side does not fit.
      */
@@ -112,7 +108,7 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
     private get items();
     /** Opens the menu. */
     show(): void;
-    /** Closes the menu, and forgets which page was showing. */
+    /** Closes the menu and returns it to its first page. */
     hide(): void;
     /** Shows an item's submenu in place of the current page. */
     private enter;

package/dist/meter/root/meter-root.d.ts

@@ -3,19 +3,18 @@ import { type PropertyValues, type TemplateResult } from 'lit';
 /** Which band a value falls in, once `optimum` has said which end is good. */
 export type MeterBand = 'fair' | 'good' | 'poor';
 /**
- * @summary A measurement in a known range, and whether it is where you want it.
+ * @summary A measurement in a known range, with optional bands that mark it good, fair, or poor.
  *
  * @description
- * **Not `Progress`, and the difference is the whole component.** A progress bar
- * reports how far along a task is: it starts empty, ends full, and full is
- * always the good end. A meter reports a level in a range that is not going
- * anywhere, and which end is good is a fact about the thing measured. So there
- * is no `indeterminate`: a measurement whose value is unknown is not one.
+ * A meter shows a level within a range. Use `Progress` to show how far along a
+ * task is. A progress bar starts empty and ends full, and full is always the
+ * good end. For a meter, which end is good depends on what is measured. There
+ * is no `indeterminate`, because a meter always has a value.
  *
- * **`low`, `high` and `optimum` are the reason it exists**, following the HTML
- * specification's own rule. The three cut the range into a low band, a middle
- * and a high band, and `optimum` says which is the one to be in; the band next
- * to it is fair and the one two away is poor.
+ * **Set `low`, `high`, and `optimum`**, as defined in the HTML specification.
+ * `low` and `high` divide the range into a low band, a middle band, and a high
+ * band. `optimum` sets the preferred band. The band next to it is fair, and the
+ * band two away is poor.
  *
  * @since 0.1.0
  * @status stable
@@ -24,15 +23,15 @@ export type MeterBand = 'fair' | 'good' | 'poor';
  * @documentation https://fusion.dev/helix/components/meter
  *
  * @csspart groove - The unfilled circle, in `ring` and `arc`.
- * @csspart indicator - The part of it the value fills.
- * @csspart indicator-fair - The fill while the reading is in a band beside the good one, beside `indicator`.
- * @csspart indicator-good - The fill while the reading is in the good band, beside `indicator`.
- * @csspart indicator-over - The fill while the value is past the top, beside `indicator`.
- * @csspart indicator-poor - The fill while the reading is two bands from the good one, beside `indicator`.
- * @csspart indicator-under - The fill while the value is below the floor, beside `indicator`.
+ * @csspart indicator - The part of the track the value fills.
+ * @csspart indicator-fair - The fill while the reading is in a band next to the good band. Set alongside `indicator`.
+ * @csspart indicator-good - The fill while the reading is in the good band. Set alongside `indicator`.
+ * @csspart indicator-over - The fill while the value is above `max`. Set alongside `indicator`.
+ * @csspart indicator-poor - The fill while the reading is two bands from the good band. Set alongside `indicator`.
+ * @csspart indicator-under - The fill while the value is below `min`. Set alongside `indicator`.
  * @csspart tick - A mark at `low` or at `high`.
  * @csspart track - The whole range, or the drawing in `ring` and `arc`.
- * @csspart value - The reading, under `show-value`.
+ * @csspart value - The reading as text, shown when `show-value` is set.
  *
  * @cssproperty --meter-along - Where a bound sits on the arc, as a length along it.
  * @cssproperty --meter-at - Where a bound sits on a linear track, as a percentage.
@@ -41,7 +40,8 @@ export type MeterBand = 'fair' | 'good' | 'poor';
  */
 export declare class HelixHeadlessMeter extends HelixElement {
     /**
-     * The band, said outright, where the three thresholds cannot say it.
+     * Sets the band directly, for a rule that `low`, `high`, and `optimum` cannot
+     * express.
      *
      * **The specification's model has a shape, and it is worth knowing before
      * reaching for this.** Three bands and a point mean it can express a
@@ -99,7 +99,7 @@ export declare class HelixHeadlessMeter extends HelixElement {
      */
     min: number;
     /**
-     * Where in the range it is best to be.
+     * The point in the range where the reading is best.
      *
      * Defaults to the middle of whatever bands are declared, which is the
      * platform's own default and the right one for a score. A meter where low is
@@ -108,7 +108,7 @@ export declare class HelixHeadlessMeter extends HelixElement {
      */
     optimum?: number;
     /**
-     * Whether the reading is drawn as a bar, a ring or an arc.
+     * Whether the reading is drawn as a bar, a ring, or an arc.
      *
      * A gauge and a meter are the same thing measured: a value in a range, with
      * bands saying which part of it is the good part. What differs between the two
@@ -137,7 +137,8 @@ export declare class HelixHeadlessMeter extends HelixElement {
      */
     value: number;
     /**
-     * What the reading says, where a number is not the whole story.
+     * Text that screen readers announce and the meter shows for the reading, in
+     * place of the percentage.
      *
      * `value-text="18 GB of 32 GB"` is announced and shown instead of `56%`. The
      * same property `Progress` carries, for the same reason: a percentage is a

package/dist/navigation/root/navigation-root.d.ts

@@ -4,21 +4,18 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @summary A set of destinations, with a marker on the current one.
  *
  * @description
- * Renders a real `<nav>`, which is the landmark a screen-reader user jumps to.
- * It exists as its own component rather than as a region of `AppHeader` because
- * a header is not inherently navigation, and navigation is not only ever in a
- * header: a footer and a sidebar hold the same thing.
+ * Renders a real `<nav>`, the landmark that screen reader users jump to.
+ * Navigation is its own component, separate from `AppHeader`, so you can use it
+ * in a header, a footer, or a sidebar.
  *
- * **It renders no links.** The consumer brings them, marked with
- * `aria-current="page"` and styled by the `data-navigation-item` recipe, for the same
- * reason nothing else here renders an anchor: a router renders its own, and
- * cannot render it inside this shadow root.
+ * **It renders no links.** Bring your own, mark the current one with
+ * `aria-current="page"`, and style them with the `data-navigation-item` recipe.
+ * A router renders its own anchors and cannot render them inside the
+ * component's shadow root.
  *
- * What this owns is the marker that travels between them, and that is the whole
- * reason it is a component. A marker that moves needs something that knows
- * where every item is, and reading `aria-current` is how it knows which: the
- * thing that makes the page announce correctly is the same thing that puts the
- * marker in the right place.
+ * The component moves a marker to the current item. It finds the current item
+ * by reading `aria-current`, so the attribute that screen readers announce also
+ * places the marker.
  *
  * @since 0.1.0
  * @status stable
@@ -26,15 +23,15 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @aliases Nav, NavList, Tabs
  * @documentation https://fusion.dev/helix/components/navigation
  *
- * @slot - The destinations, as the consumer's own links.
+ * @slot - The destinations, as your own links.
  *
- * @csspart indicator - The marker that travels to the current destination.
+ * @csspart indicator - The marker that moves to the current destination.
  * @csspart nav - The navigation landmark.
  */
 export declare class HelixHeadlessNavigation extends HelixElement {
     private readonly indicator;
     /**
-     * Accessible name for the landmark.
+     * The landmark's name, read by screen readers.
      */
     label: string;
     private current;