@fusion.dev/helix-headless 0.0.0-dev

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

@@ -0,0 +1,399 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * @summary Shows one slide of several, with controls to move between them.
+ *
+ * @description
+ * The track is a scroller with scroll snapping, so a drag, a trackpad swipe,
+ * and the browser's own momentum all work without being reimplemented. The
+ * controls scroll it; they do not drive a transform.
+ *
+ * Slides are the consumer's own elements, and nothing is written onto them. The
+ * component renders a pane per slide carrying `role="group"`,
+ * `aria-roledescription="slide"` and a name reading its position in the set,
+ * and assigns the slide into it: a screen-reader user hears where they are, and
+ * a slide that is itself a link is still a link, which it was not while the role
+ * was being written on top of it. See `assign`.
+ *
+ * **Rotation stops on focus and on hover, and once stopped it stays stopped.**
+ * The APG is explicit: rotation must not resume unless the reader asks for it,
+ * so hovering away does not start it again. The control names the action it
+ * performs, and it is first in the tab order.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category layout
+ * @aliases Slider, Gallery, Slideshow
+ * @documentation https://helix.fusion.dev/components/carousel
+ *
+ * @slot - The slides.
+ *
+ * @event {HelixSelectEvent} helix-select - Fired when the slide in view changes, with its index. Cancelable: refusing it takes the decision and nothing moves.
+ *
+ * @csspart controls - The row of controls.
+ * @csspart indicator - One of them, and a way to reach that slide.
+ * @csspart indicators - The row of controls saying where the reader is.
+ * @csspart next - The control that moves to the next slide.
+ * @csspart next-mark - The glyph on the next control.
+ * @csspart previous - The control that moves to the previous slide.
+ * @csspart previous-mark - The glyph on the previous control.
+ * @csspart rotation - The control that stops and starts rotation.
+ * @csspart rotation-mark - The glyph on the play and pause control.
+ * @csspart slide - The pane one slide is shown in, and the box the track snaps to.
+ * @csspart track - The scroller the slides sit in.
+ */
+export declare class HelixHeadlessCarousel extends HelixElement {
+    /**
+     * Manual, so each slide can be wrapped without its markup being touched.
+     *
+     * A slide has to be a `group` carrying `aria-roledescription="slide"` and a
+     * position in the run, and those are the component's facts rather than the
+     * consumer's element's. Writing them on is what a React consumer's hydration
+     * reports and does not patch up, and on a slide that is itself a link it also
+     * takes the link's role away. Assigning into a pane the component rendered
+     * says the same thing to a screen reader and leaves the consumer's element
+     * exactly as it was served. `Chat` and `DataTable` wrap their children the
+     * same way and for the first of those two reasons.
+     */
+    static shadowRootOptions: ShadowRootInit;
+    /**
+     * Accessible name for the carousel.
+     */
+    label: string;
+    /**
+     * The slide in view, counted from zero.
+     *
+     * Reading gives the real slide, in either mode. Writing sets it, the way a
+     * script assigning to a native control does. Which mode the carousel is in is
+     * read once, at the first update, from whether anything had declared an
+     * `index` by then: declared, and the consumer owns it and the carousel only
+     * announces where it would have gone; not declared, and the carousel owns it
+     * and `default-index` says where it starts.
+     *
+     * The same contract the four mixins carry, written out here rather than
+     * extracted, because a slide is addressed by position and every one of those
+     * mixins is keyed by a name. One consumer is not a mixin: if a second numeric
+     * state turns up, this is what it is extracted from.
+     *
+     *
+     */
+    get index(): number;
+    set index(next: number);
+    /**
+     * Which way the track runs.
+     *
+     * Behavior rather than presentation, which is why it is here: the scroll
+     * position and the nearest-slide arithmetic are both single-axis, and a
+     * styled-tier attribute cannot change which one they read. Two sites branch
+     * on it, `scrollTo` and the drag settle, and nothing else in the component
+     * knows about the axis at all.
+     *
+     * A vertical track needs a height, which a horizontal one does not: width
+     * comes from the page and height does not, so the styled tier gives it
+     * `--carousel-block-size` and a consumer sets that to whatever the slides
+     * want.
+     */
+    orientation?: 'horizontal' | 'vertical';
+    /**
+     * Whether the previous and next controls are shown.
+     *
+     * `auto`, which is the resting behavior and what an absent attribute means,
+     * shows them wherever the pointer can hover and hides them where it cannot.
+     * `always` keeps them on every device, and `none` never renders them at all.
+     *
+     * **Pointer and not width, which is the distinction this exists to make.** A
+     * 375px window on a desktop still has a mouse and still wants the arrows; a
+     * tablet at 1024 has neither. `.claude/rules/helix.md` forbids a component
+     * asking about the viewport, because the viewport is not the component's box,
+     * and that objection does not reach `hover` and `pointer`: those describe the
+     * input device, and the answer is the same whether this carousel is 300px in
+     * a sidebar or runs the width of the page.
+     *
+     * **Safe to hide because the arrows are not the keyboard's way in.** The
+     * indicators carry a roving `tabindex` and handle the arrow keys, so every
+     * slide is still reachable with the controls gone. Hiding a control that was
+     * the only route to something would be a different change under this name.
+     *
+     * **The rotation control is never hidden by this**, which is a decision
+     * rather than a limit of scope: content that moves on its own has to offer a
+     * way to stop it, so an autoplaying carousel keeps its pause control on a
+     * touch device exactly as it does on a desktop.
+     */
+    controls?: 'always' | 'auto' | 'none';
+    /**
+     * Slide to start on, where nothing declared one.
+     */
+    defaultIndex: number;
+    /** The slide in view, whoever set it, and `undefined` until somebody has. */
+    private indexState;
+    /**
+     * Whether moving past either end wraps to the other.
+     */
+    loop: boolean;
+    /**
+     * Whether the carousel advances on its own.
+     */
+    autoplay: boolean;
+    /**
+     * How long each slide is held, in milliseconds.
+     */
+    interval: number;
+    /**
+     * Whether rotation is running.
+     *
+     * Absent until autoplay starts it.
+     */
+    private rotating;
+    private timer;
+    /**
+     * How many slides are shown across the track at once. Absent shows one.
+     *
+     * **Here rather than on the styled tier, because it decides how many places
+     * the track can stop.** It was declared above as a width, which is what it
+     * looks like from the stylesheet: one rule per value setting a custom
+     * property, and the slides divide the track by it. But a carousel showing
+     * four of six slides has three positions, not six, and everything that counts
+     * positions is in this file. Left up there, `goTo` clamped to the last
+     * *slide*, so three of the six indicators pointed at a scroll offset the
+     * track had already reached and could not pass: pressing next walked the dots
+     * to the end while the slides stopped moving a third of the way through.
+     *
+     * No default, because it reflects. A reflected property with a value writes
+     * its attribute on upgrade, and the host then carries something a consumer's
+     * server markup never had, which React reports as a mismatch. The one-across
+     * case is the absent attribute, and the styles read it that way.
+     */
+    perView?: number;
+    /**
+     * How many distinct views the track holds, which is what the indicators count.
+     *
+     * A window of `perView` slides sliding one at a time over `n` of them stops
+     * `n - perView + 1` times, so six slides four across is three: 0 to 3, 1 to 4,
+     * 2 to 5. One at minimum, since a carousel showing everything it has still
+     * has the one place to be.
+     */
+    get positions(): number;
+    /**
+     * The panes rendered for the slides, in order. Empty until the first render.
+     *
+     * One per slide, and the box the track actually lays out: the slide itself is
+     * assigned into it and takes its size from it, so every offset the scroller
+     * is asked about is a pane's. Read fresh rather than cached, because a slide
+     * arriving or leaving re-renders the run.
+     */
+    private get panes();
+    /** The slides, in light-DOM order. Empty on the server, which has no tree. */
+    get slides(): HTMLElement[];
+    /**
+     * The arrows move between indicators, which is the tablist pattern.
+     *
+     * One tab stop for the set and the arrows within it, so a reader does not
+     * have to press Tab once per slide to get past a carousel of twelve. Moving
+     * changes the slide, because an indicator that could be focused without
+     * selecting would leave the highlight and the slide disagreeing with nothing
+     * on screen saying which is which.
+     */
+    private readonly handleIndicatorKeydown;
+    /** Moves to a slide, wrapping only where `loop` says to. */
+    goTo(index: number): void;
+    /**
+     * The leading padding the track keeps for a slide to draw its own edge in.
+     *
+     * A styled track carries one so a slide's shadow and focus ring have
+     * somewhere to go: a scroll container clips at its padding box, and a slide
+     * flush against that edge loses whatever it paints outside itself. The
+     * headless tier has no stylesheet and so no padding, and this reads zero
+     * there, which is why both tiers can share the arithmetic below.
+     *
+     * Physical sides rather than logical, to match the physical `offsetLeft` and
+     * `offsetTop` it is subtracted from. The bleed is one length on all four
+     * sides, so the two agree whatever the writing mode; if that stops being
+     * true, this is the method that has to know.
+     */
+    private bleed;
+    /**
+     * Where a slide's leading edge sits, in the scroller's own coordinates.
+     *
+     * **Both directions go through here, because they have to agree.** The
+     * offsets are measured to the track's *border* box and `scrollTop` and
+     * `scrollLeft` are measured from its content box, so the two differ by the
+     * bleed: sending the carousel to a slide and reading back which slide it is
+     * on used the same expression, and correcting one of them alone put a drag
+     * one position off what the arrows did.
+     *
+     * Unsubtracted, the leading slide's own offset *is* the bleed, so scrolling
+     * to index 0 put its edge back on the clip edge. Measured on the insights
+     * carousel: `scrollLeft` resting at 4 against a 4px bleed, the first card
+     * shaved, and no scrolling done to cause it.
+     */
+    private edgeOf;
+    private scrollToIndex;
+    /**
+     * Whether the scroll now settling is one this component asked for.
+     *
+     * Cleared by the first `scrollend` after it is set, and by a reader taking
+     * hold of the track. The second half is not belt and braces: a `scrollTo`
+     * whose target is already the scroll position fires no `scrollend` at all,
+     * and the clamped end of a `per-view` track is exactly that case. Measured:
+     * clicking past the last reachable slide moves `index` and produces no
+     * `scrollend`, so a flag that only a `scrollend` could clear would stay set
+     * and swallow the reader's next drag.
+     */
+    private settling;
+    private readonly handleTake;
+    /**
+     * Stops rotation for good.
+     *
+     * Hovering away or moving focus out does not start it again. The APG is
+     * explicit that rotation resumes only when the reader asks for it, because a
+     * carousel that starts moving again on its own is the thing the control
+     * exists to escape.
+     */
+    private stop;
+    private start;
+    /**
+     * Owns the timer, from the state rather than from the call site.
+     *
+     * `start()` and `stop()` each held the interval and `connectedCallback`
+     * started one, which the rules forbid: a DOM move re-ran connect and restarted
+     * rotation the reader had stopped, and the server, which never runs connect at
+     * all, rendered the control saying the opposite of what it would do. The
+     * state is what is declared and the timer follows it, which also means one
+     * place clears it.
+     */
+    private runTimer;
+    /**
+     * The slide the track is nearest to, or undefined when there is no track.
+     *
+     * Shared by the two readers of the scroll position, which want the same
+     * arithmetic and disagree about what to do with it: one commits where a drag
+     * settled, the other follows it while it is still moving.
+     *
+     * Only the leading edges a window can actually rest on. Past the last
+     * position every remaining slide is on screen already, and taking the nearest
+     * of *those* to the scroller's edge reported a place the reader could not get
+     * back to: dragged fully right, a four-across six reported the sixth slide
+     * and the dots jumped to an indicator that no longer existed.
+     */
+    private nearest;
+    /**
+     * Follows the track while a reader is still dragging it.
+     *
+     * **`scrollend` is the only honest place to commit an index and much too late
+     * to show one.** It fires once momentum has fully settled, which on iOS is
+     * most of a second after the finger has left the glass, so the dots sat on
+     * the old slide for the whole of the coast and then jumped. Reported exactly
+     * that way, as the delay on the indicator being too great.
+     *
+     * So showing and committing are separated. This moves the marker and nothing
+     * else: no state is written and no event is dispatched, because neither is
+     * true yet. A drag in flight is not a reader having chosen, `handleScroll`
+     * still decides that, and a consumer holding `index` still hears once.
+     *
+     * **The marker only, and not `aria-current` or the roving `tabindex`.** Those
+     * describe where the reader *is*, which is a question with one answer per
+     * settled position; moving them every frame of a drag would churn the
+     * accessibility tree to report a place nobody has arrived at.
+     *
+     * Coalesced to a frame, a scroll firing far more often than a screen
+     * refreshes, and skipped while we are settling a scroll of our own: a click
+     * has already moved the index and the track is following it, which is the
+     * precedence `handleScroll` documents at length.
+     */
+    private readonly handleTrackScroll;
+    /**
+     * Reads where a reader's drag settled, and only a reader's.
+     *
+     * **The scroll we issued ourselves ends with a `scrollend` too, and taking it
+     * as a reading is what makes the dots jump back.** This ran on every one, so
+     * the index a reader had just chosen was overwritten by whichever slide
+     * happened to be nearest the leading edge at the moment the animation
+     * finished. Any disagreement there is enough: a snap settling a pixel short of
+     * a midpoint, a target clamped by the scroller's own maximum, a fractional
+     * layout, or a smooth scroll cut off by the next click. The component asked
+     * for slide four, the pixels said three, and the pixels won.
+     *
+     * Which is the wrong precedence in one direction only. A drag is the reader
+     * moving the track and the index has to follow it; a click is the reader
+     * moving the index and the track has to follow *that*. One `scrollend` cannot
+     * tell those apart, so the flag does.
+     */
+    private readonly handleScroll;
+    /**
+     * Where the track is right now, while a drag is still running.
+     *
+     * Separate from `index`, which is where the reader has *arrived*. Undefined
+     * whenever the two would agree, so the marker falls back to the committed
+     * index the moment a drag settles and nothing has to keep them in step. See
+     * `handleTrackScroll` for why they are not one value.
+     */
+    private showing;
+    /** The pending frame for the above, so a burst of scrolls costs one reading. */
+    private scrollFrame;
+    /**
+     * Whether the reader has stopped it, as opposed to something pausing it.
+     *
+     * The two were one flag and the difference matters: `focusin` bubbles, so
+     * every focus move inside the carousel re-ran `stop()`, and a reader who
+     * pressed Start had it undone by their very next Tab. Pausing on hover and on
+     * focus is right; forgetting that the reader asked it to stop is not, and the
+     * APG is explicit that rotation resumes only when the reader asks.
+     */
+    private stopped;
+    /**
+     * Watches the light DOM for slides arriving and leaving.
+     *
+     * **A manually assigned slot does not announce them.** `slotchange` fires when
+     * an assignment changes, and under `slotAssignment: 'manual'` the only thing
+     * that changes an assignment is this component calling `assign`, so a slide
+     * appended by a consumer would reach no slot, render nowhere and be counted by
+     * nothing. The default slot used to carry that duty and could, because it took
+     * whatever was there. `Chat` watches for the same reason.
+     */
+    private watcher;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    /** Pauses without forgetting that the reader wanted it running. */
+    private readonly pause;
+    protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    /**
+     * Puts each slide into the pane rendered for it.
+     *
+     * **The panes carry the ARIA and the consumer's element carries none**, which
+     * is the whole reason this is a manual assignment rather than a plain slot.
+     * The APG wants each slide to be a `group` with `aria-roledescription="slide"`
+     * and a name saying where it sits in the run, and this used to be four
+     * `setAttribute` calls onto the elements a consumer wrote. Two things were
+     * wrong with that, and only one of them was about frameworks.
+     *
+     * **A React consumer's slides are nodes React is in the middle of hydrating.**
+     * The attributes landed before React reached them, so React found a DOM it had
+     * not rendered and reported a mismatch it says it will not patch up. It means
+     * it: the ARIA survived and the announcement was correct, so nothing looked
+     * wrong and the console was the only tell. Deferring the write was tried
+     * first, and a frame is a race rather than an ordering: measured in Chromium
+     * on the landing page, a tab opened in the foreground still reported the
+     * mismatch, and a tab opened hidden did not, only because `requestAnimationFrame`
+     * had not run there yet. `Chat` reached this same conclusion for the same
+     * reason and its comment on `shadowRootOptions` says so.
+     *
+     * **And `role="group"` on a consumer's `<a href>` is not additive.** It
+     * replaces the implicit link role, so six insight cards on the landing page
+     * announced as groups and left the links list entirely. Every slide that is
+     * itself a control had this, and no amount of deferring the write would have
+     * helped, because the write was the bug. A pane around the slide is what the
+     * pattern actually asks for: a group holding a link, rather than a link
+     * relabeled as a group.
+     *
+     * So nothing is written onto a consumer's element at all now, and the
+     * mismatch is gone by construction rather than by timing.
+     */
+    private assign;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-carousel': HelixHeadlessCarousel;
+    }
+}