@fusion.dev/helix-headless 0.104.1 → 0.106.0

package/dist/table/column/table-column.d.ts

@@ -31,51 +31,49 @@ export declare const at: (row: Readonly<Record<string, unknown>>, path: string)
  */
 export declare const edgeOf: (align: string | undefined) => string | undefined;
 /**
- * @summary One column of a table: its heading, how wide it is, and what it reads.
+ * @summary One column of a table: its heading, its width, and the field it reads from each row.
  *
  * @description
- * **The column is the source of both its heading and its track.** Add one and
- * the table has another track; remove one and it does not. That is what ties
- * the two together, and a table-level track list on its own does not: a list
- * that is accidentally the headings is invalid CSS a grid ignores in silence,
- * drawing the whole table as one column. `Table`'s `columns` is dealt out a
- * track at a time against the columns declared under it, so a heading among the
- * widths costs its own column a width and no more, and a list longer or shorter
- * than the columns is trimmed or shared rather than being a second count of
- * them. A column's own `width` wins over the track in its place.
+ * Each column provides both its heading and its grid track. Adding a column
+ * adds a track, and removing one removes it. `Table`'s `columns` is applied one
+ * track at a time to the columns declared under it:
  *
- * **It is also where every per-column fact goes**, which is the reason
- * `DataTable` needs no column config object. `field` names the key the cell
- * reads, `sortable` says a reader may reorder by it, `text-align` says which edge
- * the values line up against, and `cell` takes a function for anything the
- * field alone cannot express. The schema is markup and the data is a property:
- * a schema is small, declarative, and something a reader should be able to see
- * in the HTML, and data is large and windowed.
+ * - A heading name in the list affects only its own column's width.
+ * - A list longer or shorter than the columns is trimmed or shared.
+ * - A column's own `width` overrides the track in its place.
  *
- * **The same element serves both tables**, the markup one and the data one. It
- * is identified by a flag rather than by `instanceof`, so a `TableColumn` works
- * inside either without the two roots sharing anything else.
+ * This protects the table from a track list that contains the headings by
+ * mistake, which is invalid CSS that the grid ignores silently, drawing the
+ * whole table as one column.
  *
- * **It generates no box of its own**, the same as a row: the heading is a grid
- * item of the table, so it lines up with the cells under it rather than sitting
- * in a wrapper that has to be kept the same width.
+ * Every per-column setting goes on the column, so `DataTable` needs no column
+ * configuration object:
  *
- * **`hidden` takes the column out of the grid**, its heading and its track
- * both, so the columns after it keep their own widths and every row keeps its
- * cells under their headings. `hidden="until-found"` keeps its track, the
- * heading being left drawn, as every Helix element leaves one with that value.
- * `DataTable` draws the cells, so it leaves out the ones under a hidden column.
- * A `Table`'s cells are markup the consumer wrote, so hide them with the
- * column, as removing a column means removing its cells: a row with a cell more
- * than the table has tracks wraps into the next.
+ * - `field` names the key the cell reads.
+ * - `sortable` lets people sort by the column.
+ * - `text-align` sets which edge the values line up against.
+ * - `cell` takes a function for anything `field` alone cannot express.
  *
- * **A heading that does something holds a control that does it.** The host is
- * the column header, and a header is not focusable, so a sortable heading is a
- * `<button>` inside it: the pattern for a sortable table, and the only way a
- * reader on a keyboard reaches the sort at all. A column a reader may resize
- * carries a `separator` on its end edge, moved by dragging it or with the arrow
- * keys, and a column in a table that lets a reader reorder its columns carries
- * a grip the table moves.
+ * The same element works in both `Table` and `DataTable`. It is identified by a
+ * flag, so the two roots share nothing else.
+ *
+ * The column generates no box of its own, the same as a row. The heading is a
+ * grid item of the table, so it lines up with the cells below it.
+ *
+ * `hidden` takes the column out of the grid, both its heading and its track, so
+ * the other columns keep their widths and every row keeps its cells under their
+ * headings. `hidden="until-found"` keeps the track and leaves the heading
+ * drawn, as it does on every Helix element. `DataTable` leaves out the cells
+ * under a hidden column. In a `Table` the cells are markup you wrote, so hide
+ * them with the column: a row with more cells than the table has tracks wraps
+ * onto the next line.
+ *
+ * A heading that does something holds a control. A column header is not
+ * focusable, so a sortable heading contains a `<button>`, which is the pattern
+ * for a sortable table and the only way to reach the sort by keyboard. A
+ * resizable column has a `separator` on its end edge, moved by dragging or with
+ * the arrow keys. In a table with reorderable columns, each column has a grip
+ * that the table moves.
  *
  * @since 0.1.0
  * @status stable
@@ -84,20 +82,21 @@ export declare const edgeOf: (align: string | undefined) => string | undefined;
  *
  * @slot - The heading.
  *
- * @event {HelixBeforeResizeEvent} helix-before-resize - Fired as a reader resizes the column, with the width asked for, and cancelable.
+ * @event {HelixBeforeResizeEvent} helix-before-resize - The column is about to be resized, with the requested width. Cancelable: cancel it to keep the current width.
  *
  * @csspart column - The heading cell.
- * @csspart grip - The handle a reader moves the column by, where the table allows it.
- * @csspart grip-mark - The glyph on it.
- * @csspart resizer - The edge a reader drags to change the width, where the column allows it.
- * @csspart sort - The button a sortable heading is.
+ * @csspart grip - The handle for moving the column, when the table allows it.
+ * @csspart grip-mark - The icon on the grip.
+ * @csspart resizer - The edge that is dragged to change the width, when the column is resizable.
+ * @csspart sort - The button that a sortable heading renders as.
  *
  * @cssstate sorted-ascending - While the table is sorted by this column, smallest first.
  * @cssstate sorted-descending - While the table is sorted by this column, largest first.
  */
 export declare class HelixHeadlessTableColumn extends HelixElement {
     /**
-     * How to read the cell, where the field alone will not do.
+     * A function that reads the cell's content from a row, for cells that `field`
+     * alone cannot read.
      *
      * A property and not an attribute, because it is a function. Set it from a Lit
      * template with `.cell=${...}`, or assign it in script. A column with neither
@@ -106,7 +105,8 @@ export declare class HelixHeadlessTableColumn extends HelixElement {
      */
     cell: CellReader | undefined;
     /**
-     * How to read the value that gets sorted and filtered, where it is not the cell.
+     * A function that reads the value used for sorting and filtering, when it
+     * differs from the cell.
      *
      * **The one that is easy to leave out and expensive to add later.** A cell
      * showing `2.4 MB` sorts as a string unless something says the underlying value
@@ -132,15 +132,15 @@ export declare class HelixHeadlessTableColumn extends HelixElement {
      */
     field: string;
     /**
-     * What the grip that moves the column is called, with the heading's words as
-     * `{name}`.
+     * The accessible name of the grip that moves the column. `{name}` is replaced
+     * with the heading text.
      *
      * **Every word a column speaks is a property**, so a table in another
      * language hears its own rather than English around its own headings.
      */
     moveLabel: string;
     /**
-     * Whether a reader may change this column's width.
+     * Whether the column can be resized.
      *
      * By dragging the edge at the end of the heading, or with the arrow keys once
      * it has focus, a step at a time and four with Shift. The width lands in
@@ -149,12 +149,12 @@ export declare class HelixHeadlessTableColumn extends HelixElement {
      */
     resizable: boolean;
     /**
-     * What the separator that resizes the column is called, with the heading's
-     * words as `{name}`.
+     * The accessible name of the separator that resizes the column. `{name}` is
+     * replaced with the heading text.
      */
     resizeLabel: string;
     /**
-     * Whether a reader may reorder the set by this column.
+     * Whether the table can be sorted by this column.
      *
      * Ignored without a `field`, and silently: a column with nothing to sort by
      * has no order to offer, and refusing loudly would mean an actions column
@@ -226,7 +226,8 @@ export declare class HelixHeadlessTableColumn extends HelixElement {
      */
     width: string;
     /**
-     * How the separator reads out the column's width, with `{width}` filled in.
+     * The text screen readers announce for the column's width. `{width}` is
+     * replaced with the width.
      */
     widthLabel: string;
     /**
@@ -257,7 +258,7 @@ export declare class HelixHeadlessTableColumn extends HelixElement {
     /** Watches `hidden`, which is the platform's attribute and no property of this element's. */
     private hiding;
     /**
-     * The narrowest a reader can drag a column, in pixels.
+     * The narrowest width a column can be dragged to, in pixels.
      *
      * Three characters and the inset around them. Narrower and the heading has
      * nothing left to be read by, and the separator is a grab target with no
@@ -275,7 +276,10 @@ export declare class HelixHeadlessTableColumn extends HelixElement {
      * exactly when the heading stops being drawn.
      */
     get shown(): boolean;
-    /** Whether a reader can actually reorder by this column. */
+    /**
+     * Whether the table can be sorted by this column, which needs `sortable` and
+     * a `field`.
+     */
     get canSort(): boolean;
     /**
      * The value this column shows for a row.
@@ -285,7 +289,10 @@ export declare class HelixHeadlessTableColumn extends HelixElement {
      * default back for the rows it has nothing to say about.
      */
     read(row: Readonly<Record<string, unknown>>): unknown;
-    /** The value this column sorts and filters by, which is not always what it shows. */
+    /**
+     * The value this column sorts and filters by for a row, which can differ from
+     * what it shows.
+     */
     order(row: Readonly<Record<string, unknown>>): unknown;
     protected willUpdate(changed: PropertyValues): void;
     /** The words of the heading, for naming the controls on it. */

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

@@ -3,23 +3,22 @@ import { type PropertyValues, type TemplateResult } from 'lit';
 import { type HelixHeadlessTableColumn } from '../column/table-column.js';
 declare const HelixHeadlessTable_base: (new (...args: any[]) => import("@fusion.dev/helix-core").CollectionElement) & typeof HelixElement;
 /**
- * @summary Tabular data laid out on a grid.
+ * @summary A table of data, laid out on a grid.
  *
  * @description
- * A grid rather than a `<table>`, so every column lines up across rows while
+ * Lays out the rows on a CSS grid, so every column lines up across rows and
  * each row stays a real element that can be styled, hidden, or made
- * interactive. Table layout gives column alignment and takes away almost
- * everything else; grid gives both.
+ * interactive. A `<table>` layout aligns columns but limits almost everything
+ * else.
  *
- * The cost is that the roles have to be declared, since a grid of divs is not a
- * table to anyone reading it. `table`, `row`, `cell`, and `columnheader` are
- * all set explicitly, and rows are `display: contents` so their cells become
- * items of the one grid that does the aligning.
+ * A grid of elements has no table structure for assistive technology, so the
+ * roles are set explicitly: `table`, `row`, `cell`, and `columnheader`. Rows
+ * are `display: contents`, so their cells become items of the one grid.
  *
- * The properties below are written by this component and read by whoever draws
- * it. A consumer sets none of them: they carry a number this element computed
- * and CSS cannot, which is what lets a stylesheet on this tier draw the thing
- * without measuring anything itself.
+ * The CSS custom properties listed for this component are written by it and
+ * read by the stylesheet that draws it. Do not set them. Each holds a number
+ * the component computes and CSS cannot, so the stylesheet can draw the table
+ * without measuring anything.
  *
  * @since 0.1.0
  * @status stable
@@ -29,13 +28,13 @@ declare const HelixHeadlessTable_base: (new (...args: any[]) => import("@fusion.
  *
  * @slot - The table's rows.
  *
- * @csspart empty - Shown when there are no rows to show.
- * @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 empty - The text shown when there are no rows.
+ * @csspart head - The row that holds the column headings. It has `display: contents`, so it takes no space of its own.
+ * @csspart live - A live region that repeats the empty and loading text, so screen readers announce it when it changes. Visually hidden in the styled tier.
+ * @csspart loading - The text shown while the rows are loading.
  * @csspart table - The grid.
  *
- * @cssproperty --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. `columns` is the one to set.
+ * @cssproperty --table-template - The column track list the table works out from its columns. The component writes it inline on the element that reads it, so setting it has no effect. Set `columns` to change the tracks.
  */
 export declare class HelixHeadlessTable extends HelixHeadlessTable_base {
     /**

package/dist/table/row/table-row.d.ts

@@ -5,9 +5,9 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  *
  * @description
  * The row renders its cells straight through and lays out none of them, so a
- * sheet can take them into the table's own grid and every column lines up
- * across every row. The row still exists as an element, which is what a
- * `<table>` gives away when its cells are laid out by the table algorithm.
+ * stylesheet can place them in the table's grid and every column lines up
+ * across rows. The row still exists as an element, so you can style it, hide
+ * it, or make it interactive.
  *
  * @since 0.1.0
  * @status stable

package/dist/tabs/panel/tab-panel.d.ts

@@ -4,9 +4,9 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @summary The content shown for one tab.
  *
  * @description
- * Hidden rather than unmounted when inactive, so anything typed into a panel is
- * still there when the reader comes back to it, and so the content is in the
- * server's markup for a crawler regardless of which tab is open.
+ * An inactive panel is hidden and stays mounted. Anything typed into it is
+ * still there when the person comes back, and the content of every panel is in
+ * the server-rendered markup for crawlers, whichever tab is open.
  *
  * @since 0.1.0
  * @status stable

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

@@ -5,15 +5,16 @@ declare const HelixHeadlessTabs_base: (new (...args: any[]) => import("@fusion.d
  * @summary A row of tabs and the panel each one shows.
  *
  * @description
- * Selection is coordinated by event, the same shape the accordion and the tree
- * use: a tab dispatches `helix-select` and the root pairs it with the panel of
- * the same value. Nothing registers with anything, so tabs added later work
- * without the root being told.
+ * Selection works through an event, the same as in the accordion and the tree.
+ * A tab dispatches `helix-select`, and the root pairs it with the panel of the
+ * same value. Nothing registers with anything, so tabs added later work with no
+ * extra setup.
  *
- * The tab list is a single tab stop, moved with the arrow keys through
- * `KeyboardNavigationController`, the same one the radio and toggle groups use.
- * Selection follows focus, which is the right default for a small set where
- * showing a panel is cheap; a set where it is not should use `manual`.
+ * The tab list is a single tab stop, and the arrow keys move between tabs
+ * through `KeyboardNavigationController`, the same as in the radio and toggle
+ * groups. Selection follows focus, which suits a small set where showing a
+ * panel is cheap. Set `manual` when showing a panel is expensive, so focus can
+ * move without selecting.
  *
  * @since 0.1.0
  * @status stable
@@ -21,14 +22,14 @@ declare const HelixHeadlessTabs_base: (new (...args: any[]) => import("@fusion.d
  * @aliases TabList, Segmented control
  * @documentation https://fusion.dev/helix/components/tabs
  *
- * @slot - The tabs, which are this element's own children.
- * @slot panels - The panels, which are this element's own children. A wrapper around them is assigned to the slot and pairs with nothing, since the pairing walks these children rather than the slot's tree.
+ * @slot - The tabs, as direct children of this element.
+ * @slot panels - The panels, as direct children of this element. Panels inside a wrapper are not paired with tabs, because pairing reads only the direct children.
  *
- * @event {HelixActivateEvent} helix-activate - Fired once the current one has moved, so the element already holds it.
- * @event {HelixBeforeActivateEvent} helix-before-activate - Fired before the current tab moves, and cancelable. The only way to refuse one.
- * @event {HelixSelectEvent} helix-select - Fired when a tab is chosen. Dispatched by the tab and listened for here, because the root is what a consumer holds. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixActivateEvent} helix-activate - Fired after the active tab changes, so the element already holds the new value.
+ * @event {HelixBeforeActivateEvent} helix-before-activate - Fired before the active tab changes, and cancelable. Canceling it is the only way to block a change.
+ * @event {HelixSelectEvent} helix-select - Fired when a tab is chosen. The tab sends it and the root handles it, so you can listen on the root. Cancelable: canceling it stops the change and leaves the decision to you.
  *
- * @csspart indicator - The mark that travels to the selected tab.
+ * @csspart indicator - The marker that moves to the selected tab.
  * @csspart panels - The panel container.
  * @csspart tabs - The tab list.
  */
@@ -36,11 +37,12 @@ export declare class HelixHeadlessTabs extends HelixHeadlessTabs_base {
     protected readonly keys: KeyboardNavigationController;
     private readonly indicator;
     /**
-     * Accessible name for the tab list.
+     * The tab list's name, read by screen readers.
      */
     label: string;
     /**
-     * Whether arrowing to a tab also selects it.
+     * Stops the arrow keys from selecting each tab they move to. By default,
+     * arrowing to a tab also selects it.
      *
      * Automatic is the default because showing a panel is usually cheap. Set this
      * where it is not, so a reader arrowing past four tabs does not load four
@@ -48,7 +50,7 @@ export declare class HelixHeadlessTabs extends HelixHeadlessTabs_base {
      */
     manual: boolean;
     /**
-     * How the row reads.
+     * How the row of tabs is drawn.
      *
      * Unset is a raised pill on the selected tab with nothing behind the row,
      * which is what a set sitting inside other chrome wants. `underlined` is a

package/dist/tabs/tab/tab.d.ts

@@ -5,12 +5,12 @@ declare const HelixHeadlessTab_base: (new (...args: any[]) => import("@fusion.de
  * @summary One tab in a tab list.
  *
  * @description
- * An element rather than a slot because it owns selection and its own tab stop.
+ * A tab is an element, because it manages selection and its own tab stop.
  *
- * Its id and the id it controls are both derived from `value`, so the pairing
- * between a tab and its panel survives server rendering. A generated id would
- * differ between the server's render and the client's and break the link, and
- * `aria-controls` pointing at nothing is worse than not being there.
+ * Its id and the id it controls both come from `value`, so the link between a
+ * tab and its panel works with server rendering. A generated id would differ
+ * between the server render and the client render, and `aria-controls` would
+ * point at nothing.
  *
  * @since 0.1.0
  * @status stable
@@ -19,7 +19,7 @@ declare const HelixHeadlessTab_base: (new (...args: any[]) => import("@fusion.de
  *
  * @slot - The tab's label.
  *
- * @event {HelixSelectEvent} helix-select - Fired when the tab is chosen. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixSelectEvent} helix-select - Fired when the tab is chosen. Cancelable: canceling it stops the change and leaves the decision to you.
  *
  * @csspart tab - The tab itself.
  *

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

@@ -2,17 +2,16 @@ import { HelixElement } from '@fusion.dev/helix-core';
 import { type TemplateResult } from 'lit';
 declare const HelixHeadlessTag_base: (new (...args: any[]) => import("@fusion.dev/helix-core").DismissibleElement) & typeof HelixElement;
 /**
- * @summary Labels content with a short piece of metadata.
+ * @summary A short label that adds metadata to content.
  *
  * @description
- * A tag is a label, and optionally a label the reader can take off.
- * `dismissible` is what separates it from a badge: a badge reports a state the
- * reader cannot change, a tag names something they can.
+ * A label that people can optionally remove. `dismissible` is the difference
+ * from a badge: a badge shows a state that people cannot change, and a tag
+ * names something they can remove.
  *
- * Dismissing is a request. The tag does not remove itself, because the consumer
- * owns the list it sits in and taking the node out from under them would put
- * their state and the document out of step. Canceling `helix-dismiss` is a
- * refusal.
+ * The remove button sends `helix-dismiss`. The tag does not remove itself,
+ * because your code owns the list it is in, so remove it in your handler. A
+ * listener can cancel `helix-dismiss`, and `dismiss()` then returns `false`.
  *
  * @since 0.1.0
  * @status stable
@@ -21,12 +20,12 @@ declare const HelixHeadlessTag_base: (new (...args: any[]) => import("@fusion.de
  * @documentation https://fusion.dev/helix/components/tag
  *
  * @slot - The tag's label.
- * @slot start - A category the label belongs to, set before it and weightier.
+ * @slot start - The category the label belongs to, shown before it in a heavier weight.
  *
- * @event {HelixDismissEvent} helix-dismiss - Fired when the reader asks to remove the tag. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixDismissEvent} helix-dismiss - The remove button was pressed. The tag does not remove itself, so remove it in response. Cancelable.
  *
- * @csspart dismiss - The control that asks to remove the tag.
- * @csspart dismiss-mark - The glyph on the dismiss control, where none is slotted.
+ * @csspart dismiss - The button that removes the tag.
+ * @csspart dismiss-mark - The icon on the remove button.
  * @csspart start - The category before the label.
  */
 export declare class HelixHeadlessTag extends HelixHeadlessTag_base {

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

@@ -2,23 +2,18 @@ import { AriaForwardController, HelixFormElement } from '@fusion.dev/helix-core'
 import { type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessTextarea_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinFieldInterface) & typeof HelixFormElement;
 /**
- * @summary Several lines of text a reader types into.
+ * @summary A multi-line text field.
  *
  * @description
- * A real `<textarea>`, so the caret, the selection, spellcheck, the resize
- * handle and the keyboard a phone chooses are all the platform's, and it
- * serializes into the server's markup so the field is usable before any script
- * loads.
+ * Renders a `<textarea>`, so the caret, selection, spellcheck, resize handle,
+ * and phone keyboard come from the platform. It is in the server markup, so the
+ * field works before any script loads.
  *
- * **Not an Input with a taller box.** The difference is the Enter key: in a
- * single-line field it submits the form, and here it inserts a line. That is a
- * behavioral difference the platform owns and cannot be styled into existence,
- * which is why this is its own element rather than `Input` with a property.
+ * It is a separate element from `Input` because Enter inserts a line break
+ * here. In a single-line field, Enter submits the form.
  *
- * `rows` sets the height it starts at, and `auto-grow` lets it follow its own
- * content. They are not alternatives: `rows` is where an empty field begins and
- * `auto-grow` is what happens after, so a field that grows still has to start
- * somewhere.
+ * `rows` sets the starting height, and `auto-grow` makes the field grow with
+ * its content. You can use both: `rows` sets where an empty field begins.
  *
  * @since 0.1.0
  * @status stable
@@ -26,35 +21,37 @@ declare const HelixHeadlessTextarea_base: (new (...args: any[]) => import("@fusi
  * @aliases Multiline, TextArea
  * @documentation https://fusion.dev/helix/components/textarea
  *
- * @event {Event} change - Relayed from the textarea once the reader has finished.
+ * @event {Event} change - Sent from the textarea when the user finishes an edit.
  * @event {HelixBeforeChangeEvent} helix-before-change - Fired as the text changes, and cancelable.
- * @event {Event} input - Announced once the value has moved.
+ * @event {Event} input - Fired after the value changes.
  *
  * @csspart control - The textarea itself.
- * @csspart feedback - What is wrong with it.
- * @csspart field - The box holding the control.
+ * @csspart feedback - The message that says what is wrong.
+ * @csspart field - The box that holds the textarea.
  * @csspart hint - Help under the field, while nothing is wrong.
- * @csspart label - The question, over the field.
+ * @csspart label - The label above the field.
  *
- * @cssstate invalid - While there is feedback to show: the platform's verdict, or the consumer's `feedback`.
+ * @cssstate invalid - The control has an error to show, from the browser's validation or from your `feedback`.
  */
 export declare class HelixHeadlessTextarea extends HelixHeadlessTextarea_base {
     protected readonly aria: AriaForwardController;
     /** Typed or dragged, so every edit is announced. See `announcesInput`. */
     protected readonly announcesInput = true;
     /**
-     * What the browser may autofill here, as one of the platform's own tokens.
+     * What the browser can autofill in the field, as a standard `autocomplete`
+     * token.
      *
      * Empty leaves the attribute off, which is the browser's default. Set it to
      * a token like `email` or `bday` to ask for autofill, or to `off` to refuse.
      */
     autocomplete: string;
     /**
-     * Whether the box follows its own content rather than scrolling.
+     * Grows the box to fit its content, so it does not scroll.
      */
     autoGrow: boolean;
     /**
-     * How many characters wide the box is, where the layout is not deciding.
+     * How many characters wide the box is, when the layout does not set its
+     * width.
      *
      * Optional and absent by default, which is the reflected-property rule: a
      * `<textarea>` left alone is 20 columns wide and a styled one is whatever its
@@ -64,7 +61,7 @@ export declare class HelixHeadlessTextarea extends HelixHeadlessTextarea_base {
      */
     cols?: number;
     /**
-     * The name a second entry carries, holding which way the text runs.
+     * The name of a second form entry that submits the direction of the text.
      *
      * **Submitted through `setFormValue`, because the inner control's own
      * `dirname` cannot reach the form.** This host is form-associated and reports
@@ -75,11 +72,11 @@ export declare class HelixHeadlessTextarea extends HelixHeadlessTextarea_base {
      */
     dirName: string;
     /**
-     * Most characters the value may have.
+     * The most characters the value can have.
      */
     maxLength?: number;
     /**
-     * Fewest characters the value may have.
+     * The fewest characters the value can have.
      *
      * Forwarded to the real `<textarea>` rather than checked here, which is what
      * makes the message the browser's and therefore the reader's own language.
@@ -88,13 +85,13 @@ export declare class HelixHeadlessTextarea extends HelixHeadlessTextarea_base {
      */
     minLength?: number;
     /**
-     * Shown while the field is empty.
+     * Text shown while the field is empty.
      *
      * Not a label: it goes when typing starts.
      */
     placeholder: string;
     /**
-     * Whether the field refuses input while still submitting its value.
+     * Blocks typing in the field. The value is still submitted with the form.
      */
     readOnly: boolean;
     /** Focus is delegated to the control, so the host is never the target. */
@@ -146,7 +143,7 @@ export declare class HelixHeadlessTextarea extends HelixHeadlessTextarea_base {
      */
     private formValue;
     /**
-     * The caret and the selection, under the platform's own names.
+     * The direction of the selection, as a native textarea reports it.
      *
      * **The whole reason this renders a real `<textarea>` is the caret**, and the
      * control is inside this shadow root, so `querySelector` does not find it and
@@ -167,8 +164,8 @@ export declare class HelixHeadlessTextarea extends HelixHeadlessTextarea_base {
     get selectionStart(): number;
     set selectionStart(at: number);
     /**
-     * Selects a range, which is the one operation the three accessors above
-     * cannot express between them.
+     * Selects a range of text, which the three selection properties cannot do
+     * between them.
      *
      * Setting `selectionStart` past the current `selectionEnd` drags the end
      * along, so the two writes a consumer would make in sequence do not compose
@@ -178,9 +175,9 @@ export declare class HelixHeadlessTextarea extends HelixHeadlessTextarea_base {
     setSelectionRange(start: number, end: number, direction?: SelectionDirection): void;
     /** How many characters the value holds. */
     get textLength(): number;
-    /** What kind of control this is, which for a textarea is always the one word. */
+    /** The control's type, which is always `textarea`. */
     get type(): string;
-    /** Puts the caret in the field, the way a label pointing at one would. */
+    /** Puts the caret in the field, as a label pointing at it would. */
     focus(options?: FocusOptions): void;
     /** Reports the value and the validity the host stands behind. */
     private sync;