@fusion.dev/helix-headless 0.104.1 → 0.106.0

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;

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

@@ -2,23 +2,26 @@ import { HelixFormElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessDatePicker_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerValueInterface) & typeof HelixFormElement;
 /**
- * @summary Shows a month, and takes a date from it.
+ * @summary A month calendar for choosing one or more dates.
  *
  * @description
- * A grid of days, per the APG date grid: the whole grid is one tab stop, arrows
- * move by day and week, `PageUp` and `PageDown` by month, `Home` and `End` to
- * the ends of the week. Only the focused cell is in the tab sequence.
+ * A grid of days that follows the APG date grid pattern:
  *
- * **Dates are `YYYY-MM-DD` strings and every calculation is in UTC.** A
- * local-time `Date` shifts across a timezone or a daylight-saving boundary.
+ * - The grid is one tab stop. Only the focused cell is in the tab sequence.
+ * - Arrow keys move by day and by week.
+ * - `PageUp` and `PageDown` move by month.
+ * - `Home` and `End` move to the start and end of the week.
  *
- * `month` is what the grid shows, separately from `value`, so paging does not
- * select anything and a consumer can drive the view. Left unset it follows the
+ * **Dates are `YYYY-MM-DD` strings, and every calculation is in UTC**, because
+ * a local-time `Date` shifts across a time zone or daylight-saving boundary.
+ *
+ * `month` sets which month the grid shows, separately from `value`, so paging
+ * selects nothing and you can control the view. When unset, it follows the
  * first selected date, then the current month.
  *
- * `mode` decides how many dates are held: absent takes one, `range` takes two
- * and marks everything between them, `multiple` toggles. All three read and
- * write the same comma-separated `value`.
+ * `mode` sets how many dates are held. Unset holds one, `range` holds two and
+ * marks the dates between them, and `multiple` toggles each date. All three
+ * read and write the same comma-separated `value`.
  *
  * @since 0.1.0
  * @status stable
@@ -29,16 +32,16 @@ declare const HelixHeadlessDatePicker_base: (new (...args: any[]) => import("@fu
  * @slot next-icon - The glyph on the control that moves forward a month, usually a caret.
  * @slot previous-icon - The glyph on the control that moves back a month, usually a caret.
  *
- * @event {Event} change - Announced once the value has moved.
+ * @event {Event} change - Fired after the value changes.
  * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the dates change, and cancelable.
  * @event {HelixNavigateEvent} helix-navigate - Fired before the month on show changes, and cancelable.
- * @event {Event} input - Announced once the value has moved.
+ * @event {Event} input - Fired after the value changes.
  *
- * @csspart cell - One column of a row, which is what a range paints.
+ * @csspart cell - One column of a week row. A range is painted on the cells.
  * @csspart cell-range-end - The cell of a range's last day, beside `cell`.
  * @csspart cell-range-middle - A cell between a range's ends, beside `cell`.
  * @csspart cell-range-start - The cell of a range's first day, beside `cell`.
- * @csspart day - The shape inside a cell, which is what a single date paints.
+ * @csspart day - The shape inside a cell. A single chosen date is painted on it.
  * @csspart day-disabled - A day that cannot be chosen, beside `day`.
  * @csspart day-outside - A day from a neighboring month, filling the grid out, beside `day`.
  * @csspart day-selected - The chosen day, or either end of a chosen range, beside `day`.
@@ -59,7 +62,7 @@ declare const HelixHeadlessDatePicker_base: (new (...args: any[]) => import("@fu
  */
 export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_base {
     /**
-     * What a reader is told when the value holds something that is not a date.
+     * The validation message for a value that is not a date.
      *
      * **Every sentence a control raises in the browser's bubble is a property**,
      * named for the validity flag it reports, so a form in another language
@@ -67,7 +70,7 @@ export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_bas
      */
     badInputMessage?: string;
     /**
-     * Month to open on, where nothing declared one.
+     * The month to open on when `month` is not set.
      */
     defaultMonth: string;
     /**
@@ -111,7 +114,8 @@ export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_bas
     /** The month on show, whoever set it, and `undefined` until somebody has. */
     private monthState;
     /**
-     * The month on show, as `YYYY-MM`. Follows `value`, then the current month.
+     * The month shown, as `YYYY-MM`. When it is not set, it follows `value`,
+     * then the current month.
      *
      * Separate from `value` on purpose, so paging selects nothing and a consumer
      * can drive the view. Reading gives the month on show; writing sets it, and
@@ -137,7 +141,7 @@ export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_bas
      */
     previousLabel: string;
     /**
-     * Whether the control refuses changes while still submitting its value.
+     * Blocks changes to the dates. The value is still submitted with the form.
      *
      * **Enforced by refusing every request in one place**, which is the seam this
      * component already has: `requestValue` is what every path here comes through,
@@ -218,7 +222,7 @@ export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_bas
     connectedCallback(): void;
     disconnectedCallback(): void;
     /**
-     * Whether the form refuses to submit while nothing is chosen.
+     * Stops the form from submitting while no date is chosen.
      */
     required: boolean;
     /** Refuses every change while read-only. See `readOnly`. */
@@ -238,7 +242,7 @@ export declare class HelixHeadlessDatePicker extends HelixHeadlessDatePicker_bas
      */
     step: number;
     /**
-     * What a reader is told when a date is required and none is chosen.
+     * The validation message for a required date picker with no date chosen.
      */
     valueMissingMessage?: string;
     /**

package/dist/description-list/item/description-list-item.d.ts

@@ -4,13 +4,13 @@ import { type TemplateResult } from 'lit';
  * @summary One label and its value.
  *
  * @description
- * An element rather than a pair of slots on the list, because a pair is the
- * unit a reader hears: the label is the `<dt>` and the value its `<dd>`, and the
- * two stay together however the list lays them out.
+ * Each pair is its own element: the label is the `<dt>` and the value its
+ * `<dd>`, and a screen reader hears them together however the list lays them
+ * out.
  *
- * The value is the default slot, since it is what varies and is often more
- * than text: a tag, an avatar, a link. The label is text almost every time, so
- * it is also a property.
+ * The value is the default slot, because it varies and is often more than text,
+ * such as a tag, an avatar, or a link. The label is almost always text, so it
+ * is also a property.
  *
  * @since 0.1.0
  * @status stable
@@ -24,7 +24,7 @@ import { type TemplateResult } from 'lit';
  */
 export declare class HelixHeadlessDescriptionListItem extends HelixElement {
     /**
-     * What the value is called, for the common case of plain text.
+     * The label, when it is plain text.
      *
      * The fallback of the `label` slot, so slotted content replaces it rather than
      * appearing beside it. The value itself is the default slot: it is the half

package/dist/description-list/root/description-list-root.d.ts

@@ -1,24 +1,19 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type TemplateResult } from 'lit';
 /**
- * @summary Labels and their values, read as pairs: the details panel every
- * product has.
+ * @summary A list of labels and their values, such as a details panel.
  *
  * @description
- * "Owner: Ada, Region: us-east, Created: 3 days ago" is the commonest panel in
- * any console, and built from layout primitives it is a run of adjacent text:
- * nothing tells a screen reader that a label and a value belong together, or
- * how many pairs there are. This renders the element the platform has for it,
- * a `<dl>`, with each item's label a `<dt>` and its value a `<dd>`.
+ * Renders a `<dl>`, with each item's label as a `<dt>` and its value as a
+ * `<dd>`, for panels such as "Owner: Ada, Region: us-east, Created: 3 days
+ * ago". A screen reader announces which label goes with which value and how
+ * many pairs there are.
  *
- * **The items render their own term and description**, and the list takes them
- * through its slot. The accessibility tree is built from the flattened tree, so
- * the pairs reach it inside the list rather than beside it. Measured in
- * Chromium's tree rather than assumed, because a list whose semantics stopped
- * at a shadow boundary would look identical on screen: one description list
- * holding term and definition pairs, node for node what a plain `<dl>` with the
- * same content produces, with a slotted label and with an item drawn as
- * `display: contents` alike.
+ * **Each item renders its own term and description**, and the list takes the
+ * items through its slot. The accessibility tree is built from the flattened
+ * tree, so the pairs appear inside the list. Measured in Chromium, the result
+ * matches a plain `<dl>` with the same content node for node, both with a
+ * slotted label and with an item set to `display: contents`.
  *
  * @since 0.1.0
  * @status stable

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

@@ -2,20 +2,22 @@ import { CommandController, HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessDialog_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
 /**
- * @summary A modal window, on the platform's own dialog.
+ * @summary A modal window built on the native `<dialog>` element.
  *
  * @description
- * A real `<dialog>` opened with `showModal()`, not a div with a role and a
- * hand-built trap. The platform gives four things that are each a day's work to
- * reimplement: the top layer, so the dialog is above everything whatever
- * `z-index` anyone wrote; a real backdrop; Escape; and inert-behind, so the
- * page underneath is unreachable by pointer, keyboard or virtual cursor.
+ * Renders a native `<dialog>` opened with `showModal()`. The platform provides:
  *
- * **`open` drives `showModal()`, and every way it can close comes back through
- * `requestOpen`.** A native dialog closes from three directions: the property,
- * Escape, and a `<form method="dialog">` submit. Left alone, two of them would
- * shut the dialog while the consumer's state still said open, which is the bug
- * that makes a modal impossible to reopen.
+ * - the top layer, so the dialog is above everything whatever the `z-index`
+ * - a backdrop
+ * - closing with Escape
+ * - an inert page behind the dialog, unreachable by pointer, keyboard, or
+ *   virtual cursor
+ *
+ * `open` calls `showModal()`, and every way the dialog closes goes through
+ * `requestOpen`. A native dialog closes three ways: the property, Escape, and a
+ * `<form method="dialog">` submit. Routing all three through `requestOpen`
+ * keeps your state in step, so the dialog never closes while your state still
+ * says it is open, which would leave it impossible to reopen.
  *
  * @since 0.1.0
  * @status stable
@@ -24,14 +26,14 @@ declare const HelixHeadlessDialog_base: (new (...args: any[]) => import("@fusion
  * @documentation https://fusion.dev/helix/components/dialog
  *
  * @slot - The dialog's content.
- * @slot footer - The actions.
+ * @slot footer - The dialog's actions.
  * @slot header - The title, and anything beside it.
- * @slot icon - A single mark above the title, for a dialog that warns.
+ * @slot icon - An icon above the title, for a warning dialog.
  *
- * @event {Event} close - Relayed, because the platform's own does not escape.
+ * @event {Event} close - Sent from the host after the dialog closes, because the native `close` event does not leave the shadow root.
  * @event {HelixBeforeCloseEvent} helix-before-close - Fired before it closes, and cancelable.
  * @event {HelixBeforeOpenEvent} helix-before-open - Fired before it opens, and cancelable.
- * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
+ * @event {Event} toggle - Sent when the dialog opens or closes, with `newState` and `oldState`.
  *
  * @csspart dialog - The native dialog element.
  *
@@ -39,7 +41,7 @@ declare const HelixHeadlessDialog_base: (new (...args: any[]) => import("@fusion
  */
 export declare class HelixHeadlessDialog extends HelixHeadlessDialog_base {
     /**
-     * Which close requests the browser answers on its own.
+     * Which close requests the browser handles on its own.
      *
      * `<dialog closedby>`, forwarded, and safe to forward because every path it
      * opens still comes back through this element: a close request fires `cancel`
@@ -57,7 +59,7 @@ export declare class HelixHeadlessDialog extends HelixHeadlessDialog_base {
     label: string;
     protected readonly commands: CommandController;
     /**
-     * Whether Escape or a press on the backdrop can close it.
+     * Stops Escape and a press on the backdrop from closing the dialog.
      *
      * Off for a dialog that must be answered. It does not disable the close
      * control a consumer slots in: refusing to be dismissed is not the same as
@@ -86,10 +88,11 @@ export declare class HelixHeadlessDialog extends HelixHeadlessDialog_base {
     private returned;
     /** The native dialog, or nothing where there is no DOM to hold one. */
     private get dialog();
-    /** Moves focus into the dialog and makes the rest of the page inert. */
+    /** Opens the dialog, moves focus into it, and makes the rest of the page inert. */
     show(): void;
     /**
-     * Asks to close, which a consumer may refuse.
+     * Requests that the dialog close. A `helix-before-close` listener can cancel
+     * the request.
      *
      * Takes what the dialog closed with, the way `<dialog>.close(value)` does, so
      * the button that dismissed it can say which one it was. Set before the

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

@@ -1,18 +1,17 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 /**
- * @summary Separates content into groups with a rule.
+ * @summary A line that separates content into groups.
  *
  * @description
- * The separator role lives on the rule inside the shadow root rather than on
- * the host. A role does not need to cross the shadow boundary the way an IDREF
- * does, and putting it on the rendered element means the semantics are in the
- * server's markup with no attribute written during a lifecycle the server never
- * runs.
+ * The separator role is on the rule inside the shadow root. A role does not
+ * need to cross the shadow boundary the way an IDREF does, so it can sit on the
+ * rendered element. The semantics are then in the server-rendered markup, with
+ * no attribute written by script after the element connects.
  *
  * Use `orientation="vertical"` between items on one line, such as inside a
- * toolbar. A vertical divider stretches to its flex parent rather than setting
- * a height of its own.
+ * toolbar. A vertical divider stretches to fit its flex parent and sets no
+ * height of its own.
  *
  * @since 0.1.0
  * @status stable
@@ -20,14 +19,14 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @aliases Separator, Rule
  * @documentation https://fusion.dev/helix/components/divider
  *
- * @slot - Content set into the rule, such as the word between two sections.
+ * @slot - Content set into the line, such as a word between two sections.
  *
- * @csspart content - What is set into it.
- * @csspart line - The rule itself, or each half of it where something is set in.
+ * @csspart content - The content set into the line.
+ * @csspart line - The line, or each half of it when content is set into it.
  */
 export declare class HelixHeadlessDivider extends HelixElement {
     /**
-     * Whether the rule is announced as a separator.
+     * Whether screen readers announce the line as a separator.
      *
      * Off by default, and out of the accessibility tree. Most rules on a page
      * separate nothing: they underline a heading or close a section that space
@@ -42,7 +41,7 @@ export declare class HelixHeadlessDivider extends HelixElement {
      */
     announced: boolean;
     /**
-     * Which way the rule runs.
+     * The direction the line runs: `horizontal` or `vertical`.
      */
     orientation?: 'horizontal' | 'vertical';
     /**

package/dist/donut-chart/root/donut-chart-root.d.ts

@@ -3,18 +3,17 @@ import { nothing, type TemplateResult } from 'lit';
 import '../../tooltip/index.js';
 declare const HelixHeadlessDonutChart_base: typeof HelixElement & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinChartSourceInterface);
 /**
- * @summary Parts of a whole as a ring, read from a table.
+ * @summary A chart that shows parts of a whole as a ring, read from a table.
  *
  * @description
- * The chart with the narrowest honest use, so the component is narrow too.
+ * A donut chart divides one whole into parts, so the component reads one
+ * column.
  *
- * **It reads one column and treats the rows as the parts.** Every other chart
- * here takes a column per series; a ring has one whole to divide, so the first
- * column of numbers is the series and each row is a slice.
+ * **The first column of numbers is the series, and each row is a slice.** Other
+ * Helix charts take one column per series.
  *
- * **It refuses negative values rather than drawing them.** An arc for a
- * negative number either runs backwards over its neighbors or is silently
- * dropped. Those rows are skipped and the total is of what is left.
+ * **Negative values are skipped.** An arc cannot show a negative number, so
+ * those rows are left out and the total is the sum of the remaining rows.
  *
  * @since 0.1.0
  * @status stable
@@ -22,28 +21,28 @@ declare const HelixHeadlessDonutChart_base: typeof HelixElement & (new (...args:
  * @aliases Pie Chart, Ring Chart, Share Chart
  * @documentation https://fusion.dev/helix/components/donut-chart
  *
- * @slot - Goes in the middle of the ring. A total, usually.
+ * @slot - Content in the middle of the ring, usually a total.
  *
  * @csspart center - The middle of the ring, holding whatever is slotted.
  * @csspart mark - The invisible point the tooltip is anchored to.
  * @csspart plot - The drawing.
  * @csspart segment - One slice.
- * @csspart segment-active - The slice under the pointer, beside `segment`.
- * @csspart segment-edge - One slice as a closed shape, for a boundary to trace.
+ * @csspart segment-active - The slice under the pointer. Set alongside `segment`.
+ * @csspart segment-edge - One slice as a closed shape, used to draw its outline.
  * @csspart tooltip - The bubble, forwarded from `Tooltip`.
  * @csspart tooltip-anchor - The `Tooltip` element itself.
  * @csspart tooltip-arrow - The bubble's point, forwarded from `Tooltip`.
- * @csspart tooltip-arrow-bottom - The point while the bubble is below the reading, so on its top edge, beside `tooltip-arrow`.
- * @csspart tooltip-arrow-left - The point while the bubble is left of the reading, so on its right edge, beside `tooltip-arrow`.
- * @csspart tooltip-arrow-right - The point while the bubble is right of the reading, so on its left edge, beside `tooltip-arrow`.
- * @csspart tooltip-arrow-top - The point while the bubble is above the reading, so on its bottom edge, beside `tooltip-arrow`.
- * @csspart tooltip-bottom - The bubble while it is below the reading, beside `tooltip`.
+ * @csspart tooltip-arrow-bottom - The point while the bubble is below the reading, on its top edge. Set alongside `tooltip-arrow`.
+ * @csspart tooltip-arrow-left - The point while the bubble is left of the reading, on its right edge. Set alongside `tooltip-arrow`.
+ * @csspart tooltip-arrow-right - The point while the bubble is right of the reading, on its left edge. Set alongside `tooltip-arrow`.
+ * @csspart tooltip-arrow-top - The point while the bubble is above the reading, on its bottom edge. Set alongside `tooltip-arrow`.
+ * @csspart tooltip-bottom - The bubble while it is below the reading. Set alongside `tooltip`.
  * @csspart tooltip-cell - One column's name and value inside the tooltip.
  * @csspart tooltip-label - The slice's own name inside the tooltip.
- * @csspart tooltip-left - The bubble while it is left of the reading, beside `tooltip`.
+ * @csspart tooltip-left - The bubble while it is left of the reading. Set alongside `tooltip`.
  * @csspart tooltip-name - A column's name inside the tooltip.
- * @csspart tooltip-right - The bubble while it is right of the reading, beside `tooltip`.
- * @csspart tooltip-top - The bubble while it is above the reading, beside `tooltip`.
+ * @csspart tooltip-right - The bubble while it is right of the reading. Set alongside `tooltip`.
+ * @csspart tooltip-top - The bubble while it is above the reading. Set alongside `tooltip`.
  * @csspart tooltip-value - A column's value inside the tooltip.
  * @csspart track - The ring the slices are drawn on.
  *
@@ -67,7 +66,7 @@ export declare class HelixHeadlessDonutChart extends HelixHeadlessDonutChart_bas
      */
     connectedCallback(): void;
     /**
-     * How much is left open in the middle.
+     * The size of the hole in the middle of the ring.
      *
      * Absent is a ring with room for a total in it. `small` and `large` move the
      * hole without moving the outer edge, so a chart keeps its footprint.