@fusion.dev/helix-headless 0.105.0 → 0.107.0

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

@@ -1,20 +1,22 @@
 import { HelixElement, SourceController } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 /**
- * @summary The names a chart draws, each beside the color it is drawn in.
+ * @summary A list of the series in a chart, each name beside the color it is drawn in.
  *
  * @description
- * A legend is a list, so it is a list: not part of a chart, and shared by
- * whichever of them needs one. It takes its entries from the same table the
- * chart reads, through `for`, so the two cannot disagree.
+ * Renders a legend as a list, separate from any chart, so any chart can use
+ * one. Set `for` to the table the chart reads, and the legend takes its entries
+ * from that table, so the two always match.
  *
- * `entries` picks which way to read that table. `series` is one entry per data
- * column, named by the header row, which is a line or a bar chart.
- * `categories` is one entry per body row, which is a donut: its slices are the
- * rows and it has no axis to write their names along. `measures` drops the
- * first data column, which is a scatter.
+ * `entries` sets how the table is read:
  *
- * **The table is resolved on the client and there is no server pass.**
+ * - `series`: one entry per data column, named by the header row. Use it for a
+ *   line or bar chart.
+ * - `categories`: one entry per body row. Use it for a donut, whose slices are
+ *   the rows and which has no axis to name them on.
+ * - `measures`: drops the first data column. Use it for a scatter.
+ *
+ * The table is resolved on the client. There is no server pass.
  *
  * @since 0.1.0
  * @status stable
@@ -22,16 +24,16 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @aliases Key, Series Key
  * @documentation https://fusion.dev/helix/components/legend
  *
- * @csspart entry - One name and its swatch. The swatch is drawn on the entry,
- * which is `::part(entry)::before` from a consumer's sheet: the series is
- * already on the entry as `--chart-series`, so a box would have carried nothing,
- * and this tier ships no CSS.
- * @csspart list - The list itself.
+ * @csspart entry - One name and its swatch. Draw the swatch with
+ * `::part(entry)::before` in your stylesheet. The entry holds its series color
+ * as `--chart-series`, and this tier ships no CSS.
+ * @csspart list - The list of entries.
  * @csspart name - One series name.
  */
 export declare class HelixHeadlessLegend extends HelixElement {
     /**
-     * Which way to read the table.
+     * How the entries are read from the table: `series`, `categories`, or
+     * `measures`.
      *
      * Absent is `series`, one entry per data column. `categories` reads one entry
      * per body row instead, for a donut, whose slices are the rows.

package/dist/lightbox/item/lightbox-item.d.ts

@@ -1,18 +1,16 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 /**
- * @summary One thing a lightbox can show.
+ * @summary One item a lightbox can show, such as a picture, a video frame, or a chart.
  *
  * @description
- * A wrapper around whatever the consumer opened, which is the whole of what it
- * is: a picture, a frame of video, a chart. The family shows one at a time and
- * this is how it says which, so the content stays the consumer's and the
- * arithmetic stays the root's.
+ * Wraps one piece of content in the lightbox, such as a picture, a video frame,
+ * or a chart. The lightbox shows one item at a time, and the root decides
+ * which.
  *
- * Hidden rather than unmounted while another item is current, for the reason
- * `TabPanel` gives: what is in the markup is what a crawler reads and what a
- * server sent, and an `<img>` that has already decoded does not decode again
- * when the reader walks back to it.
+ * An item that is not current is hidden and stays in the DOM, as a `TabPanel`
+ * does. Crawlers can read it, it is in the server-rendered markup, and an
+ * `<img>` that has decoded does not decode again when you go back to it.
  *
  * @since 0.100.0
  * @status stable
@@ -20,26 +18,26 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @aliases LightboxSlide, GalleryItem
  * @documentation https://fusion.dev/helix/components/lightbox
  *
- * @slot - What is being shown.
- * @slot description - A line under it saying what it is.
+ * @slot - The content to show.
+ * @slot description - A line under the content that describes it.
  *
  * @csspart item - The box the content is shown in.
  *
- * @cssstate current - While this is the item the lightbox is showing.
+ * @cssstate current - The item the lightbox is showing.
  */
 export declare class HelixHeadlessLightboxItem extends HelixElement {
     /**
-     * Whether this is the one being shown.
+     * Whether this item is the one shown.
      *
      * Written by the root, which is the only thing that sees the set.
      */
     current: boolean;
     /**
-     * What this item is called, for the reading that says where the reader is.
+     * The item's name, used in the status text that says which item is shown.
      */
     label: string;
     /**
-     * What names this item, and what `active` on the root is compared against.
+     * The item's identifier. The root compares its `active` value against it.
      */
     value: string;
     /**

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

@@ -2,33 +2,25 @@ import { CommandController, HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessLightbox_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerActiveInterface) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
 /**
- * @summary A viewer that opens one thing over the page.
+ * @summary A viewer that shows one item at a time over the page.
  *
  * @description
- * **A lightbox is chrome around a picture rather than a picture.** It draws
- * nothing of its own: what it shows is whatever the consumer opened, so this
- * earns its place on the frame, the keyboard and the reading that says where in
- * the set the reader is.
+ * The frame around content you open, such as a picture, a video frame, or a
+ * chart. The lightbox draws no content of its own. It provides the frame, the
+ * keyboard behavior, and text that states the current position in the set.
  *
- * **The modal half is the platform's.** A real `<dialog>` opened with
- * `showModal()` brings the top layer, a backdrop, Escape and `inert` behind it,
- * and this repository has already removed one hand-written focus trap for being
- * worse than that: `inert` on the rest of the document is something no
- * JavaScript trap can achieve. Every way it can close comes back through
- * `requestOpen`, which is what `Dialog` and `Drawer` both do and for the reason
- * they both give.
+ * The modal behavior comes from a native `<dialog>` opened with `showModal()`,
+ * which provides the top layer, a backdrop, Escape to close, and `inert` on the
+ * rest of the document. Every way of closing goes through `requestOpen`, as in
+ * `Dialog` and `Drawer`.
  *
- * **The set is this component's own and not `Carousel`'s.** A carousel is a
- * track: a scroller with snap points, per-view arithmetic and stops it can rest
- * between. A lightbox shows one thing at a time and has no track, so what it
- * needs is which item is current, which is `active` and the same pair `Tabs`
- * uses. The arrow keys move the picture under a reader whose focus stays in the
- * dialog, which is also why `KeyboardNavigationController` is not the right
- * tool: that one moves focus between focusable items, and these are pictures.
+ * A lightbox shows one item at a time and has no scrolling track, so `active`
+ * holds the current item, as in `Tabs`. The arrow keys change the item while
+ * focus stays in the dialog.
  *
- * **Chrome hides while the reader is still**, on `IdleController`, and comes
- * back on a pointer move or a focus. `fullscreen` is `FullscreenController`, the
- * same pair `Video` holds and the only two it shares.
+ * The chrome hides when there is no input, through `IdleController`, and comes
+ * back on a pointer move or a focus. `fullscreen` uses `FullscreenController`,
+ * as `Video` does.
  *
  * @since 0.100.0
  * @status stable
@@ -37,27 +29,28 @@ declare const HelixHeadlessLightbox_base: (new (...args: any[]) => import("@fusi
  * @documentation https://fusion.dev/helix/components/lightbox
  *
  * @slot - The items, which are `<helix-headless-lightbox-item>` elements.
- * @slot footer - Chrome below the item, such as a counter or a thumbnail strip.
- * @slot header - Chrome above the item, such as a title and a close button.
+ * @slot footer - Content below the item, such as a counter or a thumbnail strip.
+ * @slot header - Content above the item, such as a title and a close button.
  *
- * @event {Event} close - Relayed, because the platform's own does not escape.
- * @event {HelixActivateEvent} helix-activate - Fired once the shown item has moved, so the element already holds it.
- * @event {HelixBeforeActivateEvent} helix-before-activate - Fired before the shown item changes, and cancelable. The only way to refuse one.
- * @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} close - Fired when the viewer closes. The component dispatches it again from the host, because the dialog's own event does not leave the shadow root.
+ * @event {HelixActivateEvent} helix-activate - Fired after the shown item changes, when the element already holds the new item.
+ * @event {HelixBeforeActivateEvent} helix-before-activate - Fired before the shown item changes. Cancelable: cancel it to keep the current item. It is the only way to stop the change.
+ * @event {HelixBeforeCloseEvent} helix-before-close - Fired before the viewer closes. Cancelable.
+ * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the viewer opens. Cancelable.
+ * @event {Event} toggle - Fired when the viewer opens or closes, with `newState` and `oldState`.
  *
  * @csspart dialog - The native dialog element.
- * @csspart live - The region that says which item is shown.
+ * @csspart live - The live region that announces which item is shown.
  * @csspart viewport - The box the current item is shown in.
  *
  * @cssstate fullscreen - While the viewer fills the screen.
- * @cssstate idle - While the reader has been still long enough to hide the chrome.
+ * @cssstate idle - The user has been still long enough for the controls to hide.
  * @cssstate open - While the viewer is open.
  */
 export declare class HelixHeadlessLightbox extends HelixHeadlessLightbox_base {
     /**
-     * How long the reader may be still before the chrome hides, in milliseconds.
+     * How long the user can be idle before the header and footer hide, in
+     * milliseconds.
      *
      * Zero keeps it up, which is what a viewer with a caption worth reading
      * wants. The wait is only ever about idling: whether anything else should
@@ -65,16 +58,16 @@ export declare class HelixHeadlessLightbox extends HelixHeadlessLightbox_base {
      */
     idleDelay: number;
     /**
-     * Accessible name for the viewer.
+     * The viewer's name, read by screen readers.
      */
     label: string;
     /**
-     * Whether walking past the end comes back to the beginning.
+     * Whether moving past the last item returns to the first.
      */
     loop: boolean;
     /**
-     * The reading that says where in the set the reader is, with `{index}` and
-     * `{count}` filled in.
+     * The status text that says which item is shown, with `{index}` and `{count}`
+     * filled in.
      *
      * Announced rather than only drawn, because the picture changing under a
      * reader who cannot see it is otherwise silent. A consumer who has their own
@@ -102,13 +95,19 @@ export declare class HelixHeadlessLightbox extends HelixHeadlessLightbox_base {
     private get dialog();
     /** Opens the viewer, which makes the rest of the page inert. */
     show(): void;
-    /** Asks to close, which a consumer may refuse. */
+    /** Closes the viewer, unless a `helix-before-close` listener cancels it. */
     close(): void;
-    /** Shows the next item, or the first where it is past the end and looping. */
+    /**
+     * Shows the next item. After the last item, it shows the first when `loop`
+     * is set.
+     */
     next(): void;
-    /** Shows the previous item, or the last where it is past the start and looping. */
+    /**
+     * Shows the previous item. Before the first item, it shows the last when
+     * `loop` is set.
+     */
     previous(): void;
-    /** Fills the screen with the viewer, or comes back. */
+    /** Makes the viewer fill the screen, or exits fullscreen. */
     toggleFullscreen(): void;
     /**
      * Moves the shown item, through `requestActive` so a consumer can refuse.

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

@@ -3,37 +3,28 @@ import { nothing, type TemplateResult } from 'lit';
 import '../../tooltip/index.js';
 declare const HelixHeadlessLineChart_base: typeof HelixElement & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinChartSourceInterface);
 /**
- * @summary A series over time as a line, read from a table.
+ * @summary A chart that draws series over time as lines, read from a table.
  *
  * @description
- * The chart for a shape rather than for a quantity, which is what decides the
- * one thing a bar chart is not allowed to do.
+ * A line chart shows the shape of each series: where the readings went.
  *
- * **It measures from its own range and not from zero, deliberately.** `BarChart`
- * refuses that switch because a bar's length *is* its value, so a baseline
- * anywhere else makes the lengths proportional to nothing. A line claims no
- * such thing: it says where the readings went, and forcing zero into the range
- * of a series that moves between 980 and 1020 flattens the entire shape into a
- * rule across the top of the box. The two rules are opposite because the two
- * charts answer opposite questions, and `zero` is here for the case where the
- * distance from nothing is the point.
+ * The scale covers the range of the data. Including zero in the range of a
+ * series that moves between 980 and 1020 would flatten the line into a rule
+ * across the top of the box. `BarChart` always starts at zero, because a bar's
+ * length is its value. Set `zero` when the distance from zero is the point.
  *
- * **One scale across every series**, the same as the bar chart, because two
- * series drawn to different scales are two charts sharing a picture.
+ * Every series shares one scale, as in the bar chart.
  *
- * **Not the chart for a total made of parts.** `area` washes each series from
- * the floor on its own, so they overlap; `Area Chart` stacks them, so the top
- * edge is the total and each band is a share. A line chart answers how each
- * series moved, an area chart how the whole is made up.
+ * `area` fills each series down to the floor on its own, so the fills overlap.
+ * For a total made of parts, use `Area Chart`, which stacks the series so the
+ * top edge is the total and each band is a share.
  *
- * **The labels are HTML beside the drawing rather than `<text>` inside it**, for
- * the reason `BarChart` records: an `<svg>` that fills its box scales its type
- * with everything else, the same `font-size` arriving at 10px in a narrow chart
- * and 43px in a wide one, and there is no non-scaling-font to answer it the way
- * `vector-effect` answers strokes.
+ * The labels are HTML beside the drawing, as in `BarChart`. Text inside an
+ * `<svg>` that fills its box scales with the box, so the same `font-size` can
+ * render at 10px in a narrow chart and 43px in a wide one.
  *
- * The table is the accessible representation and this drawing is `aria-hidden`.
- * A reader who wants the numbers gets the numbers, not a described picture.
+ * The table is the accessible representation, and the drawing is `aria-hidden`.
+ * Screen reader users get the numbers.
  *
  * @since 0.1.0
  * @status stable
@@ -42,13 +33,13 @@ declare const HelixHeadlessLineChart_base: typeof HelixElement & (new (...args:
  * @documentation https://fusion.dev/helix/components/line-chart
  *
  * @csspart area - The wash under one line, where `area` is set.
- * @csspart band - The slot the pointer is resting in.
+ * @csspart band - The band around the reading under the pointer.
  * @csspart baseline - The rule at zero, where zero is inside the range.
  * @csspart gridline - One rule across the plot, under `gridlines`.
  * @csspart guide - A rule down the reading a pointer is resting on.
  * @csspart label - One reading's name.
  * @csspart labels - The row of reading names.
- * @csspart line - One series.
+ * @csspart line - The line for one series.
  * @csspart mark - The invisible point the tooltip is anchored to.
  * @csspart plot - The drawing.
  * @csspart svg - The drawing surface the lines and areas sit on.
@@ -74,8 +65,8 @@ declare const HelixHeadlessLineChart_base: typeof HelixElement & (new (...args:
  */
 export declare class HelixHeadlessLineChart extends HelixHeadlessLineChart_base {
     /**
-     * Whether a wash is drawn under each line, each from the floor on its own.
-     * The washes overlap rather than add up: for parts that make a total, use
+     * Draws a wash under each line, down to the floor of the plot. The washes
+     * overlap and do not add up, so for parts that make a total, use
      * `Area Chart`, which stacks them.
      *
      * Absent is lines alone, which is what suits more than one series: washes
@@ -174,7 +165,7 @@ export declare class HelixHeadlessLineChart extends HelixHeadlessLineChart_base
     /** The domain every series is drawn against, which the tooltip also needs. */
     private range;
     /**
-     * Whether zero is forced into the range.
+     * Whether the range always includes zero.
      *
      * Absent measures from the data's own extent, which is what a line is for.
      * Set it where the distance from nothing is the point rather than the shape,

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

@@ -4,26 +4,21 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
  * @summary One row of a list.
  *
  * @description
- * Layout and semantics, and deliberately not a target.
+ * Provides layout and semantics. The row is a target only when you set `href`.
  *
- * **`href` makes the row itself the link.** A whole-row target needs the anchor
- * to wrap the layout, which a *consumer's* anchor cannot do for slots it does not
- * own. The component's can: an `<a part="row">` wraps this component's own layout
- * perfectly well, which is what `Tree.Item` does.
+ * **`href` makes the whole row a link.** The component wraps its own layout in
+ * an `<a part="row">`, as `Tree.Item` does. An anchor of your own cannot wrap
+ * slots it does not own. With the anchor, the whole row is a target, Enter
+ * follows it, middle click opens a new tab, the status bar shows the
+ * destination, and all of it works before JavaScript runs.
  *
- * What the anchor buys is what the row could not fake: the whole row is a
- * target, Enter follows it, middle click opens a tab, the status bar shows the
- * destination, and it all works before any JavaScript runs.
+ * Client-side routing needs your own handling. A router cannot render its
+ * anchor inside the shadow root, so to navigate without a page load, intercept
+ * the click: the anchor is in `composedPath()`. Handle only a plain primary
+ * click, so native gestures keep working.
  *
- * What it costs is client-side routing, and that is the consumer's to restore.
- * A router renders its own anchor and cannot render one inside this shadow
- * root, so a framework wanting a soft navigation intercepts the click on the
- * way out: the anchor is in `composedPath()`, and taking only a plain primary
- * press leaves every native gesture alone.
- *
- * **`data-list-item` is still the answer for a row that is not a destination.**
- * A list row is often a container of controls rather than a place to go, and a
- * row with `href` unset behaves exactly as it always did.
+ * **For a row that holds controls and is not a destination, use
+ * `data-list-item`.** With `href` unset, the row is not a link.
  *
  * @since 0.1.0
  * @status stable
@@ -35,11 +30,11 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
  * @slot end - Trailing content.
  * @slot start - Leading content, usually an icon or an avatar.
  *
- * @csspart row - The layout, held off the host so the host can carry a marker.
+ * @csspart row - The row's layout. It sits inside the host so the host can carry a list marker.
  */
 export declare class HelixHeadlessListItem extends HelixElement {
     /**
-     * Where the row goes, and nothing when it goes nowhere.
+     * The URL the row links to. Leave it empty for a row that is not a link.
      *
      * Empty rather than optional, and unset by default: a list is not always a
      * list of links, and an empty `href` written onto every row would be a link
@@ -47,12 +42,12 @@ export declare class HelixHeadlessListItem extends HelixElement {
      */
     href: string;
     /**
-     * What the link declares about where it goes. The consumer's decision rather
-     * than one derived from `target`, for the reason `Tree.Item` gives.
+     * The link's `rel` value. You set it yourself. It is not derived from
+     * `target`, for the reason `Tree.Item` gives.
      */
     rel: string;
     /**
-     * Where the link opens, for the rare row that leaves the site.
+     * Where the link opens. Use it for a row that leaves the site.
      */
     target: string;
     protected willUpdate(changed: PropertyValues): void;

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

@@ -1,12 +1,11 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 /**
- * @summary A set of rows, read as a set.
+ * @summary A set of rows, announced as a list.
  *
  * @description
- * `role="list"` on the host, so the rows are counted and announced as "1 of 7"
- * rather than as seven unrelated passages. That count is the whole reason to
- * use a list rather than a stack of divs.
+ * Sets `role="list"` on the host, so a screen reader counts the rows and
+ * announces each one's position, such as "1 of 7".
  *
  * @since 0.1.0
  * @status stable
@@ -18,7 +17,7 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  */
 export declare class HelixHeadlessList extends HelixElement {
     /**
-     * What kind of list this is, which is a fact about the content.
+     * The kind of list, which follows from the content.
      *
      * On the headless tier because it is meaning rather than decoration, the same
      * argument `severity` makes on `Callout`. A numbered list is numbered because
@@ -41,11 +40,11 @@ export declare class HelixHeadlessList extends HelixElement {
      */
     kind?: 'default' | 'description' | 'ordered' | 'unordered';
     /**
-     * Accessible name for the set.
+     * The list's name, read by screen readers.
      */
     label: string;
     /**
-     * Which markers an ordered list draws, in `<ol type>`'s own five values.
+     * The markers an ordered list draws. It takes the five values of `<ol type>`.
      *
      * Reflected, because this is one of the things a stylesheet selects on, each
      * value mapping to a `list-style-type`. The platform's spellings rather than