@fusion.dev/helix-headless 0.105.0 → 0.107.0

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

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

@@ -3,68 +3,62 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 import '../../option/index.js';
 import '../../select/index.js';
 /**
- * @summary Chooses how many items a page holds.
+ * @summary A control for choosing how many items each page shows.
  *
  * @description
- * Its own element beside `Pagination` rather than a slot inside it, for the
- * reason `Pagination.Summary` is: a footer's direction and order are the
- * consumer's, and a control that can only sit at one end of one row has taken
- * that decision for them.
+ * A separate element that you place beside `Pagination`, like
+ * `Pagination.Summary`, so you choose the direction and order of your footer.
  *
- * **`Select`, not a native `<select>`.** Two dropdowns identical closed and
- * different open meet each other in the same footer as a table's filters. The
- * caret is `Select`'s rather than a color literal baked into a data URI,
- * because a background image cannot read `currentColor`, and the label is a
- * real `<label for>` against the trigger's own id.
+ * It uses `Select`, so it matches a table's filter dropdowns in the same
+ * footer, both open and closed. The caret is `Select`'s, so it follows
+ * `currentColor`, and the label is a real `<label for>` pointing at the
+ * trigger's id.
  *
- * **The label sits on the row, not above it.** `Select`'s host is a column, and
- * an outer-tree rule beats a `:host` rule, so turning it into a row needs no
- * property on `Select` and nothing written into the consumer's markup.
+ * The label sits on the same row as the select. `Select`'s host is a column,
+ * and an outer-tree rule overrides a `:host` rule, so the row layout needs no
+ * property on `Select` and nothing added to your markup.
  *
- * **An empty `sizes` renders nothing**, rather than falling back to the
- * built-in list, which would be a component overruling a consumer who said
- * "none". Same rule as `Pagination` over a single page, and reported the same
- * way, through `ElementInternals.states` rather than an attribute the server
- * never wrote.
+ * An empty `sizes` renders nothing and does not fall back to the built-in list.
+ * `Pagination` does the same with a single page, and both report it through
+ * `ElementInternals.states`.
  *
- * `value` is the size the control holds and `default-value` is what the markup
- * declared.
- * Changing it announces `helix-before-change`; re-querying and moving back to
- * page one is the consumer's, because only they know whether the reader's
- * position should survive it.
+ * `value` is the current size, and `default-value` is the size from the markup.
+ * Changing it dispatches `helix-before-change`. Re-querying and returning to
+ * page one is up to you, because only you know whether the current position
+ * should be kept.
  *
  * @since 0.1.0
  * @status stable
  * @aliases Page size, Rows per page
  * @documentation https://fusion.dev/helix/components/pagination
  *
- * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the size changes, and cancelable. The only way to refuse one.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the size changes, and cancelable. Canceling it is the only way to stop a size change.
  *
  * @csspart control - The select.
- * @csspart control-feedback - What is wrong with it.
+ * @csspart control-feedback - The message that says what is wrong with the value.
  * @csspart control-hint - Help under the trigger.
- * @csspart control-indicator - The caret saying the control opens.
- * @csspart control-label - The words beside the number.
- * @csspart control-listbox - The list inside it.
- * @csspart control-listbox-empty - Shown when a filter has hidden everything.
- * @csspart control-listbox-feedback - What is wrong with the list.
- * @csspart control-listbox-filter-icon - The mark beside the filter field.
- * @csspart control-listbox-filter-mark - The glyph beside the filter field, where none is slotted.
+ * @csspart control-indicator - The caret that shows the control opens.
+ * @csspart control-label - The label beside the number.
+ * @csspart control-listbox - The list inside the panel.
+ * @csspart control-listbox-empty - The text shown when the filter hides every option.
+ * @csspart control-listbox-feedback - The inner list's message that says what is wrong with the value.
+ * @csspart control-listbox-filter-icon - The icon beside the filter field.
+ * @csspart control-listbox-filter-mark - The default icon beside the filter field, shown when none is slotted.
  * @csspart control-listbox-hint - Help under the list.
- * @csspart control-listbox-items - The list itself.
- * @csspart control-listbox-label - The question, over the list.
- * @csspart control-listbox-live - The inner listbox's `live`, the region a screen reader hears its empty and loading lines from.
- * @csspart control-listbox-loading - Shown while the options are still on their way.
- * @csspart control-listbox-search - The region holding the field that narrows the list.
- * @csspart control-listbox-search-field - The field itself.
+ * @csspart control-listbox-items - The list of options.
+ * @csspart control-listbox-label - The label above the list.
+ * @csspart control-listbox-live - The inner list's `live` part, the region screen readers announce its empty and loading text from.
+ * @csspart control-listbox-loading - The text shown while the options load.
+ * @csspart control-listbox-search - The region that holds the filter field.
+ * @csspart control-listbox-search-field - The filter field.
  * @csspart control-surface - The floating panel.
- * @csspart control-trigger - The closed control, which says what size is chosen.
+ * @csspart control-trigger - The closed control, which shows the chosen size.
  * @csspart control-value - The chosen size inside the trigger.
  * @csspart option - One size on offer.
  * @csspart option-description - The caption under the number, when there is one.
  * @csspart option-item - The row.
  * @csspart option-item-active - The row the keyboard is on.
- * @csspart option-item-selected - The row of the size chosen.
+ * @csspart option-item-selected - The row of the chosen size.
  * @csspart option-label - The number.
  * @csspart option-text - The number and the caption, as one column.
  *
@@ -72,11 +66,11 @@ import '../../select/index.js';
  */
 export declare class HelixHeadlessPaginationSize extends HelixElement {
     /**
-     * Size to start on, where nothing declared one.
+     * The size to start on when `value` is not set.
      */
     defaultValue: number;
     /**
-     * The words beside the control.
+     * The label beside the control.
      */
     label: string;
     /**
@@ -94,7 +88,7 @@ export declare class HelixHeadlessPaginationSize extends HelixElement {
      */
     sizes: string;
     /**
-     * The size in force.
+     * The current page size.
      *
      * Reading gives the real one; writing declares it the consumer's, and
      * `default-value` seeds one this element owns. Same accessor pair as

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

@@ -1,22 +1,19 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type TemplateResult } from 'lit';
 /**
- * @summary Reads out which items of how many are on show.
+ * @summary Text that shows which items are on the current page, out of the total.
  *
  * @description
- * Its own element rather than a part of `Pagination`, so a consumer decides
- * where it goes: above, below, in a table's caption, or on the other side of
- * the page. Inside the run it could only ever be at one end of one row.
+ * A separate element from `Pagination`, so you decide where the count goes:
+ * above, below, in a table caption, or elsewhere on the page.
  *
- * **It repeats `page`, `page-size` and `total`, and the cost of that is skew.**
- * Those three come from the consumer's own query, so writing them on two
- * elements is one variable used twice; what it risks is the two disagreeing.
+ * You set `page`, `page-size`, and `total` on both this element and
+ * `Pagination`. They come from your own query, so use the same values for both
+ * and the two elements agree.
  *
- * **Nothing removes that at this level, and it was measured.** A coordinating
- * root can only reach light-DOM children by writing attributes onto them, which
- * a framework reports as a hydration error, or through context, which is dead
- * on a server: `@lit/context` subscribes from `connectedCallback`, and Lit SSR
- * does not call it.
+ * A shared parent cannot pass the values down. Writing attributes onto light
+ * DOM children causes hydration errors in frameworks, and `@lit/context`
+ * subscribes in `connectedCallback`, which Lit SSR does not call.
  *
  * @since 0.1.0
  * @status stable
@@ -25,7 +22,8 @@ import { type TemplateResult } from 'lit';
  */
 export declare class HelixHeadlessPaginationSummary extends HelixElement {
     /**
-     * The reading, with `{from}`, `{to}` and `{total}` filled in.
+     * The text shown. `{from}`, `{to}`, and `{total}` are replaced with the first
+     * item, the last item, and the item count.
      *
      * A template rather than a prefix and a suffix, because word order is not
      * universal: `format="{total} 件中 {from}-{to} 件"` is one attribute here and
@@ -47,7 +45,7 @@ export declare class HelixHeadlessPaginationSummary extends HelixElement {
      */
     locale: string;
     /**
-     * The page on show, one-based.
+     * The current page, counting from one.
      */
     page: number;
     /**