@fusion.dev/helix-headless 0.105.0 → 0.106.0

package/dist/date-picker/root/date-picker-root.d.ts

@@ -2,23 +2,26 @@ import { HelixFormElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessDatePicker_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & typeof HelixFormElement;
 /**
- * @summary Shows a month, and takes a date from it.
+ * @summary A month calendar for choosing one or more dates.
  *
  * @description
- * A grid of days, per the APG date grid: the whole grid is one tab stop, arrows
- * move by day and week, `PageUp` and `PageDown` by month, `Home` and `End` to
- * the ends of the week. Only the focused cell is in the tab sequence.
+ * A grid of days that follows the APG date grid pattern:
  *
- * **Dates are `YYYY-MM-DD` strings and every calculation is in UTC.** A
- * local-time `Date` shifts across a timezone or a daylight-saving boundary.
+ * - The grid is one tab stop. Only the focused cell is in the tab sequence.
+ * - Arrow keys move by day and by week.
+ * - `PageUp` and `PageDown` move by month.
+ * - `Home` and `End` move to the start and end of the week.
  *
- * `month` is what the grid shows, separately from `value`, so paging does not
- * select anything and a consumer can drive the view. Left unset it follows the
+ * **Dates are `YYYY-MM-DD` strings, and every calculation is in UTC**, because
+ * a local-time `Date` shifts across a time zone or daylight-saving boundary.
+ *
+ * `month` sets which month the grid shows, separately from `value`, so paging
+ * selects nothing and you can control the view. When unset, it follows the
  * first selected date, then the current month.
  *
- * `mode` decides how many dates are held: absent takes one, `range` takes two
- * and marks everything between them, `multiple` toggles. All three read and
- * write the same comma-separated `value`.
+ * `mode` sets how many dates are held. Unset holds one, `range` holds two and
+ * marks the dates between them, and `multiple` toggles each date. All three
+ * read and write the same comma-separated `value`.
  *
  * @since 0.1.0
  * @status stable
@@ -29,16 +32,16 @@ declare const HelixHeadlessDatePicker_base: (new (...args: any[]) => import("@fu
  * @slot next-icon - The glyph on the control that moves forward a month, usually a caret.
  * @slot previous-icon - The glyph on the control that moves back a month, usually a caret.
  *
- * @event {Event} change - Announced once the value has moved.
+ * @event {Event} change - Fired after the value changes.
  * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the dates change, and cancelable.
  * @event {HelixNavigateEvent} helix-navigate - Fired before the month on show changes, and cancelable.
- * @event {Event} input - Announced once the value has moved.
+ * @event {Event} input - Fired after the value changes.
  *
- * @csspart cell - One column of a row, which is what a range paints.
+ * @csspart cell - One column of a week row. A range is painted on the cells.
  * @csspart cell-range-end - The cell of a range's last day, beside `cell`.
  * @csspart cell-range-middle - A cell between a range's ends, beside `cell`.
  * @csspart cell-range-start - The cell of a range's first day, beside `cell`.
- * @csspart day - The shape inside a cell, which is what a single date paints.
+ * @csspart day - The shape inside a cell. A single chosen date is painted on it.
  * @csspart day-disabled - A day that cannot be chosen, beside `day`.
  * @csspart day-outside - A day from a neighboring month, filling the grid out, beside `day`.
  * @csspart day-selected - The chosen day, or either end of a chosen range, beside `day`.
@@ -59,7 +62,7 @@ declare const HelixHeadlessDatePicker_base: (new (...args: any[]) => import("@fu
  */
 export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_base {
     /**
-     * What a reader is told when the value holds something that is not a date.
+     * The validation message for a value that is not a date.
      *
      * **Every sentence a control raises in the browser's bubble is a property**,
      * named for the validity flag it reports, so a form in another language
@@ -67,7 +70,7 @@ export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_bas
      */
     badInputMessage?: string;
     /**
-     * Month to open on, where nothing declared one.
+     * The month to open on when `month` is not set.
      */
     defaultMonth: string;
     /**
@@ -111,7 +114,8 @@ export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_bas
     /** The month on show, whoever set it, and `undefined` until somebody has. */
     private monthState;
     /**
-     * The month on show, as `YYYY-MM`. Follows `value`, then the current month.
+     * The month shown, as `YYYY-MM`. When it is not set, it follows `value`,
+     * then the current month.
      *
      * Separate from `value` on purpose, so paging selects nothing and a consumer
      * can drive the view. Reading gives the month on show; writing sets it, and
@@ -137,7 +141,7 @@ export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_bas
      */
     previousLabel: string;
     /**
-     * Whether the control refuses changes while still submitting its value.
+     * Blocks changes to the dates. The value is still submitted with the form.
      *
      * **Enforced by refusing every request in one place**, which is the seam this
      * component already has: `requestValue` is what every path here comes through,
@@ -218,7 +222,7 @@ export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_bas
     connectedCallback(): void;
     disconnectedCallback(): void;
     /**
-     * Whether the form refuses to submit while nothing is chosen.
+     * Stops the form from submitting while no date is chosen.
      */
     required: boolean;
     /** Refuses every change while read-only. See `readOnly`. */
@@ -238,7 +242,7 @@ export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_bas
      */
     step: number;
     /**
-     * What a reader is told when a date is required and none is chosen.
+     * The validation message for a required date picker with no date chosen.
      */
     valueMissingMessage?: string;
     /**

package/dist/description-list/item/description-list-item.d.ts

@@ -4,13 +4,13 @@ import { type TemplateResult } from 'lit';
  * @summary One label and its value.
  *
  * @description
- * An element rather than a pair of slots on the list, because a pair is the
- * unit a reader hears: the label is the `<dt>` and the value its `<dd>`, and the
- * two stay together however the list lays them out.
+ * Each pair is its own element: the label is the `<dt>` and the value its
+ * `<dd>`, and a screen reader hears them together however the list lays them
+ * out.
  *
- * The value is the default slot, since it is what varies and is often more
- * than text: a tag, an avatar, a link. The label is text almost every time, so
- * it is also a property.
+ * The value is the default slot, because it varies and is often more than text,
+ * such as a tag, an avatar, or a link. The label is almost always text, so it
+ * is also a property.
  *
  * @since 0.1.0
  * @status stable
@@ -24,7 +24,7 @@ import { type TemplateResult } from 'lit';
  */
 export declare class HelixHeadlessDescriptionListItem extends HelixElement {
     /**
-     * What the value is called, for the common case of plain text.
+     * The label, when it is plain text.
      *
      * The fallback of the `label` slot, so slotted content replaces it rather than
      * appearing beside it. The value itself is the default slot: it is the half

package/dist/description-list/root/description-list-root.d.ts

@@ -1,24 +1,19 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type TemplateResult } from 'lit';
 /**
- * @summary Labels and their values, read as pairs: the details panel every
- * product has.
+ * @summary A list of labels and their values, such as a details panel.
  *
  * @description
- * "Owner: Ada, Region: us-east, Created: 3 days ago" is the commonest panel in
- * any console, and built from layout primitives it is a run of adjacent text:
- * nothing tells a screen reader that a label and a value belong together, or
- * how many pairs there are. This renders the element the platform has for it,
- * a `<dl>`, with each item's label a `<dt>` and its value a `<dd>`.
+ * Renders a `<dl>`, with each item's label as a `<dt>` and its value as a
+ * `<dd>`, for panels such as "Owner: Ada, Region: us-east, Created: 3 days
+ * ago". A screen reader announces which label goes with which value and how
+ * many pairs there are.
  *
- * **The items render their own term and description**, and the list takes them
- * through its slot. The accessibility tree is built from the flattened tree, so
- * the pairs reach it inside the list rather than beside it. Measured in
- * Chromium's tree rather than assumed, because a list whose semantics stopped
- * at a shadow boundary would look identical on screen: one description list
- * holding term and definition pairs, node for node what a plain `<dl>` with the
- * same content produces, with a slotted label and with an item drawn as
- * `display: contents` alike.
+ * **Each item renders its own term and description**, and the list takes the
+ * items through its slot. The accessibility tree is built from the flattened
+ * tree, so the pairs appear inside the list. Measured in Chromium, the result
+ * matches a plain `<dl>` with the same content node for node, both with a
+ * slotted label and with an item set to `display: contents`.
  *
  * @since 0.1.0
  * @status stable

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

@@ -2,20 +2,22 @@ import { CommandController, HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessDialog_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
 /**
- * @summary A modal window, on the platform's own dialog.
+ * @summary A modal window built on the native `<dialog>` element.
  *
  * @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: the top layer, so the dialog is above everything whatever
- * `z-index` anyone wrote; a real backdrop; Escape; and inert-behind, so the
- * page underneath is unreachable by pointer, keyboard or virtual cursor.
+ * Renders a native `<dialog>` opened with `showModal()`. The platform provides:
  *
- * **`open` drives `showModal()`, and every way it can close comes back through
- * `requestOpen`.** A native dialog closes from three directions: the property,
- * Escape, and a `<form method="dialog">` submit. Left alone, two of them would
- * shut the dialog while the consumer's state still said open, which is the bug
- * that makes a modal impossible to reopen.
+ * - the top layer, so the dialog is above everything whatever the `z-index`
+ * - a backdrop
+ * - closing with Escape
+ * - an inert page behind the dialog, unreachable by pointer, keyboard, or
+ *   virtual cursor
+ *
+ * `open` calls `showModal()`, and every way the dialog closes goes through
+ * `requestOpen`. A native dialog closes three ways: the property, Escape, and a
+ * `<form method="dialog">` submit. Routing all three through `requestOpen`
+ * keeps your state in step, so the dialog never closes while your state still
+ * says it is open, which would leave it impossible to reopen.
  *
  * @since 0.1.0
  * @status stable
@@ -24,14 +26,14 @@ declare const HelixHeadlessDialog_base: (new (...args: any[]) => import("@fusion
  * @documentation https://fusion.dev/helix/components/dialog
  *
  * @slot - The dialog's content.
- * @slot footer - The actions.
+ * @slot footer - The dialog's actions.
  * @slot header - The title, and anything beside it.
- * @slot icon - A single mark above the title, for a dialog that warns.
+ * @slot icon - An icon above the title, for a warning dialog.
  *
- * @event {Event} close - Relayed, because the platform's own does not escape.
+ * @event {Event} close - Sent from the host after the dialog closes, because the native `close` event does not leave the shadow root.
  * @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 {Event} toggle - Sent when the dialog opens or closes, with `newState` and `oldState`.
  *
  * @csspart dialog - The native dialog element.
  *
@@ -39,7 +41,7 @@ declare const HelixHeadlessDialog_base: (new (...args: any[]) => import("@fusion
  */
 export declare class HelixHeadlessDialog extends HelixHeadlessDialog_base {
     /**
-     * Which close requests the browser answers on its own.
+     * Which close requests the browser handles on its own.
      *
      * `<dialog closedby>`, forwarded, and safe to forward because every path it
      * opens still comes back through this element: a close request fires `cancel`
@@ -57,7 +59,7 @@ export declare class HelixHeadlessDialog extends HelixHeadlessDialog_base {
     label: string;
     protected readonly commands: CommandController;
     /**
-     * Whether Escape or a press on the backdrop can close it.
+     * Stops Escape and a press on the backdrop from closing the dialog.
      *
      * 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
@@ -86,10 +88,11 @@ export declare class HelixHeadlessDialog extends HelixHeadlessDialog_base {
     private returned;
     /** The native dialog, or nothing where there is no DOM to hold one. */
     private get dialog();
-    /** Moves focus into the dialog and makes the rest of the page inert. */
+    /** Opens the dialog, moves focus into it, and makes the rest of the page inert. */
     show(): void;
     /**
-     * Asks to close, which a consumer may refuse.
+     * Requests that the dialog close. A `helix-before-close` listener can cancel
+     * the request.
      *
      * 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

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

@@ -1,18 +1,17 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 /**
- * @summary Separates content into groups with a rule.
+ * @summary A line that separates content into groups.
  *
  * @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.
+ * The separator role is on the rule inside the shadow root. A role does not
+ * need to cross the shadow boundary the way an IDREF does, so it can sit on the
+ * rendered element. The semantics are then in the server-rendered markup, with
+ * no attribute written by script after the element connects.
  *
  * 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.
+ * toolbar. A vertical divider stretches to fit its flex parent and sets no
+ * height of its own.
  *
  * @since 0.1.0
  * @status stable
@@ -20,14 +19,14 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @aliases Separator, Rule
  * @documentation https://fusion.dev/helix/components/divider
  *
- * @slot - Content set into the rule, such as the word between two sections.
+ * @slot - Content set into the line, such as a 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.
+ * @csspart content - The content set into the line.
+ * @csspart line - The line, or each half of it when content is set into it.
  */
 export declare class HelixHeadlessDivider extends HelixElement {
     /**
-     * Whether the rule is announced as a separator.
+     * Whether screen readers announce the line 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
@@ -42,7 +41,7 @@ export declare class HelixHeadlessDivider extends HelixElement {
      */
     announced: boolean;
     /**
-     * Which way the rule runs.
+     * The direction the line runs: `horizontal` or `vertical`.
      */
     orientation?: 'horizontal' | 'vertical';
     /**

package/dist/donut-chart/root/donut-chart-root.d.ts

@@ -3,18 +3,17 @@ import { nothing, type TemplateResult } from 'lit';
 import '../../tooltip/index.js';
 declare const HelixHeadlessDonutChart_base: typeof HelixElement & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinChartSourceInterface);
 /**
- * @summary Parts of a whole as a ring, read from a table.
+ * @summary A chart that shows 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.
+ * A donut chart divides one whole into parts, so the component reads one
+ * column.
  *
- * **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, so the first
- * column of numbers is the series and each row is a slice.
+ * **The first column of numbers is the series, and each row is a slice.** Other
+ * Helix charts take one column per series.
  *
- * **It refuses negative values rather than drawing them.** 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.
+ * **Negative values are skipped.** An arc cannot show a negative number, so
+ * those rows are left out and the total is the sum of the remaining rows.
  *
  * @since 0.1.0
  * @status stable
@@ -22,28 +21,28 @@ declare const HelixHeadlessDonutChart_base: typeof HelixElement & (new (...args:
  * @aliases Pie Chart, Ring Chart, Share Chart
  * @documentation https://fusion.dev/helix/components/donut-chart
  *
- * @slot - Goes in the middle of the ring. A total, usually.
+ * @slot - Content in the middle of the ring, usually a total.
  *
  * @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-active - The slice under the pointer, beside `segment`.
- * @csspart segment-edge - One slice as a closed shape, for a boundary to trace.
+ * @csspart segment-active - The slice under the pointer. Set alongside `segment`.
+ * @csspart segment-edge - One slice as a closed shape, used to draw its outline.
  * @csspart tooltip - The bubble, forwarded from `Tooltip`.
  * @csspart tooltip-anchor - The `Tooltip` element itself.
  * @csspart tooltip-arrow - The bubble's point, forwarded from `Tooltip`.
- * @csspart tooltip-arrow-bottom - The point while the bubble is below the reading, so on its top edge, beside `tooltip-arrow`.
- * @csspart tooltip-arrow-left - The point while the bubble is left of the reading, so on its right edge, beside `tooltip-arrow`.
- * @csspart tooltip-arrow-right - The point while the bubble is right of the reading, so on its left edge, beside `tooltip-arrow`.
- * @csspart tooltip-arrow-top - The point while the bubble is above the reading, so on its bottom edge, beside `tooltip-arrow`.
- * @csspart tooltip-bottom - The bubble while it is below the reading, beside `tooltip`.
+ * @csspart tooltip-arrow-bottom - The point while the bubble is below the reading, on its top edge. Set alongside `tooltip-arrow`.
+ * @csspart tooltip-arrow-left - The point while the bubble is left of the reading, on its right edge. Set alongside `tooltip-arrow`.
+ * @csspart tooltip-arrow-right - The point while the bubble is right of the reading, on its left edge. Set alongside `tooltip-arrow`.
+ * @csspart tooltip-arrow-top - The point while the bubble is above the reading, on its bottom edge. Set alongside `tooltip-arrow`.
+ * @csspart tooltip-bottom - The bubble while it is below the reading. Set alongside `tooltip`.
  * @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-left - The bubble while it is left of the reading, beside `tooltip`.
+ * @csspart tooltip-left - The bubble while it is left of the reading. Set alongside `tooltip`.
  * @csspart tooltip-name - A column's name inside the tooltip.
- * @csspart tooltip-right - The bubble while it is right of the reading, beside `tooltip`.
- * @csspart tooltip-top - The bubble while it is above the reading, beside `tooltip`.
+ * @csspart tooltip-right - The bubble while it is right of the reading. Set alongside `tooltip`.
+ * @csspart tooltip-top - The bubble while it is above the reading. Set alongside `tooltip`.
  * @csspart tooltip-value - A column's value inside the tooltip.
  * @csspart track - The ring the slices are drawn on.
  *
@@ -67,7 +66,7 @@ export declare class HelixHeadlessDonutChart extends HelixHeadlessDonutChart_bas
      */
     connectedCallback(): void;
     /**
-     * How much is left open in the middle.
+     * The size of the hole in the middle of the ring.
      *
      * Absent is a ring with room for a total in it. `small` and `large` move the
      * hole without moving the outer edge, so a chart keeps its footprint.

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

@@ -5,23 +5,24 @@ declare const HelixHeadlessDrawer_base: (new (...args: any[]) => import("@fusion
  * @summary A panel that slides in from an edge.
  *
  * @description
- * Takes `MixinControllerOpen`, so `open`, `defaultOpen` and the
- * `helix-before-open` and `helix-before-close` requests behave exactly as they
- * do on an accordion item, and a consumer already knows the API.
+ * Uses `MixinControllerOpen`, so `open`, `defaultOpen`, and the
+ * `helix-before-open` and `helix-before-close` events work the same way as on
+ * an accordion item.
  *
- * Modal by default, which is three things together and not one: focus is
- * trapped inside, Escape and an outside press close it, and the page behind is
- * covered. A panel with the look of a modal and none of its behavior is worse
- * than an inline one, because it invites the reader to treat it as blocking.
+ * The drawer is modal by default, which means three things:
  *
- * Content stays mounted when closed, so it is in the server's markup and can
- * animate. A closed `<dialog>` is already out of the tab order and out of the
- * accessibility tree, so nothing here writes `inert`. The `role`, the
- * `aria-modal` and the scrim come from the element too, and
- * `drawer-root.ssr.spec.ts` asserts the panel carries no hand-written `inert`
- * and no hand-written `role`.
+ * - focus is trapped inside
+ * - Escape and a press outside close it
+ * - the page behind is covered
  *
- * Opened declaratively with the platform's invoker attributes:
+ * Content stays mounted when the drawer is closed, so it is in the server
+ * markup and can animate. A closed `<dialog>` is already out of the tab order
+ * and the accessibility tree, so the drawer does not write `inert`. The `role`,
+ * `aria-modal`, and the scrim also come from the `<dialog>` element.
+ * `drawer-root.ssr.spec.ts` checks that the panel has no hand-written `inert`
+ * or `role`.
+ *
+ * Open the drawer declaratively with the platform's invoker attributes:
  *
  * ```html
  * <helix-headless-button commandfor="nav" command="--toggle">Menu</helix-headless-button>
@@ -37,10 +38,10 @@ declare const HelixHeadlessDrawer_base: (new (...args: any[]) => import("@fusion
  * @slot - The drawer's content.
  * @slot header - Content pinned above the scrolling area.
  *
- * @event {Event} close - Relayed, because the platform's own does not escape.
+ * @event {Event} close - Sent from the host after the drawer closes, because the native `close` event does not leave the shadow root.
  * @event {HelixBeforeCloseEvent} helix-before-close - Fired before the panel closes, and cancelable.
- * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the panel opens. Cancelable: refusing it takes the decision and nothing moves.
- * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
+ * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the panel opens, and cancelable. Canceling it keeps the panel closed.
+ * @event {Event} toggle - Sent when the drawer opens or closes, with `newState` and `oldState`.
  *
  * @csspart content - The scrolling content region.
  * @csspart header - The header region.
@@ -51,7 +52,7 @@ declare const HelixHeadlessDrawer_base: (new (...args: any[]) => import("@fusion
 export declare class HelixHeadlessDrawer extends HelixHeadlessDrawer_base {
     protected readonly commands: CommandController;
     /**
-     * Which close requests the browser answers on its own.
+     * Which close requests the browser handles on its own.
      *
      * `<dialog closedby>`, forwarded, and safe to forward because every path it
      * opens still comes back through this element: a close request fires `cancel`

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

@@ -1,43 +1,43 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 /**
- * @summary One row of a drill-down, which may hold a page of its own.
+ * @summary One row of a drill-down, which can open a page of its own.
  *
  * @description
- * A row that opens a page *contains* that page: its rows are this row's own
- * children, assigned to the `page` slot. The tree is the structure, so there
- * are no ids to wire and a consumer who moves a row has moved its page with it.
+ * A row that opens a page contains that page: the page's rows are this row's
+ * own children, assigned to the `page` slot. There are no ids to wire, and
+ * moving a row moves its page with it.
  *
- * **It renders one of three things**, and which one is the stack's business
- * rather than its own. On the page showing, it is a row. Showing its own page,
- * it contributes that page's rows and nothing else, because its row belongs to
- * the page above. On neither, it renders nothing at all: the rows are in the
- * light DOM and come back untouched, so there is no state to keep and nothing
- * to hide with an attribute this element would have to write onto itself.
+ * What the item renders depends on the stack:
  *
- * Choosing is announced, never applied. The row dispatches and the stack
- * decides whether that means drilling in or choosing a command.
+ * - On the page that is showing, it renders its row.
+ * - When its own page is showing, it renders only that page's rows. Its row
+ *   belongs to the page above.
+ * - Otherwise it renders nothing. The rows stay in the light DOM untouched, so
+ *   there is no state to keep.
  *
- * **A row that opens a page says so**, with a caret after its words and
- * `aria-haspopup`, the way `Menu` marks a row with a submenu: a row that goes
- * somewhere and a row that does something otherwise look the same until one is
- * pressed. Not on the server, which cannot see the children and so cannot know.
+ * Choosing a row dispatches an event, and the stack decides whether that drills
+ * in or runs a command.
+ *
+ * A row that opens a page shows a caret after its text and sets
+ * `aria-haspopup`, the same way `Menu` marks a row with a submenu. The server
+ * render leaves both out, because the server cannot see the children.
  *
  * @since 0.1.0
  * @status stable
  * @aliases Panel item, Drill row
  * @documentation https://fusion.dev/helix/components/drilldown
  *
- * @slot - The words naming this row.
- * @slot end - After the words, usually a mark or a count.
- * @slot page - The rows of the page this one opens.
- * @slot start - Before the words, usually an icon.
+ * @slot - The row's label.
+ * @slot end - Content after the label, usually an icon or a count.
+ * @slot page - The rows of the page this row opens.
+ * @slot start - Content before the label, usually an icon.
  *
- * @event {HelixSelectEvent} helix-select - Fired when the row is chosen. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixSelectEvent} helix-select - Fired when the row is chosen. Cancelable: canceling it stops the change and leaves the decision to you.
  *
  * @csspart item - The row itself.
- * @csspart label - The words.
- * @csspart mark - The caret at the end of a row that opens a page, after the `end` slot. A caret points, so a sheet mirrors it in a right-to-left document.
+ * @csspart label - The row's label.
+ * @csspart mark - The caret at the end of a row that opens a page, after the `end` slot. The caret points, so a stylesheet mirrors it in a right-to-left document.
  */
 export declare class HelixHeadlessDrilldownItem extends HelixElement {
     /**
@@ -45,7 +45,7 @@ export declare class HelixHeadlessDrilldownItem extends HelixElement {
      */
     disabled: boolean;
     /**
-     * Whether this row holds the region's tab stop. Written by the stack.
+     * Whether this row holds the region's tab stop. Set by the drill-down.
      *
      * A drill-down keeps one stop and moves within it on the arrows, so every
      * other row is at `-1`. Leave it off every row, including the first, and
@@ -77,7 +77,7 @@ export declare class HelixHeadlessDrilldownItem extends HelixElement {
      */
     showingPage: boolean;
     /**
-     * Identifies the row to whatever is listening.
+     * Identifies the row to your event listeners.
      */
     value: string;
     /**
@@ -112,8 +112,8 @@ export declare class HelixHeadlessDrilldownItem extends HelixElement {
     /** Moves focus onto the row itself. */
     focusItem(): void;
     /**
-     * Whether this is the row the set is on, which in a drill-down is where focus
-     * is.
+     * Whether this is the current row, which in a drill-down is the row with
+     * focus.
      *
      * A radio group's selection is an answer it holds; a page of rows has no
      * answer, only the row a reader has walked to, so focus is the whole of what
@@ -129,7 +129,7 @@ export declare class HelixHeadlessDrilldownItem extends HelixElement {
      * dereferences what it ran out of.
      */
     get selected(): boolean;
-    /** Announces that this row was chosen. */
+    /** Fires `helix-select` for this row. */
     select(): void;
     protected render(): TemplateResult | typeof nothing;
 }