@fusion.dev/helix-headless 0.104.1 → 0.106.0

package/dist/object-inspector/root/object-inspector-root.d.ts

@@ -14,44 +14,32 @@ interface Row {
     value: unknown;
 }
 /**
- * @summary A value read as a tree: collapse what you do not need, count what
- * you collapsed, copy the part you do.
+ * @summary A structured value shown as a tree, where you can close branches,
+ * see how many entries each holds, and copy any part.
  *
  * @description
- * What a developer-facing product shows constantly is a structured value: an
- * API response, a config, a row's raw record. As text in a code block, a reader
- * scrolls a wall of JSON and cannot put away the branch they do not care about;
- * as a Tree, every node is a label and a string reads the same as a number. This
- * reads the value and draws each entry with its type visible.
+ * Object Inspector shows a structured value, such as an API response, a config,
+ * or a raw record, as a read-only tree with each entry's type visible.
  *
- * **It reads and never edits.** An inspector that edits is a different
- * component, with validation, undo and a model of what changed, and the reading
- * one is what is wanted.
+ * Pass the object to `value`, or name a `<script type="application/json">` by
+ * id with `for`, the same source `VirtualList` and the charts read. JSON text
+ * works with server rendering and with React hydration, which skips object
+ * properties. `value` wins when both are set.
  *
- * **The data is text in the page or a property.** `for` names a
- * `<script type="application/json">` by id, the channel `VirtualList` and the
- * charts already read: it survives a server, which has attributes and no
- * children, and React's hydration, which skips object properties. `value` is
- * there for a page that already holds the object, and wins when both are set.
+ * The tree is one tab stop. Up and Down move between rows, Right opens a branch
+ * or moves into it, Left closes it or moves to its parent, and Home and End
+ * move to the first and last rows. Focus stays on the tree, and
+ * `aria-activedescendant` marks the active row. Each row carries its real
+ * level, position, and set size, including in a windowed tree.
  *
- * **One tab stop, and the rows are reached with the arrow keys**, the tree
- * pattern: Up and Down move, Right opens a branch or enters it, Left closes it or
- * goes to its parent, Home and End go to the ends. The tree keeps focus and
- * points at the active row with `aria-activedescendant`, which is what lets a
- * windowed tree drop rows from the page without dropping focus with them. Each
- * row carries its real level, position and set size, so a reader on a windowed
- * row hears where it is in the value rather than in the slice drawn.
+ * The copy button copies the active row, a branch as JSON and a string as its
+ * text. So do Command+C and Control+C while the tree has focus and no text is
+ * selected. The button sits beside the tree, because assistive technology
+ * cannot reliably reach a button inside a tree item.
  *
- * **Copying takes the active row**, as JSON for a branch and as itself for a
- * string, from the copy button or from Command or Control with C while the tree
- * has focus and nothing is selected. The button sits beside the tree rather than in each row, where a
- * button would be an interactive control inside a tree item, which assistive
- * technology cannot reach reliably.
- *
- * **`windowed` draws only the rows in view**, for a value of thousands of
- * entries, through the same controller `VirtualList` and `DataTable` use. The
- * box has to have a height for that to mean anything, which the styled tier
- * gives it and a headless consumer has to.
+ * `windowed` draws only the rows in view, for values with thousands of entries.
+ * The box needs a height for windowing to work. The styled tier sets one, and
+ * in the headless tier you set it yourself.
  *
  * @since 0.1.0
  * @status stable
@@ -61,48 +49,48 @@ interface Row {
  *
  * @event {HelixCopyEvent} helix-copy - A value was put on the clipboard, from the copy button or the keyboard.
  *
- * @csspart after - The room the rows after the window would take, when windowed.
- * @csspart before - The room the rows before the window would take, when windowed.
+ * @csspart after - The space the rows below the drawn rows would take, when `windowed` is set.
+ * @csspart before - The space the rows above the drawn rows would take, when `windowed` is set.
  * @csspart boolean - A `true` or `false`.
  * @csspart copy - The copy button, which copies the active row.
- * @csspart copy-button - The inner button.
- * @csspart copy-mark - The clipboard glyph, and the confirmation that replaces it.
- * @csspart copy-tooltip - The bubble, forwarded from the tooltip inside.
- * @csspart copy-tooltip-arrow - The point, resting against the trigger.
- * @csspart copy-tooltip-arrow-bottom - The point while the bubble is below the copy button, so on its top edge, beside `copy-tooltip-arrow`.
- * @csspart copy-tooltip-arrow-left - The point while the bubble is left of the copy button, so on its right edge, beside `copy-tooltip-arrow`.
- * @csspart copy-tooltip-arrow-right - The point while the bubble is right of the copy button, so on its left edge, beside `copy-tooltip-arrow`.
- * @csspart copy-tooltip-arrow-top - The point while the bubble is above the copy button, so on its bottom edge, beside `copy-tooltip-arrow`.
- * @csspart copy-tooltip-bottom - The bubble while it is below the copy button, beside `copy-tooltip`.
- * @csspart copy-tooltip-left - The bubble while it is left of the copy button, beside `copy-tooltip`.
- * @csspart copy-tooltip-right - The bubble while it is right of the copy button, beside `copy-tooltip`.
- * @csspart copy-tooltip-top - The bubble while it is above the copy button, beside `copy-tooltip`.
- * @csspart count - How many entries a branch holds.
+ * @csspart copy-button - The button inside the copy control.
+ * @csspart copy-mark - The clipboard icon, and the confirmation icon that replaces it.
+ * @csspart copy-tooltip - The tooltip, forwarded from the copy button's tooltip.
+ * @csspart copy-tooltip-arrow - The tooltip's arrow, pointing at the copy button.
+ * @csspart copy-tooltip-arrow-bottom - The arrow while the tooltip is below the copy button, on the tooltip's top edge. Set alongside `copy-tooltip-arrow`.
+ * @csspart copy-tooltip-arrow-left - The arrow while the tooltip is left of the copy button, on the tooltip's right edge. Set alongside `copy-tooltip-arrow`.
+ * @csspart copy-tooltip-arrow-right - The arrow while the tooltip is right of the copy button, on the tooltip's left edge. Set alongside `copy-tooltip-arrow`.
+ * @csspart copy-tooltip-arrow-top - The arrow while the tooltip is above the copy button, on the tooltip's bottom edge. Set alongside `copy-tooltip-arrow`.
+ * @csspart copy-tooltip-bottom - The tooltip while it is below the copy button. Set alongside `copy-tooltip`.
+ * @csspart copy-tooltip-left - The tooltip while it is left of the copy button. Set alongside `copy-tooltip`.
+ * @csspart copy-tooltip-right - The tooltip while it is right of the copy button. Set alongside `copy-tooltip`.
+ * @csspart copy-tooltip-top - The tooltip while it is above the copy button. Set alongside `copy-tooltip`.
+ * @csspart count - The number of entries a branch holds.
  * @csspart frame - The tree and the copy button beside it.
- * @csspart header - The bar carrying the label, where there is one.
+ * @csspart header - The bar that holds the label, when there is one.
  * @csspart key - A property name or an array index.
  * @csspart label - The label.
  * @csspart null - A `null`.
  * @csspart number - A number.
- * @csspart row - One entry, a tree item.
- * @csspart row-active - The entry the keyboard is on, beside `row`.
+ * @csspart row - One entry, as a tree item.
+ * @csspart row-active - The entry the keyboard is on. Set alongside `row`.
  * @csspart string - A string, in quotes.
- * @csspart summary - The brackets standing for a branch's contents.
- * @csspart toggle - The caret on a branch: down when open, across when closed.
- * @csspart tree - The tree, the one thing focus lands on.
+ * @csspart summary - The brackets that stand for a branch's contents.
+ * @csspart toggle - The caret on a branch. It points down when the branch is open and sideways when it is closed.
+ * @csspart tree - The tree, which is the element that receives focus.
  *
  * @cssproperty --object-inspector-level - How deep a row is, from 0 at the root, for indenting it.
  */
 export declare class HelixHeadlessObjectInspector extends HelixElement {
     /**
-     * What the copy control is called on a row with a key, with the key as
-     * `{name}`.
+     * The copy button's accessible name on a row with a key, with the key filled
+     * in as `{name}`.
      *
      * **Every word the inspector speaks is a property**, so a page in another
      * language hears its own rather than English around its own keys.
      */
     copyLabel: string;
-    /** What the copy control is called where there is no key, on the value itself. */
+    /** The copy button's accessible name on a row without a key, such as the root. */
     copyValueLabel: string;
     /**
      * How many levels start open.
@@ -126,7 +114,7 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
      */
     label: string;
     /**
-     * Whether to leave the copy button off.
+     * Hides the copy button.
      *
      * Negative for the reason Code Block's is: a boolean attribute defaulting to
      * true could never be turned off from markup.
@@ -140,7 +128,7 @@ export declare class HelixHeadlessObjectInspector extends HelixElement {
      */
     noCopy: boolean;
     /**
-     * The value itself, for a page that already holds it.
+     * The value to show, when your code already holds it as an object.
      *
      * Takes precedence over `for`. Anything JSON can say is drawn; anything else
      * is shown as its string.

package/dist/option/group/option-group.d.ts

@@ -1,31 +1,31 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 /**
- * @summary A named run of options inside a listbox.
+ * @summary A labeled group of options inside a listbox.
  *
  * @description
- * A heading over a set, and nothing else: it holds no selection and no value,
- * because grouping is presentation over a list whose owner is the listbox. Its
- * options are still the listbox's options, which is what keeps the keyboard
- * moving through a grouped list exactly as it moves through a flat one.
+ * A heading over a set of options. The group holds no selection and no value,
+ * because the listbox owns those. Its options are still the listbox's options,
+ * so the keyboard moves through a grouped list the same way as a flat one.
  *
- * `role="group"` named by the heading, so a screen reader announces which run
- * an option is in without the heading becoming something to land on.
+ * The group has `role="group"` and takes its name from the heading, so a screen
+ * reader announces which group an option is in, and the heading is not a stop
+ * of its own.
  *
  * @since 0.1.0
  * @status stable
  * @aliases OptGroup, Section
  * @documentation https://fusion.dev/helix/components/option
  *
- * @slot - The options in this run.
- * @slot label - Richer than a string.
+ * @slot - The options in the group.
+ * @slot label - The group's heading, for a heading that needs more than plain text.
  *
- * @csspart items - The run itself.
+ * @csspart items - The element that holds the group's options.
  * @csspart label - The heading.
  */
 export declare class HelixHeadlessOptionGroup extends HelixElement {
     /**
-     * The heading over the run.
+     * The heading above the group's options.
      */
     label: string;
     protected willUpdate(changed: PropertyValues): void;

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

@@ -21,24 +21,18 @@ export declare const optionsAmong: (elements: readonly Element[]) => HelixHeadle
  * @summary One choice in a listbox.
  *
  * @description
- * **Its own family rather than a part of Select, and the reason is what it
- * belongs to.** `role="option"` requires an owning `role="listbox"`, which is
- * the ARIA contract: an option cannot stand alone. But a Select is *a listbox
- * with a trigger*, a Combobox is *a listbox with a text input*, and a command
- * palette is the same listbox again. The thing an option belongs to is the
- * listbox, not any one control that happens to contain one.
+ * Options are their own family, separate from Select, because an option belongs
+ * to a listbox and several controls contain one. `role="option"` requires an
+ * owning `role="listbox"`. A Select is a listbox with a trigger, a Combobox is
+ * a listbox with a text input, and a command palette is a listbox in a dialog.
+ * `Radio` is a part of its group, because a radio has only one kind of owner.
  *
- * That is the difference from `Radio`, which is a part of its group: a radio
- * has exactly one kind of owner, and an option has several.
+ * Selection works the way it does for a radio. Choosing an option dispatches an
+ * event, the listbox decides whether the choice stands, and the listbox sets
+ * `selected`.
  *
- * Selection is announced rather than applied, the way a radio's is. The option
- * says it was chosen, the listbox decides whether that stands, and the listbox
- * writes `selected` back. An option that selected itself would be a second
- * answer to which one is chosen.
- *
- * **Nothing here knows about filtering.** A hidden option is hidden by whatever
- * owns it, through `hidden`, because what counts as a match is the listbox's
- * question and differs between a select and a command palette.
+ * Filtering belongs to the owner, which hides an option with `hidden`. What
+ * counts as a match differs between a select and a command palette.
  *
  * @since 0.1.0
  * @status stable
@@ -46,18 +40,18 @@ export declare const optionsAmong: (elements: readonly Element[]) => HelixHeadle
  * @aliases Item, Choice
  * @documentation https://fusion.dev/helix/components/option
  *
- * @slot - The words naming this choice.
- * @slot end - After them, for a shortcut or a count.
- * @slot start - Before the words, for an icon or an avatar.
+ * @slot - The option's label.
+ * @slot end - Content after the label, such as a shortcut or a count.
+ * @slot start - Content before the label, such as an icon or an avatar.
  *
- * @event {HelixSelectEvent} helix-select - Fired when this choice is made. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixSelectEvent} helix-select - The option was chosen. Cancelable: canceling it leaves the selection as it was.
  *
- * @csspart description - The caption under the words, when there is one.
+ * @csspart description - The description under the label, when there is one.
  * @csspart item - The row.
- * @csspart item-active - The row the keyboard is on, beside `item`.
- * @csspart item-selected - The row of a chosen option, beside `item`.
- * @csspart label - The words.
- * @csspart text - The words and the caption under them, as one column.
+ * @csspart item-active - The row the keyboard is on. Set alongside `item`.
+ * @csspart item-selected - The row of a selected option. Set alongside `item`.
+ * @csspart label - The option's label.
+ * @csspart text - The label and the description under it, as one column.
  *
  * @cssstate selected - While the option is chosen.
  */
@@ -69,7 +63,8 @@ export declare class HelixHeadlessOption extends HelixElement {
      */
     active: boolean;
     /**
-     * A second destination for this row, taken with the modifier held.
+     * A second destination for the row, opened when you choose it with the
+     * modifier key held.
      *
      * **An attribute rather than a second row, which is the whole point.** A
      * palette that offered every component a reference page and a sandbox as
@@ -86,7 +81,7 @@ export declare class HelixHeadlessOption extends HelixElement {
      */
     alternate: string;
     /**
-     * What the second destination is, for a reader who cannot see the footer.
+     * The name of the second destination, announced to screen reader users.
      *
      * A row with two destinations needs both said, or a screen reader is told
      * about one of them and the other is a key nobody mentioned. It goes to
@@ -96,7 +91,7 @@ export declare class HelixHeadlessOption extends HelixElement {
      */
     alternateLabel: string;
     /**
-     * Whether the markup declared this one chosen, which is what a reset returns to.
+     * Whether the markup declares this option selected. A form reset returns to it.
      *
      * `<option selected>` reflects to `defaultSelected` and `option.selected` is
      * live state that does not reflect, and those are two different facts. This
@@ -125,7 +120,7 @@ export declare class HelixHeadlessOption extends HelixElement {
     get defaultSelected(): boolean;
     set defaultSelected(next: boolean);
     /**
-     * A second line under the words, for what the choice actually is.
+     * A second line under the label that describes the choice.
      *
      * A palette row reads better as a name and a caption than as one sentence
      * carrying both: "Helix" and "the design system" are two facts, and a comma
@@ -147,7 +142,7 @@ export declare class HelixHeadlessOption extends HelixElement {
      */
     description?: string;
     /**
-     * Whether this choice can be made.
+     * Prevents the option from being chosen.
      */
     disabled: boolean;
     /**
@@ -166,11 +161,11 @@ export declare class HelixHeadlessOption extends HelixElement {
      */
     selected: boolean;
     /**
-     * Identifies this choice, and is what a form submits.
+     * The value that identifies the option, and that a form submits.
      */
     value: string;
     /**
-     * The words, for a listbox that has to match text against them.
+     * The option's text, which a listbox matches typed text against.
      *
      * Read from the rendered content rather than required as a property, because
      * the content is where a consumer naturally puts it and asking for both is
@@ -208,7 +203,7 @@ export declare class HelixHeadlessOption extends HelixElement {
      * it is in every comparison too.
      */
     get text(): string;
-    /** Makes this choice and announces it. */
+    /** Sends `helix-select` for this option. Does nothing when it is disabled. */
     select(): void;
     /**
      * Mirrors the chosen state where a stylesheet can select on it.

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

@@ -1,20 +1,20 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 /**
- * @summary Links to the headings on this page, marking the one being read.
+ * @summary Links to the headings on the page, with the section in view marked.
  *
  * @description
- * A table of contents, named for the job. It sits beside `Navigation`, which is
- * the same job at the other scale: one navigates a site, the other a document.
+ * Outline is a table of contents for a document. `Navigation` does the same job
+ * for a site.
  *
- * **The links are the consumer's own anchors.** A router renders its own `<a>`
- * and cannot render one inside this shadow root, and the hrefs are fragments
- * the page already knows.
+ * The links are your own anchors. A router renders its own `<a>` and cannot
+ * render one inside the outline's shadow root, and the hrefs are fragments on
+ * the same page.
  *
- * **What is current is decided by position, not by intersection.** An
- * `IntersectionObserver` with a band near the top fails in both directions:
- * with headings far apart nothing is in the band and the marker goes out, and
- * with headings close together several are in it at once.
+ * The current section is decided by the headings' positions. An
+ * `IntersectionObserver` with a band near the top fails both ways: when
+ * headings are far apart, none is in the band and no section is marked, and
+ * when they are close together, several are in the band at once.
  *
  * @since 0.1.0
  * @status stable
@@ -24,15 +24,15 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  *
  * @slot - The links, as anchors with fragment hrefs.
  *
- * @event {HelixActivateEvent} helix-activate - The section being read has changed, carrying its id as the value. An announcement: it is read off where the page is scrolled to, so there is no decision here to take.
+ * @event {HelixActivateEvent} helix-activate - Fired when the section in view changes, with its id as the value. It reports the scroll position and cannot be prevented.
  *
- * @csspart indicator - The mark that travels to the section being read.
+ * @csspart indicator - The mark that moves to the section in view.
  * @csspart nav - The navigation landmark.
  */
 export declare class HelixHeadlessOutline extends HelixElement {
     private readonly indicator;
     /**
-     * How a click on one of these links travels to its section.
+     * How the page scrolls to a section when its link is clicked.
      *
      * The platform's own vocabulary, because this is the platform's own option:
      * `auto` defers to whatever `scroll-behavior` the page has set on its scroll
@@ -54,12 +54,13 @@ export declare class HelixHeadlessOutline extends HelixElement {
      */
     behavior: ScrollBehavior;
     /**
-     * Accessible name for the navigation.
+     * The navigation's name, read by screen readers.
      */
     label: string;
     /**
-     * How far below the top of what scrolls a heading counts as reached, in
-     * pixels: the window, or the panel the sections scroll in.
+     * How far below the top of the scroll container a heading counts as reached,
+     * in pixels. The scroll container is the window or the panel the sections
+     * scroll in.
      *
      * The reading line. A page with a sticky masthead sets this to its height, or
      * a little more: without it the current section changes as a heading slides
@@ -67,7 +68,7 @@ export declare class HelixHeadlessOutline extends HelixElement {
      */
     offset: number;
     /**
-     * The id of the section being read, or empty before anything is measured.
+     * The id of the section in view, or empty before anything is measured.
      *
      * Read-only, and a getter rather than a property for that reason: it is
      * derived from where the page is scrolled to, so a consumer setting it would

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

@@ -1,37 +1,32 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 /**
- * @summary Moves between pages of a longer result.
+ * @summary Controls for moving between the pages of a long set of results.
  *
  * @description
- * **The component is the truncation.** Given a page and a total it works out
- * which numbers to show and where the runs break, so this is data-driven rather
- * than composed: `<helix-headless-pagination page="4" pages="12">` rather than
- * twelve slotted children a consumer keeps in step with their own query.
+ * Set a page and a total, and the component works out which page numbers to
+ * show and where the gaps go:
+ * `<helix-headless-pagination page="4" pages="12">`. You do not slot a child
+ * for each page.
  *
- * **The width does not change as you page.** The run around the current page is
- * `siblings` either side, and grows to absorb a gap slot at a boundary, so the
- * control holds the same number of slots from the first page to the last.
- * Anything that lets the count vary moves the buttons under the pointer between
- * one click and the next.
+ * The width stays the same as you page. The run around the current page is
+ * `siblings` on each side and grows to absorb a gap at either end, so the
+ * control shows the same number of slots from the first page to the last, and
+ * the buttons do not move under the pointer.
  *
- * **A gap is only drawn where it hides more than one page, and a gap is a
- * control.** It goes to the middle of the run it stands over, which is the
- * binary-search step: any page in a set of any size is a handful of presses.
+ * A gap appears only where it hides more than one page. A gap is a control: it
+ * goes to the middle of the pages it hides, so any page is a few presses away.
  *
- * **`href` is what makes these links.** Set it and every page renders an `<a>`
- * with `{page}` filled in, so the output is crawlable, a middle click opens a
- * tab, and the address bar is the state. Left unset they are buttons, which is
- * right for a table paging in place. Either way the click announces
- * `helix-navigate` first, and `preventDefault()` stops the navigation as well
- * as the change, which is how a router takes over.
+ * Set `href` to render every page as an `<a>`, with `{page}` replaced by the
+ * page number. The links can be crawled, a middle click opens a tab, and the
+ * address bar holds the state. Without `href` the pages are buttons, for a
+ * table that pages in place. Either way, a click dispatches `helix-navigate`
+ * first. Call `preventDefault()` to stop both the navigation and the page
+ * change, for example to hand navigation to a router. There is no
+ * `helix-change`, because moving to another page selects nothing.
  *
- * **`helix-navigate` and not `helix-change`.** Moving to page four chooses
- * nothing; it moves the view over a result that has not changed.
- *
- * **The count and the page-size control are their own elements.**
- * `Pagination.Summary` and `Pagination.Size` sit beside this one, because a
- * slot can only offer one place: at one end of one row, in one order.
+ * `Pagination.Summary` and `Pagination.Size` are separate elements that you
+ * place beside this one, so you choose where they go and in what order.
  *
  * @since 0.1.0
  * @status stable
@@ -44,22 +39,22 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @slot next-icon - The glyph on the forward-one-page control, usually a caret.
  * @slot previous-icon - The glyph on the back-one-page control, usually a caret.
  *
- * @event {HelixNavigateEvent} helix-navigate - Fired before the page changes, and cancelable. The only way to refuse one.
+ * @event {HelixNavigateEvent} helix-navigate - Fired before the page changes, and cancelable. Canceling it is the only way to stop a page change.
  *
  * @csspart first - The control that jumps to the first page, under `ends`.
- * @csspart gap - The control standing over pages not shown, which jumps into them.
+ * @csspart gap - The control in place of hidden pages, which jumps into them.
  * @csspart item - One slot in the run, holding a page or a gap.
  * @csspart last - The control that jumps to the last page, under `ends`.
  * @csspart list - The run of pages.
- * @csspart live - The region that says the page changed. Clipped, not hidden.
- * @csspart mark - The glyph on a first, previous, next or last control, where none is slotted.
+ * @csspart live - The live region that announces a page change. It is clipped out of view and still read.
+ * @csspart mark - The glyph on a first, previous, next, or last control, where none is slotted.
  * @csspart next - The control that moves forward one page.
  * @csspart page - The control for one page.
  * @csspart page-current - The page you are on, beside `page`.
  * @csspart previous - The control that moves back one page.
- * @csspart status - The reading of where you are, in `compact`.
+ * @csspart status - The text that says which page you are on, in `compact`.
  *
- * @cssstate empty - While there is one page or none, which is nothing to page through.
+ * @cssstate empty - There is one page or none, so there is nothing to page through.
  */
 export declare class HelixHeadlessPagination extends HelixElement {
     /**
@@ -67,7 +62,8 @@ export declare class HelixHeadlessPagination extends HelixElement {
      */
     boundaries: number;
     /**
-     * Where the numbers are replaced by a reading of the two.
+     * Replaces the page numbers with the current page and the page count, as
+     * written by `status-label`.
      *
      * A different structure rather than a different look, which is why it is
      * here: the run of pages is gone and a single status line stands in its
@@ -79,11 +75,11 @@ export declare class HelixHeadlessPagination extends HelixElement {
      */
     compact: boolean;
     /**
-     * Page to open on, where nothing declared one.
+     * The page to open on when `page` is not set.
      */
     defaultPage: number;
     /**
-     * Whether to offer a jump to the first and last pages.
+     * Shows controls that jump to the first and last pages.
      *
      * Off by default. The gaps already reach any page in a few presses and the
      * last page is one of the two the run always shows, so on a short set these
@@ -102,11 +98,11 @@ export declare class HelixHeadlessPagination extends HelixElement {
      */
     firstLabel: string;
     /**
-     * Accessible name for a gap, with `{page}` filled in as where it goes.
+     * Accessible name for a gap. `{page}` is replaced with the page it jumps to.
      */
     gapLabel: string;
     /**
-     * Address for a page, with `{page}` standing in for its number.
+     * The URL for each page. `{page}` is replaced with the page number.
      *
      * Absent renders buttons. Present renders links, which is what a paged result
      * with its own URL should be: a crawler follows them, a middle click opens
@@ -140,7 +136,7 @@ export declare class HelixHeadlessPagination extends HelixElement {
      */
     nextLabel: string;
     /**
-     * The page on show, one-based.
+     * The current page, counting from one.
      *
      * An accessor pair, the same shape as the calendar's `month`. Reading gives
      * the page on show; writing sets it, and `default-page` seeds one the element
@@ -158,7 +154,8 @@ export declare class HelixHeadlessPagination extends HelixElement {
     get page(): number;
     set page(next: number);
     /**
-     * Accessible name for one page, with `{page}` and `{pages}` filled in.
+     * Accessible name for one page. `{page}` and `{pages}` are replaced with the
+     * page number and the page count.
      */
     pageLabel: string;
     /**
@@ -190,7 +187,8 @@ export declare class HelixHeadlessPagination extends HelixElement {
      */
     siblings: number;
     /**
-     * The reading shown in `compact`, with `{page}` and `{pages}` filled in.
+     * The text shown in `compact`. `{page}` and `{pages}` are replaced with the
+     * current page and the page count.
      *
      * No noun: the landmark this sits in is already named "Pagination", so
      * "Page 7 of 24" says it twice to a screen reader and takes a third of the