@fusion.dev/helix 0.104.1 → 0.106.0

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

@@ -2,28 +2,28 @@ import { HelixHeadlessTourStop } from '@fusion.dev/helix-headless/tour';
 import type { CSSResultGroup } from 'lit';
 import '../../button/index.js';
 /**
- * @summary One stop on a tour: what it points at, and a panel to say it in.
+ * @summary One stop on a tour: the element it points at, and a panel of content about it.
  *
  * @description
- * The panel is `Popover`'s panel by another name, on purpose: a surface, an
- * inset and a lift, so a stop and a flyout on the same page are the same
- * object. What this tier adds beyond that is the point, which no other surface
- * here draws.
+ * The panel uses the same styles as `Popover`'s panel, with a surface, an
+ * inset, and a shadow, so a stop matches a popover on the same page. The styled
+ * tier adds the pointer toward the target, which no other Helix surface draws.
  *
  * @since 0.1.0
  * @status stable
  * @category overlays
  * @documentation https://fusion.dev/helix/components/tour
  *
- * @cssproperty --tour-arrow-size - The point's box, before it is rotated.
- * @cssproperty --tour-border-width - Width of the panel's edge. Follows
- *   `--helix-border-floating`, which is `0`, so the panel is told apart by its lift unless a
- *   theme says otherwise.
- * @cssproperty --tour-bubble-size - How wide the panel may grow.
- * @cssproperty --tour-padding - Inset inside the panel.
- * @cssproperty --tour-shadow - Lift under the panel. Follows `--helix-shadow-floating`: a
- *   floating surface sits over content nobody can predict, so it keeps a lift by default.
- * @cssproperty --tour-surface-color - The panel's own surface.
+ * @cssproperty --tour-arrow-size - The size of the arrow's box, before it is rotated.
+ * @cssproperty --tour-border-width - The width of the panel's border. It follows
+ *   `--helix-border-floating`, which is `0`, so the panel stands out by its
+ *   shadow unless a theme sets a border.
+ * @cssproperty --tour-bubble-size - The widest the panel can grow.
+ * @cssproperty --tour-padding - The padding inside the panel.
+ * @cssproperty --tour-shadow - The shadow under the panel. It follows
+ *   `--helix-shadow-floating`. The panel can sit over any content, so it has a
+ *   shadow by default.
+ * @cssproperty --tour-surface-color - The color of the panel's surface.
  */
 export declare class HelixTourStop extends HelixHeadlessTourStop {
     static tier: string;

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

@@ -4,14 +4,11 @@ import type { CSSResultGroup } from 'lit';
  * @summary One node in a tree.
  *
  * @description
- * Indent comes from the `level` the tree sets, as a multiple of one hook, so a
- * node moved to another depth re-indents without any nested selector. Nesting
- * selectors by depth is the usual approach and stops working at whatever depth
- * nobody wrote a rule for.
+ * Indentation is a multiple of one hook, set from the `level` the tree assigns,
+ * so an item moved to another depth re-indents with no nested selectors, at any
+ * depth.
  *
- * The twisty rotates rather than swapping glyphs, so opening a branch is a
- * short movement instead of a substitution. Motion carries the state change;
- * the row itself stays flat.
+ * The twisty rotates when a branch opens. The row itself stays flat.
  *
  * @since 0.1.0
  * @status stable
@@ -21,7 +18,7 @@ import type { CSSResultGroup } from 'lit';
  * @slot - The item's label.
  * @slot children - Nested items, which make this a branch.
  *
- * @event {HelixSelectEvent} helix-select - Fired when the item is chosen. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixSelectEvent} helix-select - Fired when the item is chosen, and cancelable. Canceling it changes nothing.
  *
  * @csspart group - The container for nested items.
  * @csspart item - The node, and the focus target.
@@ -32,7 +29,7 @@ import type { CSSResultGroup } from 'lit';
  * @cssproperty --tree-chevron-size - Size of the chevron, and the gutter a leaf reserves.
  * @cssproperty --tree-gap - Space between rows.
  * @cssproperty --tree-indent - Indent added per level.
- * @cssproperty --tree-row-size - Least height of a row, so rows with and without an icon match.
+ * @cssproperty --tree-row-size - Minimum height of a row, so rows with and without an icon match.
  */
 export declare class HelixTreeItem extends HelixHeadlessTreeItem {
     static styles: CSSResultGroup;

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

@@ -1,12 +1,11 @@
 import { HelixHeadlessTree } from '@fusion.dev/helix-headless/tree';
 import type { CSSResultGroup } from 'lit';
 /**
- * @summary A tree of items, navigable entirely from the keyboard.
+ * @summary A hierarchy of items, with branches that open and close.
  *
  * @description
  * Quiet by default: no rules between rows and no fill except on the selected
- * item. A navigation tree is read by scanning, and every line of chrome added
- * to it is one more thing between the reader and the label.
+ * item, so the labels are easy to scan.
  *
  * @since 0.1.0
  * @status stable
@@ -16,17 +15,17 @@ import type { CSSResultGroup } from 'lit';
  *
  * @slot - The tree's items.
  *
- * @event {HelixSelectEvent} helix-select - Fired when an item is chosen. Dispatched by the item and listened for here, because the tree is what a consumer holds a reference to. Cancelable: refusing it takes the decision and nothing moves.
+ * @event {HelixSelectEvent} helix-select - Fired when an item is chosen. The item sends it, and you can listen for it on the tree. Cancelable: canceling it changes nothing.
  *
- * @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 live - A copy of the empty and loading messages, in a live region that announces them when they change. Visually hidden in the styled tier.
  * @csspart tree - The tree container.
  *
- * @cssproperty --tree-chevron-gap - Set from `chevron-placement`; the space before the chevron.
- * @cssproperty --tree-chevron-order - Set from `chevron-placement`; read by each item.
+ * @cssproperty --tree-chevron-gap - The space before the chevron. Set from `chevron-placement`.
+ * @cssproperty --tree-chevron-order - The chevron's order in the row. Set from `chevron-placement` and read by each item.
  * @cssproperty --tree-chevron-size - Size of the chevron, and the gutter a leaf reserves.
  * @cssproperty --tree-gap - Space between rows.
  * @cssproperty --tree-indent - Indent added per level.
- * @cssproperty --tree-row-size - Least height of a row, so rows with and without an icon match.
+ * @cssproperty --tree-row-size - Minimum height of a row, so rows with and without an icon match.
  */
 export declare class HelixTree extends HelixHeadlessTree {
     /**

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

@@ -2,28 +2,21 @@ import { HelixHeadlessTrend } from '@fusion.dev/helix-headless/trend';
 import type { CSSResultGroup } from 'lit';
 import '../../icon/index.js';
 /**
- * @summary Which way a measurement moved, and whether that is good news.
+ * @summary An indicator that shows which way a measurement moved, and whether the change is good.
  *
  * @description
- * The arrow takes the judgment color and the number does not, which is the
- * opposite of the dashboard convention and is measured rather than preferred:
- * in light mode the success token is 3.8:1 on the surface, enough for a glyph
- * and short of what 13px text needs, and there is no darker green in the ramp.
- * The number therefore keeps the page's own foreground and stays the most
- * legible thing here, which is right anyway, since the number is what a reader
- * reads and the judgment is a gloss on it.
+ * The arrow takes the judgment color and the number keeps the foreground color.
+ * In light mode the success token has 3.8:1 contrast on the surface, enough for
+ * a glyph and short of what 13px text needs, and the ramp has no darker green.
+ * The number stays the most legible part.
  *
- * **No visual axis applies here, and that is the answer rather than a gap.**
- * `emphasis` is how much ink a mark claims, and there is no mark: an arrow glyph
- * and two runs of text, whose weight is `Text`'s business and whose size is the
- * region's. `material` is what reads through a surface, and a 13px glyph has
- * nothing behind it. `wash` is a gradient across an area, and there is no area.
+ * Trend has no `emphasis`, `material`, or `wash`. It has no mark for emphasis,
+ * no surface for material, and no area for a wash. The text weight comes from
+ * `Text` and the size from the region.
  *
- * The meaning axis is here and is *derived*, which is the more interesting half:
- * `direction` and `good` together resolve to success, danger or muted, so a
- * consumer states the metric's polarity once rather than picking a color. A
- * declared `tone` would let the color disagree with the arrow, which is the one
- * thing this component exists to stop.
+ * The meaning axis is derived: `direction` and `good` resolve to success,
+ * danger, or muted, so you state the metric's polarity once. There is no
+ * `tone`, because a declared tone could disagree with the arrow.
  *
  * @since 0.1.0
  * @status stable
@@ -32,7 +25,7 @@ import '../../icon/index.js';
  * @aliases Delta, Change, Movement
  * @documentation https://fusion.dev/helix/components/trend
  *
- * @cssproperty --trend-color - Color of the arrow, overriding the judgment.
+ * @cssproperty --trend-color - Color of the arrow. Setting it overrides the color that `good` sets.
  * @cssproperty --trend-icon-size - Size of the arrow.
  */
 export declare class HelixTrend extends HelixHeadlessTrend {

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

@@ -3,39 +3,33 @@ import type { CSSResultGroup } from 'lit';
 import '../../icon/index.js';
 import '../../menu/index.js';
 /**
- * @summary Plays a video, with controls this library draws rather than the
- * browser's.
+ * @summary A video player with controls drawn by Helix.
  *
  * @description
- * The player is the headless tier's. What this adds is the bar: where it sits, when
- * it is there, and what the two ranges look like, which is the whole reason to
- * replace a control set that cannot be styled.
+ * The player comes from the headless tier. This tier adds the control bar:
+ * where it sits, when it shows, and how the two ranges look.
  *
- * **The bar is over the picture, not under it.** A bar in the layout would move
- * everything below the video by its own height and would leave a strip of page
- * color under a picture that is meant to be the whole of it. Over it, the
- * video is the component's size and the controls belong to it.
+ * The bar sits over the picture, so the video keeps its own size and nothing
+ * below it moves.
  *
- * **It goes when nobody is using it, and comes back for the keyboard.** Hidden
- * once a playing video has gone `idle-delay` without being touched, shown again
- * the moment the pointer moves, and shown whenever anything inside it has
- * focus, which is what keeps it reachable without a pointer. A paused video
- * keeps its bar, because a reader who stopped it is deciding what to do next.
+ * The bar hides once a playing video has gone `idle-delay` without input. It
+ * shows again when the pointer moves, and whenever anything inside it has
+ * focus, so you can reach it with the keyboard. A paused video keeps its bar.
  *
  * @since 0.1.0
  * @status stable
  * @category media
  * @documentation https://fusion.dev/helix/components/video
  *
- * @cssproperty --video-accent-color - The played part of the scrubber.
+ * @cssproperty --video-accent-color - Color of the played part of the scrubber.
  * @cssproperty --video-aspect-ratio - The shape of the box. Defaults to the
  * video's own once known, and `16 / 9` until then.
- * @cssproperty --video-controls-color - The ink on the bar.
- * @cssproperty --video-radius - The corner it is cut to.
- * @cssproperty --video-speed-size - How wide the playback speed control is
- * held, so the row does not move when the number changes.
- * @cssproperty --video-start-size - Width of the mark that starts it.
- * @cssproperty --video-well-color - Behind the picture, and in the letterbox bars.
+ * @cssproperty --video-controls-color - Color of the icons and text on the control bar.
+ * @cssproperty --video-radius - Corner radius of the player.
+ * @cssproperty --video-speed-size - Width of the playback speed control, fixed so the row
+ * does not shift when the number changes.
+ * @cssproperty --video-start-size - Width of the large play button.
+ * @cssproperty --video-well-color - Color behind the picture and in the letterbox bars.
  */
 export declare class HelixVideo extends HelixHeadlessVideo {
     /**

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

@@ -4,16 +4,16 @@ import type { CSSResultGroup } from 'lit';
  * @summary One entry in a video playlist.
  *
  * @description
- * Presentation only: the row, its thumbnail column, and the mark on the one
- * playing. The base class holds what the entry is and what it announces.
+ * Styles the row, its thumbnail column, and the marker on the playing entry.
+ * The base class holds the entry's data and its accessibility semantics.
  *
  * @since 0.1.0
  * @status stable
  * @category media
  * @documentation https://fusion.dev/helix/components/video-playlist
  *
- * @cssproperty --video-playlist-item-background-color - Fill behind a row.
- * @cssproperty --video-playlist-media-size - Width of the thumbnail column.
+ * @cssproperty --video-playlist-item-background-color - The fill behind a row.
+ * @cssproperty --video-playlist-media-size - The width of the thumbnail column.
  */
 export declare class HelixVideoPlaylistItem extends HelixHeadlessVideoPlaylistItem {
     static styles: CSSResultGroup;

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

@@ -6,21 +6,19 @@ import '../../menu/index.js';
  * @summary The playlist's entries, as a menu inside the player's control bar.
  *
  * @description
- * Presentation only: a control-bar button drawn like the ones beside it, and a
- * menu that opens over the picture rather than under it. The base class holds
- * where the playlist is, what the entries are, and what choosing announces.
+ * Styles the trigger as a control-bar button like the ones beside it, and opens
+ * the menu over the video. The base class holds the link to the playlist, the
+ * entries, and what a screen reader announces when you choose one.
  *
- * The trigger's declarations are `Video`'s control rule written out a second
- * time, which is not duplication that could be avoided. That rule is
- * `[part="controls"] :where(a, button)` inside `Video`'s shadow root, and this
- * element sits in its light DOM: a shadow rule reaches an assigned node only
- * through `::slotted()` and never reaches into the node's own shadow root at
- * all. So the button here is two boundaries away from the rule that styles
- * every button beside it, and the same tokens are what make the two agree.
+ * The trigger repeats the declarations of `Video`'s control rule,
+ * `[part="controls"] :where(a, button)`. That rule is inside `Video`'s shadow
+ * root, and this element is in its light DOM. A shadow rule reaches a slotted
+ * node only through `::slotted()` and never reaches into that node's own shadow
+ * root, so the rule cannot style this button. Shared tokens keep the two
+ * buttons consistent.
  *
- * Color is inherited rather than named, so the bar's own color arrives on
- * its own. `--video-playlist-menu-color` is there for the case where it should
- * not.
+ * Color is inherited from the control bar. To set a different color, use
+ * `--video-playlist-menu-color`.
  *
  * @since 0.1.0
  * @status stable
@@ -28,9 +26,9 @@ import '../../menu/index.js';
  * @aliases Episode Menu, Queue Menu, Up Next
  * @documentation https://fusion.dev/helix/components/video-playlist
  *
- * @cssproperty --video-playlist-menu-color - Color of the trigger, defaulting to the control bar's.
- * @cssproperty --video-playlist-menu-poster - Width of an entry's still.
- * @cssproperty --video-playlist-menu-size - Size of the trigger's glyph.
+ * @cssproperty --video-playlist-menu-color - The color of the trigger. Defaults to the control bar's color.
+ * @cssproperty --video-playlist-menu-poster - The width of an entry's poster image.
+ * @cssproperty --video-playlist-menu-size - The size of the trigger's icon.
  */
 export declare class HelixVideoPlaylistMenu extends HelixHeadlessVideoPlaylistMenu {
     static tier: string;

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

@@ -1,11 +1,11 @@
 import { HelixHeadlessVideoPlaylist } from '@fusion.dev/helix-headless/video-playlist';
 import type { CSSResultGroup } from 'lit';
 /**
- * @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
- * Presentation only: the arrangement of the two regions and the scroller the
- * entries sit in. Everything about which clip is current is the base class.
+ * Styles the layout of the two regions and the scroller that holds the entries.
+ * The base class tracks which clip is current.
  *
  * @since 0.1.0
  * @status stable
@@ -13,8 +13,8 @@ import type { CSSResultGroup } from 'lit';
  * @aliases Playlist, Queue, Up next
  * @documentation https://fusion.dev/helix/components/video-playlist
  *
- * @cssproperty --video-playlist-layout - Columns for the player and the list.
- * @cssproperty --video-playlist-size - How tall the list gets before it scrolls.
+ * @cssproperty --video-playlist-layout - The grid columns for the player and the list.
+ * @cssproperty --video-playlist-size - The height the list reaches before it scrolls.
  */
 export declare class HelixVideoPlaylist extends HelixHeadlessVideoPlaylist {
     static styles: CSSResultGroup;

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

@@ -1,22 +1,20 @@
 import { HelixHeadlessVirtualList } from '@fusion.dev/helix-headless/virtual-list';
 import type { CSSResultGroup } 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 styled tier adds the scrolling box's own treatment and nothing else. Rows
- * are the consumer's markup in the light DOM, so they are styled by the
- * consumer's stylesheet the way any other content is, and this must not reach
- * into them: a rule here for a row would be a design system styling markup it
- * did not write.
+ * The styled tier styles only the scrolling box. Rows are your markup in the
+ * light DOM, so your stylesheet styles them the same as any other content, and
+ * this tier sets no rules for them.
  *
  * @category layout
  * @since 0.1.0
  * @status stable
  * @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 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.
  *
  * @cssproperty --virtual-list-block-size - How tall the scrolling box is.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix",
   "description": "Styled component tier. Extends the headless tier with token-driven presentation.",
-  "version": "0.104.1",
+  "version": "0.106.0",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -47,13 +47,13 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "dependencies": {
-    "@fusion.dev/helix-core": "0.104.1",
-    "@fusion.dev/helix-headless": "0.104.1",
-    "@fusion.dev/helix-styles": "0.104.1"
+    "@fusion.dev/helix-core": "0.106.0",
+    "@fusion.dev/helix-headless": "0.106.0",
+    "@fusion.dev/helix-styles": "0.106.0"
   },
   "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",