@fusion.dev/helix-headless 0.105.0 → 0.106.0

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

@@ -4,21 +4,19 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
  * @summary One row in a menu: a command, a choice, or a way into a submenu.
  *
  * @description
- * Three shapes, one element, because a reader moving down a menu with the
- * arrow keys does not care which kind each row is and neither should the
- * markup. What it is follows from what it was given: something slotted into
- * `submenu` makes it a way in, `checked` makes it a choice, and neither makes
- * it a command.
+ * One element covers three kinds of row, and what you give it decides which:
+ * - Content in the `submenu` slot makes the row open a submenu page.
+ * - `checked` makes the row a choice.
+ * - With neither, the row is a command.
  *
- * **The role follows the shape.** A row that can be ticked is
- * `menuitemcheckbox` and carries `aria-checked`, because a reader is told "one
- * of these is on" rather than "here is a button"; `exclusive` makes it
- * `menuitemradio`, for a set where only one can be. A row that opens a page
- * keeps `menuitem` and says `aria-haspopup`, since the page it opens is a menu.
+ * The role follows the kind. A row with `checked` is `menuitemcheckbox` with
+ * `aria-checked`, and `exclusive` makes it `menuitemradio`, for a set where
+ * only one can be on. A row that opens a page keeps `menuitem` and sets
+ * `aria-haspopup`.
  *
- * Whether it is on the page showing is set by the menu as a property, never as
- * an attribute: an attribute written onto a consumer's element after it
- * upgrades is a hydration mismatch waiting to happen.
+ * The menu sets whether the row's page is showing as a property, never as an
+ * attribute. An attribute written onto your element after it upgrades causes a
+ * hydration mismatch.
  *
  * @since 0.1.0
  * @status stable
@@ -26,15 +24,15 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
  * @documentation https://fusion.dev/helix/components/menu
  *
  * @slot - The label.
- * @slot start - Before the label. A mark about the row.
- * @slot submenu - Rows this one opens, which makes it a way in.
+ * @slot start - Content before the label, such as an icon.
+ * @slot submenu - The rows of a submenu that this row opens.
  *
- * @event {HelixSelectEvent} helix-select - Fired when the row is chosen. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixSelectEvent} helix-select - The row was chosen. Cancelable: cancel it to keep the menu open.
  *
  * @csspart item - The row, which is an `<a>` where `href` is set.
- * @csspart mark - The trailing mark: a tick when checked, a caret when it opens
- * a page. One column, because a row is never both.
- * @csspart start - The leading column, which is a slot and is always there.
+ * @csspart mark - The trailing mark: a check mark when the row is checked, or a caret
+ * when it opens a submenu. A row never shows both, so they share one column.
+ * @csspart start - The leading column that holds the `start` slot. It is always rendered.
  */
 export declare class HelixHeadlessMenuItem extends HelixElement {
     /**
@@ -50,15 +48,15 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      */
     checkable: boolean;
     /**
-     * Whether the row is ticked.
+     * Whether the row is checked.
      */
     checked: boolean;
     /**
-     * Whether the row can be chosen.
+     * Whether the row is disabled, so it cannot be chosen.
      */
     disabled: boolean;
     /**
-     * Whether the link saves the file rather than opening it.
+     * Whether the link downloads the file when the row is chosen.
      *
      * Only meaningful beside an `href`, and only for a file served from this
      * origin: the attribute is ignored cross-origin, which is the browser's rule
@@ -66,7 +64,7 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      */
     download: boolean;
     /**
-     * Whether only one row of the set it belongs to can be on.
+     * Whether only one row in its set can be checked at a time.
      *
      * Announcement and nothing else, the way `checkable` is: this element applies
      * no choice and polices no group, so what it does is tell a reader which kind
@@ -79,7 +77,7 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      */
     exclusive: boolean;
     /**
-     * Where the row goes, which makes it a real link.
+     * The URL the row links to. Setting it renders the row as a link.
      *
      * **The row itself becomes an `<a>`, and the role goes with it.** A
      * `menuitem` cannot contain a link: measured in Chromium, an anchor inside
@@ -100,7 +98,7 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      */
     href: string;
     /**
-     * Whether this row is on the page currently showing.
+     * Whether the row is on the menu page that is showing.
      *
      * Set by the menu, and a property rather than an attribute for that reason.
      * Public because the menu has to reach it, and not something a consumer
@@ -108,7 +106,7 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      */
     onPage: boolean;
     /**
-     * The relationship, which `target="_blank"` should always set.
+     * The link's `rel`. Set it whenever you set `target="_blank"`.
      */
     rel: string;
     /**
@@ -123,11 +121,11 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      */
     showingSubmenu: boolean;
     /**
-     * Where the link opens, for the rows that should leave the page.
+     * Where the link opens, for rows that should open outside the current page.
      */
     target: string;
     /**
-     * What this row stands for, carried in the event when it is chosen.
+     * The row's value, sent in `helix-select` when the row is chosen.
      */
     value: string;
     /**
@@ -217,16 +215,17 @@ export declare class HelixHeadlessMenuItem extends HelixElement {
      */
     focus(): void;
     /**
-     * `NavigableItem`, so the arrow keys can be the shared controller's business.
+     * Moves focus to the row. Part of `NavigableItem`, which the shared keyboard
+     * controller uses for the arrow keys.
      *
      * `focus()` above already puts focus on the control inside the row rather than
      * on the row, which is the whole of what moving here means.
      */
     focusItem(): void;
-    /** Chooses the row, which is the same act as pressing it. */
+    /** Chooses the row, the same as pressing it. */
     select(): void;
     /**
-     * Whether this is the row the set is on, which in a menu is where focus is.
+     * Whether the row has focus, which is what selected means in a menu.
      *
      * A radio group's selection is an answer it holds; a menu has no answer, only
      * a row the reader has walked to, so focus is the whole of what "the current

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

@@ -2,25 +2,21 @@ import { HelixElement, KeyboardNavigationController, type Placement } from '@fus
 import { type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessMenu_base: (new (...args: any[]) => import("@fusion.dev/helix-core").CollectionElement) & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerOpenInterface) & typeof HelixElement;
 /**
- * @summary A menu of commands, opened from a trigger.
+ * @summary A menu of commands that opens from a trigger.
  *
  * @description
- * The trigger is slotted and stays the consumer's own element, the same way the
- * tooltip takes one. The surface is rendered here, in the top layer through the
- * popover API, so it clears any ancestor with `overflow: hidden` without a
- * `z-index` anywhere.
+ * The trigger is slotted and stays your own element, as with the tooltip. The
+ * menu renders its surface in the top layer with the popover API, so an
+ * ancestor with `overflow: hidden` does not clip it and it needs no `z-index`.
  *
- * **It drills down rather than flying out.** A submenu replaces what is on
- * screen and a back row returns, instead of opening a second panel beside the
- * first. Panels beside panels need a diagonal path a pointer has to travel
- * without straying, they run off the edge of a narrow window, and on a touch
- * screen there is no hover to open them with at all. One panel that changes
- * what it holds has none of those problems and reads the same on a phone.
+ * Submenus drill down. A submenu replaces the panel's content, and a back row
+ * returns to the previous page. One panel avoids the diagonal pointer path that
+ * side-by-side panels need, stays inside a narrow window, and works on touch
+ * screens, which have no hover.
  *
- * The open page is held here rather than in each item, because only one page
- * shows at a time and something has to know which. Items are told by property,
- * not by attribute: an attribute written onto a consumer's element after it
- * upgrades is a hydration mismatch waiting to happen.
+ * The root holds which page is open, because only one page shows at a time. It
+ * sets this on items as a property, never as an attribute. An attribute written
+ * onto your element after it upgrades causes a hydration mismatch.
  *
  * @since 0.1.0
  * @status stable
@@ -29,30 +25,30 @@ declare const HelixHeadlessMenu_base: (new (...args: any[]) => import("@fusion.d
  * @documentation https://fusion.dev/helix/components/menu
  *
  * @slot - The items.
- * @slot trigger - What opens it.
+ * @slot trigger - The control that opens the menu.
  *
- * @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 item is chosen. 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 menu is about to close. Cancelable: cancel it to keep it open.
+ * @event {HelixBeforeOpenEvent} helix-before-open - The menu is about to open. Cancelable: cancel it to keep it closed.
+ * @event {HelixSelectEvent} helix-select - An item was chosen. Cancelable: cancel it to keep the menu open.
+ * @event {Event} toggle - The menu opened or closed. The event carries `newState` and `oldState`.
  *
  * @csspart back - The control that returns from a submenu.
  * @csspart back-mark - The glyph on the back control of a submenu.
- * @csspart empty - Shown when there are no items to show.
+ * @csspart empty - The text shown when the menu has no items.
  * @csspart header - The bar above a submenu, holding the way back and its name.
- * @csspart live - The empty and loading lines again, in a region a screen reader hears when they change. Visually hidden in the styled tier.
- * @csspart loading - Shown while the items are still on their way.
+ * @csspart live - A live region that repeats the empty and loading text, so screen readers announce it when it changes. Visually hidden in the styled tier.
+ * @csspart loading - The text shown while the items are loading.
  * @csspart surface - The floating panel the menu is drawn on.
  * @csspart title - The name of the submenu that is showing.
  *
- * @cssstate drilled - While a submenu's page is showing rather than the menu's own, so what is not a row can leave with the page it was on.
- * @cssstate mark - While a row on the page showing can be ticked or leads to a page, so the trailing column is held open for every row.
+ * @cssstate drilled - A submenu's page is showing, so content that is not a row can hide with the top page.
+ * @cssstate mark - A row on the current page has a checkbox or a link, so every row keeps the trailing column.
  * @cssstate open - While the menu is open.
- * @cssstate start - While a row on the page showing has something in its leading column, so that column is held open for every row.
+ * @cssstate start - A row on the current page has content in its leading column, so every row keeps that column.
  */
 export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
     /**
-     * What the row returning from a submenu reads.
+     * The text of the row that returns from a submenu.
      */
     backLabel: string;
     /**
@@ -64,7 +60,7 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
      */
     offset: number;
     /**
-     * Preferred side.
+     * The side the menu opens on, when there is room.
      *
      * It moves if that side does not fit.
      */
@@ -112,7 +108,7 @@ export declare class HelixHeadlessMenu extends HelixHeadlessMenu_base {
     private get items();
     /** Opens the menu. */
     show(): void;
-    /** Closes the menu, and forgets which page was showing. */
+    /** Closes the menu and returns it to its first page. */
     hide(): void;
     /** Shows an item's submenu in place of the current page. */
     private enter;

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

@@ -3,19 +3,18 @@ import { type PropertyValues, type TemplateResult } from 'lit';
 /** Which band a value falls in, once `optimum` has said which end is good. */
 export type MeterBand = 'fair' | 'good' | 'poor';
 /**
- * @summary A measurement in a known range, and whether it is where you want it.
+ * @summary A measurement in a known range, with optional bands that mark it good, fair, or poor.
  *
  * @description
- * **Not `Progress`, and the difference is the whole component.** A progress bar
- * reports how far along a task is: it starts empty, ends full, and full is
- * always the good end. A meter reports a level in a range that is not going
- * anywhere, and which end is good is a fact about the thing measured. So there
- * is no `indeterminate`: a measurement whose value is unknown is not one.
+ * A meter shows a level within a range. Use `Progress` to show how far along a
+ * task is. A progress bar starts empty and ends full, and full is always the
+ * good end. For a meter, which end is good depends on what is measured. There
+ * is no `indeterminate`, because a meter always has a value.
  *
- * **`low`, `high` and `optimum` are the reason it exists**, following the HTML
- * specification's own rule. The three cut the range into a low band, a middle
- * and a high band, and `optimum` says which is the one to be in; the band next
- * to it is fair and the one two away is poor.
+ * **Set `low`, `high`, and `optimum`**, as defined in the HTML specification.
+ * `low` and `high` divide the range into a low band, a middle band, and a high
+ * band. `optimum` sets the preferred band. The band next to it is fair, and the
+ * band two away is poor.
  *
  * @since 0.1.0
  * @status stable
@@ -24,15 +23,15 @@ export type MeterBand = 'fair' | 'good' | 'poor';
  * @documentation https://fusion.dev/helix/components/meter
  *
  * @csspart groove - The unfilled circle, in `ring` and `arc`.
- * @csspart indicator - The part of it the value fills.
- * @csspart indicator-fair - The fill while the reading is in a band beside the good one, beside `indicator`.
- * @csspart indicator-good - The fill while the reading is in the good band, beside `indicator`.
- * @csspart indicator-over - The fill while the value is past the top, beside `indicator`.
- * @csspart indicator-poor - The fill while the reading is two bands from the good one, beside `indicator`.
- * @csspart indicator-under - The fill while the value is below the floor, beside `indicator`.
+ * @csspart indicator - The part of the track the value fills.
+ * @csspart indicator-fair - The fill while the reading is in a band next to the good band. Set alongside `indicator`.
+ * @csspart indicator-good - The fill while the reading is in the good band. Set alongside `indicator`.
+ * @csspart indicator-over - The fill while the value is above `max`. Set alongside `indicator`.
+ * @csspart indicator-poor - The fill while the reading is two bands from the good band. Set alongside `indicator`.
+ * @csspart indicator-under - The fill while the value is below `min`. Set alongside `indicator`.
  * @csspart tick - A mark at `low` or at `high`.
  * @csspart track - The whole range, or the drawing in `ring` and `arc`.
- * @csspart value - The reading, under `show-value`.
+ * @csspart value - The reading as text, shown when `show-value` is set.
  *
  * @cssproperty --meter-along - Where a bound sits on the arc, as a length along it.
  * @cssproperty --meter-at - Where a bound sits on a linear track, as a percentage.
@@ -41,7 +40,8 @@ export type MeterBand = 'fair' | 'good' | 'poor';
  */
 export declare class HelixHeadlessMeter extends HelixElement {
     /**
-     * The band, said outright, where the three thresholds cannot say it.
+     * Sets the band directly, for a rule that `low`, `high`, and `optimum` cannot
+     * express.
      *
      * **The specification's model has a shape, and it is worth knowing before
      * reaching for this.** Three bands and a point mean it can express a
@@ -99,7 +99,7 @@ export declare class HelixHeadlessMeter extends HelixElement {
      */
     min: number;
     /**
-     * Where in the range it is best to be.
+     * The point in the range where the reading is best.
      *
      * Defaults to the middle of whatever bands are declared, which is the
      * platform's own default and the right one for a score. A meter where low is
@@ -108,7 +108,7 @@ export declare class HelixHeadlessMeter extends HelixElement {
      */
     optimum?: number;
     /**
-     * Whether the reading is drawn as a bar, a ring or an arc.
+     * Whether the reading is drawn as a bar, a ring, or an arc.
      *
      * A gauge and a meter are the same thing measured: a value in a range, with
      * bands saying which part of it is the good part. What differs between the two
@@ -137,7 +137,8 @@ export declare class HelixHeadlessMeter extends HelixElement {
      */
     value: number;
     /**
-     * What the reading says, where a number is not the whole story.
+     * Text that screen readers announce and the meter shows for the reading, in
+     * place of the percentage.
      *
      * `value-text="18 GB of 32 GB"` is announced and shown instead of `56%`. The
      * same property `Progress` carries, for the same reason: a percentage is a

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

@@ -4,21 +4,18 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @summary A set of destinations, with a marker on the current one.
  *
  * @description
- * Renders a real `<nav>`, which is the landmark a screen-reader user jumps to.
- * It exists as its own component rather than as a region of `AppHeader` because
- * a header is not inherently navigation, and navigation is not only ever in a
- * header: a footer and a sidebar hold the same thing.
+ * Renders a real `<nav>`, the landmark that screen reader users jump to.
+ * Navigation is its own component, separate from `AppHeader`, so you can use it
+ * in a header, a footer, or a sidebar.
  *
- * **It renders no links.** The consumer brings them, marked with
- * `aria-current="page"` and styled by the `data-navigation-item` recipe, for the same
- * reason nothing else here renders an anchor: a router renders its own, and
- * cannot render it inside this shadow root.
+ * **It renders no links.** Bring your own, mark the current one with
+ * `aria-current="page"`, and style them with the `data-navigation-item` recipe.
+ * A router renders its own anchors and cannot render them inside the
+ * component's shadow root.
  *
- * What this owns is the marker that travels between them, and that is the whole
- * reason it is a component. A marker that moves needs something that knows
- * where every item is, and reading `aria-current` is how it knows which: the
- * thing that makes the page announce correctly is the same thing that puts the
- * marker in the right place.
+ * The component moves a marker to the current item. It finds the current item
+ * by reading `aria-current`, so the attribute that screen readers announce also
+ * places the marker.
  *
  * @since 0.1.0
  * @status stable
@@ -26,15 +23,15 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @aliases Nav, NavList, Tabs
  * @documentation https://fusion.dev/helix/components/navigation
  *
- * @slot - The destinations, as the consumer's own links.
+ * @slot - The destinations, as your own links.
  *
- * @csspart indicator - The marker that travels to the current destination.
+ * @csspart indicator - The marker that moves to the current destination.
  * @csspart nav - The navigation landmark.
  */
 export declare class HelixHeadlessNavigation extends HelixElement {
     private readonly indicator;
     /**
-     * Accessible name for the landmark.
+     * The landmark's name, read by screen readers.
      */
     label: string;
     private current;

package/dist/notifications/group/notification-group.d.ts

@@ -7,24 +7,19 @@ declare const HelixHeadlessNotificationGroup_base: (new (...args: any[]) => impo
  * them.
  *
  * @description
- * **What groups with what is the consumer's, and this never guesses.** A feed
- * can be cut by day, by the thing being talked about, by the person doing the
- * talking, or by nothing at all, and which of those is right is a question about
- * the product. So a group is written by hand around the rows that belong
- * together and told what to call itself, exactly as `FilterField` is told what
- * its operators are.
+ * You decide what goes in each group. A feed can be grouped by day, by subject,
+ * by person, or not at all, so you write a group around the rows that belong
+ * together and give it a `label`, the same way you give `FilterField` its
+ * operators.
  *
- * **Collapsed shows the first row and assigns the rest nowhere.** Not `hidden`,
- * not `inert`, not a stylesheet: the slot is assigned imperatively, so a
- * collapsed group's later rows are absent from the layout and from the
- * accessibility tree with no CSS at all, which is what the headless tier claims
- * for itself. `Notifications` already assigns its list this way and this borrows
- * the mechanism.
+ * A collapsed group shows its first row and assigns the rest to no slot. The
+ * slot is assigned imperatively, so the later rows are absent from the layout
+ * and from the accessibility tree without any CSS. `Notifications` assigns its
+ * list the same way.
  *
- * The count is separate from how many rows are written, because it usually is: a
- * group saying five with one row under it and a link to the rest is the common
- * shape, and computing the number from the children would make that unsayable.
- * Left off, it is the number of rows.
+ * `count` is set separately from the rows, so a group can show a count of five
+ * with one row under it and a link to the rest. When `count` is not set, it is
+ * the number of rows.
  *
  * @since 0.24.0
  * @status stable
@@ -34,19 +29,19 @@ declare const HelixHeadlessNotificationGroup_base: (new (...args: any[]) => impo
  *
  * @slot - The notifications in this group.
  * @slot actions - Beside the count, for a link to the rest of them.
- * @slot label - Replaces the group's name, for a heading that needs a mark in it.
+ * @slot label - Replaces the group's name, for a heading that includes an icon.
  *
- * @event {HelixBeforeCloseEvent} helix-before-close - Fired before the group folds, and cancelable.
- * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the group unfolds. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixBeforeCloseEvent} helix-before-close - Fired before the group collapses. Cancelable.
+ * @event {HelixBeforeOpenEvent} helix-before-open - Fired before the group expands. Cancelable: cancel it to keep the group collapsed.
  *
  * @csspart actions - The trailing region of the header.
- * @csspart count - How many are in the group.
- * @csspart header - The label, the count and the action together.
+ * @csspart count - The number of notifications in the group.
+ * @csspart header - The label, the count, and the actions together.
  * @csspart items - The region holding the notifications.
- * @csspart label - What the group is called.
- * @csspart trigger - The control that collapses and expands, where collapsible.
+ * @csspart label - The group's name.
+ * @csspart trigger - The control that collapses and expands the group, when `collapsible` is set.
  *
- * @cssstate open - While the group shows every notification in it rather than the first.
+ * @cssstate open - The group shows all of its notifications.
  */
 export declare class HelixHeadlessNotificationGroup extends HelixHeadlessNotificationGroup_base {
     /**
@@ -73,7 +68,7 @@ export declare class HelixHeadlessNotificationGroup extends HelixHeadlessNotific
      */
     collapsible: boolean;
     /**
-     * How many notifications this group stands for.
+     * The number of notifications the group represents.
      *
      * **Not the number of rows, and that is the point.** A group saying five with
      * one row under it and a link to the rest is the ordinary shape of a feed that
@@ -82,14 +77,15 @@ export declare class HelixHeadlessNotificationGroup extends HelixHeadlessNotific
      */
     count?: number;
     /**
-     * What the group is called: a day, a subject, a person.
+     * The group's name, such as a day, a subject, or a person.
      *
      * The slot's fallback rather than its replacement, so a consumer who wants a
      * mark beside the name slots `label` and this goes unused.
      */
     label: string;
     /**
-     * What this is, for the feed above it to recognize without importing it.
+     * Marks this element as a notification group, so the feed can recognize it
+     * without importing its class.
      *
      * The same seam `Notification` uses: a root reads a child's markers rather
      * than its constructor, so the two tiers never have to agree about which class
@@ -98,7 +94,10 @@ export declare class HelixHeadlessNotificationGroup extends HelixHeadlessNotific
     readonly isNotificationGroup = true;
     /** The notifications written into this group, in the order they were given. */
     get items(): HelixHeadlessNotification[];
-    /** How many the group says it stands for, which is the count or the rows. */
+    /**
+     * The number of notifications the group represents: `count` when it is set,
+     * or the number of rows.
+     */
     get total(): number;
     /**
      * The same number where anything can know it, and nothing where nothing can.