@fusion.dev/helix-headless 0.104.1 → 0.106.0

package/dist/copy-button/root/copy-button-root.d.ts

@@ -2,19 +2,17 @@ import { type TemplateResult } from 'lit';
 import { HelixHeadlessIconButton } from '../../icon-button/root/icon-button-root.js';
 import '../../tooltip/index.js';
 /**
- * @summary A button that puts a string on the clipboard and says it did.
+ * @summary A button that copies a string to the clipboard and confirms the copy.
  *
  * @description
- * **The confirmation is the component.** Writing to the clipboard is three
- * lines; what makes this worth an element is that the platform gives a reader
- * no feedback at all, so a press that copies looks identical to one that
- * failed.
+ * Copies text to the clipboard and confirms the copy. The platform gives no
+ * feedback for a clipboard write, so without a confirmation a press that copies
+ * looks the same as one that fails.
  *
- * **Announced after the write, never before.** A clipboard write is a
- * permission the browser may refuse, for real reasons: an insecure origin, a
- * document that is not focused, a gesture that did not qualify. The
- * confirmation and the event both wait for the promise, and a refusal leaves
- * the button exactly as it was.
+ * The confirmation and the event wait for the write to finish. The browser can
+ * refuse a clipboard write, for example on an insecure origin, in a document
+ * that is not focused, or after a gesture that does not qualify. A refused
+ * write leaves the button unchanged.
  *
  * @since 0.1.0
  * @status stable
@@ -22,34 +20,34 @@ import '../../tooltip/index.js';
  * @aliases Copy, Copy to clipboard
  * @documentation https://fusion.dev/helix/components/copy-button
  *
- * @slot - The resting icon. Falls back to a clipboard.
- * @slot copied - What replaces it once the write succeeds. Falls back to a check.
+ * @slot - The icon shown before a copy. Defaults to a clipboard.
+ * @slot copied - The icon shown after a successful copy. Defaults to a check mark.
  *
  * @event {HelixCopyEvent} helix-copy - Fired after the clipboard write succeeds.
  *
  * @csspart button - The inner button.
- * @csspart mark - The clipboard glyph, and the confirmation that replaces it.
- * @csspart tooltip - The bubble, forwarded from the tooltip inside.
- * @csspart tooltip-arrow - The point, resting against the trigger.
- * @csspart tooltip-arrow-bottom - The point while the bubble is below the button, so on its top edge, beside `tooltip-arrow`.
- * @csspart tooltip-arrow-left - The point while the bubble is left of the button, so on its right edge, beside `tooltip-arrow`.
- * @csspart tooltip-arrow-right - The point while the bubble is right of the button, so on its left edge, beside `tooltip-arrow`.
- * @csspart tooltip-arrow-top - The point while the bubble is above the button, so on its bottom edge, beside `tooltip-arrow`.
- * @csspart tooltip-bottom - The bubble while it is below the button, beside `tooltip`.
- * @csspart tooltip-left - The bubble while it is left of the button, beside `tooltip`.
- * @csspart tooltip-right - The bubble while it is right of the button, beside `tooltip`.
- * @csspart tooltip-top - The bubble while it is above the button, beside `tooltip`.
+ * @csspart mark - The clipboard icon, and the confirmation icon that replaces it.
+ * @csspart tooltip - The tooltip bubble, forwarded from the tooltip inside the button.
+ * @csspart tooltip-arrow - The tooltip's arrow, which points at the button.
+ * @csspart tooltip-arrow-bottom - The arrow while the bubble is below the button, on the bubble's top edge. Set together with `tooltip-arrow`.
+ * @csspart tooltip-arrow-left - The arrow while the bubble is left of the button, on the bubble's right edge. Set together with `tooltip-arrow`.
+ * @csspart tooltip-arrow-right - The arrow while the bubble is right of the button, on the bubble's left edge. Set together with `tooltip-arrow`.
+ * @csspart tooltip-arrow-top - The arrow while the bubble is above the button, on the bubble's bottom edge. Set together with `tooltip-arrow`.
+ * @csspart tooltip-bottom - The bubble while it is below the button. Set together with `tooltip`.
+ * @csspart tooltip-left - The bubble while it is left of the button. Set together with `tooltip`.
+ * @csspart tooltip-right - The bubble while it is right of the button. Set together with `tooltip`.
+ * @csspart tooltip-top - The bubble while it is above the button. Set together with `tooltip`.
  */
 export declare class HelixHeadlessCopyButton extends HelixHeadlessIconButton {
     /**
-     * What it is called, and says, after one.
+     * The button's name and tooltip text after a copy.
      *
      * `attribute` written out, because Lit lowercases a property name rather than
      * dash-casing it, and `copiedlabel` is not what anyone would type.
      */
     copiedLabel: string;
     /**
-     * What it is called, and says, before a press.
+     * The button's name and tooltip text before a copy.
      *
      * Defaulted rather than left empty. An icon-only control must be named, and
      * the name of this one is not a judgment call: every copy button in the
@@ -57,7 +55,7 @@ export declare class HelixHeadlessCopyButton extends HelixHeadlessIconButton {
      */
     label: string;
     /**
-     * What goes on the clipboard.
+     * The text copied to the clipboard.
      *
      * **Narrows `Button.value`, which is the submit value, and the two agree.**
      * A copy button is `type="button"` and never submits, so the inherited

package/dist/data-table/root/data-table-root.d.ts

@@ -6,13 +6,12 @@ import '../../pagination/index.js';
 import { type DataRow } from './order.js';
 declare const HelixHeadlessDataTable_base: (new (...args: any[]) => import("@fusion.dev/helix-core").CollectionElement) & typeof HelixElement;
 /**
- * @summary A table that owns a result: rows as data, with sort, filter and paging.
+ * @summary A table drawn from an array of rows, with sorting, filtering, and paging.
  *
  * @description
- * **The schema is markup and the data is a property.** Columns are declared as
- * `TableColumn` children, because a schema is small and something a reader
- * should see in the HTML; rows are handed over as an array, because a table
- * that draws ten thousand elements cannot window them.
+ * Declare the columns as `TableColumn` children and pass the rows as an array.
+ * The schema stays readable in the HTML, and the rows can be windowed, which
+ * ten thousand row elements cannot be.
  *
  * ```html
  * <helix-headless-data-table .rows=${rows} sort="name:asc" page-size="20">
@@ -21,45 +20,42 @@ declare const HelixHeadlessDataTable_base: (new (...args: any[]) => import("@fus
  * </helix-headless-data-table>
  * ```
  *
- * `Table` takes rows as markup and is the right component for a table of twelve
- * things a person wrote out.
+ * For a short table written out by hand, use `Table`, which takes rows as
+ * markup.
  *
- * **Sort and filter apply to the whole set, never the page.** Sorting the drawn
- * window is correct on the first screen and wrong on every other one.
+ * Sort and filter apply to the whole set, including the rows on other pages.
  *
- * **The cell values do not server-render.** The headings do, and the row
- * elements do, but reading a cell needs the columns, and the columns are markup
- * children Lit SSR does not hand this element. So a crawler sees a table of the
- * right shape with nothing in it. That is the cost of the first paragraph: use
- * `Table` where the served HTML has to carry the values.
+ * **The cell values do not server-render.** The headings and the row elements
+ * do. Reading a cell needs the columns, and Lit SSR does not pass the column
+ * children to this element, so a crawler sees an empty table of the right
+ * shape. Use `Table` when the served HTML has to carry the values.
  *
- * **`selectable` adds a column of checkboxes, keyed on `row-key`.** A row is
- * selected by its identity rather than its position, so a selection survives a
- * sort, a filter and a page. `selected` is the chosen keys, comma separated, the
- * shape Listbox uses for a multiple choice, and like `sort` writing it applies
- * while `default-selected` is what the markup declared. The box in the heading
- * selects every row in the result, across pages, and shows a dash while only
- * some are chosen.
- * Choosing one of many, rather than several, is opening a row, and that is a
- * link or a button in a cell rather than a selection.
+ * `selectable` adds a column of checkboxes, keyed on `row-key`:
  *
- * **A reader can size and order the columns.** `resizable` on a column puts a
- * separator on its edge; `reorderable` on the table puts a grip on each heading
- * that has a `field`, moved by dragging or with the arrow keys. The order lands
- * in `order` as fields, and the consumer's own markup is never rewritten: the
- * table assigns the headings to its header in that order instead.
+ * - A row is selected by its key, so the selection survives a sort, a filter,
+ *   and a page change.
+ * - `selected` holds the chosen keys, comma separated, the same shape `Listbox`
+ *   uses for a multiple choice. As with `sort`, writing it applies the
+ *   selection, and `default-selected` holds what the markup declared.
+ * - The checkbox in the heading selects every row in the result, across pages,
+ *   and shows a dash while only some are chosen.
  *
- * **`csv()` hands back the result as text**: every row the filter lets through,
- * in the order on screen, in the columns on screen. Saving it is the page's
- * business, the same as any other file.
+ * To act on a single row, such as opening it, put a link or a button in a cell.
  *
- * **There is no `columns` attribute here, and Table has one.** The difference
- * is what a column is in each: here it is the schema, so a table without one
- * has nothing to read a row with, and every column is a place to write a
- * `width`. A Table holds cells a consumer wrote and can be written with no
- * column at all, so its `columns` is where such a table is sized from. Written
- * on this element the attribute is inert, which is the trap worth knowing when
- * moving between the two.
+ * People can resize and reorder the columns. `resizable` on a column puts a
+ * separator on its edge. `reorderable` on the table puts a grip on each heading
+ * that has a `field`, moved by dragging or with the arrow keys. The new order
+ * is written to `order` as a list of fields. Your markup is not rewritten: the
+ * table assigns the headings to its header in that order.
+ *
+ * `csv()` returns the result as text: every row that passes the filter, in the
+ * order and the columns on screen. Saving the file is up to you.
+ *
+ * `DataTable` has no `columns` attribute. Each `TableColumn` is part of the
+ * schema, so you size a column with its own `width`. `Table` has `columns`
+ * because its cells are markup you write and it can have no columns at all.
+ * Written on `DataTable`, `columns` has no effect, so watch for it when you
+ * move a table from `Table` to `DataTable`.
  *
  * @since 0.1.0
  * @status stable
@@ -67,57 +63,57 @@ declare const HelixHeadlessDataTable_base: (new (...args: any[]) => import("@fus
  * @aliases Grid, Result table, Data grid
  * @documentation https://fusion.dev/helix/components/data-table
  *
- * @slot - The columns, declared rather than drawn.
- * @slot footer - Below the grid, replacing the pagination this would otherwise draw.
- * @slot toolbar - Above the grid, for a search field or actions.
+ * @slot - The columns, as `TableColumn` elements.
+ * @slot footer - Content below the grid. It replaces the built-in pagination.
+ * @slot toolbar - Content above the grid, such as a search field or actions.
  *
- * @event {HelixFilterEvent} helix-filter - Fired when the query changes, and cancelable.
- * @event {HelixNavigateEvent} helix-navigate - Fired when a reader asks for another page, and cancelable.
- * @event {HelixReorderEvent} helix-reorder - Fired when a reader asks for the columns in another order, with every field in the new one, and cancelable.
- * @event {HelixSelectEvent} helix-select - Fired when a reader changes which rows are selected, with every selected key comma separated, and cancelable.
- * @event {HelixSortEvent} helix-sort - Fired when a reader asks for a different order, and cancelable.
+ * @event {HelixFilterEvent} helix-filter - The search query is about to change. Cancelable: cancel it to keep the current query.
+ * @event {HelixNavigateEvent} helix-navigate - Another page was requested. Cancelable: cancel it to stay on the current page.
+ * @event {HelixReorderEvent} helix-reorder - The columns were moved. The event carries every field in the new order. Cancelable: cancel it to keep the current order.
+ * @event {HelixSelectEvent} helix-select - The selection changed. The event carries every selected key, separated by commas. Cancelable: cancel it to keep the current selection.
+ * @event {HelixSortEvent} helix-sort - A different sort order was requested. Cancelable: cancel it to keep the current order.
  *
- * @csspart after - The room the rows below the window would have taken. Windowed only.
- * @csspart before - The room the rows above the window would have taken. Windowed only.
+ * @csspart after - The space that stands in for the rows below the window. Only while `windowed`.
+ * @csspart before - The space that stands in for the rows above the window. Only while `windowed`.
  * @csspart cell - One cell.
- * @csspart cell-selected - A cell of a selected row, beside `cell`.
- * @csspart checkbox - A row's checkbox, or the one in the heading that selects them all.
- * @csspart checkbox-box - The frame the checkbox's input is painted as.
+ * @csspart cell-selected - Added to `cell` in a selected row.
+ * @csspart checkbox - A row's checkbox, or the checkbox in the heading that selects every row.
+ * @csspart checkbox-box - The box drawn for the checkbox's input.
  * @csspart checkbox-control - The checkbox's input.
- * @csspart checkbox-feedback - Forwarded from the checkbox, and never drawn here.
- * @csspart checkbox-field - The row the checkbox's box sits in.
- * @csspart checkbox-hint - Forwarded from the checkbox, and never drawn here.
- * @csspart checkbox-label - Forwarded from the checkbox; the label is spoken, not shown.
- * @csspart checkbox-mark - The tick, or the dash while some rows are selected.
- * @csspart checkbox-mark-checked - The mark while its box is checked, beside `checkbox-mark`.
- * @csspart checkbox-mark-indeterminate - The dash while only some rows are selected, beside `checkbox-mark`.
- * @csspart empty - Shown when the result has nothing in it, whether it arrived empty or a filter emptied it. A result still on its way is `loading` instead, which wins over this.
+ * @csspart checkbox-feedback - Forwarded from the checkbox. Not shown in the table.
+ * @csspart checkbox-field - The row that holds the checkbox's box.
+ * @csspart checkbox-hint - Forwarded from the checkbox. Not shown in the table.
+ * @csspart checkbox-label - Forwarded from the checkbox. The label is read by screen readers only.
+ * @csspart checkbox-mark - The check mark, or the dash while some rows are selected.
+ * @csspart checkbox-mark-checked - Added to `checkbox-mark` while its box is checked.
+ * @csspart checkbox-mark-indeterminate - Added to `checkbox-mark` while only some rows are selected.
+ * @csspart empty - Shown when there are no rows, because none arrived or the filter matches none. While rows are loading, the `loading` part is shown in its place.
  * @csspart footer - The region below the grid.
- * @csspart head - The row the column headings sit in. `display: contents`, so it takes no space.
- * @csspart live - The empty and loading lines again, in a region a screen reader hears when they change. Visually hidden in the styled tier.
- * @csspart loading - Shown while the rows are still on their way.
- * @csspart pagination - The pagination, where this draws one.
- * @csspart pagination-first - The pagination's control that jumps to the first page, under `ends`.
- * @csspart pagination-gap - The pagination's control standing over pages not shown.
- * @csspart pagination-item - One slot in the pagination's run, holding a page or a gap.
- * @csspart pagination-last - The pagination's control that jumps to the last page, under `ends`.
- * @csspart pagination-list - The pagination's run of pages.
- * @csspart pagination-live - The region that says the page changed. Clipped, not hidden.
- * @csspart pagination-mark - The glyph on a first, previous, next or last control.
- * @csspart pagination-next - The pagination's control that moves forward one page.
- * @csspart pagination-page - The pagination's control for one page.
- * @csspart pagination-page-current - The page you are on, beside `pagination-page`.
- * @csspart pagination-previous - The pagination's control that moves back one page.
- * @csspart pagination-status - The pagination's reading of where you are, in `compact`.
+ * @csspart head - The row that holds the column headings. It is `display: contents`, so it takes no space.
+ * @csspart live - A copy of the empty and loading messages, which screen readers announce when they change. Visually hidden in the styled tier.
+ * @csspart loading - Shown while the rows are loading.
+ * @csspart pagination - The built-in pagination, when it is shown.
+ * @csspart pagination-first - The pagination's button that goes to the first page, shown with `ends`.
+ * @csspart pagination-gap - The pagination's marker for pages that are not shown.
+ * @csspart pagination-item - One item in the pagination's list, holding a page or a gap.
+ * @csspart pagination-last - The pagination's button that goes to the last page, shown with `ends`.
+ * @csspart pagination-list - The pagination's list of pages.
+ * @csspart pagination-live - The region that announces a page change. It is clipped out of sight and still read by screen readers.
+ * @csspart pagination-mark - The icon on the first, previous, next, and last buttons.
+ * @csspart pagination-next - The pagination's button that goes forward one page.
+ * @csspart pagination-page - The pagination's button for one page.
+ * @csspart pagination-page-current - Added to `pagination-page` for the current page.
+ * @csspart pagination-previous - The pagination's button that goes back one page.
+ * @csspart pagination-status - The pagination's text that says which page is shown, in `compact`.
  * @csspart row - One row of data.
- * @csspart select - The cell holding a row's checkbox.
- * @csspart select-all - The heading holding the checkbox that selects every row.
- * @csspart select-selected - The checkbox cell of a selected row, beside `select`.
+ * @csspart select - The cell that holds a row's checkbox.
+ * @csspart select-all - The heading that holds the checkbox that selects every row.
+ * @csspart select-selected - Added to `select` in a selected row.
  * @csspart table - The grid.
  * @csspart toolbar - The region above the grid.
  *
- * @cssproperty --data-table-cell-align - The edge the column a cell sits under is set to, `start`, `center` or `end`, and unset under a column that sets none. Written by the component onto each cell it draws, read by the sheet that paints one; Table publishes `--table-cell-align` for the same attribute on the cells a consumer wrote, under its own family's name.
- * @cssproperty --data-table-template - The column track list this element worked out from the columns declared in it. Written by the component, read by the sheet that paints: a stylesheet takes it to lay the grid out, and setting it does nothing, because the component writes it inline on the very element that reads it and an inline declaration beats any sheet. A column's `width` is the one to set.
+ * @cssproperty --data-table-cell-align - The alignment of the cell's column: `start`, `center`, or `end`. Unset when the column sets none. The component writes it on each cell it draws, and the stylesheet reads it. `Table` sets `--table-cell-align` for the same purpose.
+ * @cssproperty --data-table-template - The column track list, worked out from the columns. The component writes it inline on the element that reads it, so setting it has no effect. Set a column's `width` to change it.
  */
 export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base {
     /**
@@ -132,31 +128,32 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      */
     static shadowRootOptions: ShadowRootInit;
     /**
-     * Query to open with, where nothing declared one.
+     * The starting search query, used until `filter` is set.
      */
     defaultFilter: string;
     /**
-     * Column order to open with, where nothing declared one.
+     * The starting column order, used until `order` is set.
      */
     defaultOrder: string;
     /**
-     * Page to open on, where nothing declared one.
+     * The starting page, used until `page` is set.
      */
     defaultPage: number;
     /**
-     * Page size to open with, where nothing declared one.
+     * The starting page size, used until `pageSize` is set.
      */
     defaultPageSize: number;
     /**
-     * Keys to open with selected, comma separated, where nothing declared any.
+     * The keys selected at the start, separated by commas. Used until `selected`
+     * is set.
      */
     defaultSelected: string;
     /**
-     * Order to open on, where nothing declared one.
+     * The starting sort order, used until `sort` is set.
      */
     defaultSort: string;
     /**
-     * How tall a row is taken to be before it has been drawn, in pixels.
+     * The estimated height of a row before it is drawn, in pixels.
      *
      * Only read while `windowed`, and a starting guess rather than a claim: a
      * cell that wraps makes its row taller than its neighbors, and the window
@@ -166,7 +163,7 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      */
     estimate: number;
     /**
-     * What the rows are narrowed to, as one query across every column.
+     * The search query. A row is shown when the query matches any of its columns.
      *
      * One query rather than a predicate per column, which is what a reader means
      * by a search box above a table. It matches on each column's ordering value,
@@ -175,11 +172,12 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     get filter(): string;
     set filter(next: string);
     /**
-     * Accessible name for the grid.
+     * The grid's name, read by screen readers.
      */
     label: string;
     /**
-     * Whether this element does the work or asks the consumer to.
+     * Where filtering, sorting, and paging happen. `client` does them in the
+     * table, and `server` leaves them to your code.
      *
      * `client` filters, sorts and pages `rows` itself. `server` applies none of
      * them: `rows` is the page, `total` is the size of the whole result, and the
@@ -190,7 +188,7 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      */
     mode: 'client' | 'server';
     /**
-     * The columns' order, as their fields separated by spaces.
+     * The column order, as field names separated by spaces.
      *
      * A reader's move fires `helix-reorder` first, and refusing it leaves the
      * columns where they were, which is how a consumer who stores the order takes
@@ -201,7 +199,7 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     get order(): string;
     set order(next: string);
     /**
-     * The page on show, from 1.
+     * The page shown, counting from 1.
      *
      * Clamped on the way out, so what this reports is the page it drew: a
      * bookmarked link to page 99 of a result that has since shrunk reads back as
@@ -210,7 +208,7 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     get page(): number;
     set page(next: number);
     /**
-     * How many rows a page holds. Zero is every row, which is what "no paging" means.
+     * The number of rows on a page. `0` shows every row, with no paging.
      *
      * **It announces nothing, and that is not an omission.** Nothing in this
      * element ever asks for a different page size: a size selector is
@@ -221,7 +219,7 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     get pageSize(): number;
     set pageSize(next: number);
     /**
-     * Whether to draw a pagination under the grid.
+     * Shows a pagination under the grid.
      *
      * On by default once a page size is set, because a paged table with no way to
      * change pages shows a reader the first twenty rows and no way to know there
@@ -231,14 +229,14 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     get paginated(): boolean;
     set paginated(next: boolean);
     /**
-     * Whether a reader may move the columns.
+     * Lets users reorder the columns.
      *
      * Each heading with a `field` gets a grip, dragged along the header or moved a
      * place at a time with the arrow keys once it has focus.
      */
     reorderable: boolean;
     /**
-     * The field naming a row's stable identity.
+     * The field that identifies each row.
      *
      * **Needed before selection exists, not after.** Lit keys the rendered rows by
      * it, so a sort moves a row's element rather than rewriting every cell in
@@ -253,7 +251,7 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      */
     rowKey: string;
     /**
-     * The whole result, in the order it arrived.
+     * Every row of the result, in the order it arrived.
      *
      * A property and not an attribute: it is an array. Left alone this element
      * filters, sorts and pages it; in `server` mode it is the page the consumer
@@ -265,14 +263,14 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      */
     rows: readonly DataRow[];
     /**
-     * Whether a reader may select rows, with a column of checkboxes.
+     * Adds a column of checkboxes for selecting rows.
      *
      * Wants `row-key`: a selection is a set of identities, and without one the rows
      * are known by their place in the result, which a sort changes.
      */
     selectable: boolean;
     /**
-     * The keys of the selected rows, comma separated.
+     * The keys of the selected rows, separated by commas.
      *
      * A string rather than an array, so it is an attribute a server writes and a
      * framework's hydration keeps, and the shape a multiple Listbox already uses.
@@ -283,7 +281,7 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     get selected(): string;
     set selected(next: string);
     /**
-     * The order, as `field:direction`.
+     * The sort order, as `field:direction`.
      *
      * Set it and this element defers: a reader's click fires `helix-sort` and
      * changes nothing until a new value arrives. `default-sort` seeds an order this
@@ -292,7 +290,8 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     get sort(): string;
     set sort(next: string);
     /**
-     * How many rows the whole result has, where this element cannot count them.
+     * The number of rows in the whole result, for when the table cannot count
+     * them.
      *
      * Only read in `server` mode, where `rows` is one page and its length says
      * nothing about the result. Ignored in `client` mode rather than trusted,
@@ -301,7 +300,7 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      */
     total: number;
     /**
-     * Draws the rows in view and stands empty space in for the rest.
+     * Draws only the rows in view, with empty space in place of the rest.
      *
      * **Not a `mode`.** `mode` says where the rows come from and who filtered
      * them; this says how many of the ones we hold get drawn. They are
@@ -376,7 +375,7 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     /** The columns declared as children, in the order they are written. */
     get tableColumns(): HelixHeadlessTableColumn[];
     /**
-     * The columns in the order a reader arranged them.
+     * The columns in their current order.
      *
      * The ones with a field are put in `order`'s order, those it does not name
      * after them in the order they were written, and a column with no field stays
@@ -542,8 +541,8 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     /** Every field in order, with one taken out and put back beside another. */
     private placed;
     /**
-     * The result as CSV: every row the filter lets through, in the order on
-     * screen, in the columns on screen, headed by their headings.
+     * Returns the result as CSV: every row that matches the filter, in the order
+     * and columns shown, under a line of the column headings.
      *
      * **Values, not cells.** A cell may be a template, a badge or a link, so each
      * column gives its field's value, which is what a spreadsheet wants anyway.
@@ -563,7 +562,7 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
     /** Asks for a different page. */
     private requestPage;
     /**
-     * Narrows the rows, from a consumer's own search field.
+     * Filters the rows by a query from your own search field.
      *
      * Public because the query lives above the table in every design that has one,
      * and a consumer wiring their own input needs somewhere to send it. Returns
@@ -571,7 +570,7 @@ export declare class HelixHeadlessDataTable extends HelixHeadlessDataTable_base
      */
     search(query: string): boolean;
     /**
-     * Cycles the order by one column, which is what a click on its heading means.
+     * Cycles the sort order of one column, as a click on its heading does.
      *
      * Ascending, descending, then the order the rows arrived in. Public for the
      * same reason `search` is: a consumer's own heading UI needs a way to ask.