@fusion.dev/helix-headless 0.104.1 → 0.106.0

package/dist/skip-link/root/skip-link-root.d.ts

@@ -1,35 +1,28 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type TemplateResult } from 'lit';
 /**
- * @summary The first stop on a page, which moves the reader past everything
- * repeated on every page.
+ * @summary A link at the start of a page that moves keyboard focus past the
+ * header to the main content.
  *
  * @description
- * A keyboard reader arriving on a page tabs through the whole header before
- * reaching anything the page is about, and does it again on the next page. This
- * is the control that skips it: first in the document, and pointed at the
- * content.
+ * Without a skip link, keyboard users tab through the whole header on every
+ * page before they reach the content. The skip link goes first in the document
+ * and points at the content.
  *
- * **It moves focus, not only the scroll position.** An in-page link on its own
- * scrolls to its target and leaves focus behind, so the next Tab goes to
- * whatever followed the link, which is the header it was meant to skip. Pressed,
- * this focuses the target. A target that cannot take focus, which is most of
- * them, since `<main>` cannot, is given `tabindex="-1"` for as long as it holds
- * focus and has it taken off again when focus leaves, so the page ends up as the
- * consumer wrote it.
+ * Pressing it moves focus as well as the scroll position. An in-page link alone
+ * scrolls but leaves focus behind, so the next Tab lands in the header. A
+ * target that cannot take focus, such as `<main>`, gets `tabindex="-1"` while
+ * it has focus, and the attribute is removed when focus leaves.
  *
- * **The address is left alone.** The press is handled rather than followed, so
- * no `#main` lands in the URL and no history entry is added, which matters to a
- * router reading the hash. The anchor is still a real anchor with a real
- * `href`, so before any script has run the link does what a plain link does:
- * it scrolls there and moves the point the next Tab starts from.
+ * The press is handled in script, so no `#main` is added to the URL and no
+ * history entry is created, and a router that reads the hash is not affected.
+ * The anchor has a real `href`, so before any script runs it works as a plain
+ * link: it scrolls to the target and moves the point the next Tab starts from.
  *
- * **Hidden until focused is the styled tier's**, being a decision about paint,
- * and on this tier the link is simply a link. A headless consumer hides
- * `::part(link)` while the host is not `:focus-within` and shows it when it is.
- * Hiding with `display: none` or `visibility: hidden` takes it out of the tab
- * order as well, and a skip link nobody can reach is the most common way one is
- * broken.
+ * The styled tier hides the link until it has focus. On this tier the link is
+ * always visible. To hide it yourself, hide `::part(link)` while the host is
+ * not `:focus-within`. Do not use `display: none` or `visibility: hidden`,
+ * because they also remove the link from the tab order.
  *
  * @since 0.1.0
  * @status stable
@@ -37,15 +30,15 @@ import { type TemplateResult } from 'lit';
  * @aliases Skip navigation, Skip to content
  * @documentation https://fusion.dev/helix/components/skip-link
  *
- * @slot - The link's words. Falls back to `label`.
+ * @slot - The link's text. Defaults to `label`.
  *
- * @csspart link - The anchor, which is what takes focus.
+ * @csspart link - The anchor. It takes the focus.
  */
 export declare class HelixHeadlessSkipLink extends HelixElement {
     /** Focus goes to the anchor inside, so the host is never the focus target. */
     static shadowRootOptions: ShadowRootInit;
     /**
-     * Where the reader is sent, as an in-page fragment.
+     * The in-page fragment the link moves focus to, such as `#main`.
      *
      * `#main` by default, because that is the id the content region almost always
      * has; a page whose content is somewhere else says so. Anything that is not a
@@ -54,7 +47,7 @@ export declare class HelixHeadlessSkipLink extends HelixElement {
      */
     href: string;
     /**
-     * The link's words, for the common case of plain text.
+     * The link's text, when it is plain text.
      *
      * The fallback of the default slot, so slotted content replaces it rather than
      * appearing beside it.

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

@@ -5,30 +5,27 @@ declare const HelixHeadlessSlider_base: (new (...args: any[]) => import("@fusion
  * @summary A value chosen from a range by dragging.
  *
  * @description
- * A real `<input type="range">`, so the drag, the arrow keys, Home and End, the
- * page keys and the touch target are the platform's. The last is the one nobody
- * notices: a native range has a hit area larger than its thumb, sized by the
- * platform for a finger.
+ * Renders a native `<input type="range">`, so the drag, the arrow keys, Home,
+ * End, the page keys, and the touch target come from the platform. A native
+ * range has a hit area larger than its thumb, sized for a finger.
  *
- * **The value is a string, like every other form control's.** A range submits
- * text and `MixinControllerValue` holds text, so the number is a reading of the
- * value. `valueAsNumber` is there for arithmetic.
+ * The value is a string, like every other form control's, and
+ * `MixinControllerValue` holds text. Use `valueAsNumber` for arithmetic.
  *
- * **Marks are drawn rather than left to `<datalist>`**, whose ticks cannot be
- * styled and which Firefox does not render for a range at all. A mark is
- * decoration; what a reader can land on is `step`, which the input enforces
- * whether or not anything is drawn. `markers` is a count rather than a flag, so
- * a slider from zero to a hundred cannot silently ask for a hundred and one.
+ * Marks are drawn by the component. The ticks of a `<datalist>` cannot be
+ * styled, and Firefox does not render them for a range. Marks are decoration.
+ * `step` sets where the value can land, and the input enforces it whether or
+ * not marks are drawn. `markers` is a count, so a slider from zero to a hundred
+ * does not draw a hundred and one marks by accident.
  *
- * **A range is two of them.** There is no native two-thumb range, so two are
- * stacked on one track and each thumb keeps its own.
+ * A range with two thumbs is two inputs stacked on one track, because there is
+ * no native two-thumb range. Each thumb keeps its own value.
  *
- * **`required` arrives with the field mixin and cannot fail here**, which is
- * worth saying rather than leaving a reader to find. A range is never empty:
- * the platform shows its own midpoint whatever is set, and `willUpdate` seeds
- * that midpoint into `defaultValue` so the value agrees with the handle from the
- * first render. HTML does not apply `required` to a range either, so it stays
- * off the control and the marker beside the label is all it does.
+ * `required` comes with the field mixin and cannot fail. A range is never
+ * empty: the platform shows its midpoint when no value is set, and `willUpdate`
+ * seeds that midpoint into `defaultValue`, so the value matches the handle from
+ * the first render. HTML does not apply `required` to a range either, so it is
+ * not set on the input. It only adds the marker beside the label.
  *
  * @since 0.1.0
  * @status stable
@@ -36,33 +33,33 @@ declare const HelixHeadlessSlider_base: (new (...args: any[]) => import("@fusion
  * @aliases Range, Range input
  * @documentation https://fusion.dev/helix/components/slider
  *
- * @event {Event} change - Relayed once the reader has let go.
- * @event {HelixBeforeChangeEvent} helix-before-change - Fired as the value changes, and cancelable.
- * @event {Event} input - Announced once the value has moved.
+ * @event {Event} change - Fired when the user releases the thumb.
+ * @event {HelixBeforeChangeEvent} helix-before-change - Fired as the value changes. Cancelable: call `preventDefault()` to keep the current value.
+ * @event {Event} input - Fired after the value changes.
  *
  * @csspart control - The range input.
- * @csspart feedback - What is wrong with it.
- * @csspart field - The row: the control and its readout.
- * @csspart hint - Help under the track, while nothing is wrong.
- * @csspart label - The question, over the track.
- * @csspart marker - One mark.
+ * @csspart feedback - The error message under the track.
+ * @csspart field - The row that holds the control and its readout.
+ * @csspart hint - The help text under the track, shown while there is no error.
+ * @csspart label - The label above the track.
+ * @csspart marker - One mark on the track.
  * @csspart marker-label - The value a mark stands at, when `marker-labels` is set.
  * @csspart markers - The row of marks along the track.
- * @csspart output - The current value, shown beside it.
+ * @csspart output - The current value, shown beside the track.
  *
  * @cssproperty --slider-fraction - The value as a fraction of the range, 0 to 1.
  * @cssproperty --slider-from - Where a range's filled span starts, as a fraction of the track, 0 to 1.
  * @cssproperty --slider-marker-at - Where one marker sits, as a percentage of the track.
  * @cssproperty --slider-to - Where a range's filled span ends, as a fraction of the track, 0 to 1.
  *
- * @cssstate invalid - While there is feedback to show: the platform's verdict, or the consumer's `feedback`.
+ * @cssstate invalid - The slider has an error to show, from the browser's validation or from your `feedback`.
  */
 export declare class HelixHeadlessSlider extends HelixHeadlessSlider_base {
     protected readonly aria: AriaForwardController;
     /** Typed or dragged, so every edit is announced. See `announcesInput`. */
     protected readonly announcesInput = true;
     /**
-     * Whether each mark says which value it stands at.
+     * Shows the value at each mark.
      */
     markerLabels: boolean;
     /**
@@ -82,11 +79,11 @@ export declare class HelixHeadlessSlider extends HelixHeadlessSlider_base {
      */
     markers: number;
     /**
-     * The largest value the reader can choose.
+     * The largest value that can be chosen.
      */
     max: number;
     /**
-     * What the upper thumb of a range is called, after the slider's own label.
+     * The name of a range's upper thumb, read after the slider's label.
      *
      * **Named with the label rather than instead of it.** Each thumb was
      * `aria-label="${label} maximum"`, which overrode the `<label>` and read the
@@ -96,13 +93,13 @@ export declare class HelixHeadlessSlider extends HelixHeadlessSlider_base {
      */
     maximumLabel: string;
     /**
-     * The smallest value the reader can choose.
+     * The smallest value that can be chosen.
      */
     min: number;
-    /** What the lower thumb of a range is called, after the slider's own label. */
+    /** The name of a range's lower thumb, read after the slider's label. */
     minimumLabel: string;
     /**
-     * Which way the track runs, `vertical` standing it on end.
+     * The direction the track runs. `vertical` stands it on end.
      *
      * For a level rather than a quantity: a fader, a channel, anything a reader
      * pictures as high and low rather than as less and more. Absent is
@@ -115,7 +112,7 @@ export declare class HelixHeadlessSlider extends HelixHeadlessSlider_base {
      */
     orientation?: 'horizontal' | 'vertical';
     /**
-     * Whether there are two thumbs and the value is a pair.
+     * Adds a second thumb, so the value is a pair.
      *
      * The pair is one string, `"10,50"`, which is what a form submits and what
      * `MixinControllerValue` already holds. `valueAsNumber` reads the lower of
@@ -123,7 +120,7 @@ export declare class HelixHeadlessSlider extends HelixHeadlessSlider_base {
      */
     range: boolean;
     /**
-     * Whether the chosen value is shown beside the track.
+     * Shows the chosen value beside the track.
      */
     showValue: boolean;
     /**
@@ -214,7 +211,7 @@ export declare class HelixHeadlessSlider extends HelixHeadlessSlider_base {
     private snapped;
     protected willUpdate(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
-    /** How far one press of an arrow key moves it. */
+    /** How far one press of an arrow key moves the thumb. */
     step: number;
     protected render(): TemplateResult;
 }

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

@@ -1,35 +1,29 @@
 import { type Curve, HelixElement, SourceController } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 /**
- * @summary A line with no axes, for the shape of a series beside the number it belongs to.
+ * @summary A small chart with no axes that shows the shape of a series beside its number.
  *
  * @description
- * The one chart here that takes its numbers from an attribute, and the reversal
- * is deliberate. Every other chart reads a table because a reader might want to
- * interrogate it; nobody interrogates the squiggle next to a figure. A
- * fourteen-row table behind a bare trend line is fourteen dates read aloud in
- * place of the one sentence that carries the meaning, so `values` is the list
- * and `label` is the sentence.
+ * Takes its numbers from the `values` attribute. The other charts read a table,
+ * but a table behind a small trend line would be read aloud row by row. Set
+ * `values` to the data and `label` to the one sentence a screen reader
+ * announces.
  *
- * That is the library's own rule rather than a second data channel: a content
- * property is its slot's fallback, which is why `Tooltip` takes `content` and
- * `Avatar` takes `name`. `for` stays for the sparkline that genuinely has a
- * table behind it, and it wins where both are given.
+ * This follows the library's rule that a content property is the fallback for
+ * its slot, as with `Tooltip`'s `content` and `Avatar`'s `name`. Use `for` when
+ * a sparkline has a real table behind it. `for` wins when both are set.
  *
- * **No label means decorative, and that is a choice rather than an oversight.**
- * A sparkline beside a stat that already says "Sessions, 1,102" has nothing of
- * its own to announce, and an unnamed `role="img"` announces "graphic" and
- * stops. So an unlabeled sparkline is `aria-hidden`, and a labeled one is an
- * image named by its sentence.
+ * Without a `label` the sparkline is decorative and `aria-hidden`, for example
+ * beside a stat that already says "Sessions, 1,102". With a `label` it is an
+ * image named by that sentence.
  *
- * It goes *beside* a `Stat` rather than inside one: a change beside a figure is
- * a second fact, which is what `Stat`'s own spec says. `Trend` composes the same
- * way.
+ * Place it beside a `Stat`, because a change beside a figure is a second fact,
+ * as `Stat`'s own spec says. `Trend` is composed the same way.
  *
- * 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 component writes the properties listed below, and the stylesheet that
+ * draws the sparkline reads them. Do not set them yourself. They carry numbers
+ * the component computes and CSS cannot, so a stylesheet can draw the sparkline
+ * without measuring anything.
  *
  * @since 0.1.0
  * @status stable
@@ -38,8 +32,8 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @documentation https://fusion.dev/helix/components/sparkline
  *
  * @csspart area - The region between the line and the bottom of its range.
- * @csspart bar - One column, under `plot="bar"`.
- * @csspart line - The path itself.
+ * @csspart bar - One column, drawn when `plot="bar"`.
+ * @csspart line - The line's path.
  * @csspart svg - The drawing.
  * @csspart terminus - The mark on the last value.
  * @csspart wash-end - The far stop of the area's gradient.
@@ -50,7 +44,7 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  */
 export declare class HelixHeadlessSparkline extends HelixElement {
     /**
-     * How the line gets from one reading to the next.
+     * How the line is drawn from one reading to the next.
      *
      * **`smooth` is the resting curve.** A straight segment asserts nothing about
      * the values between two readings and a curve invents them, which is why
@@ -79,7 +73,7 @@ export declare class HelixHeadlessSparkline extends HelixElement {
      */
     curve?: Curve;
     /**
-     * The id of a table to read instead, when there is one behind the line.
+     * The id of a table to read the readings from, when a table holds the data.
      *
      * The first column of numbers is the series drawn. This wins over `values`,
      * because a table is the readable representation and a list of numbers in an
@@ -90,7 +84,7 @@ export declare class HelixHeadlessSparkline extends HelixElement {
      */
     for: string;
     /**
-     * What the line says, in a sentence.
+     * A sentence that describes what the line shows.
      *
      * "Sessions rose from 1,240 to 1,318 and fell to 1,102 over fourteen days" is
      * the accessible representation of a sparkline, and a list of the fourteen

package/dist/speed-dial/item/speed-dial-item.d.ts

@@ -1,19 +1,16 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type TemplateResult } from 'lit';
 /**
- * @summary One action in a speed dial: a mark, and a name beside it.
+ * @summary One action in a speed dial: an icon and a name beside it.
  *
  * @description
- * **A command, which is why this is a `menuitem` and a megamenu's rows are not.**
- * The distinction is what the thing does, not what it looks like: a megamenu
- * holds destinations, so it is a disclosure of links, and this holds actions a
- * screen can take, which is exactly what `role="menu"` was written for. The
- * roles follow the contents.
+ * Each item is a command, so it has the `menuitem` role. A megamenu holds
+ * destinations, so it is a disclosure of links. A speed dial holds actions,
+ * which is what `role="menu"` is for.
  *
- * **The name is text, not a title.** A dial's actions are icons, and an icon
- * with a `title` is an action whose name only exists for whoever hovers it long
- * enough. The label is rendered beside the mark and is the accessible name by
- * being there, so it is read, searched and translated like anything else.
+ * The name is text rendered beside the icon, and it is the accessible name. A
+ * `title` on an icon shows only on hover. Visible text is read, searched, and
+ * translated like other text.
  *
  * @since 0.1.0
  * @status stable
@@ -22,21 +19,21 @@ import { type TemplateResult } from 'lit';
  * @documentation https://fusion.dev/helix/components/speed-dial
  *
  * @slot - The action's name.
- * @slot icon - The mark, which is what a dial is read by.
+ * @slot icon - The action's icon, the main way the action is recognized.
  *
- * @event {HelixSelectEvent} helix-select - Fired when the action is chosen. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixSelectEvent} helix-select - The action was chosen. Cancelable: cancel it to keep the dial open.
  *
- * @csspart icon - The mark's box.
- * @csspart item - The control.
- * @csspart label - The name beside it.
+ * @csspart icon - The box that holds the icon.
+ * @csspart item - The control for the action.
+ * @csspart label - The action's name, beside the icon.
  */
 export declare class HelixHeadlessSpeedDialItem extends HelixElement {
     /**
-     * Whether the action can be chosen.
+     * Whether the action is disabled, so it cannot be chosen.
      */
     disabled: boolean;
     /**
-     * What this action stands for, carried in the event when it is chosen.
+     * The action's value, sent in `helix-select` when the action is chosen.
      */
     value: string;
     /**
@@ -45,14 +42,17 @@ export declare class HelixHeadlessSpeedDialItem extends HelixElement {
      * protected. Not a consumer's to read or set.
      */
     readonly isSpeedDialItem = true;
-    /** Puts focus on the control inside, which is what a reader can reach. */
+    /** Puts focus on the control inside the item. */
     focus(): void;
-    /** `NavigableItem`, so the arrow keys are the shared controller's business. */
+    /**
+     * Moves focus to the action. Part of `NavigableItem`, which the shared
+     * keyboard controller uses for the arrow keys.
+     */
     focusItem(): void;
-    /** Chooses the action, which is the same act as pressing it. */
+    /** Chooses the action, the same as pressing it. */
     select(): void;
     /**
-     * Whether this is the row the set is on, which here is where focus is.
+     * Whether the action has focus, which is what selected means in a speed dial.
      *
      * Asked of the document rather than of the shadow root: focus lands on the
      * control inside this element and the platform retargets it, so from outside

package/dist/speed-dial/root/speed-dial-root.d.ts

@@ -2,29 +2,26 @@ import { HelixElement, KeyboardNavigationController, type Placement, PopoverCont
 import { type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessSpeedDial_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
 /**
- * @summary A button that fans out the few actions a screen is for.
+ * @summary A floating button that opens a short list of the main actions on a screen.
  *
  * @description
- * **A menu, and deliberately not a new one.** Its rows are commands, which is
- * what `role="menu"` and `menuitem` exist for, so this takes them and takes the
- * behavior with them: the arrow keys are `KeyboardNavigationController`, the
- * panel is `PopoverController`, and open and closed is `MixinControllerOpen`.
- * `Menu` is built from the same pieces. What is not shared is what actually
- * differs: a dial has no submenus, no headers, no checkable rows and no long
- * list to type ahead through, and shipping it as an appearance of `Menu` would
- * mean defining what a dial with a submenu in it does.
+ * A speed dial is a menu. Its items are commands, so it uses `role="menu"` and
+ * `menuitem`, and it is built from the same pieces as `Menu`:
+ * - `KeyboardNavigationController` for the arrow keys
+ * - `PopoverController` for the panel
+ * - `MixinControllerOpen` for open and closed
  *
- * **The trigger is a control the consumer slots**, and the floating action
- * button is the usual one: `IconButton` with `shape="circle"` and `raised`.
- * There is no `helix-fab`, because it would re-declare `emphasis`, `tone`,
- * `label` and a size around a control that already has all four. A round raised
- * button is a shape, and where it sits is `data-dock` in the base layer.
+ * It is a separate component because a speed dial has no submenus, headers,
+ * checkable items, or type-ahead.
  *
- * **Nothing is reserved from the keyboard.** A menu that drills has to keep the
- * horizontal pair for going in and coming back; a dial goes nowhere, so all four
- * arrows move through the actions and a reader who guesses either axis is
- * answered. That is the controller's own house position, and this is a component
- * with no reason to argue with it.
+ * You slot the trigger. The usual floating action button is `IconButton` with
+ * `shape="circle"` and `raised`. There is no `helix-fab`, because `IconButton`
+ * already has `emphasis`, `tone`, `label`, and a size. Position the button with
+ * `data-dock` in the base layer.
+ *
+ * All four arrow keys move through the actions, because a speed dial has no
+ * nested levels to reserve the horizontal pair for. This is the default
+ * behavior of the keyboard controller.
  *
  * @since 0.1.0
  * @status stable
@@ -33,21 +30,21 @@ declare const HelixHeadlessSpeedDial_base: (new (...args: any[]) => import("@fus
  * @documentation https://fusion.dev/helix/components/speed-dial
  *
  * @slot - The actions.
- * @slot trigger - The control that opens it. Falls back to a button named by `label`.
+ * @slot trigger - The control that opens the actions. Without one, a button named by `label` is drawn.
  *
- * @event {HelixBeforeCloseEvent} helix-before-close - Fired before it closes, and cancelable.
- * @event {HelixBeforeOpenEvent} helix-before-open - Fired before it opens, and cancelable.
- * @event {HelixSelectEvent} helix-select - Fired when an action is chosen. Dispatched by the action and listened for here, and the dial closes behind it once it has been heard. Cancelable: refusing it takes the decision and the dial stays open.
- * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
+ * @event {HelixBeforeCloseEvent} helix-before-close - The actions are about to close. Cancelable: cancel it to keep them open.
+ * @event {HelixBeforeOpenEvent} helix-before-open - The actions are about to open. Cancelable: cancel it to keep them closed.
+ * @event {HelixSelectEvent} helix-select - An action was chosen. The action sends the event, and the dial closes after it. Cancelable: cancel it to keep the dial open.
+ * @event {Event} toggle - The dial opened or closed. The event carries `newState` and `oldState`.
  *
  * @csspart actions - The region the actions are drawn in.
- * @csspart trigger - The default trigger, where none was slotted.
+ * @csspart trigger - The default trigger, drawn when none is slotted.
  *
  * @cssstate open - While the actions are out.
  */
 export declare class HelixHeadlessSpeedDial extends HelixHeadlessSpeedDial_base {
     /**
-     * Names the trigger and the set of actions it opens.
+     * Accessible name for the trigger and the set of actions it opens.
      */
     label: string;
     /**
@@ -55,7 +52,8 @@ export declare class HelixHeadlessSpeedDial extends HelixHeadlessSpeedDial_base
      */
     offset: number;
     /**
-     * Which way the actions fan out. They move if that side does not fit.
+     * The direction the actions open in. They move to another side if that side
+     * does not fit.
      *
      * Up by default, because the control this hangs off is usually docked to the
      * bottom of the window and there is nothing below it to fan into.