@fusion.dev/helix-headless 0.105.0 → 0.107.0

package/dist/video-playlist/item/video-playlist-item.d.ts

@@ -4,23 +4,18 @@ import { type TemplateResult } from 'lit';
  * @summary One entry in a video playlist.
  *
  * @description
- * **It holds what the player needs and nothing about playing.** A source, a
- * poster and a name: the entry knows which file it stands for, and the playlist
- * is what hands that to a player. Nothing here touches a `<video>`, which is
- * what keeps a playlist usable with a player the consumer configured
- * themselves.
+ * **An entry holds a source, a poster, and a name**, and the playlist passes
+ * them to the player. The entry does not touch a `<video>`, so the playlist
+ * works with a player you configured yourself.
  *
- * **A real `<button>`, in a `listitem`.** A playlist is a list of things to
- * choose, and the list roles are the honest ones: `list` and `listitem` say how
- * many there are and where you are in them, which `listbox` would too, at the
- * cost of the pattern a listbox obliges. `Option` records that trap in full,
- * that a listbox has to keep focus elsewhere and say which item is current with
- * `aria-activedescendant`. Nothing here needs that, because focus really moves
- * to the button.
+ * **Each entry is a `<button>` inside a `listitem`.** The `list` and `listitem`
+ * roles tell a screen reader how many entries there are and the position of the
+ * focused one. Focus moves to the button, so the entry does not need the
+ * `listbox` pattern, which keeps focus elsewhere and marks the current item
+ * with `aria-activedescendant`. `Option` documents that pattern.
  *
- * `aria-current` rather than `aria-selected`, which belongs to the roles that
- * have a selection. What is true of the entry playing now is that it is the one
- * the player is on.
+ * The entry playing now carries `aria-current`. `aria-selected` belongs to
+ * roles that have a selection.
  *
  * @since 0.1.0
  * @status stable
@@ -28,21 +23,21 @@ import { type TemplateResult } from 'lit';
  * @documentation https://fusion.dev/helix/components/video-playlist
  *
  * @slot - The entry's name.
- * @slot media - A thumbnail. Falls back to an image of `poster`.
- * @slot meta - After the name. A duration, or a date.
+ * @slot media - A thumbnail. Defaults to an image of `poster`.
+ * @slot meta - Content after the name, such as a duration or a date.
  *
- * @event {HelixSelectEvent} helix-select - Fired when the entry is chosen. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixSelectEvent} helix-select - The entry was chosen. Cancelable: cancel it to keep the current entry.
  *
- * @csspart container - The `listitem`, which the button sits in.
+ * @csspart container - The list item that holds the button.
  * @csspart item - The row, which is a button.
- * @csspart item-current - The row of the entry the player is on, beside `item`.
- * @csspart label - The name and whatever follows it.
- * @csspart media - The leading column.
- * @csspart thumbnail - The image `poster` falls back to.
+ * @csspart item-current - Added to `item` for the entry that is playing.
+ * @csspart label - The name and the content after it.
+ * @csspart media - The column at the start of the row.
+ * @csspart thumbnail - The image of `poster`, shown when the `media` slot is empty.
  */
 export declare class HelixHeadlessVideoPlaylistItem extends HelixElement {
     /**
-     * Whether the player is on this entry.
+     * Whether this entry is the one playing.
      *
      * Written by the playlist rather than by the entry, the way an option's
      * selection is: an entry that made itself current would be a second answer to
@@ -50,11 +45,11 @@ export declare class HelixHeadlessVideoPlaylistItem extends HelixElement {
      */
     current: boolean;
     /**
-     * Whether the entry can be chosen.
+     * Prevents the entry from being chosen.
      */
     disabled: boolean;
     /**
-     * What covers the picture before this entry plays, and the row's thumbnail.
+     * The image shown before this entry plays, also used as the row's thumbnail.
      *
      * One property doing both, because they are the same picture: the frame that
      * stands for the clip stands for it in the list too. It is the `media` slot's
@@ -68,11 +63,11 @@ export declare class HelixHeadlessVideoPlaylistItem extends HelixElement {
      */
     src: string;
     /**
-     * What identifies the entry, and what `active` is compared against.
+     * The entry's identifier, compared against the playlist's `active`.
      */
     value: string;
     /**
-     * The entry's name, which is the words and not everything in it.
+     * The entry's name: its own text, without the content in its named slots.
      *
      * `textContent` takes the whole subtree: a row with a duration in `meta`
      * reads as "His Girl Friday0:06", and that string reaches the player and the

package/dist/video-playlist/menu/video-playlist-menu.d.ts

@@ -5,15 +5,11 @@ import '../../menu/index.js';
  * @summary The playlist's entries, as a menu inside the player's control bar.
  *
  * @description
- * The entries again, reachable without leaving the picture. A playlist beside
- * the player is a list a reader scrolls to; the same list in the control bar is
- * one they open over the video.
+ * Opens the playlist entries from the player's control bar, over the video.
  *
- * **It is placed by the consumer, not rendered by the playlist**, and that is
- * forced rather than chosen: a shadow root cannot project into a sibling's
- * light DOM, so nothing the playlist renders can land inside the player's
- * control bar. What can is an element the consumer writes there, which is what
- * `Video`'s `controls` slot is for.
+ * **You place the menu yourself**, in `Video`'s `controls` slot. A shadow root
+ * cannot project into a sibling's light DOM, so the playlist cannot render into
+ * the player's control bar.
  *
  * @since 0.1.0
  * @status stable
@@ -23,27 +19,27 @@ import '../../menu/index.js';
  *
  * @slot trigger - Replaces the button that opens the menu.
  *
- * @event {HelixSelectEvent} helix-select - Fired with the chosen entry's value. The playlist listens for it. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixSelectEvent} helix-select - An entry was chosen. The event carries its value, and the playlist listens for it. Cancelable: cancel it to keep the current entry.
  *
  * @csspart entry - One entry in the menu.
- * @csspart entry-item - The row, which is an `<a>` where `href` is set.
- * @csspart entry-mark - The trailing mark: a tick when checked, a caret when it opens
- * @csspart entry-start - The leading column, which is a slot and is always there.
+ * @csspart entry-item - The entry's row. It is an `<a>` when `href` is set.
+ * @csspart entry-mark - The mark at the end of an entry: a check mark when it is checked, or a caret when it opens a submenu.
+ * @csspart entry-start - The column at the start of an entry. It is a slot and is always present.
  * @csspart menu - The menu that holds the entries.
- * @csspart menu-back - The control that returns from a submenu.
- * @csspart menu-back-mark - The glyph on the back control of a submenu.
+ * @csspart menu-back - The button that goes back from a submenu.
+ * @csspart menu-back-mark - The icon on a submenu's back button.
  * @csspart menu-empty - Shown when there are no items to show.
- * @csspart menu-header - The bar above a submenu, holding the way back and its name.
- * @csspart menu-live - The inner menu's `live`, the region a screen reader hears its empty and loading lines from.
- * @csspart menu-loading - Shown while the items are still on their way.
+ * @csspart menu-header - The bar above a submenu, holding the back button and the submenu's name.
+ * @csspart menu-live - The inner menu's `live` part, the region screen readers announce its empty and loading messages from.
+ * @csspart menu-loading - Shown while the items are loading.
  * @csspart menu-surface - The floating panel the menu is drawn on.
- * @csspart menu-title - The name of the submenu that is showing.
- * @csspart poster - An entry's still, where it has one.
- * @csspart trigger - The button that opens it.
+ * @csspart menu-title - The name of the submenu that is shown.
+ * @csspart poster - An entry's poster image, if it has one.
+ * @csspart trigger - The button that opens the menu.
  */
 export declare class HelixHeadlessVideoPlaylistMenu extends HelixElement {
     /**
-     * The menu's accessible name, and its trigger's.
+     * The name of the menu and its trigger, read by screen readers.
      *
      * "Episodes" suits a series and is wrong for a set of camera angles, and the
      * component cannot know which one it is in.

package/dist/video-playlist/root/video-playlist-root.d.ts

@@ -2,31 +2,27 @@ import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 declare const HelixHeadlessVideoPlaylist_base: (new (...args: any[]) => import("@fusion.dev/helix-core").MixinControllerActiveInterface) & typeof HelixElement;
 /**
- * @summary A set of clips and the one player they take turns in.
+ * @summary A list of video clips that play one after another in a single player.
  *
  * @description
- * **The player is slotted, never rendered here.** A consumer's player carries
- * their appearance, their extra controls, their captions and their poster
- * treatment, and a playlist that rendered its own would either lose all of that
- * or grow a property for each of them. `Sandbox` takes its preview and `Menu`
- * its trigger the same way.
+ * **You slot the player**, so it keeps your appearance, extra controls,
+ * captions, and poster treatment. `Sandbox` takes its preview and `Menu` its
+ * trigger the same way.
  *
- * **The entries are markup rather than an array property.** A list of objects
- * would be the shorter API and it does not survive the trip: React skips every
- * property it would have to apply imperatively while hydrating, so an array
- * handed to a custom element is missing on the first paint of every
- * server-rendered page. `using-the-elements.mdx` carries the measurement. Markup
- * is also what makes each entry a real button with a real name in it.
+ * **Entries are markup.** React skips properties it would set imperatively
+ * during hydration, so an array property on a custom element is missing on the
+ * first paint of a server-rendered page. `using-the-elements.mdx` has the
+ * measurement. Markup also makes each entry a real button with its name inside.
  *
- * **Nothing here plays anything.** It sets `src` on the player and lets the
- * player be a player. What the playlist owns is which entry is current, and it
- * moves that on three signals: an entry pressed, `helix-next` or
- * `helix-previous` from the player, and the player reaching the end.
+ * **The playlist does not play media.** It sets `src` on the player and tracks
+ * which entry is current. The current entry moves when:
  *
- * `ended` advances without asking, because a set of clips that stopped between
- * each one is a set the reader has to nurse. The clip that follows starts where
- * the last one left off, which is `autoplay` in the only sense that matters
- * here: the reader already pressed play once.
+ * - an entry is pressed,
+ * - the player dispatches `helix-next` or `helix-previous`, or
+ * - the player reaches the end.
+ *
+ * On `ended` the playlist advances and the next clip starts playing, because
+ * the user already pressed play once.
  *
  * @since 0.1.0
  * @status stable
@@ -35,17 +31,17 @@ declare const HelixHeadlessVideoPlaylist_base: (new (...args: any[]) => import("
  * @documentation https://fusion.dev/helix/components/video-playlist
  *
  * @slot - The entries.
- * @slot player - The player the entries take turns in.
+ * @slot player - The player that plays the entries.
  *
- * @event {HelixActivateEvent} helix-activate - Fired once the current one has moved, so the element already holds it.
- * @event {HelixBeforeActivateEvent} helix-before-activate - Fired before the current entry changes, and cancelable.
+ * @event {HelixActivateEvent} helix-activate - The current entry changed. The playlist already holds the new entry when this is sent.
+ * @event {HelixBeforeActivateEvent} helix-before-activate - The current entry is about to change. Cancelable: cancel it to keep the current entry.
  *
  * @csspart items - The list of entries.
- * @csspart player - The region holding the player.
+ * @csspart player - The region that holds the player.
  */
 export declare class HelixHeadlessVideoPlaylist extends HelixHeadlessVideoPlaylist_base {
     /**
-     * Accessible name for the list, which usually has no visible heading.
+     * The list's name, read by screen readers.
      */
     label: string;
     /**

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

@@ -1,58 +1,59 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 /**
- * @summary Renders the rows of a long set that are on screen, and no others.
+ * @summary A list that renders only the rows of a long set that are on screen.
  *
  * @description
- * **The set arrives as data, which is what makes this a virtual list rather
- * than a box that hides children.** `for` names a
- * `<script type="application/json">` holding an array of objects, and a
- * `<template>` child says what one row looks like: elements carrying
- * `data-field="name"` are filled with that field of the item.
+ * The items arrive as data:
  *
- * Both halves are markup, and that is the reason for the shape. An `items`
- * property cannot survive React hydration, which skips every property it would
- * have to apply imperatively, and light-DOM children exist by the time anything
- * could decide not to create them. Text in the document is neither, and it is
- * one node whatever the row count.
+ * - `for` names a `<script type="application/json">` that holds an array of
+ *   objects.
+ * - A `<template>` child defines one row. Elements with `data-field="name"` are
+ *   filled with that field of the item.
  *
- * **The accessible version is not a `<table>`**, the way it is for the charts
- * that share this `for="<id>"` shape: ten thousand rows in one is the cost this
- * exists to avoid. It is the rendered window plus `aria-setsize`.
+ * Both are markup. React hydration skips every property it would have to set
+ * imperatively, so an `items` property would be lost, and light-DOM children
+ * would all exist before anything could window them. The JSON text is one node
+ * whatever the row count.
  *
- * **The box scrolls on this tier.** The viewport carries `data-scroller` and
- * `core` ships `[data-scroller] { overflow: auto }` into every shadow root, so
- * `scrollTop` exists with no stylesheet at all. What a headless consumer still
- * has to supply is a block size, which is a design decision; the `overflow`
- * they used to supply was a mechanism they had no way of knowing was missing.
+ * For assistive technology the list exposes the rendered window with
+ * `aria-setsize`. Charts that use the same `for="<id>"` shape render an
+ * accessible `<table>`, and ten thousand rows in one is the cost this component
+ * avoids.
+ *
+ * The viewport scrolls on this tier. It carries `data-scroller`, and `core`
+ * ships `[data-scroller] { overflow: auto }` into every shadow root, so
+ * `scrollTop` works with no stylesheet. You still need to set a block size.
  *
  * @since 0.1.0
  * @status stable
  * @category layout
  * @documentation https://fusion.dev/helix/components/virtual-list
  *
- * @csspart after - The space standing in for rows below the window.
- * @csspart before - The space standing in for rows above the window.
- * @csspart viewport - The scrolling box. Needs a block size on this tier, and nothing else.
+ * @csspart after - The space that stands in for the rows below the rendered ones.
+ * @csspart before - The space that stands in for the rows above the rendered ones.
+ * @csspart viewport - The scrolling box. On this tier, it needs only a block size.
  */
 export declare class HelixHeadlessVirtualList extends HelixElement {
     /**
-     * How tall one row is, in pixels, used to map scroll offset to an index.
+     * The height of one row, in pixels, used to find the row at a scroll offset.
      *
      * An estimate rather than a measurement while `measured` is off, which is
      * right whenever the rows really are one height and is the cheaper of the two.
      */
     estimate: number;
     /**
-     * Id of the element holding the rows, as JSON in a script.
+     * The id of the script element that holds the rows as JSON.
      */
     for: string;
     /**
-     * What the list is called, since the rendered rows are only a window on it.
+     * The list's name, read by screen readers, because only some of its rows
+     * are rendered at a time.
      */
     label: string;
     /**
-     * Places rows by what they came to rather than by `estimate`.
+     * Places rows by their measured height. Without it, every row is placed by
+     * `estimate`.
      *
      * **Off by default, because the straight line is better when it holds.** One
      * estimate makes offset and index convert by division, which can never

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-headless",
   "description": "Headless component tier. Structure, accessibility, state, and form participation. No styling.",
-  "version": "0.105.0",
+  "version": "0.107.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -46,13 +46,13 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.105.0",
-    "@fusion.dev/helix-icons": "0.105.0",
+    "@fusion.dev/helix-core": "0.107.0",
+    "@fusion.dev/helix-icons": "0.107.0",
     "uqr": "^0.1.3"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.105.0",
-    "@fusion.dev/helix-testing": "0.105.0",
+    "@fusion.dev/helix-cem": "0.107.0",
+    "@fusion.dev/helix-testing": "0.107.0",
     "@fusion.dev/scripts": "0.0.0-dev",
     "@happy-dom/global-registrator": "^20.0.0",
     "@lit-labs/ssr": "^4.1.0",