@fusion.dev/helix-headless 0.0.0-dev

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

@@ -0,0 +1,237 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * @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.
+ */
+export declare class HelixHeadlessOutline extends HelixElement {
+    private readonly indicator;
+    /**
+     * Accessible name for the navigation.
+     */
+    label: string;
+    /**
+     * 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.
+     */
+    offset: number;
+    /**
+     * 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.
+     */
+    behavior: ScrollBehavior;
+    /**
+     * 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(): string;
+    /**
+     * What `current` reports, which only `mark` writes.
+     */
+    private reading;
+    private observer;
+    private resize;
+    /** The links, in document order. Empty on the server, which has no tree. */
+    private get links();
+    /** What each link points at, paired with the link, skipping anything missing. */
+    private get sections();
+    /**
+     * 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.
+     */
+    private mark;
+    /** Where the destination is set, whether measured or asked for. */
+    private markTo;
+    /**
+     * 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.
+     */
+    private get atEnd();
+    /** The frame a mark is already scheduled for, so a scroll asks for one. */
+    private frame;
+    /** Where a click said to go, while the page is still on its way there. */
+    private landing;
+    /** The guard behind `scrollend`, in case it never comes. */
+    private landed;
+    /**
+     * 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.
+     */
+    private readonly handleScroll;
+    /**
+     * 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.
+     */
+    private reach;
+    /**
+     * 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`.
+     */
+    private readonly handleClick;
+    /**
+     * 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.
+     */
+    private watch;
+    /**
+     * 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.
+     */
+    private readonly handleSlotChange;
+    disconnectedCallback(): void;
+    connectedCallback(): void;
+    protected firstUpdated(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-outline': HelixHeadlessOutline;
+    }
+}