@fusion.dev/helix-headless 0.105.0 → 0.107.0

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.

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

@@ -7,15 +7,13 @@ declare const HelixHeadlessDateInput_base: (new (...args: any[]) => import("@fus
  * @summary A date, typed or picked from a calendar.
  *
  * @description
- * **The calendar is `DatePicker`, not a second one written here.** It already
- * knows about months, ranges, disabled days, the first day of the week and
- * every keyboard rule a grid owes a reader. This element is the field, the
- * overlay, and the translation between them.
+ * The calendar is `DatePicker`, which handles months, ranges, disabled days,
+ * the first day of the week, and the grid's keyboard behavior. The date input
+ * adds the field, the overlay, and the connection between them.
  *
- * **Typed as well as picked, and the typing is why it is not
- * `<input type="date">`.** The native control gives a free picker and a free
- * locale and takes almost all styling with it. What is kept from it is the part
- * worth keeping: a real text field.
+ * You can type a date as well as pick one. The native `<input type="date">`
+ * gives a picker and locale formatting but allows almost no styling, so the
+ * field is a text field.
  *
  * @since 0.1.0
  * @status stable
@@ -23,55 +21,55 @@ declare const HelixHeadlessDateInput_base: (new (...args: any[]) => import("@fus
  * @aliases DatePicker, DateField, InputDate
  * @documentation https://fusion.dev/helix/components/date-input
  *
- * @slot feedback - What is wrong with it.
- * @slot hint - Help under the field.
- * @slot trigger - The mark on the field saying a calendar opens.
+ * @slot feedback - The error message under the field.
+ * @slot hint - The help text under the field.
+ * @slot trigger - The icon on the button that opens the calendar.
  *
- * @event {Event} change - Announced once the value has moved.
- * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the date changes. Cancelable: refusing it takes the decision and nothing moves.
- * @event {HelixBeforeCloseEvent} helix-before-close - Fired before it closes. Cancelable: refusing it takes the decision and nothing moves.
- * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the calendar opens. Cancelable: refusing it takes the decision and nothing moves.
- * @event {Event} input - Announced once the value has moved.
- * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
+ * @event {Event} change - Fired after the value changes.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the date changes. Cancelable: call `preventDefault()` to keep the current date.
+ * @event {HelixBeforeCloseEvent} helix-before-close - Fired before the calendar closes. Cancelable: call `preventDefault()` to keep it open.
+ * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the calendar opens. Cancelable: call `preventDefault()` to keep it closed.
+ * @event {Event} input - Fired after the value changes.
+ * @event {Event} toggle - Fired when the calendar opens or closes, with `newState` and `oldState`.
  *
  * @csspart control - The text input.
  * @csspart date - One held date, as a tag, in `multiple`.
  * @csspart date-dismiss - The remove button, when `dismissible`.
- * @csspart date-dismiss-mark - The glyph on the dismiss control, where none is slotted.
+ * @csspart date-dismiss-mark - The icon on the remove button, shown when no icon is slotted.
  * @csspart date-start - The category before the label.
- * @csspart feedback - What is wrong with it.
- * @csspart field - The box holding the text and the trigger.
- * @csspart hint - Help under the field, while nothing is wrong.
- * @csspart label - The question, over the field.
- * @csspart picker - The date picker inside it.
- * @csspart picker-cell - One column of a row, which is what a range paints.
- * @csspart picker-cell-range-end - The cell of a range's last day, beside `picker-cell`.
- * @csspart picker-cell-range-middle - A cell between a range's ends, beside `picker-cell`.
- * @csspart picker-cell-range-start - The cell of a range's first day, beside `picker-cell`.
- * @csspart picker-day - The shape inside a cell, which is what a single date paints.
- * @csspart picker-day-disabled - A day that cannot be chosen, beside `picker-day`.
- * @csspart picker-day-outside - A day from a neighboring month, beside `picker-day`.
- * @csspart picker-day-selected - The chosen day, or either end of a chosen range, beside `picker-day`.
- * @csspart picker-day-today - Today, beside `picker-day`.
+ * @csspart feedback - The error message under the field.
+ * @csspart field - The box that holds the text and the trigger.
+ * @csspart hint - The help text under the field, shown while there is no error.
+ * @csspart label - The label above the field.
+ * @csspart picker - The date picker inside the panel.
+ * @csspart picker-cell - One cell in a row of days. A range colors these cells.
+ * @csspart picker-cell-range-end - The cell of a range's last day. Applied with `picker-cell`.
+ * @csspart picker-cell-range-middle - A cell between a range's ends. Applied with `picker-cell`.
+ * @csspart picker-cell-range-start - The cell of a range's first day. Applied with `picker-cell`.
+ * @csspart picker-day - The shape inside a cell. A single chosen date colors the shape.
+ * @csspart picker-day-disabled - A day that cannot be chosen. Applied with `picker-day`.
+ * @csspart picker-day-outside - A day from a neighboring month. Applied with `picker-day`.
+ * @csspart picker-day-selected - The chosen day, or either end of a chosen range. Applied with `picker-day`.
+ * @csspart picker-day-today - Today. Applied with `picker-day`.
  * @csspart picker-grid - The grid of days.
  * @csspart picker-header - The month name and its controls.
  * @csspart picker-heading - The month and year being shown.
- * @csspart picker-month - One month, its header and its grid.
- * @csspart picker-months - The run of months.
+ * @csspart picker-month - One month, with its header and its grid.
+ * @csspart picker-months - The row of months.
  * @csspart picker-next - The control that moves to the next month.
- * @csspart picker-next-mark - The glyph on the next month control.
+ * @csspart picker-next-mark - The icon on the next month control.
  * @csspart picker-previous - The control that moves to the previous month.
- * @csspart picker-previous-mark - The glyph on the previous month control.
+ * @csspart picker-previous-mark - The icon on the previous month control.
  * @csspart picker-week - One row of days.
  * @csspart picker-weekday - A column header naming a day of the week.
- * @csspart rest - How many dates are held beyond the ones shown. A `<button>` with `expandable`, a `<span>` without it.
+ * @csspart rest - The count of dates beyond the ones shown. It is a `<button>` with `expandable` and a `<span>` without it.
  * @csspart surface - The floating panel.
  * @csspart tags - The row the dates sit in.
  * @csspart trigger - The control that opens the calendar.
- * @csspart trigger-icon - The mark on the button that opens the calendar.
+ * @csspart trigger-icon - The icon on the button that opens the calendar.
  *
- * @cssstate invalid - While there is feedback to show: the platform's verdict, or the consumer's `feedback`.
- * @cssstate open - While the calendar is open.
+ * @cssstate invalid - The field has an error to show, from the browser's validation or from your `feedback`.
+ * @cssstate open - The calendar is open.
  */
 export declare class HelixHeadlessDateInput extends HelixHeadlessDateInput_base {
     protected readonly aria: AriaForwardController;
@@ -113,23 +111,25 @@ export declare class HelixHeadlessDateInput extends HelixHeadlessDateInput_base
      */
     disableDates: string;
     /**
-     * Days of the week that cannot be chosen, `0` for Sunday through `6`.
+     * Days of the week that cannot be chosen, from `0` for Sunday to `6` for
+     * Saturday.
      */
     disableDays: string;
     /**
-     * First column of the week in the calendar, `0` for Sunday through `6`.
+     * The day in the calendar's first column, from `0` for Sunday to `6` for
+     * Saturday.
      */
     firstDayOfWeek: number;
     /**
-     * Language tag the calendar names its months and days in.
+     * The language tag for the names of months and days in the calendar.
      */
     locale: string;
     /**
-     * Latest date that can be chosen, as `YYYY-MM-DD`.
+     * The latest date that can be chosen, as `YYYY-MM-DD`.
      */
     max: string;
     /**
-     * Earliest date that can be chosen, as `YYYY-MM-DD`.
+     * The earliest date that can be chosen, as `YYYY-MM-DD`.
      */
     min: string;
     /**
@@ -182,11 +182,11 @@ export declare class HelixHeadlessDateInput extends HelixHeadlessDateInput_base
     protected placed(room: number | undefined): void;
     protected willUpdate(changed: PropertyValues): void;
     /**
-     * What the field says before a date is in it.
+     * The text the field shows before a date is entered.
      */
     placeholder: string;
     /**
-     * What a reader is told when a range holds more than two dates.
+     * The message shown when a range holds more than two dates.
      *
      * **Every sentence a control raises in the browser's bubble is a property**,
      * so a form in another language speaks it. Absent is the control's own
@@ -194,17 +194,18 @@ export declare class HelixHeadlessDateInput extends HelixHeadlessDateInput_base
      */
     rangeLengthMessage?: string;
     /**
-     * What a reader is told when a date is after `max`, with `{max}` filled in
-     * as the field writes it.
+     * The message shown when a date is after `max`. `{max}` is replaced with
+     * `max`, written the way the field writes dates.
      */
     rangeOverflowMessage?: string;
     /**
-     * What a reader is told when a date is before `min`, with `{min}` filled
-     * in as the field writes it.
+     * The message shown when a date is before `min`. `{min}` is replaced with
+     * `min`, written the way the field writes dates.
      */
     rangeUnderflowMessage?: string;
     /**
-     * What the control removing one date is called, with `{name}` filled in.
+     * The name of the button that removes one date. `{name}` is replaced with
+     * the date.
      *
      * **The name goes in**, so a row of them is heard as which one each
      * removes rather than as "Remove" said once per date.
@@ -257,7 +258,7 @@ export declare class HelixHeadlessDateInput extends HelixHeadlessDateInput_base
     /** What is wrong with the dates, which the text input cannot say. */
     protected validate(): string;
     /**
-     * Accessible name for the control that opens the calendar.
+     * The name of the button that opens the calendar, read by screen readers.
      */
     triggerLabel: string;
     protected updated(changed: PropertyValues): void;