@fusion.dev/helix-headless 0.105.0 → 0.106.0

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

@@ -5,38 +5,38 @@ declare const HelixHeadlessAccordionItem_base: (new (...args: any[]) => import("
  * @summary One collapsible section of an accordion.
  *
  * @description
- * Carries its own open state, which is why it is an element rather than a slot.
- * Used alone, outside an accordion, it is a disclosure.
+ * Holds its own open state. Used alone, outside an accordion, it works as a
+ * disclosure.
  *
- * Content stays mounted when closed, so it can animate and so the text is
- * present in server-rendered HTML. Closed content carries both `hidden` and
- * `inert`: the first collapses it with no stylesheet in play, the second keeps
- * it out of the tab order and the accessibility tree once the styled tier's
- * `display` has overridden the first.
+ * Content stays mounted when the item is closed, so it can animate and its text
+ * is present in server-rendered HTML. Closed content has both `hidden` and
+ * `inert`. `hidden` collapses it when no stylesheet is loaded. `inert` keeps it
+ * out of the tab order and the accessibility tree after the styled tier's
+ * `display` overrides `hidden`.
  *
  * @since 0.1.0
  * @status stable
  * @aliases Collapsible, Expander, Disclosure
  * @documentation https://fusion.dev/helix/components/accordion
  *
- * @slot - The content revealed when open.
- * @slot summary - The always-visible trigger content.
+ * @slot - The content shown when the section is open.
+ * @slot summary - The text of the button that opens and closes the section. Always shown.
  *
- * @event {HelixBeforeCloseEvent} helix-before-close - Fired before the section closes, and cancelable.
- * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the section opens. Cancelable: refusing it takes the decision and nothing moves.
- * @event {Event} toggle - Says the state moved, carrying `newState` and `oldState`.
+ * @event {HelixBeforeCloseEvent} helix-before-close - The section is about to close. Cancelable: cancel it to keep it open.
+ * @event {HelixBeforeOpenEvent} helix-before-open - The section is about to open. Cancelable: cancel it to keep it closed.
+ * @event {Event} toggle - The section opened or closed. The event carries `newState` and `oldState`.
  *
  * @csspart chevron - The open and close indicator.
  * @csspart container - The outer wrapper.
- * @csspart content - The revealed region.
+ * @csspart content - The region that holds the content.
  * @csspart content-inner - The clipping box inside the animated region.
- * @csspart trigger - The clickable summary row.
+ * @csspart trigger - The button that opens and closes the section, holding the summary.
  *
  * @cssstate open - While the item is open.
  */
 export declare class HelixHeadlessAccordionItem extends HelixHeadlessAccordionItem_base {
     /**
-     * Where the open indicator sits, or whether there is one.
+     * Where the chevron sits, or `none` for no chevron.
      *
      * `auto` resolves to `end`, which is where a reader scanning a list of
      * summaries expects it: the label starts at the same x on every row, and the
@@ -49,7 +49,8 @@ export declare class HelixHeadlessAccordionItem extends HelixHeadlessAccordionIt
     /** The chevron, or nothing when suppressed. */
     private renderChevron;
     /**
-     * A group name, which is how `<details>` says a set is exclusive.
+     * A group name. Opening an item closes the other items with the same name,
+     * as `<details name>` does.
      *
      * **Two ways of saying the same thing, and the platform's one does not need a
      * parent.** An accordion's `mode` makes its own children exclusive, which

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

@@ -2,27 +2,23 @@ import { HelixElement, KeyboardNavigationController } from '@fusion.dev/helix-co
 import { type TemplateResult } from 'lit';
 import { HelixHeadlessAccordionItem } from '../item/accordion-item.js';
 /**
- * @summary Groups collapsible sections, one open at a time by default.
+ * @summary A group of collapsible sections.
  *
  * @description
- * Holds the mode and nothing else. The item that was clicked is what
- * coordinates: it walks up to the nearest accordion, reads the mode off it, and
- * closes its peers itself.
+ * Holds the mode. Each item coordinates itself: when you click an item, it
+ * finds the nearest accordion, reads the mode, and closes the other items.
  *
- * Coordination is structural, not a subscription. `helix-before-open` does not bubble
- * and is not composed, because overlays nest and an inner one's lifecycle must
- * never read as the outer one's, so an accordion cannot learn that a child
- * opened by listening for it.
+ * The accordion does not listen for items opening. `helix-before-open` does not
+ * bubble and is not composed, because overlays nest and an inner overlay's
+ * events must stay separate from the outer one's.
  *
- * Membership resolves on demand, so there is no registry to keep in step: an
- * item added a second after render coordinates on its first click.
+ * Items are found when they are clicked, so there is no registry to keep up to
+ * date. An item added after render coordinates on its first click. Items are
+ * matched with `instanceof HelixHeadlessAccordionItem`, so the headless tier
+ * does not depend on the styled tier's tag names.
  *
- * Items are matched with `instanceof HelixHeadlessAccordionItem`, never by tag
- * name, so this tier does not learn about the styled one.
- *
- * The keyboard listener is the controller's and is attached on connect, so
- * none of it runs on the server, where there is no tree to walk and no events
- * to hear.
+ * The keyboard listener belongs to the controller and is attached on connect,
+ * so it does not run on the server.
  *
  * @since 0.1.0
  * @status stable
@@ -44,7 +40,7 @@ export declare class HelixHeadlessAccordion extends HelixElement {
      * `collapsible` alongside `multiple` expressible and meaningless.
      */
     mode?: 'single' | 'single-collapsible';
-    /** Direct items, in light-DOM order. Client only: the server has no tree. */
+    /** The accordion's own items, in the order they are written. Browser only. */
     get items(): HelixHeadlessAccordionItem[];
     protected readonly keys: KeyboardNavigationController;
     protected render(): TemplateResult;

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

@@ -2,33 +2,26 @@ import { ArrivalController, HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessAnnouncement_base: (new (...args: any[]) => import("@fusion.dev/helix-core").DismissibleElement) & typeof HelixElement;
 /**
- * @summary A page-level message above the masthead, which can be dismissed.
+ * @summary A message for the whole page, shown above its header, that can be dismissed.
  *
  * @description
- * Chrome rather than content. An announcement sits above the header and speaks
- * for the whole page: a trial ending, a service degraded, a change of terms. A
- * passage that interrupts a document to set itself apart is a `Callout`, which
- * is read where it sits and cannot be dismissed. Neither is a variant of the
- * other.
+ * An announcement is a banner above the page header with news about the whole
+ * site or session, such as a trial ending, a degraded service, or a change of
+ * terms. For a passage inside a document, use `Callout`, which stays where it
+ * is placed and cannot be dismissed.
  *
- * **Always a polite live region.** `role="alert"` is assertive and interrupts
- * whatever is being read, which is right for something that appears mid-session
- * and wrong for something that was in the served HTML: an assertive
- * announcement would cut across a screen-reader user on every page load, before
- * they had read anything. Politeness costs a moment and is never wrong; the tone
- * does not change that, because an error that was always there is still not an
- * interruption.
+ * The announcement is always a polite live region, whatever its `tone`.
+ * `role="alert"` is assertive and interrupts a screen reader, so an
+ * announcement served with the page would interrupt on every page load.
  *
- * **The region is its own, and there before its words.** The host was the
- * region, and a banner raised mid-session arrives with its message already in
- * it, which a screen reader reads inconsistently at best. So the message is said
- * from a region filled a frame after the banner appears, and one that came with
- * the page is filled at once and says nothing, being no news.
+ * The live region is its own part. When the announcement appears after the page
+ * has loaded, the message is written into the region one frame later, so screen
+ * readers read it reliably. When the announcement is in the served HTML, the
+ * region is filled at once and nothing is read out.
  *
- * Dismissing is a request. The announcement does not remove itself, because the
- * consumer owns the markup and taking the node out from under them would put
- * their state and the document out of step. `preventDefault()` on the
- * `helix-dismiss` is a refusal.
+ * The dismiss button fires `helix-dismiss`, and the announcement stays in the
+ * document, so remove it in your listener. The event is cancelable, and
+ * `dismiss()` returns `false` when a listener calls `preventDefault()`.
  *
  * @since 0.1.0
  * @status stable
@@ -37,20 +30,20 @@ declare const HelixHeadlessAnnouncement_base: (new (...args: any[]) => import("@
  * @documentation https://fusion.dev/helix/components/announcement
  *
  * @slot - The message.
- * @slot actions - What to do about it, usually a link or a button.
- * @slot icon - Replaces the glyph inside the dismiss control.
+ * @slot actions - Actions for the message, usually a link or a button.
+ * @slot icon - Replaces the icon inside the dismiss button.
  *
- * @event {HelixDismissEvent} helix-dismiss - Fired when the reader asks to close it. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixDismissEvent} helix-dismiss - The dismiss button was pressed. The announcement does not remove itself, so remove it in response. Cancelable.
  *
- * @csspart actions - The trailing action region.
- * @csspart content - The message region.
- * @csspart dismiss - The control that asks to close.
- * @csspart dismiss-mark - The glyph on the dismiss control, where none is slotted.
- * @csspart live - The message again, in a region a screen reader hears when the band appears mid-session. Visually hidden in the styled tier.
+ * @csspart actions - The region after the message that holds the actions.
+ * @csspart content - The region that holds the message.
+ * @csspart dismiss - The button that dismisses the announcement.
+ * @csspart dismiss-mark - The icon on the dismiss button, shown when the `icon` slot is empty.
+ * @csspart live - A copy of the message in a live region, read by screen readers when the announcement appears after the page has loaded. Visually hidden in the styled tier.
  */
 export declare class HelixHeadlessAnnouncement extends HelixHeadlessAnnouncement_base {
     /**
-     * Which color the band wears.
+     * The band's color.
      *
      * Paint only: unlike `Callout`, no value here draws a mark, changes the label,
      * or moves the live region off polite. `neutral` is the resting value, said

package/dist/app-header/root/app-header-root.d.ts

@@ -4,18 +4,17 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @summary Page-level banner holding brand, navigation, and actions.
  *
  * @description
- * Tracks whether the page has scrolled and carries it as the custom state
- * `scrolled`, so the styled tier can lift the bar without a scroll handler of
- * its own. It is read on connect rather than derived: a fresh load starts at
- * the top, which is what the server rendered, and a reload part-way down
- * corrects on hydration.
+ * Tracks whether the page has scrolled and sets the custom state `scrolled`, so
+ * the styled tier can lift the bar without a scroll handler of its own. The
+ * state is read when the element connects. A fresh load starts at the top,
+ * which matches the server markup, and a reload partway down the page is
+ * corrected on hydration.
  *
- * **A custom state and never `data-scrolled`.** An attribute the element writes
- * onto its own host is one the server did not send, so a hydrating framework
- * reports a mismatch, intermittently: only when the reader reloads far enough
- * down the page. `ElementInternals.states` is not in the DOM, so there is
- * nothing for a hydration pass to disagree with, and `:state(scrolled)` selects
- * it.
+ * The element uses a custom state because an attribute such as `data-scrolled`,
+ * written onto its own host, is one the server did not send. A hydrating
+ * framework would report a mismatch whenever the page reloads far enough down.
+ * `ElementInternals.states` is not in the DOM, so hydration has nothing to
+ * compare. Select the state with `:state(scrolled)`.
  *
  * @since 0.1.0
  * @status stable
@@ -28,9 +27,10 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @slot start - Leading content, usually a wordmark.
  *
  * @event {HelixScrolledEvent} helix-scrolled - Fired when the page crosses the
- * threshold, with the new state. A custom state cannot be observed the way an
- * attribute could, so the header says when it changes rather than leaving
- * consumers to run a second scroll listener and disagree about the hysteresis.
+ * scroll threshold, with the new state. A custom state cannot be observed the
+ * way an attribute can, so listen for this event to follow it. The event uses
+ * the header's own threshold and hysteresis, so you do not need a second scroll
+ * listener.
  *
  * @csspart content - The middle region.
  * @csspart end - The trailing region.

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

@@ -16,60 +16,40 @@ export interface AreaStack {
 }
 declare const HelixHeadlessAreaChart_base: typeof HelixElement & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinChartSourceInterface);
 /**
- * @summary How a total is made up over time, as bands stacked on one another.
+ * @summary A chart that shows how a total is made up over time, as bands stacked on one another.
  *
  * @description
- * The chart for a composition: every column of the table is a part, the parts
- * sum to the whole at each reading, and the top edge is that whole. What a line
- * chart of the same table cannot show is the share, which here is the
- * thickness of a band.
+ * Shows how a total is made up. Each numeric column of the table is a part, the
+ * parts add up to the total at each reading, and the top edge is that total.
+ * The thickness of a band is that part's amount.
  *
- * **Not `Line Chart` with `area`.** That washes each series from the floor on
- * its own, so the series overlap; this adds them. Reach for `Line Chart` when
- * the question is how each series moved, and for this when it is how the whole
- * is made up.
+ * Use `LineChart` with `area` to show how each series moved: it fills each
+ * series from the floor separately, so the fills overlap. Use this chart to
+ * show the composition: it stacks the series.
  *
- * **It measures from zero, always**, which is `BarChart`'s rule and for the same
- * reason: a band's thickness *is* its value, so a range that starts anywhere
- * else draws every part in proportion to nothing. `LineChart` measures from its
- * own range because a line claims a position; a band claims an amount.
+ * **The value axis always starts at zero**, as in `BarChart`, because a band's
+ * thickness is its value. For the same reason there is no streamgraph mode,
+ * which moves the baseline. To show how the composition changed, set `share`.
  *
- * **And so it is not a streamgraph**, which is the near neighbor to name.
- * A streamgraph moves its baseline to center the bands and reads as a river; it
- * is a real form and it is the one thing the rule above refuses, so this
- * carries no alias for it. What it has instead is `share`, which answers the
- * question a streamgraph is usually reached for, how the composition changed,
- * without giving up a floor a reader can measure against.
+ * Band edges are straight between readings by default. A smoothed curve through
+ * one sum can dip below the curve through the sum beneath it, which draws a
+ * part as less than zero. Other curves:
  *
- * **Straight between readings unless asked otherwise.** A band's top edge is a
- * sum, and a curve fitted through one sum can pass under the curve fitted
- * through the sum beneath it, so a smoothed stack can draw a part as less than
- * nothing between two readings. Straight segments between ordered points stay
- * ordered. `curve="smooth"` is there for a stack that is read as a shape.
+ * - `curve="smooth"`: for a stack read as an overall shape.
+ * - `curve="step"`: holds each reading and jumps at the midpoint, so stacked
+ *   edges stay in order, as with `straight`. Use it for a quantity that changes
+ *   at a moment, such as a headcount or a price.
  *
- * `curve="step"` falls on the safe side of that argument rather than being
- * unanswered by it, and it is worth saying which side because a reader cannot
- * tell from the argument alone. A step takes no value the readings do not have:
- * it holds one, jumps at the midpoint, and holds the next. So two stepped edges
- * that are ordered at every reading are ordered everywhere between them, which
- * is what `straight` is chosen for. It is the curve for a quantity that changes
- * at a moment rather than across an interval, a headcount or a price, where a
- * sloped edge claims a gradual change nothing measured.
+ * `share` draws each reading as 100 percent, so the top edge is flat and the
+ * bands show each part's share. Use it to see which part grew. The default
+ * shows whether the total grew.
  *
- * **`share` draws each reading as a hundred percent**, so the bands are the
- * parts' shares and the top edge is flat. It answers "which part grew" where
- * the default answers "did the whole grow".
+ * The drawing is `aria-hidden`. The text summary gives the latest reading's
+ * total and each part's share of it, and the table beside the chart has every
+ * number.
  *
- * **What a reader without the picture is told is the total and the share**, not
- * every band in turn. The table beside the chart already reads out every
- * number; what the drawing adds is the composition, so the summary says the
- * latest reading's total and each part's share of it. The drawing itself is
- * `aria-hidden`.
- *
- * Every numeric column is a part. A table that carries its own total column
- * would count it twice, so leave it out of the table the chart reads.
- * A negative reading is drawn as none: a part of a whole cannot be less than
- * nothing, and a band that folded under its neighbor would say it was.
+ * Every numeric column is a part, so leave a total column out of the table the
+ * chart reads, or it is counted twice. A negative reading is drawn as zero.
  *
  * @since 0.1.0
  * @status stable
@@ -86,7 +66,7 @@ declare const HelixHeadlessAreaChart_base: typeof HelixElement & (new (...args:
  * @csspart line - The top edge of one part's band.
  * @csspart mark - The invisible point the tooltip is anchored to.
  * @csspart plot - The drawing.
- * @csspart summary - The total and the shares at the latest reading, for a reader who cannot see the bands.
+ * @csspart summary - The total and each part's share at the latest reading, written as a sentence for screen readers.
  * @csspart svg - The drawing surface the bands sit on.
  * @csspart tooltip - The bubble, forwarded from `Tooltip`.
  * @csspart tooltip-anchor - The `Tooltip` element itself.
@@ -134,14 +114,15 @@ export declare class HelixHeadlessAreaChart extends HelixHeadlessAreaChart_base
      */
     gridlines?: 'both' | 'category' | 'value';
     /**
-     * Whether each reading is drawn as a hundred percent.
+     * Draws each reading as a hundred percent, so each band shows its share of
+     * the total.
      *
      * Absent stacks the amounts, so the top edge is the total. Set, every reading
      * fills the height and the bands are shares of it.
      */
     share: boolean;
     /**
-     * What to call the sum of the parts, in the tooltip and the summary.
+     * The name for the sum of the parts, shown in the tooltip and the summary.
      */
     totalLabel: string;
     private warnedAboutNegatives;

package/dist/avatar/group/avatar-group.d.ts

@@ -14,16 +14,14 @@ export declare const FOLDS_UP_TO = 12;
  * @summary Overlapping avatars, with a count for the ones not shown.
  *
  * @description
- * A part of `Avatar` rather than a family of its own: it arranges avatars and
- * is about nothing else.
+ * A part of `Avatar` that arranges avatars.
  *
- * **The overflow count is the group's, not a slot.** Which avatars are hidden
- * is a fact the group works out from `max`, so a consumer writing the "+3"
- * would be writing a number that has to agree with a list they do not control.
+ * The group computes the overflow count from `max` and renders the "+3" itself.
+ * There is no slot for it, because the number has to match which avatars are
+ * hidden.
  *
- * **Hidden, not removed.** Past `max` the extra avatars stay in the DOM and
- * stop being shown, so nothing re-renders when `max` changes and the accessible
- * name is still built from all of them.
+ * Avatars past `max` stay in the DOM and are hidden. Changing `max` re-renders
+ * nothing, and the accessible name is still built from all of them.
  *
  * @since 0.1.0
  * @status stable

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

@@ -3,19 +3,19 @@ import { type PropertyValues, type TemplateResult } from 'lit';
 /** Initials for a name: first letter of the first and last words. */
 export declare const initialsOf: (name: string) => string;
 /**
- * @summary Represents a person or entity with an image or their initials.
+ * @summary A person or entity, shown as an image or as their initials.
  *
  * @description
- * Shows `src` until it fails to load. Without an image, or after a failure,
- * the default slot is shown; its own fallback is the initials.
+ * Shows `src` until it fails to load. Without an image, or after a failure, the
+ * default slot is shown, and its own fallback is the initials.
  *
- * The host carries the accessible name, taken from `name`, so the `<img>` has an
- * empty `alt` and the initials are hidden from assistive technology. Announcing
- * either would repeat the name. An `aria-label` on the host overrides `name`,
- * for an avatar standing for something a person's name does not describe.
+ * The host carries the accessible name, taken from `name`. The `<img>` has an
+ * empty `alt` and the initials are hidden from assistive technology, so the
+ * name is announced once. Set `aria-label` on the host to override `name` when
+ * a person's name does not describe what the avatar stands for.
  *
- * `load` and `error` are relayed from the host. They are not composed, so they
- * stop at the shadow boundary otherwise.
+ * `load` and `error` are re-dispatched from the host, because they are not
+ * composed and would otherwise stop at the shadow boundary.
  *
  * @since 0.1.0
  * @status stable
@@ -45,8 +45,8 @@ export declare class HelixHeadlessAvatar extends HelixElement {
      */
     src: string;
     /**
-     * Where the image stands: still on its way, arrived, or failed and replaced
-     * by the initials.
+     * The image's state: `loading` while it is on its way, `loaded` once it
+     * arrives, or `error` when it fails and the initials replace it.
      *
      * Read-only to a consumer: it is a report rather than a setting, and the same
      * report `Image` gives, for the same reason. `load` and `error` fire once, so

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

@@ -1,23 +1,22 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type TemplateResult } from 'lit';
 /**
- * @summary Attaches a count or a presence mark to another element.
+ * @summary A count or a dot pinned to the corner of another element.
  *
  * @description
- * Wraps whatever it decorates and pins the indicator to its corner, so the
- * thing being counted stays the thing in the layout: a badge is an annotation,
- * not a container that happens to hold an icon.
+ * Badge wraps the element it decorates and pins an indicator to its corner, so
+ * the wrapped element keeps its place in the layout.
  *
- * The indicator says how many, and none is none. A `value` that reads as zero
- * shows no mark at all, an absent one shows a bare dot, and any other value
- * shows the value. `max` caps the top: past it the indicator reads `{max}+`
- * rather than growing to fit, since a corner mark that widens with its value
- * pushes the layout around.
+ * What the indicator shows depends on `value`:
  *
- * **A dot needs a label.** Without one it is a colored circle that announces
- * nothing, which tells a sighted reader there is something new and tells
- * everyone else there is not. The label is required in that form, and the
- * indicator is hidden from assistive technology when a number already says it.
+ * - A `value` of zero shows no indicator.
+ * - No `value` shows a dot.
+ * - Any other value shows the value. Above `max`, the indicator shows `{max}+`,
+ *   so its width stays the same as the count grows.
+ *
+ * A count is announced from its own text, and `label` replaces that with a
+ * fuller name, such as `4 unread`. A dot needs a `label`. Without one, the dot
+ * is a colored circle that screen readers do not announce.
  *
  * @since 0.1.0
  * @status stable
@@ -31,13 +30,13 @@ import { type TemplateResult } from 'lit';
  */
 export declare class HelixHeadlessBadge extends HelixElement {
     /**
-     * Accessible name.
+     * The badge's name, read by screen readers.
      *
      * Required for a dot, which has no text to read.
      */
     label: string;
     /**
-     * Cap for a numeric value.
+     * The largest number the badge shows.
      *
      * Past it the indicator reads `{max}+`.
      */