@fusion.dev/helix-headless 0.4.2 → 0.4.4

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

@@ -11,36 +11,13 @@ import type { HelixHeadlessTourStop } from '../stop/tour-stop.js';
  *
  * **The spotlight is a shadow, not a hole.** The scrim is a box the size of the
  * current target with an enormous spread on its `box-shadow`, so the darkness
- * is what the shadow paints and the target is simply where the box is. A
- * `clip-path` on a full-screen scrim is the other way to do it and is worse
- * here: it needs the viewport in the same coordinate space as the cut, which
- * stops being true the moment anything between them is transformed.
+ * is what the shadow paints. A `clip-path` on a full-screen scrim needs the
+ * viewport in the same coordinate space as the cut, which stops being true the
+ * moment anything between them is transformed.
  *
- * **It measures, and this is a case where measuring is the only option.** The
- * target is an element somewhere else on the page whose position nothing can
- * know statically. That is different from a trail folding by width, where the
- * design rule was expressible and the measurement was answering a question
- * nobody had asked. Here the question is "where is that button", and there is
- * no other way to ask it.
- *
- * **Nothing is measured on the server and nothing needs to be.** A tour starts
- * closed and a closed tour draws nothing, so the server renders the stops as
- * inert markup and the first frame is correct. This is also what makes it
- * acceptable for the root to write `current` onto stops it does not own: there
- * is no server state for the write to disagree with.
- *
- * **It cannot point inside a modal, and nothing can fix that here.**
- * `showModal()` makes everything outside the dialog's own subtree inert, so a
- * panel anywhere else is unpressable however the top layer is ordered: this is
- * what modal means rather than a stacking accident. Measured with a modal
- * `Drawer` open, `elementsFromPoint` over the tour's own Done button returned
- * the drawer, the press light-dismissed the drawer, and the tour heard nothing
- * at all. Anything a tour points into has to stay reachable, which for `Drawer`
- * and `Dialog` means not modal while the tour is running.
- *
- * **Focus is not trapped.** A reader has to be able to look at, and reach, the
- * thing being pointed at. `Escape` leaves, which is the one binding a tour
- * needs and the one every reader already tries.
+ * **It measures, and the target is an element elsewhere on the page whose
+ * position nothing can know statically.** Nothing is measured on the server and
+ * nothing needs to be: a tour starts when a reader asks for it.
  *
  * @since 0.1.0
  * @status experimental

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

@@ -5,45 +5,23 @@ declare const HelixHeadlessTreeItem_base: (new (...args: any[]) => import("@fusi
  * @summary One node in a tree.
  *
  * @description
- * **`open`, on `MixinControllerOpen`, rather than a bare boolean of its own.** A
- * branch showing its children is the same state a disclosure holds, and
- * `AccordionItem` is on that mixin too. A hand-written toggle announces nothing,
- * so a consumer can neither know a branch opened nor own the state.
- * `aria-expanded` is still what the row renders, because that is the attribute a
- * tree uses; the property is what differs, not the semantics.
+ * **`open`, on `MixinControllerOpen`, rather than a bare boolean of its own.**
+ * A branch showing its children is the same state a disclosure holds. A
+ * hand-written toggle announces nothing, so a consumer could neither know a
+ * branch opened nor own the state. `aria-expanded` is still what the row
+ * renders: the property differs, not the semantics.
  *
- * An element rather than a slot because it owns state: whether it is open,
- * whether it is selected, and whether it is the one holding focus.
+ * An element rather than a slot, because it owns state: whether it is open,
+ * selected, and whether it holds focus.
  *
  * A branch is any item with something slotted into `children`, detected in
- * `firstUpdated` rather than declared by the consumer. That is a client-side
- * enhancement by necessity, since the server cannot inspect children, so the
- * server renders the node as a leaf and the twisty appears on hydration. It
- * appears rather than disappearing, which is the harmless direction.
+ * `firstUpdated` because the server cannot inspect children. The server renders
+ * the node as a leaf and the twisty appears on hydration, which is the harmless
+ * direction.
  *
- * **`href` makes the row itself the link.** A tree used as navigation is a list
- * of links, and the row is what a reader presses: with the anchor slotted into
- * the name instead, everything outside the words is dead, Enter does nothing,
- * and there is no middle-click, no status bar and no open-in-new-tab. Given an
- * `href` the row *is* an `<a>`, so the platform provides all of that and the
- * keyboard needs no handler at all.
- *
- * It changes the shape of the ARIA, which is why it is a property and not the
- * default. An anchor cannot contain the group, since the group holds more
- * anchors and nesting them is invalid, so the row carries `treeitem` and the
- * group becomes its sibling under a presentational wrapper. That is exactly the
- * navigation flavor of the tree pattern, and the arrangement without an `href`
- * stays as it was: `treeitem` containing `group`, which is what an `<li>`
- * holding a `<ul>` is.
- *
- * A consumer whose framework owns routing slots its own link instead and leaves
- * `href` unset. The row follows that one too, so the whole row works either
- * way; what the anchor adds is what only a real anchor can give.
- *
- * The properties below are written by this component and read by whoever draws
- * it. A consumer sets none of them: they carry a number this element computed
- * and CSS cannot, which is what lets a stylesheet on this tier draw the thing
- * without measuring anything itself.
+ * **`href` makes the row itself the link.** With the anchor slotted into the
+ * name instead, everything outside the words is dead: no Enter, no middle
+ * click, no status bar. Given an `href` the row *is* an `<a>`.
  *
  * @since 0.1.0
  * @status experimental

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

@@ -7,57 +7,29 @@ import '../../menu/index.js';
  *
  * @description
  * **The picture is a real `<video>`.** Decoding, buffering, captions, Picture
- * in Picture, AirPlay and the codecs a device happens to have are all the
- * platform's, and none of them can be had from anything else. What is replaced
- * is the control bar, which is the one part of a video element that cannot be
- * styled and looks different in every browser.
+ * in Picture, AirPlay and whatever codecs a device has are the platform's. What
+ * is replaced is the control bar, which is the one part that cannot be styled.
  *
  * **Every control is a real control.** The scrubber and the volume are
- * `<input type="range">`, so a reader gets arrow keys, Home and End, the
- * platform's own touch target and its screen reader announcement without this
- * element implementing any of it. Drawing a div and listening for pointer moves
- * is how a media player ends up unusable from a keyboard.
+ * `<input type="range">`, so arrow keys, Home and End, the platform's touch
+ * target and its screen reader announcement all come for free.
  *
  * **Native controls are the fallback, not the default.** Where a consumer sets
- * `controls`, the browser's bar is used and this one is not drawn: two sets of
- * controls over one video is worse than either alone, and a consumer who asked
- * for the native bar has a reason.
+ * `controls` the browser's bar is used and this one is not drawn, and the keys
+ * below are not bound: two handlers on one press is a video that seeks twice.
  *
  * The keys are the ones every player uses: Space and `k` to play or pause, the
- * arrows to seek and to change the volume, `m` to mute, `f` for fullscreen.
- * They are bound on this element rather than on the document, because a video
- * is not a palette: keys belong to it only while a reader is on it. Where
- * `controls` is set they are not bound at all, since two handlers on one press
- * is a video that seeks twice, and the focus stop goes with them.
+ * arrows to seek and to change volume, `m` to mute, `f` for fullscreen. They
+ * are bound on this element rather than on the document, because a video is not
+ * a palette.
  *
  * **`<source>` and `<track>` are copied into the video, never slotted into it.**
  * A media element runs resource selection over its own child *nodes*, and a slot
  * is one node, so slotted sources reach it as nothing: no text tracks, no
  * current source, `readyState` zero. A video given sources that way does not
- * merely lack captions, it does not play.
- *
- * They are copied rather than moved, because the consumer's light DOM is theirs
- * and a framework that re-renders it would find its children gone. The copies
- * are rebuilt whenever the slot changes and the video is asked to load again,
- * which is what makes a `<track>` added later take effect.
- *
- * **The lock screen and a headset's buttons work, and one player owns them.**
- * There is one `navigator.mediaSession` per page, so the rule is stated rather
- * than left to render order: whichever player was started last owns it, which
- * is what a reader means by "this one" when they press play on their
- * headphones. The title comes from `label` and the artwork from `poster`.
- *
- * **`remote` sends the picture somewhere else.** The Remote Playback API is
- * what Safari implements for AirPlay and Chrome for Cast, so one control covers
- * both and the platform supplies the device list. It is offered only once
- * something has answered `watchAvailability`: a button that opens an empty list
- * is worse than no button, and a consumer who wants none can set
- * `disableremoteplayback` on this element.
- *
- * The properties below are written by this component and read by whoever draws
- * it. A consumer sets none of them: they carry a number this element computed
- * and CSS cannot, which is what lets a stylesheet on this tier draw the thing
- * without measuring anything itself.
+ * merely lack captions, it does not play. They are copied rather than moved,
+ * because the consumer's light DOM is theirs, and rebuilt whenever the slot
+ * changes.
  *
  * @since 0.1.0
  * @status experimental

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

@@ -7,35 +7,13 @@ import '../../menu/index.js';
  * @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, which is what a full-screen player has and what
- * a phone has room for.
+ * one they open 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
+ * 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:
- *
- * ```html
- * <helix-video-playlist>
- *   <helix-video slot="player" controls>
- *     <helix-video-playlist-menu slot="controls"></helix-video-playlist-menu>
- *   </helix-video>
- *   <helix-video-playlist-item value="one" src="/one.mp4">One</helix-video-playlist-item>
- * </helix-video-playlist>
- * ```
- *
- * So it finds its playlist upward rather than being handed one, and that chain
- * crosses a shadow boundary in the ordinary arrangement, which is why it is
- * `closestInstance` and not `closest`.
- *
- * **Choosing dispatches `helix-select`, the same event an entry dispatches.**
- * It never writes `active` on the playlist, which looks like the shorter path
- * and skips the cancelable request: an assignment applies the change with no
- * `helix-before-activate` for anyone to refuse. Announcing is what an entry
- * does, the playlist already listens for it, and a consumer refusing a
- * selection gets `preventDefault()` on one event rather than two paths that
- * behave differently.
+ * `Video`'s `controls` slot is for.
  *
  * @since 0.1.0
  * @status experimental

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

@@ -10,58 +10,19 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * `<template>` child says what one row looks like: elements carrying
  * `data-field="name"` are filled with that field of the item.
  *
- * Both halves are markup, and that is the whole reason for the shape.
- * `VirtualizeController` says why the obvious alternatives are shut: an `items`
+ * 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. A server
- * emits it, React re-emits it as a child rather than applying it, and it is one
- * node whatever the row count.
+ * could decide not to create them. Text in the document is neither, and it is
+ * one node whatever the row count.
  *
  * **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` and
- * `aria-posinset`, which is what says "four thousand of ten thousand" rather
- * than "four of twenty".
+ * exists to avoid. It is the rendered window plus `aria-setsize`.
  *
- * **Rows are light DOM, deliberately.** They are cloned from the consumer's
- * template and appended to the host, so a document rule reaches them, the base
- * layer applies, and a class in the template means what it says. Cloned into
- * the shadow root they would be markup the consumer wrote and could not style,
- * which is the one thing a row template must not be.
- *
- * **Reading the source is client-only**, because a server has no document to
- * query. The window renders empty from the server and fills on the first update,
- * which is the same client-side enhancement rule every tree-reading component
- * here follows.
- *
- * **On this tier the consumer gives the viewport its box**, and the component
- * cannot do it for them: `helix/headless` ships no stylesheet, and a height is a
- * decision rather than a fact this could publish. So a base list wants two rules
- * before it is a list at all:
- *
- * ```css
- * helix-headless-virtual-list::part(viewport) {
- *   block-size: 12rem;
- *   overflow-y: auto;
- * }
- * ```
- *
- * **Without them it is not a scroller**, and the failure is worse than it
- * sounds. `scrollTop` is always zero, so nothing ever windows; and the box has
- * no height of its own, so `clientHeight` is a function of the rows just drawn.
- * Measuring then moves what is being measured, and the two need not converge:
- * measured in Chromium at 500 rows, it settled into a two-cycle between 378 and
- * 379 rows and stayed there, at two and a half thousand passes in eight seconds.
- * `VirtualizeController` gives up after ten passes and says so, so this now
- * draws a bad window rather than stopping the page, but a bad window is still
- * the answer until the rules are written.
- *
- * The styled tier writes them for you, with `--virtual-list-block-size`.
- *
- * @category layout
  * @since 0.1.0
  * @status experimental
+ * @category layout
  * @documentation https://helix.fusion.dev/components/virtual-list
  *
  * @csspart after - The space standing in for rows below the window.

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.4.2",
+  "version": "0.4.4",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -21,41 +21,40 @@
       "types": "./dist/*/index.d.ts",
       "default": "./dist/*/index.js"
     },
-    "./jsx": "./jsx.d.ts",
-    "./svelte": "./svelte.d.ts",
-    "./vue": "./vue.d.ts"
+    "./custom-elements.json": "./custom-elements.json",
+    "./jsx": "./types/jsx.d.ts",
+    "./svelte": "./types/svelte.d.ts",
+    "./vue": "./types/vue.d.ts"
   },
   "files": [
     "custom-elements.json",
     "dist",
-    "jsx.d.ts",
-    "svelte.d.ts",
-    "vue.d.ts"
+    "types"
   ],
   "customElements": "custom-elements.json",
-  "sideEffects": [
-    "./dist/**/*.js"
-  ],
+  "sideEffects": true,
   "scripts": {
-    "analyze": "cem analyze --config custom-elements-manifest.config.ts",
-    "build": "tsc -p tsconfig.json && tsc -p tsconfig.types.json",
-    "test": "bun run test:pure && bun run test:dom && bun run test:ssr",
+    "analyze": "bun --bun cem analyze --config cem.config.ts",
+    "build": "bun run element-events && tsc -p tsconfig.build.json && tsc -p tsconfig.types.json",
+    "element-events": "build-element-events --package headless",
+    "test": "bun run element-events && bun run test:pure && bun run test:dom && bun run test:ssr",
     "test:dom": "bun test dom.spec",
     "test:pure": "bun test pure.spec",
     "test:ssr": "bun test ssr.spec",
-    "typecheck": "tsc -p tsconfig.json --noEmit"
+    "typecheck": "bun run element-events && tsc -p tsconfig.json --noEmit"
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.4.2",
-    "@fusion.dev/helix-icons": "0.4.2",
+    "@fusion.dev/helix-core": "0.4.4",
+    "@fusion.dev/helix-icons": "0.4.4",
     "uqr": "^0.1.3"
   },
   "devDependencies": {
     "@custom-elements-manifest/analyzer": "^0.11.0",
+    "@fusion.dev/helix-cem": "0.4.4",
+    "@fusion.dev/helix-testing": "0.4.4",
+    "@fusion.dev/scripts": "0.0.0-dev",
     "@happy-dom/global-registrator": "^20.0.0",
-    "@fusion.dev/helix-cem": "0.4.2",
-    "@fusion.dev/helix-testing": "0.4.2",
     "@lit-labs/ssr": "^3.3.0",
     "@types/bun": "^1.3.0",
     "lit": "^3.2.1"