@fusion.dev/helix-headless 0.144.0 → 0.145.0

package/dist/scroll-area/root/scroll-area-root.js

@@ -4,14 +4,20 @@ 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 } from '@fusion.dev/helix-core';
+import { capturePointer, customElement, DelayController, HelixElement, isRtl, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
+import { hasScrollbar, offsetAt, scrollFraction, scrollPerPixel, showsScrollbar, thumbFraction, } from '../scrollbar.js';
 const EDGES = ['block-start', 'block-end', 'inline-start', 'inline-end'];
 let HelixHeadlessScrollArea = class HelixHeadlessScrollArea extends HelixElement {
     constructor() {
         super(...arguments);
+        this.hideDelay = 600;
         this.label = '';
+        this.active = false;
+        this.hovered = false;
+        this.over = false;
+        this.hide = new DelayController(this, { renders: false });
         this.more = [];
         this.scrolls = false;
         this.measure = () => {
@@ -36,6 +42,56 @@ let HelixHeadlessScrollArea = class HelixHeadlessScrollArea extends HelixElement
             }
             this.more = found;
             this.scrolls = box.scrollHeight > box.clientHeight || box.scrollWidth > box.clientWidth;
+            if (this.scrollbars) {
+                this.readBars(box);
+            }
+        };
+        this.handleVerticalDown = (event) => {
+            this.grab(event, 'vertical');
+        };
+        this.handleHorizontalDown = (event) => {
+            this.grab(event, 'horizontal');
+        };
+        this.handleDragMove = (event) => {
+            const drag = this.drag;
+            const box = this.scroller;
+            if (!drag || !box) {
+                return;
+            }
+            const pointer = drag.axis === 'vertical' ? event.clientY : event.clientX;
+            this.scrollAlong(box, drag.axis, drag.from + (pointer - drag.pointer) * drag.sign * drag.perPixel);
+        };
+        this.handleDragEnd = () => {
+            if (!this.drag) {
+                return;
+            }
+            this.drag = undefined;
+            this.wake();
+            this.requestUpdate();
+        };
+        this.handleBarEnter = () => {
+            this.over = true;
+        };
+        this.handleBarLeave = () => {
+            this.over = false;
+            this.wake();
+        };
+        this.handleEnter = () => {
+            this.hovered = true;
+        };
+        this.handleLeave = () => {
+            this.hovered = false;
+            if (this.scrollbars === 'hover') {
+                this.wake();
+            }
+        };
+        this.handleScroll = (event) => {
+            this.measure();
+            this.wake();
+            this.relayNativeEvent(event);
+        };
+        this.handleScrollEnd = (event) => {
+            this.relayNativeEvent(event);
         };
         this.handleSlotChange = (event) => {
             const slot = event.target;
@@ -48,8 +104,84 @@ let HelixHeadlessScrollArea = class HelixHeadlessScrollArea extends HelixElement
     get scroller() {
         return this.partNamed('viewport');
     }
+    extent(box, axis) {
+        return axis === 'vertical'
+            ? { client: box.clientHeight, offset: box.scrollTop, scroll: box.scrollHeight }
+            : { client: box.clientWidth, offset: Math.abs(box.scrollLeft), scroll: box.scrollWidth };
+    }
+    readBars(box) {
+        const mode = this.scrollbars ?? 'auto';
+        const style = getComputedStyle(box);
+        const bar = (axis, overflow) => {
+            const extent = this.extent(box, axis);
+            return {
+                along: scrollFraction(extent),
+                drawn: hasScrollbar(mode, !['clip', 'hidden', 'visible'].includes(overflow), extent.offset > 1 || extent.client < extent.scroll - 1),
+                thumb: thumbFraction(extent),
+            };
+        };
+        const next = {
+            horizontal: bar('horizontal', style.overflowX),
+            vertical: bar('vertical', style.overflowY),
+        };
+        if (JSON.stringify(next) !== JSON.stringify(this.bars)) {
+            this.bars = next;
+        }
+    }
+    wake() {
+        if (this.scrollbars !== 'scroll' && this.scrollbars !== 'hover') {
+            return;
+        }
+        this.active = true;
+        this.hide.start(this.hideDelay, () => {
+            this.active = false;
+        });
+    }
+    scrollAlong(box, axis, offset) {
+        box.scrollTo(axis === 'vertical'
+            ? { behavior: 'instant', top: offset }
+            : { behavior: 'instant', left: isRtl(box) ? -offset : offset });
+    }
+    grab(event, axis) {
+        const box = this.scroller;
+        const bar = event.currentTarget;
+        const thumb = bar.querySelector('[part~="thumb"]');
+        if (event.button !== 0 || !box || !thumb) {
+            return;
+        }
+        event.preventDefault();
+        const vertical = axis === 'vertical';
+        const rtl = !vertical && isRtl(box);
+        const track = bar.getBoundingClientRect();
+        const held = thumb.getBoundingClientRect();
+        const length = vertical ? track.height : track.width;
+        const size = vertical ? held.height : held.width;
+        const extent = this.extent(box, axis);
+        const pointer = vertical ? event.clientY : event.clientX;
+        let from = extent.offset;
+        if (!thumb.contains(event.target)) {
+            const along = vertical
+                ? pointer - track.top
+                : rtl
+                    ? track.right - pointer
+                    : pointer - track.left;
+            from = offsetAt(extent, along, length, size);
+            this.scrollAlong(box, axis, from);
+        }
+        this.drag = {
+            axis,
+            from,
+            perPixel: scrollPerPixel(extent, length, size),
+            pointer,
+            sign: rtl ? -1 : 1,
+        };
+        capturePointer(bar, event.pointerId);
+        this.requestUpdate();
+    }
     connectedCallback() {
         super.connectedCallback();
+        this.addEventListener('pointerenter', this.handleEnter);
+        this.addEventListener('pointerleave', this.handleLeave);
         this.watcher = new ResizeObserver(this.measure);
         if (this.hasUpdated) {
             this.watchContent();
@@ -57,8 +189,14 @@ let HelixHeadlessScrollArea = class HelixHeadlessScrollArea extends HelixElement
     }
     disconnectedCallback() {
         super.disconnectedCallback();
+        this.removeEventListener('pointerenter', this.handleEnter);
+        this.removeEventListener('pointerleave', this.handleLeave);
         this.watcher?.disconnect();
         this.watcher = undefined;
+        this.drag = undefined;
+        this.active = false;
+        this.hovered = false;
+        this.over = false;
     }
     firstUpdated(changed) {
         super.firstUpdated?.(changed);
@@ -79,11 +217,20 @@ let HelixHeadlessScrollArea = class HelixHeadlessScrollArea extends HelixElement
     }
     updated(changed) {
         super.updated?.(changed);
+        if (changed.has('scrollbars') && this.hasUpdated && this.scrollbars) {
+            const box = this.scroller;
+            if (box) {
+                this.readBars(box);
+            }
+        }
         this.toggleState('scrolls', this.scrolls);
         this.toggleState('more-block-start', this.more.includes('block-start'));
         this.toggleState('more-block-end', this.more.includes('block-end'));
         this.toggleState('more-inline-start', this.more.includes('inline-start'));
         this.toggleState('more-inline-end', this.more.includes('inline-end'));
+        const drawn = this.scrollbars ? this.bars : undefined;
+        this.toggleState('scrollbar-horizontal', drawn?.horizontal.drawn === true);
+        this.toggleState('scrollbar-vertical', drawn?.vertical.drawn === true);
     }
     render() {
         return html `<div
@@ -92,7 +239,8 @@ let HelixHeadlessScrollArea = class HelixHeadlessScrollArea extends HelixElement
       role=${this.label ? 'region' : nothing}
       aria-label=${this.label || nothing}
       tabindex=${this.scrolls ? '0' : nothing}
-      @scroll=${this.measure}
+      @scroll=${this.handleScroll}
+      @scrollend=${this.handleScrollEnd}
     >
       <slot @slotchange=${this.handleSlotChange}></slot>
     </div>
@@ -104,12 +252,79 @@ let HelixHeadlessScrollArea = class HelixHeadlessScrollArea extends HelixElement
     <div
       part="edges"
       aria-hidden="true"
-    ></div>`;
+    ></div>${this.scrollbars ? this.renderScrollbars(this.scrollbars) : nothing}`;
+    }
+    renderScrollbars(mode) {
+        const bars = this.bars;
+        const moment = {
+            active: this.active,
+            held: this.over || this.drag !== undefined,
+            hovered: this.hovered,
+        };
+        const shown = showsScrollbar(mode, moment);
+        const facts = (bar) => bar
+            ? `--scroll-area-thumb-fraction: ${bar.thumb}; --scroll-area-scroll-fraction: ${bar.along}`
+            : nothing;
+        const vertical = bars?.vertical.drawn === true;
+        const horizontal = bars?.horizontal.drawn === true;
+        return html `<div
+        part="scrollbar scrollbar-vertical${vertical && shown ? ' scrollbar-visible' : ''}"
+        aria-hidden="true"
+        ?hidden=${!vertical}
+        style=${facts(bars?.vertical)}
+        @pointerdown=${this.handleVerticalDown}
+        @pointermove=${this.handleDragMove}
+        @pointerup=${this.handleDragEnd}
+        @pointercancel=${this.handleDragEnd}
+        @lostpointercapture=${this.handleDragEnd}
+        @pointerenter=${this.handleBarEnter}
+        @pointerleave=${this.handleBarLeave}
+      >
+        <div part="thumb thumb-vertical"></div>
+      </div>
+      <div
+        part="scrollbar scrollbar-horizontal${horizontal && shown ? ' scrollbar-visible' : ''}"
+        aria-hidden="true"
+        ?hidden=${!horizontal}
+        style=${facts(bars?.horizontal)}
+        @pointerdown=${this.handleHorizontalDown}
+        @pointermove=${this.handleDragMove}
+        @pointerup=${this.handleDragEnd}
+        @pointercancel=${this.handleDragEnd}
+        @lostpointercapture=${this.handleDragEnd}
+        @pointerenter=${this.handleBarEnter}
+        @pointerleave=${this.handleBarLeave}
+      >
+        <div part="thumb thumb-horizontal"></div>
+      </div>
+      <div
+        part="corner"
+        aria-hidden="true"
+        ?hidden=${!(vertical && horizontal)}
+      ></div>`;
     }
 };
+__decorate([
+    property({ attribute: 'hide-delay', type: Number })
+], HelixHeadlessScrollArea.prototype, "hideDelay", void 0);
 __decorate([
     property()
 ], HelixHeadlessScrollArea.prototype, "label", void 0);
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessScrollArea.prototype, "scrollbars", void 0);
+__decorate([
+    state()
+], HelixHeadlessScrollArea.prototype, "bars", void 0);
+__decorate([
+    state()
+], HelixHeadlessScrollArea.prototype, "active", void 0);
+__decorate([
+    state()
+], HelixHeadlessScrollArea.prototype, "hovered", void 0);
+__decorate([
+    state()
+], HelixHeadlessScrollArea.prototype, "over", void 0);
 __decorate([
     state()
 ], HelixHeadlessScrollArea.prototype, "more", void 0);

package/dist/scroll-area/scrollbar.d.ts

@@ -0,0 +1,65 @@
+/**
+ * The arithmetic behind the scrollbars a scroll area draws under `scrollbars`.
+ *
+ * Every length here is along one axis and counted from that axis' start, which
+ * is the right-hand edge on a right-to-left page for the horizontal one. The
+ * component turns a pointer and a `scrollLeft` into those counts, so nothing
+ * below has to know which way the line runs.
+ */
+/** Which scrollbars are drawn, and when. Absent keeps the browser's own. */
+export type Scrollbars = 'always' | 'auto' | 'hover' | 'scroll';
+/** One axis of the viewport, read off the box. */
+export interface Extent {
+    /** How much of the content the viewport shows, `clientHeight` or `clientWidth`. */
+    client: number;
+    /** How far from its start the axis is scrolled, never negative. */
+    offset: number;
+    /** The whole length of the content, `scrollHeight` or `scrollWidth`. */
+    scroll: number;
+}
+/**
+ * The share of the track the thumb covers, from 0 to 1: how much of the content
+ * is in view. A box with no content, or one that shows all of it, is 1.
+ */
+export declare const thumbFraction: ({ client, scroll }: Extent) => number;
+/**
+ * How far along the axis is scrolled, from 0 at the start to 1 at the end. An
+ * axis with nothing to scroll is 0.
+ */
+export declare const scrollFraction: ({ client, offset, scroll }: Extent) => number;
+/**
+ * How far the content moves for each pixel the thumb is dragged.
+ *
+ * The thumb travels the track less its own length, and the content travels
+ * its length less the view, so the ratio of the two is the gearing. Zero where
+ * the thumb fills the track and cannot move.
+ */
+export declare const scrollPerPixel: (extent: Extent, track: number, thumb: number) => number;
+/**
+ * The offset that puts the middle of the thumb under a press on the track.
+ *
+ * `along` is where the press landed, counted from the track's start. The thumb
+ * stops at either end of the track, so a press near an end scrolls to that end.
+ */
+export declare const offsetAt: (extent: Extent, along: number, track: number, thumb: number) => number;
+/**
+ * Whether an axis has a scrollbar at all: it can scroll, and under every value
+ * but `always` it has something to scroll.
+ *
+ * An axis whose `overflow` is `hidden` or `clip` cannot be scrolled by a reader,
+ * so it gets no scrollbar whatever `scrollbars` says. That is how a consumer
+ * keeps a horizontal bar off a list that only scrolls down.
+ */
+export declare const hasScrollbar: (mode: Scrollbars, scrollable: boolean, overflows: boolean) => boolean;
+/**
+ * Whether a scrollbar that exists is showing at this moment.
+ *
+ * `auto` and `always` show it the whole time. `scroll` shows it while the
+ * content is moving and for the hide delay after, and while the pointer holds
+ * it. `hover` adds the time the pointer is over the scroll area.
+ */
+export declare const showsScrollbar: (mode: Scrollbars, moment: {
+    active: boolean;
+    held: boolean;
+    hovered: boolean;
+}) => boolean;

package/dist/scroll-area/scrollbar.js

@@ -0,0 +1,24 @@
+const clamp = (value, low, high) => Math.min(Math.max(value, low), high);
+export const thumbFraction = ({ client, scroll }) => scroll <= 0 ? 1 : clamp(client / scroll, 0, 1);
+export const scrollFraction = ({ client, offset, scroll }) => {
+    const room = scroll - client;
+    return room <= 0 ? 0 : clamp(offset / room, 0, 1);
+};
+export const scrollPerPixel = (extent, track, thumb) => {
+    const run = track - thumb;
+    return run <= 0 ? 0 : Math.max(0, extent.scroll - extent.client) / run;
+};
+export const offsetAt = (extent, along, track, thumb) => {
+    const run = track - thumb;
+    if (run <= 0) {
+        return 0;
+    }
+    return clamp((along - thumb / 2) / run, 0, 1) * Math.max(0, extent.scroll - extent.client);
+};
+export const hasScrollbar = (mode, scrollable, overflows) => scrollable && (mode === 'always' || overflows);
+export const showsScrollbar = (mode, moment) => {
+    if (mode === 'auto' || mode === 'always') {
+        return true;
+    }
+    return moment.active || moment.held || (mode === 'hover' && moment.hovered);
+};

package/dist/select/root/select-root.js

@@ -222,7 +222,7 @@ let HelixHeadlessSelect = class HelixHeadlessSelect extends MixinControllerOpen(
       ?multiple=${this.multiple}
       ?filterable=${this.filterable}
       manual
-      aria-label=${this.label || nothing}
+      aria-label=${this.label || this.getAttribute('aria-label') || nothing}
       @keydown=${this.handleListKeydown}
       @helix-before-change=${this.handleChange}
       @change=${this.stopInner}

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

@@ -179,6 +179,17 @@ export declare class HelixHeadlessSplitter extends HelixElement {
      */
     get position(): number;
     set position(next: number);
+    /**
+     * Where a dragged divider snaps, comma separated, as Web Awesome's split
+     * panel does: a bare number is a percentage and a length such as `240px` is
+     * measured along the splitter, so `snap="25, 50, 75"` or `snap="240px, 50"`.
+     * The arrow keys move by `step` and do not snap.
+     */
+    snap: string;
+    /**
+     * How close a drag has to come to a snap point to land on it, in pixels.
+     */
+    snapThreshold: number;
     /**
      * How far one arrow key press moves the divider, as a percentage.
      */
@@ -434,6 +445,8 @@ export declare class HelixHeadlessSplitter extends HelixElement {
     private settle;
     private readonly handlePointerDown;
     private readonly handlePointerMove;
+    /** Where a drag at `position` lands once `snap` has had its say. */
+    private snapped;
     private readonly handlePointerUp;
     /**
      * The keys a separator answers.

package/dist/splitter/root/splitter-root.js

@@ -5,9 +5,10 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 var HelixHeadlessSplitter_1;
-import { AriaForwardController, capturePointer, closestInstance, customElement, HelixBeforeCollapseEvent, HelixBeforeResizeEvent, HelixCollapseEvent, HelixElement, HelixResizedEvent, inlineStep, isRtl, requestChange, } from '@fusion.dev/helix-core';
+import { AriaForwardController, capturePointer, closestInstance, commaList, customElement, HelixBeforeCollapseEvent, HelixBeforeResizeEvent, HelixCollapseEvent, HelixElement, HelixResizedEvent, inlineStep, isRtl, requestChange, } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
+import { snapTo } from '../snap.js';
 const STACK_BELOW = 512;
 let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitter extends HelixElement {
     constructor() {
@@ -23,6 +24,8 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
         });
         this.max = 100;
         this.min = 0;
+        this.snap = '';
+        this.snapThreshold = 12;
         this.step = 2;
         this.positionState = undefined;
         this.collapsedState = undefined;
@@ -57,7 +60,7 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
             const along = this.vertical ? event.clientY : event.clientX;
             const raw = ((along - origin.start) / origin.length) * 100;
             const rtl = !this.vertical && isRtl(this);
-            this.move(rtl ? 100 - raw : raw);
+            this.move(this.snapped(rtl ? 100 - raw : raw, origin.length));
         };
         this.handlePointerUp = (event) => {
             if (!this.origin) {
@@ -345,6 +348,15 @@ let HelixHeadlessSplitter = HelixHeadlessSplitter_1 = class HelixHeadlessSplitte
             });
         }
     }
+    snapped(position, length) {
+        if (this.snap === '' || length <= 0) {
+            return position;
+        }
+        const points = commaList(this.snap)
+            .map((point) => this.toPercent(point, Number.NaN))
+            .filter((point) => Number.isFinite(point));
+        return snapTo(position, points, (this.snapThreshold / length) * 100);
+    }
     travel(key) {
         if (!this.vertical) {
             return inlineStep(this, key);
@@ -541,6 +553,12 @@ __decorate([
 __decorate([
     property({ type: Number })
 ], HelixHeadlessSplitter.prototype, "position", null);
+__decorate([
+    property()
+], HelixHeadlessSplitter.prototype, "snap", void 0);
+__decorate([
+    property({ attribute: 'snap-threshold', type: Number })
+], HelixHeadlessSplitter.prototype, "snapThreshold", void 0);
 __decorate([
     property({ type: Number })
 ], HelixHeadlessSplitter.prototype, "step", void 0);

package/dist/splitter/snap.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Where a dragged divider lands: on the nearest snap point within `threshold`,
+ * or where the pointer is.
+ *
+ * Every number is a percentage of the splitter's box, so the caller turns a
+ * point written as a length, and the threshold, into one first. Ties go to the
+ * point written first.
+ */
+export declare const snapTo: (position: number, points: readonly number[], threshold: number) => number;

package/dist/splitter/snap.js

@@ -0,0 +1,12 @@
+export const snapTo = (position, points, threshold) => {
+    let best;
+    let distance = Number.POSITIVE_INFINITY;
+    for (const point of points) {
+        const away = Math.abs(point - position);
+        if (away <= threshold && away < distance) {
+            best = point;
+            distance = away;
+        }
+    }
+    return best ?? position;
+};

package/dist/steps/reach.d.ts

@@ -0,0 +1,15 @@
+/** What linear mode reads of a step. */
+export interface ReachableStep {
+    /** Whether the stage is finished. */
+    complete: boolean;
+    /** Whether a reader may pass the stage without finishing it. */
+    optional: boolean;
+}
+/**
+ * Whether a reader on step `from` may go to step `to`, in a linear sequence.
+ *
+ * Back is always allowed, as Ark UI's linear steps allow it. Forward is allowed
+ * only where every stage from the one the reader is on up to the target is
+ * complete or optional, so no stage is passed unfinished.
+ */
+export declare const canReach: (steps: readonly ReachableStep[], from: number, to: number) => boolean;

package/dist/steps/reach.js

@@ -0,0 +1,12 @@
+export const canReach = (steps, from, to) => {
+    if (to <= from) {
+        return true;
+    }
+    for (let at = Math.max(from, 0); at < to; at += 1) {
+        const step = steps[at];
+        if (step && !step.complete && !step.optional) {
+            return false;
+        }
+    }
+    return true;
+};

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

@@ -13,6 +13,13 @@ declare const HelixHeadlessSteps_base: (new (...args: any[]) => import("@fusion.
  * sequence is correct in the server's markup, where the root cannot count its
  * slotted children.
  *
+ * `linear` keeps a reader from passing a stage they have not finished, as Ark
+ * UI's linear steps do: a stage ahead is out of reach, and its button disabled,
+ * until every stage before it is `complete` or `optional`. Going back is always
+ * allowed. To check a stage before a reader leaves it, cancel
+ * `helix-before-activate` while it is not valid. `next()` and `previous()` move
+ * one stage either way, under the same rules, for your own buttons.
+ *
  * @since 0.1.0
  * @status stable
  * @category navigation
@@ -33,6 +40,11 @@ export declare class HelixHeadlessSteps extends HelixHeadlessSteps_base {
      * needs a name of its own rather than borrowing the heading above it.
      */
     label: string;
+    /**
+     * Whether a reader has to finish each stage, or pass an `optional` one,
+     * before going on to the next.
+     */
+    linear: boolean;
     /**
      * Which way the steps run.
      *
@@ -62,6 +74,24 @@ export declare class HelixHeadlessSteps extends HelixHeadlessSteps_base {
     variant?: 'numeric';
     /** The steps, in the order the consumer wrote them. */
     private get steps();
+    /** The index of the stage the reader is on, or `-1`. */
+    private get at();
+    /**
+     * Moves to the next stage that can be gone to, as Ark UI's `goToNextStep`
+     * does. Returns whether it moved: not past the last stage, not into a stage
+     * `linear` holds out of reach, and not where a listener refused.
+     */
+    next(): boolean;
+    /** Moves to the stage before, as Ark UI's `goToPrevStep` does. Returns whether it moved. */
+    previous(): boolean;
+    /** Moves `delta` stages, skipping disabled ones. */
+    private step;
+    /** Whether the stage at `index` can be gone to from where the reader is. */
+    private reachable;
+    /** Marks the stages a linear sequence holds out of reach. Client only. */
+    private lock;
+    /** Watches what decides a stage's reach: which is current, which are done. */
+    private watcher;
     /**
      * Puts `active` on whichever step owns it.
      *

package/dist/steps/root/steps-root.js

@@ -7,23 +7,62 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement, hostAria, MixinControllerActive, whenHydrated, } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
+import { canReach } from '../reach.js';
 let HelixHeadlessSteps = class HelixHeadlessSteps extends MixinControllerActive(HelixElement) {
     constructor() {
         super(...arguments);
         this.label = 'Steps';
+        this.linear = false;
         this.handleSelection = (event) => {
             if (event.defaultPrevented || !this.steps.includes(event.target)) {
                 return;
             }
+            if (!this.reachable(this.steps.indexOf(event.target))) {
+                return;
+            }
             this.requestActive(event.detail.value);
         };
         this.handleSlotChange = () => {
             this.sync();
+            this.lock();
         };
     }
     get steps() {
         return [...this.querySelectorAll(':scope > *')].filter((one) => 'current' in one);
     }
+    get at() {
+        return this.steps.findIndex((step) => step.current);
+    }
+    next() {
+        return this.step(1);
+    }
+    previous() {
+        return this.step(-1);
+    }
+    step(delta) {
+        const steps = this.steps;
+        let index = this.at + delta;
+        while (steps[index]?.disabled) {
+            index += delta;
+        }
+        const target = steps[index];
+        if (!target || !this.reachable(index)) {
+            return false;
+        }
+        return this.requestActive(target.value);
+    }
+    reachable(index) {
+        return !this.linear || canReach(this.steps, this.at, index);
+    }
+    lock() {
+        const steps = this.steps;
+        steps.forEach((step, index) => {
+            const locked = !this.reachable(index);
+            whenHydrated(step, () => {
+                step.locked = locked;
+            });
+        });
+    }
     sync() {
         if (this.active === '') {
             return;
@@ -40,10 +79,18 @@ let HelixHeadlessSteps = class HelixHeadlessSteps extends MixinControllerActive(
     connectedCallback() {
         super.connectedCallback();
         this.addEventListener('helix-select', this.handleSelection);
+        this.watcher = new MutationObserver(() => this.lock());
+        this.watcher.observe(this, {
+            attributeFilter: ['complete', 'current', 'optional'],
+            attributes: true,
+            subtree: true,
+        });
     }
     disconnectedCallback() {
         super.disconnectedCallback();
         this.removeEventListener('helix-select', this.handleSelection);
+        this.watcher?.disconnect();
+        this.watcher = undefined;
     }
     willUpdate(changed) {
         super.willUpdate(changed);
@@ -54,6 +101,9 @@ let HelixHeadlessSteps = class HelixHeadlessSteps extends MixinControllerActive(
         if (changed.has('active')) {
             this.sync();
         }
+        if (changed.has('linear') || changed.has('active')) {
+            this.lock();
+        }
     }
     render() {
         return html `<slot @slotchange=${this.handleSlotChange}></slot>`;
@@ -62,6 +112,9 @@ let HelixHeadlessSteps = class HelixHeadlessSteps extends MixinControllerActive(
 __decorate([
     property()
 ], HelixHeadlessSteps.prototype, "label", void 0);
+__decorate([
+    property({ reflect: true, type: Boolean })
+], HelixHeadlessSteps.prototype, "linear", void 0);
 __decorate([
     property({ reflect: true })
 ], HelixHeadlessSteps.prototype, "orientation", void 0);