@fusion.dev/helix-headless 0.0.0-dev

package/dist/outline/root/outline-root.js

@@ -0,0 +1,519 @@
+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, HelixBeforeActivateEvent, HelixElement, IndicatorController, } from '@fusion.dev/helix-core';
+import { html } from 'lit';
+import { property, state } from 'lit/decorators.js';
+/**
+ * @summary Links to the headings on this page, marking the one being read.
+ *
+ * @description
+ * A table of contents, named for the job. Three of the obvious names are taken
+ * by things that are not this: `Outline` is a CSS property and the focus ring's
+ * whole vocabulary, `Contents` is `display: contents` and the `content` part
+ * half this library renders, and `TableOfContents` would sit beside `Table` and
+ * `TableColumn` and read as a third part of that family. `Outline` sits beside
+ * `Navigation`, which is the same job at the other scale: one navigates a site, the
+ * other navigates a document.
+ *
+ * **The links are the consumer's own anchors**, the same as `Navigation`. A router
+ * renders its own `<a>` and cannot render one inside this shadow root, and the
+ * hrefs are fragments the page already knows.
+ *
+ * **What is current is decided by position, not by intersection.** The obvious
+ * build is an `IntersectionObserver` with a thin band near the top of the
+ * window, and it fails in both directions: with headings far apart nothing is
+ * in the band and the marker goes out entirely, and with headings close
+ * together several are and it flickers between them. So the observer is only
+ * the *trigger*, and the answer is computed from where the headings actually
+ * are: the current section is the last one whose top has passed the reading
+ * line, or the first heading before any of them has.
+ *
+ * That rule is what a reader means. Two headings on screen at once are not
+ * ambiguous to a person: they are reading under the upper one.
+ *
+ * **`aria-current="location"`, and it is written onto the consumer's anchor.**
+ * This library does not normally write to light-DOM children, because an
+ * attribute added after upgrade is one a server's markup never had. It is right
+ * here for the reason `Carousel` names its slides: what is current is derived
+ * from scroll position, so no server could have rendered it and there is
+ * nothing for hydration to disagree with. `location` rather than `page`, which
+ * is what `Navigation` uses: `page` means this is the page, and every one of these
+ * is the same page.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category navigation
+ * @aliases Table of contents, On this page, Outline
+ * @documentation https://helix.fusion.dev/components/outline
+ *
+ * @slot - The links, as anchors with fragment hrefs.
+ *
+ * @event {HelixBeforeActivateEvent} helix-before-activate - The section being read has changed, carrying its id as the value. Cancelable: refusing it takes the decision and nothing moves.
+ *
+ * @csspart indicator - The mark that travels to the section being read.
+ * @csspart nav - The navigation landmark.
+ */
+let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
+    constructor() {
+        super(...arguments);
+        /* The mark. Vertical, which the controller needs no telling about: it writes
+           all four values and the stylesheet uses the two it cares about. */
+        this.indicator = new IndicatorController(this, {
+            active: () => this.links.find((link) => link.hasAttribute('aria-current')),
+            indicator: () => this.renderRoot?.querySelector('[part="indicator"]'),
+            surface: () => this.renderRoot?.querySelector('[part="nav"]'),
+        });
+        /**
+         * Accessible name for the navigation.
+         */
+        this.label = 'On this page';
+        /**
+         * How far below the top of the window a heading counts as reached, in pixels.
+         *
+         * The reading line. A page with a sticky masthead sets this to its height, or
+         * a little more: without it the current section changes as a heading slides
+         * under the chrome rather than as it reaches the top of what can be seen.
+         */
+        this.offset = 0;
+        /**
+         * How a click on one of these links travels to its section.
+         *
+         * The platform's own vocabulary, because this is the platform's own option:
+         * `auto` defers to whatever `scroll-behavior` the page has set on its scroll
+         * container, which is the honest default and means an outline changes nothing
+         * a consumer did not ask it to. `smooth` slides, `instant` jumps.
+         *
+         * **`auto` is also the only value that leaves the navigation to the browser.**
+         * A fragment link does four things: it scrolls, it writes the hash, it pushes
+         * a history entry, and it moves the sequential focus point so the next Tab
+         * continues from the heading rather than from the link. Choosing a behavior
+         * means intercepting the click, and an interception that does only the first
+         * of those is a keyboard reader stranded in the contents list. So the other
+         * three are done by hand here, and only when there is a reason to take over.
+         *
+         * `smooth` becomes `instant` under `prefers-reduced-motion: reduce`. That is
+         * read at the click rather than cached, because a reader can change it while
+         * the page is open and this is the only motion in the component that
+         * JavaScript rather than CSS decides.
+         */
+        this.behavior = 'auto';
+        /**
+         * What `current` reports, which only `mark` writes.
+         */
+        this.reading = '';
+        /** The frame a mark is already scheduled for, so a scroll asks for one. */
+        this.frame = 0;
+        /**
+         * The two things an `IntersectionObserver` cannot see, and one listener for
+         * both.
+         *
+         * This component's own note said the observer keeps the marker honest without
+         * a scroll listener. It was wrong twice.
+         *
+         * *At the bottom*, arriving at the end of a page changes no intersection: a
+         * short last section is fully visible long before the final pixel, so its
+         * ratio reached 1 and stopped moving. Nothing fires for the scroll that ends
+         * the page.
+         *
+         * *And at the end of a smooth scroll*, which is the one that showed up in
+         * use. Clicking a link in the contents list scrolled to the section and left
+         * the mark where it was. Measured on the shipped example: after clicking
+         * `#usage` the heading sat at 72px, exactly the reading line, and `current`
+         * was still `install`. The observer fires several times during the travel and
+         * the last of them lands a frame or two before the final position, where the
+         * heading has not crossed yet, and no callback follows for the rest of the
+         * way.
+         *
+         * There was a listener already, added for the first of those, and it compared
+         * two numbers and marked only when the answer *changed*. That was too clever
+         * by half: it fixed the bottom and could not fix the settle. Marking once per
+         * animation frame while a scroll is happening covers both and every other case
+         * of the same shape, and the cost is what `mark()` costs, a `getBoundingClientRect`
+         * per section on frames a reader is already scrolling through. Passive, and
+         * coalesced to one call per frame however many events arrive.
+         */
+        this.handleScroll = () => {
+            if (this.frame !== 0) {
+                return;
+            }
+            this.frame = globalThis.requestAnimationFrame(() => {
+                this.frame = 0;
+                this.mark();
+            });
+        };
+        /**
+         * Takes a link's click, but only where `auto` would not have done the job.
+         *
+         * Left the platform's wherever it can be: a modified click is a new tab or a
+         * download and none of this applies, a click something else has already
+         * handled is not ours, and `auto` is the whole point of `auto`.
+         */
+        this.handleClick = (event) => {
+            if (event.defaultPrevented || event.button !== 0) {
+                return;
+            }
+            if (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey) {
+                return;
+            }
+            const link = event.target?.closest?.('a[href^="#"]');
+            const section = this.sections.find((one) => one.link === link);
+            if (!section) {
+                return;
+            }
+            /* The destination is marked now, and everything between here and there is
+             * not.
+             *
+             * The marker follows the scroll, which is right when a reader is scrolling
+             * and wrong when they have said where they are going: traveling to the
+             * fifth section passes the second, third and fourth, each became current
+             * for a frame or two on the way, and the mark stepped down the list one
+             * item at a time instead of making the journey. Asked for as "it stops at
+             * each item rather than seamlessly moving", which is exactly what it was
+             * doing.
+             *
+             * Suppressed for any click on one of these links, not only the ones this
+             * component scrolls itself: a consumer with `scroll-behavior: smooth` on
+             * their own scroll container gets the same travel and the same stepping,
+             * and `behavior="auto"` does not mean "nobody is animating".
+             *
+             * `landing` is cleared when the page stops moving, by the same `scrollend`
+             * and timeout pair the mark uses elsewhere, because a scroll that is
+             * interrupted by a reader grabbing the page has to hand the marker back. */
+            this.landing = section;
+            this.markTo(section);
+            clearTimeout(this.landed);
+            const arrive = () => {
+                clearTimeout(this.landed);
+                this.landing = undefined;
+                globalThis.removeEventListener?.('scrollend', arrive);
+                this.mark();
+            };
+            globalThis.addEventListener?.('scrollend', arrive, { once: true });
+            this.landed = setTimeout(arrive, 1200);
+            if (this.behavior === 'auto') {
+                return;
+            }
+            event.preventDefault();
+            const reduced = globalThis.matchMedia?.('(prefers-reduced-motion: reduce)').matches === true;
+            section.target.scrollIntoView({
+                behavior: reduced && this.behavior === 'smooth' ? 'instant' : this.behavior,
+                block: 'start',
+            });
+            /* The three things the anchor would have done and the scroll does not. The
+               history entry keeps Back working and the address bar copyable; the focus
+               move is what stops Tab continuing from the contents list. `preventScroll`
+               because the scroll above is already under way and focusing would fight it,
+               instantly, wherever `smooth` was asked for. */
+            globalThis.history?.pushState(null, '', link?.getAttribute('href') ?? '');
+            const target = section.target;
+            if (!target.hasAttribute('tabindex')) {
+                target.setAttribute('tabindex', '-1');
+            }
+            target.focus({ preventScroll: true });
+        };
+        /**
+         * The set changed: watch it, and measure it.
+         *
+         * Both, for the reason the tab strip records: the host renders before its
+         * links have anything to point at, so the first measurement finds nothing,
+         * and without a second one at `slotchange` the mark stays unplaced for the
+         * life of the page.
+         */
+        this.handleSlotChange = () => {
+            this.watch();
+            this.indicator.place();
+        };
+    }
+    /**
+     * The id of the section being read, or empty before anything is measured.
+     *
+     * Read-only, and a getter rather than a property for that reason: it is
+     * derived from where the page is scrolled to, so a consumer setting it would
+     * be overwritten by the next thing that crossed the reading line. Every other
+     * writable property in this library that a component also writes is state a
+     * consumer can own; this one cannot be, and saying so with the type is better
+     * than saying it in a sentence nobody reads.
+     */
+    get current() {
+        return this.reading;
+    }
+    /** The links, in document order. Empty on the server, which has no tree. */
+    get links() {
+        const slot = this.renderRoot?.querySelector('slot');
+        return (slot?.assignedElements({ flatten: true }) ?? []).filter((element) => element instanceof HTMLAnchorElement &&
+            element.getAttribute('href')?.startsWith('#') === true);
+    }
+    /** What each link points at, paired with the link, skipping anything missing. */
+    get sections() {
+        const root = this.getRootNode();
+        return this.links.flatMap((link) => {
+            const id = decodeURIComponent(link.getAttribute('href')?.slice(1) ?? '');
+            const target = id ? root.getElementById?.(id) : null;
+            /* A section that is not rendered is not one that can be read.
+             *
+             * `display: none` reports a zero rect, and zero is above the reading line,
+             * so an unrendered section counts as passed on every measurement and the
+             * marker lands on the last one of them. Found on a reference page that
+             * shows one API tier at a time and hides the other: the rail marked a
+             * heading the reader could not see, and no scrolling could move it,
+             * because the hidden sections always won the comparison.
+             *
+             * `getClientRects()` rather than a size check, because it is empty for
+             * exactly the case in question and non-empty for a section that is merely
+             * scrolled out of view, which is very much readable. */
+            return target && target.getClientRects().length > 0 ? [{ link, target }] : [];
+        });
+    }
+    /**
+     * Works out which section is being read, and marks its link.
+     *
+     * Positional rather than a reading of what intersects, for the reason above.
+     * The comparison is against `offset` and not zero, so the reading line is
+     * wherever the page says the top of the readable area is.
+     */
+    mark() {
+        /* A destination beats a measurement. See `handleClick`: while the page is
+           traveling to somewhere a reader asked for, what it passes on the way is
+           not what they are reading. */
+        if (this.landing) {
+            return;
+        }
+        const sections = this.sections;
+        if (sections.length === 0) {
+            return;
+        }
+        const passed = sections.filter(({ target }) => target.getBoundingClientRect().top - this.offset <= 1);
+        /* At the end of the page the last section is what is being read, whether or
+           not its top ever reached the reading line.
+         *
+         * The positional rule has one blind spot and it is at the bottom: a section
+         * is current once its top passes the line, and a section near the end of the
+         * document may not have enough page beneath it to get there. Measured on
+         * three sections with a short last one, scrolled fully to the end, 910 of
+         * 910: the third heading sat at 530px, plainly on screen and plainly the
+         * thing being read, and the marker stayed on the second. The last item in a
+         * contents list was unreachable by scrolling.
+         *
+         * The same fault has no mirror at the top, where `passed` is empty and the
+         * first section is already the fallback. Asked, because the shape suggests
+         * one: the first heading's top starts *at* the line rather than below it,
+         * so there is nothing for it to fail to reach.
+         *
+         * What this cannot do is tell trailing sections apart. If the last three
+         * share the final screenful, none of them can reach the line and the page
+         * has no scroll left to distinguish them, so all three collapse into "you
+         * are at the end". That is a fact about the page rather than a choice made
+         * here: the component cannot invent room to scroll. */
+        const active = this.atEnd ? sections.at(-1) : (passed.at(-1) ?? sections[0]);
+        this.markTo(active);
+    }
+    /** Where the destination is set, whether measured or asked for. */
+    markTo(active) {
+        for (const { link, target } of this.sections) {
+            if (target === active?.target) {
+                link.setAttribute('aria-current', 'location');
+            }
+            else {
+                link.removeAttribute('aria-current');
+            }
+        }
+        /* And say so, which it did not.
+         *
+         * `reading` is derived from scroll position and was announced to nobody, so
+         * a consumer syncing a URL hash to the reading position had to poll for it:
+         * the one fact this component computes that nothing else on the page can,
+         * and the only way out of it was a `MutationObserver` on the anchors.
+         *
+         * Only on a change, because this runs from a scroll frame and an event per
+         * frame is not a signal, it is a firehose. */
+        const next = active?.target.id ?? '';
+        if (next !== this.reading) {
+            this.reading = next;
+            this.dispatchEvent(new HelixBeforeActivateEvent({ value: next }));
+        }
+    }
+    /**
+     * Whether the page has no more scroll left.
+     *
+     * `Math.ceil` and a pixel of slack, because a fractional device pixel ratio
+     * leaves the position a hair under the height at the very bottom and an exact
+     * comparison never fires.
+     *
+     * **All three numbers off the same element**, which this did not do: it added
+     * `scrollY` and `innerHeight`, both of the window, and compared them against
+     * `documentElement.scrollHeight`. Those are one coordinate system only while
+     * the viewport is what scrolls, and the body takes that job the moment it
+     * becomes a scroll container. Measured on a page whose body is
+     * `overflow: clip visible`, which is a pair CSS resolves by making the
+     * `visible` axis `auto`: `documentElement.scrollTop` read 1126 at the bottom
+     * of the page and `window.scrollY` read 240, so a contents rail never learned
+     * it had reached the end and its last item stayed unreachable. That page is
+     * this library's own base layer.
+     *
+     * `clientHeight` rather than `innerHeight` for the same reason, and because it
+     * is the one that excludes a scrollbar, which is what `scrollHeight` is
+     * measured against.
+     */
+    get atEnd() {
+        const doc = globalThis.document?.scrollingElement ?? globalThis.document?.documentElement;
+        if (!doc) {
+            return false;
+        }
+        return Math.ceil(doc.scrollTop + doc.clientHeight) >= doc.scrollHeight - 1;
+    }
+    /**
+     * Gives every section the same reading line the marker uses.
+     *
+     * `offset` described where the top of the readable area is and was read by
+     * exactly one thing, the marker. Click a link and the browser put the heading
+     * against the very top of the window, underneath the sticky masthead whose
+     * height the consumer had just finished measuring for us. So the component
+     * knew about the chrome when deciding what you were reading and forgot about
+     * it when taking you somewhere, which is the same number meaning two things.
+     *
+     * `scroll-margin-block-start` rather than an interception, because it is the
+     * property the platform provides for exactly this and the UA honours it on
+     * ordinary fragment navigation, on `scrollIntoView`, and on a browser
+     * restoring a position. Nothing has to be taken over to get it.
+     *
+     * Written onto the consumer's element, like `aria-current` above and for the
+     * same reason: it is derived from a property describing the page's chrome,
+     * so no server rendered it and there is nothing to disagree with. Cleared
+     * rather than set to `0px` when there is no offset, so the common case leaves
+     * no attribute at all.
+     */
+    reach() {
+        for (const { target } of this.sections) {
+            const element = target;
+            element.style.scrollMarginBlockStart = this.offset > 0 ? `${this.offset}px` : '';
+        }
+    }
+    /**
+     * Watches every section, and re-marks whenever any of them crosses anything.
+     *
+     * The thresholds are what make the trigger frequent enough: an observer fires
+     * on entering and leaving, and a long section scrolled slowly crosses neither
+     * for a long time. Asking for a callback at each quarter of visibility is
+     * cheap and keeps the marker honest without a scroll listener.
+     */
+    watch() {
+        this.observer?.disconnect();
+        /* Nothing to watch yet is not nothing to watch ever.
+         *
+         * This returned when no href resolved at first update, having already
+         * disconnected the observer, and only `slotchange` ever called it again: a
+         * page whose sections arrive after the nav does, which is every page that
+         * renders its content asynchronously, left the component dead for good. The
+         * observer is left disconnected either way, so re-running is the whole of
+         * the fix, and `updated` re-runs it while there is nothing to watch. */
+        if (this.sections.length === 0) {
+            this.observer = undefined;
+            return;
+        }
+        this.observer = new IntersectionObserver(() => this.mark(), {
+            threshold: [0, 0.25, 0.5, 0.75, 1],
+        });
+        for (const { target } of this.sections) {
+            this.observer.observe(target);
+        }
+        this.reach();
+        this.mark();
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.removeEventListener('click', this.handleClick);
+        globalThis.removeEventListener?.('scroll', this.handleScroll);
+        if (this.frame !== 0) {
+            globalThis.cancelAnimationFrame(this.frame);
+            this.frame = 0;
+        }
+        this.observer?.disconnect();
+        this.observer = undefined;
+        this.resize?.disconnect();
+        this.resize = undefined;
+        /* The landing timer, which nothing was clearing. It holds a closure over
+           this element for 1.2 seconds after it leaves the document and then
+           touches it, which on a route change is a write to a tree nobody is
+           looking at. Every other subscription here was already torn down, which is
+           what made this one easy to miss. */
+        clearTimeout(this.landed);
+        this.landed = undefined;
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        this.addEventListener('click', this.handleClick);
+        globalThis.addEventListener?.('scroll', this.handleScroll, { passive: true });
+        /* Both observers are rebuilt on reconnection, and neither was.
+         *
+         * They were created in `firstUpdated`, which runs once for the life of the
+         * element, and torn down in `disconnectedCallback`, which runs every time it
+         * moves. So a outline moved in the DOM, which a framework does on any
+         * reorder, came back permanently frozen: `aria-current`, `current` and the
+         * traveling mark all stopped for the rest of the page's life with nothing
+         * to say why. Guarded on `hasUpdated`, because the first connection happens
+         * before the first render and there is nothing to watch yet. */
+        if (this.hasUpdated) {
+            this.watch();
+            this.resize = new ResizeObserver(() => this.indicator.place());
+            this.resize.observe(this);
+        }
+    }
+    firstUpdated(changed) {
+        super.firstUpdated(changed);
+        this.watch();
+        /* The links are text in a column, so anything that changes the column's
+           width rewraps them and moves every one below. Nothing else would notice:
+           the intersection observer watches the sections, and a resize moves the
+           links without moving the page. */
+        this.resize = new ResizeObserver(() => this.indicator.place());
+        this.resize.observe(this);
+    }
+    updated(changed) {
+        super.updated(changed);
+        /* The reading line moved, so where the reader is may have changed without
+           the page having moved at all. Nothing else would notice: the observer
+           fires on sections crossing the viewport, and this changes what crossing
+           means rather than whether anything did. */
+        if (changed.has('offset')) {
+            this.reach();
+            this.mark();
+        }
+        /* Try again while there is nothing being watched. Cheap: `watch` returns on
+           the first line once it has something, and this is the only path back for
+           a nav whose sections had not rendered when it first looked. */
+        if (!this.observer) {
+            this.watch();
+        }
+        /* After the render that applied the new `aria-current`, not inside `mark()`
+           beside the attribute write. The current link is styled differently, and
+           on a narrow column the extra weight is enough to rewrap it, so measuring
+           before the style lands measures the wrong height. */
+        this.indicator.place();
+    }
+    render() {
+        return html `<nav part="nav" aria-label=${this.label}>
+      <slot @slotchange=${this.handleSlotChange}></slot>
+      <span part="indicator" aria-hidden="true"></span>
+    </nav>`;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessOutline.prototype, "label", void 0);
+__decorate([
+    property({ type: Number })
+], HelixHeadlessOutline.prototype, "offset", void 0);
+__decorate([
+    property()
+], HelixHeadlessOutline.prototype, "behavior", void 0);
+__decorate([
+    state()
+], HelixHeadlessOutline.prototype, "reading", void 0);
+HelixHeadlessOutline = __decorate([
+    customElement('helix-headless-outline')
+], HelixHeadlessOutline);
+export { HelixHeadlessOutline };

package/dist/pagination/index.d.ts

@@ -0,0 +1,3 @@
+export * from './root/pagination-root.js';
+export * from './size/pagination-size.js';
+export * from './summary/pagination-summary.js';

package/dist/pagination/index.js

@@ -0,0 +1,3 @@
+export * from './root/pagination-root.js';
+export * from './size/pagination-size.js';
+export * from './summary/pagination-summary.js';