@fusion.dev/helix-headless 0.104.1 → 0.106.0

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.104.1",
+  "version": "0.106.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.104.1",
-    "@fusion.dev/helix-icons": "0.104.1",
+    "@fusion.dev/helix-core": "0.106.0",
+    "@fusion.dev/helix-icons": "0.106.0",
     "uqr": "^0.1.3"
   },
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.104.1",
-    "@fusion.dev/helix-testing": "0.104.1",
+    "@fusion.dev/helix-cem": "0.106.0",
+    "@fusion.dev/helix-testing": "0.106.0",
     "@fusion.dev/scripts": "0.0.0-dev",
     "@happy-dom/global-registrator": "^20.0.0",
     "@lit-labs/ssr": "^4.1.0",