@fusion.dev/helix-headless 0.144.0 → 0.145.0

package/dist/tabs/tab/tab.js

@@ -4,31 +4,74 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { customElement, HelixElement, MixinSelectableItem } from '@fusion.dev/helix-core';
-import { html } from 'lit';
+import { customElement, HelixElement, MixinSelectableItem, reflectElements, } from '@fusion.dev/helix-core';
+import { html, nothing } from 'lit';
+import { property } from 'lit/decorators.js';
 let HelixHeadlessTab = class HelixHeadlessTab extends MixinSelectableItem(HelixElement) {
     constructor() {
         super(...arguments);
         this.itemPart = 'tab';
+        this.controls = undefined;
+        this.handleLinkClick = (event) => {
+            if (event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
+                return;
+            }
+            if (!this.select()) {
+                event.preventDefault();
+            }
+        };
+    }
+    updated(changed) {
+        super.updated(changed);
+        const control = this.renderRoot.querySelector('[part="tab"]');
+        reflectElements(control, 'ariaControlsElements', this.controls ? [this.controls] : [], true);
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
         this.finishHydration();
     }
     render() {
+        const tabindex = this.selected || !this.childrenKnown ? '0' : '-1';
+        if ((this.href ?? '') !== '') {
+            return html `<a
+        part="tab"
+        role="tab"
+        href=${this.disabled ? nothing : (this.href ?? nothing)}
+        target=${this.target || nothing}
+        rel=${this.rel || nothing}
+        aria-selected=${this.selected ? 'true' : 'false'}
+        aria-disabled=${this.disabled ? 'true' : nothing}
+        tabindex=${this.disabled ? nothing : tabindex}
+        @click=${this.handleLinkClick}
+      >
+        <slot></slot>
+      </a>`;
+        }
         return html `<button
       part="tab"
       role="tab"
       type="button"
       aria-selected=${this.selected ? 'true' : 'false'}
       ?disabled=${this.disabled}
-      tabindex=${this.selected || !this.childrenKnown ? '0' : '-1'}
+      tabindex=${tabindex}
       @click=${() => this.select()}
     >
       <slot></slot>
     </button>`;
     }
 };
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessTab.prototype, "controls", void 0);
+__decorate([
+    property()
+], HelixHeadlessTab.prototype, "href", void 0);
+__decorate([
+    property()
+], HelixHeadlessTab.prototype, "rel", void 0);
+__decorate([
+    property()
+], HelixHeadlessTab.prototype, "target", void 0);
 HelixHeadlessTab = __decorate([
     customElement('helix-headless-tab')
 ], HelixHeadlessTab);

package/dist/timeline/group/timeline-group.d.ts

@@ -0,0 +1,46 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * @summary A run of timeline entries under a heading, such as a day.
+ *
+ * @description
+ * Groups entries by date, such as "Today" and "Yesterday", in a timeline that
+ * holds many. The group is an entry of the timeline, and its entries are a
+ * list of their own, named by the heading. A screen reader lists the heading
+ * with the page's headings and hears how many entries each day holds.
+ *
+ * The heading's level is `heading-level`, and 3 where it is not set.
+ *
+ * Each group draws its own line, so the line stops at the last entry of one
+ * day and starts again at the first entry of the next.
+ *
+ * @since 0.1.0
+ * @status stable
+ * @aliases Day, Section, Date group
+ * @documentation https://fusion.dev/helix/components/timeline
+ *
+ * @slot - The entries.
+ * @slot heading - The heading, when it is more than text. Falls back to `label`.
+ *
+ * @csspart entries - The list that holds the entries.
+ * @csspart heading - The heading.
+ */
+export declare class HelixHeadlessTimelineGroup extends HelixElement {
+    /**
+     * The level of the group's heading, from 1 to 6.
+     */
+    headingLevel?: number;
+    /**
+     * The heading, when it is plain text, such as "Today".
+     *
+     * The fallback of the `heading` slot, so slotted content replaces it.
+     */
+    label: string;
+    protected willUpdate(changed: PropertyValues): void;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-timeline-group': HelixHeadlessTimelineGroup;
+    }
+}

package/dist/timeline/group/timeline-group.js

@@ -0,0 +1,37 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+import { customElement, HelixElement, hostAria } from '@fusion.dev/helix-core';
+import { html } from 'lit';
+import { property } from 'lit/decorators.js';
+const HEADING_ID = 'heading';
+let HelixHeadlessTimelineGroup = class HelixHeadlessTimelineGroup extends HelixElement {
+    constructor() {
+        super(...arguments);
+        this.label = '';
+    }
+    willUpdate(changed) {
+        super.willUpdate(changed);
+        hostAria(this.internals, { role: 'listitem' });
+    }
+    render() {
+        const level = Math.min(6, Math.max(1, Math.trunc(this.headingLevel ?? 3)));
+        return html `<div part="heading" id=${HEADING_ID} role="heading" aria-level=${level}>
+        <slot name="heading">${this.label}</slot>
+      </div>
+      <div part="entries" role="list" aria-labelledby=${HEADING_ID}><slot></slot></div>`;
+    }
+};
+__decorate([
+    property({ attribute: 'heading-level', type: Number })
+], HelixHeadlessTimelineGroup.prototype, "headingLevel", void 0);
+__decorate([
+    property()
+], HelixHeadlessTimelineGroup.prototype, "label", void 0);
+HelixHeadlessTimelineGroup = __decorate([
+    customElement('helix-headless-timeline-group')
+], HelixHeadlessTimelineGroup);
+export { HelixHeadlessTimelineGroup };

package/dist/timeline/index.d.ts

@@ -1,2 +1,3 @@
+export * from './group/timeline-group.js';
 export * from './item/timeline-item.js';
 export * from './root/timeline-root.js';

package/dist/timeline/index.js

@@ -1,2 +1,3 @@
+export * from './group/timeline-group.js';
 export * from './item/timeline-item.js';
 export * from './root/timeline-root.js';

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

@@ -16,8 +16,15 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * The host has `role="list"`, because the entries are your elements in the
  * light DOM. `Steps` does the same.
  *
- * A timeline runs down the page and has no horizontal layout. For stages laid
- * out horizontally, use `Steps`, which is horizontal by default.
+ * **Group entries by date with `Timeline.Group`**, which puts a heading such as
+ * "Today" over its entries. The group is an entry of the timeline, and its
+ * entries are a list of their own named by the heading.
+ *
+ * **The reading order is the order you write the entries in**, in every layout
+ * the styled tier draws: down the page, either side of a line down the middle,
+ * or across the page. Inside each entry the time is read before what happened.
+ * Write the entries in the order the events happened, oldest or newest first,
+ * and the layout only moves where they are drawn.
  *
  * @since 0.1.0
  * @status stable
@@ -25,7 +32,7 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @aliases Activity feed, History, Changelog, Audit trail
  * @documentation https://fusion.dev/helix/components/timeline
  *
- * @slot - The entries.
+ * @slot - The entries, and any groups of them.
  */
 export declare class HelixHeadlessTimeline extends HelixElement {
     /**

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

@@ -78,11 +78,16 @@ export declare class HelixHeadlessToastItem extends HelixHeadlessToastItem_base
     protected readonly swipes: SwipeController;
     /** Writes how far a swipe has moved the message toward the end of the line. */
     private slide;
-    /** When the current run of the timer began, or nothing while it is paused. */
-    private startedAt;
-    /** What is left of the duration, so resuming continues rather than restarts. */
-    private remaining;
-    private timer;
+    /**
+     * The dismiss timer, which pauses while a reader is on the message and
+     * continues from what was left.
+     *
+     * Paused is said on the host so the indicator can freeze with the clock. A
+     * `data-` attribute rather than a property, because it is written after
+     * upgrade from a pointer moving: nothing declares it and no server rendered
+     * it, which is the same reason `Carousel` names its slides from here.
+     */
+    private readonly countdown;
     /**
      * The kind of message, which sets its mark and the mark's accessible name.
      *
@@ -104,21 +109,9 @@ export declare class HelixHeadlessToastItem extends HelixHeadlessToastItem_base
     pause(): void;
     /** Restarts the dismiss timer from where it paused. */
     resume(): void;
-    /**
-     * How many reasons there are to hold the clock, rather than whether there is
-     * one.
-     *
-     * Hover and focus stop the same timer, and the two are genuinely independent:
-     * a pointer can leave while focus stays, and focus can leave while the
-     * pointer stays. Uncounted, a reader who tabs into a message and then moves
-     * the pointer off it has the clock restarted underneath them, which is the
-     * case the pause exists for. Only the last one out starts it again.
-     */
-    private holds;
     private readonly handlePause;
     private readonly handleResume;
     connectedCallback(): void;
-    disconnectedCallback(): void;
     protected willUpdate(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;
     protected firstUpdated(changed: PropertyValues): void;

package/dist/toast/item/toast-item.js

@@ -4,7 +4,7 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
-import { customElement, drawDismiss, drawDismissGlyph, HelixElement, hostAria, isRtl, MixinDismissible, requestChange, SwipeController, settleSwipe, swipeEdge, toneMark, towardEdge, } from '@fusion.dev/helix-core';
+import { CountdownController, customElement, drawDismiss, drawDismissGlyph, HelixElement, hostAria, isRtl, MixinDismissible, requestChange, SwipeController, settleSwipe, swipeEdge, toneMark, towardEdge, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
@@ -31,17 +31,20 @@ let HelixHeadlessToastItem = class HelixHeadlessToastItem extends MixinDismissib
             start: (_target, event) => event.pointerType !== 'mouse',
             surface: () => this.partNamed('item'),
         });
+        this.countdown = new CountdownController(this, {
+            done: () => {
+                this.dismiss();
+            },
+            paused: (paused) => {
+                this.toggleAttribute('data-paused', paused);
+            },
+        });
         this.openState = undefined;
-        this.holds = 0;
         this.handlePause = () => {
-            this.holds += 1;
-            this.pause();
+            this.countdown.hold();
         };
         this.handleResume = () => {
-            this.holds = Math.max(this.holds - 1, 0);
-            if (this.holds === 0) {
-                this.resume();
-            }
+            this.countdown.release();
         };
     }
     get open() {
@@ -60,8 +63,7 @@ let HelixHeadlessToastItem = class HelixHeadlessToastItem extends MixinDismissib
         if (!this.open) {
             return true;
         }
-        clearTimeout(this.timer);
-        this.timer = undefined;
+        this.countdown.cancel();
         return requestChange({
             apply: () => {
                 const previous = this.open;
@@ -74,25 +76,10 @@ let HelixHeadlessToastItem = class HelixHeadlessToastItem extends MixinDismissib
         });
     }
     pause() {
-        if (this.timer === undefined || this.startedAt === undefined) {
-            return;
-        }
-        clearTimeout(this.timer);
-        this.timer = undefined;
-        this.remaining = Math.max((this.remaining ?? 0) - (Date.now() - this.startedAt), 0);
-        this.startedAt = undefined;
-        this.toggleAttribute('data-paused', true);
+        this.countdown.pause();
     }
     resume() {
-        if (this.timer !== undefined || this.remaining === undefined || this.remaining <= 0) {
-            return;
-        }
-        this.startedAt = Date.now();
-        this.toggleAttribute('data-paused', false);
-        this.timer = setTimeout(() => {
-            this.timer = undefined;
-            this.dismiss();
-        }, this.remaining);
+        this.countdown.resume();
     }
     connectedCallback() {
         super.connectedCallback();
@@ -100,11 +87,6 @@ let HelixHeadlessToastItem = class HelixHeadlessToastItem extends MixinDismissib
             this.resume();
         }
     }
-    disconnectedCallback() {
-        super.disconnectedCallback();
-        this.pause();
-        this.holds = 0;
-    }
     willUpdate(changed) {
         super.willUpdate(changed);
         this.toggleAttribute('data-closed', !this.open);
@@ -122,10 +104,7 @@ let HelixHeadlessToastItem = class HelixHeadlessToastItem extends MixinDismissib
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
-        if (this.duration !== undefined && this.duration > 0) {
-            this.remaining = this.duration;
-            this.resume();
-        }
+        this.countdown.start(this.duration);
     }
     renderIcon(mark) {
         return html `<slot name="icon">

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

@@ -12,6 +12,14 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * focus counts as a control, including your own elements. A child that takes no
  * focus, such as a divider, is skipped. A menu is reached at its trigger.
  *
+ * Controls inside a plain wrapper, such as a `Button Group`, are each a stop
+ * of the toolbar's own, as React Aria's toolbar flattens a group: the arrows
+ * walk through the group's buttons and on past it, and the group takes no tab
+ * stop of its own.
+ *
+ * The arrows wrap from the last control to the first. Set `stop-at-ends` to
+ * keep them at the ends, as Radix's `loop` set to false does.
+ *
  * A nested composite, such as a toggle group, is one stop on the toolbar's
  * axis: the toolbar's arrows move past it, and the arrows across the toolbar
  * move inside it. A composite with a `focusable` property, as Toggle Group
@@ -49,6 +57,11 @@ export declare class HelixHeadlessToolbar extends HelixElement {
      * The direction the arrow keys move focus in.
      */
     orientation?: 'horizontal' | 'vertical';
+    /**
+     * Whether the arrow keys stop at the first and the last control. Unset, they
+     * wrap around from one end to the other.
+     */
+    stopAtEnds: boolean;
     private watcher;
     /**
      * The children that take part in the toolbar, in document order, each with

package/dist/toolbar/root/toolbar-root.js

@@ -31,6 +31,7 @@ let HelixHeadlessToolbar = class HelixHeadlessToolbar extends HelixElement {
             target: () => this.partNamed('toolbar'),
         });
         this.wroteForeign = false;
+        this.stopAtEnds = false;
         this.handleFocusIn = (event) => {
             const control = this.origin(event);
             if (control) {
@@ -75,11 +76,14 @@ let HelixHeadlessToolbar = class HelixHeadlessToolbar extends HelixElement {
                 return;
             }
             let next = current;
+            const last = controls.length - 1;
             if (forward) {
-                next = (current + 1) % controls.length;
+                next = this.stopAtEnds ? Math.min(current + 1, last) : (current + 1) % controls.length;
             }
             else if (back) {
-                next = (current - 1 + controls.length) % controls.length;
+                next = this.stopAtEnds
+                    ? Math.max(current - 1, 0)
+                    : (current - 1 + controls.length) % controls.length;
             }
             else if (event.key === 'Home') {
                 next = 0;
@@ -110,9 +114,12 @@ let HelixHeadlessToolbar = class HelixHeadlessToolbar extends HelixElement {
                 child.getAttribute('aria-hidden') === 'true') {
                 continue;
             }
-            const stops = takesFocus(child) ? this.inside(child) : this.within(child);
-            if (stops.length > 0) {
-                controls.push({ child, stops });
+            if (takesFocus(child)) {
+                controls.push({ child, stops: this.inside(child) });
+                continue;
+            }
+            for (const stop of this.within(child)) {
+                controls.push({ child: stop, stops: [stop] });
             }
         }
         return controls;
@@ -204,6 +211,9 @@ __decorate([
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessToolbar.prototype, "orientation", void 0);
+__decorate([
+    property({ attribute: 'stop-at-ends', type: Boolean })
+], HelixHeadlessToolbar.prototype, "stopAtEnds", void 0);
 HelixHeadlessToolbar = __decorate([
     customElement('helix-headless-toolbar')
 ], HelixHeadlessToolbar);

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

@@ -23,21 +23,33 @@ declare const HelixHeadlessTreeItem_base: (new (...args: any[]) => import("@fusi
  * a `value` is chosen as well and sends `helix-select`, unless the tree has
  * `nesting="heading"`, where a branch names the list under it.
  *
+ * A `disabled` item is reached by the arrow keys and announced as unavailable,
+ * and a press, Enter or Space on it does nothing.
+ *
+ * A `lazy` item is a branch whose children you load when it opens: opening it
+ * sends `helix-load`, the row says it is busy, and the children you add appear
+ * in it. Remove `lazy` once they are in.
+ *
  * @since 0.1.0
  * @status stable
  * @aliases TreeNode, Branch, Leaf
  * @documentation https://fusion.dev/helix/components/tree
  *
  * @slot - The item's label.
+ * @slot chevron - Replaces the expand and collapse mark of a branch, such as with your own icon.
  * @slot children - Nested items, which make this a branch.
  * @slot end - Content after the label, at the far side of the row, such as a count or a state.
  * @slot start - Content before the label and after the chevron, such as a mark for the item.
  *
  * @event {HelixBeforeCloseEvent} helix-before-close - Fired before a branch closes, and cancelable.
  * @event {HelixBeforeOpenEvent} helix-before-open - Fired before a branch opens, and cancelable.
+ * @event {HelixLoadEvent} helix-load - Fired when a `lazy` item opens, so you can load its children.
  * @event {HelixSelectEvent} helix-select - Fired when the item is chosen, and cancelable. Canceling it changes nothing.
  * @event {ToggleEvent} toggle - Sent when the branch opens or closes, with `newState` and `oldState`.
  *
+ * @csspart checkbox - The check mark's box, in a tree with `selection-mode="multiple"`.
+ * @csspart checkbox-checked - The check mark's box while the item is checked.
+ * @csspart checkbox-mixed - The check mark's box while some of a branch's items are checked.
  * @csspart group - The container for nested items.
  * @csspart item - The node, and the focus target unless `href` moves it to the row.
  * @csspart label - The label text.
@@ -46,10 +58,26 @@ declare const HelixHeadlessTreeItem_base: (new (...args: any[]) => import("@fusi
  *
  * @cssproperty --tree-level - How deep this row sits, counting from one as `aria-level` does, for the indent.
  *
+ * @cssstate loading - While a `lazy` item is open and its children have not arrived.
  * @cssstate open - While its children are shown.
  * @cssstate selected - While it is selected.
  */
 export declare class HelixHeadlessTreeItem extends HelixHeadlessTreeItem_base {
+    /**
+     * @internal Set by the tree: whether the item draws a check mark and is
+     * checked rather than selected, as under `selection-mode="multiple"`.
+     */
+    checkable: boolean;
+    /**
+     * @internal Set by the tree in `selection-mode="multiple"`: whether the item
+     * is checked, `mixed` for a branch some of whose items are.
+     */
+    checked: boolean | 'mixed';
+    /**
+     * Whether the item cannot be chosen, opened or followed. The arrow keys still
+     * reach it, so a reader knows it is there.
+     */
+    disabled: boolean;
     /**
      * @internal Set by the tree: whether a branch heads the list under it, as
      * under `nesting="heading"`. Such a branch only opens and closes when it is
@@ -64,6 +92,13 @@ export declare class HelixHeadlessTreeItem extends HelixHeadlessTreeItem_base {
      * current page on every item a consumer never asked to be one.
      */
     href: string;
+    /**
+     * Whether the item is a branch whose children are loaded when it opens.
+     *
+     * Opening it sends `helix-load`. Add the children to its `children` slot,
+     * and remove `lazy` once they are in, as Web Awesome's tree item does.
+     */
+    lazy: boolean;
     /**
      * The node's depth from the root. The tree counts it, so indentation needs no
      * nested CSS.
@@ -151,7 +186,7 @@ export declare class HelixHeadlessTreeItem extends HelixHeadlessTreeItem_base {
      * row rather than the wrapper around it.
      */
     focusItem(): void;
-    /** Selects this node and sends `helix-select`. */
+    /** Selects this node and sends `helix-select`. A disabled node sends nothing. */
     select(): void;
     /**
      * Chooses this node, as a press or Enter does.
@@ -163,6 +198,13 @@ export declare class HelixHeadlessTreeItem extends HelixHeadlessTreeItem_base {
      * value and nothing listens for it.
      */
     activate(): void;
+    /**
+     * Opens or closes a branch, unless the item is disabled.
+     *
+     * Every press and key that opens a branch comes through here, so `disabled`
+     * holds for all of them. A script can still set `open`.
+     */
+    toggleOpen(): boolean;
     /**
      * Follows a link slotted into the name, if there is one.
      *
@@ -184,8 +226,17 @@ export declare class HelixHeadlessTreeItem extends HelixHeadlessTreeItem_base {
      * its children.
      */
     private follow;
+    /** A press on the check mark checks the item and leaves a branch as it is. */
+    private readonly handleCheckClick;
     private readonly handleToggleClick;
     private readonly handleRowClick;
+    /**
+     * The expand and collapse mark of a branch, as the `chevron` slot's
+     * fallback, so an icon of your own replaces it by being slotted.
+     */
+    protected renderToggle(): TemplateResult;
+    /** The check mark, in a tree with `selection-mode="multiple"`. */
+    private renderCheckbox;
     /** Everything inside the row, which is the same whichever element it is. */
     private renderRow;
     /**
@@ -204,6 +255,8 @@ export declare class HelixHeadlessTreeItem extends HelixHeadlessTreeItem_base {
      * a consumer's markup means. What stops is the write back.
      */
     protected willUpdate(changed: PropertyValues): void;
+    /** Asks for a lazy branch's children when it opens. */
+    protected updated(changed: PropertyValues): void;
     protected render(): TemplateResult;
 }
 declare global {