@fusion.dev/helix-headless 0.0.0-dev → 0.0.3

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

@@ -11,13 +11,11 @@ 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.
+ * A table of contents, named for the job. It sits beside `Navigation`, which is
+ * the same job at the other scale: one navigates a site, the other navigates a
+ * document. `Contents` and `TableOfContents` are both taken by something else,
+ * `display: contents` and the `content` part in one case and the `Table` family
+ * in the other.
  *
  * **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
@@ -67,18 +65,6 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
             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.
          *
@@ -101,6 +87,18 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
          * JavaScript rather than CSS decides.
          */
         this.behavior = 'auto';
+        /**
+         * 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;
         /**
          * What `current` reports, which only `mark` writes.
          */
@@ -111,9 +109,6 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
          * 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
@@ -128,13 +123,12 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
          * 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.
+         * Marking once per animation frame while a scroll is happening covers both,
+         * where a listener that marks only when its own comparison changes fixes the
+         * bottom and cannot fix the settle. 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) {
@@ -171,9 +165,7 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
              * 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.
+             * item at a time instead of making the journey.
              *
              * Suppressed for any click on one of these links, not only the ones this
              * component scrolls itself: a consumer with `scroll-behavior: smooth` on
@@ -298,10 +290,10 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
          * 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.
+         * There is no mirror of it at the top: `passed` is empty there and the first
+         * section is already the fallback, and 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
@@ -321,12 +313,10 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
                 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.
+        /* And say so. `reading` is derived from scroll position, which is the one
+         * fact this component computes that nothing else on the page can, so a
+         * consumer syncing a URL hash to it has no other way in short of 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. */
@@ -343,16 +333,16 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
      * 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
+     * **All three numbers off the same element.** Adding the window's `scrollY`
+     * and `innerHeight` and comparing them against
+     * `documentElement.scrollHeight` mixes two coordinate systems, which agree
+     * 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.
+     * it had reached the end and its last item stayed unreachable. This library's
+     * own base layer produces exactly that page.
      *
      * `clientHeight` rather than `innerHeight` for the same reason, and because it
      * is the one that excludes a scrollbar, which is what `scrollHeight` is
@@ -368,15 +358,14 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
     /**
      * 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.
+     * `offset` says where the top of the readable area is, so it has to govern
+     * where a click lands as much as what the marker calls current. Read by the
+     * marker alone, a click puts the heading against the very top of the window
+     * and underneath the sticky masthead the consumer measured the offset from,
+     * 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
+     * property the platform provides for exactly this and the UA honors it on
      * ordinary fragment navigation, on `scrollIntoView`, and on a browser
      * restoring a position. Nothing has to be taken over to get it.
      *
@@ -398,18 +387,17 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
      * 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.
+     * cheap. It is still only a trigger: see `handleScroll` for the two cases no
+     * intersection can see.
      */
     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. */
+        /* Nothing to watch yet is not nothing to watch ever. A page whose sections
+         * arrive after the nav does, which is every page rendering its content
+         * asynchronously, resolves no href at first update, and returning here
+         * without leaving a way back kills the component for the life of the page.
+         * `updated` re-runs this while `observer` is undefined, which is why the
+         * field is cleared rather than left holding a disconnected observer. */
         if (this.sections.length === 0) {
             this.observer = undefined;
             return;
@@ -435,11 +423,9 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
         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. */
+        /* The landing timer 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. */
         clearTimeout(this.landed);
         this.landed = undefined;
     }
@@ -447,15 +433,13 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
         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. */
+        /* Both observers are rebuilt on reconnection. `firstUpdated` runs once for
+         * the life of the element and `disconnectedCallback` runs every time it
+         * moves, so without this an outline moved in the DOM, which a framework does
+         * on any reorder, comes back permanently frozen: `aria-current`, `current`
+         * and the traveling mark all stop 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());
@@ -501,15 +485,15 @@ let HelixHeadlessOutline = class HelixHeadlessOutline extends HelixElement {
     </nav>`;
     }
 };
+__decorate([
+    property()
+], HelixHeadlessOutline.prototype, "behavior", void 0);
 __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);

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

@@ -40,13 +40,12 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * result that has not changed. A consumer driving the view has to be able to
  * hear that without being told an answer changed.
  *
- * **The count and the page-size control are their own elements.** They were
- * briefly a part and a pair of slots in here, and a slot can only offer one
- * place: at one end of one row, in one order, on one axis. `Pagination.Summary`
- * and `Pagination.Size` sit beside this one instead, so the direction and the
- * order of a footer are the consumer's, which is what they were always going to
- * want. `total` and `page-size` stay here for the arithmetic below and nothing
- * else.
+ * **The count and the page-size control are their own elements.** A slot can
+ * only offer one place: at one end of one row, in one order, on one axis.
+ * `Pagination.Summary` and `Pagination.Size` sit beside this one instead, so
+ * the direction and the order of a footer are the consumer's, which is what
+ * they were always going to want. `total` and `page-size` stay here for the
+ * arithmetic below and nothing else.
  *
  * **A single page renders nothing.** A control offering one page offers no
  * navigation, and the row it sits in should close over it rather than hold a
@@ -56,16 +55,16 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * framework reports the difference; a custom state carries the same fact to a
  * stylesheet and none of that to the DOM.
  *
- * **And a page change is announced.** Nothing did: moving the page moves
- * `aria-current` onto a different element, and a screen reader does not announce
- * that, so a reader who pressed 5 heard the word "5" from the button they were
- * on and nothing at all about having arrived. A polite live region says where
- * they now are. It ships empty and is filled only on a change, because a region
- * populated as it enters the document announces itself on arrival.
+ * **And a page change is announced.** Moving the page moves `aria-current` onto
+ * a different element, which a screen reader does not announce, so a reader who
+ * pressed 5 hears the word "5" from the button they were on and nothing at all
+ * about having arrived. A polite live region says where they now are. It ships
+ * empty and is filled only on a change, because a region populated as it enters
+ * the document announces itself on arrival.
  *
- * `page` is the controlled property and `default-page` seeds one the element
- * owns. Naming `page` is a claim of ownership: the element announces and waits
- * to be told, which is what a consumer paging through a router already wants.
+ * `page` is what the element holds and `default-page` seeds it. A consumer
+ * paging through a router refuses `helix-navigate` and assigns their own, which
+ * is how they take the decision.
  *
  * @since 0.1.0
  * @status experimental
@@ -94,35 +93,25 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  */
 export declare class HelixHeadlessPagination extends HelixElement {
     /**
-     * How many pages there are in total.
-     *
-     * Clamped to at least one wherever it is read, so a result that has not
-     * loaded yet renders a single page rather than an empty control that then
-     * appears and pushes the layout down.
-     *
-     * Left unset where `total` and `page-size` are both given, since the two of
-     * them already say it. A fallback rather than an override: writing this wins,
-     * so there is never a question of which of two sources is current.
+     * How many pages to show at each end, whatever the current one is.
      */
-    pages: number;
+    boundaries: number;
     /**
-     * How many items there are across every page.
+     * Where the numbers are replaced by a reading of the two.
      *
-     * What `pages` falls back to together with `page-size`. Unset is the common
-     * case, where a consumer knows the page total and not the item total.
+     * A different structure rather than a different look, which is why it is
+     * here: the run of pages is gone and a single status line stands in its
+     * place. This is the shape a narrow screen wants, and the only shape possible
+     * where the total is large enough that no window over it is useful.
      *
-     * Nothing is rendered from it. `Pagination.Summary` is what reads a total out
-     * to a reader, and takes its own.
+     * Not reflected, for the reason `ends` is not: it decides what renders, so
+     * nothing has to select on it.
      */
-    total: number;
+    compact: boolean;
     /**
-     * How many items are on a page.
-     *
-     * Only arithmetic: this does not slice anything, because the component never
-     * sees the items. It is what turns `total` into a page count, and nothing
-     * else.
+     * Page to open on, where nothing declared one.
      */
-    pageSize: number;
+    defaultPage: number;
     /**
      * Whether to offer a jump to the first and last pages.
      *
@@ -142,34 +131,28 @@ export declare class HelixHeadlessPagination extends HelixElement {
      * The page on show, one-based.
      *
      * An accessor pair, the same shape as the calendar's `month`. Reading gives
-     * the page on show; writing declares it the consumer's, and `default-page`
-     * seeds one the element owns.
+     * the page on show; writing sets it, and `default-page` seeds one the element
+     * keeps until somebody does.
      *
      * **Clamped on the way out, because "the page on show" is what it says it
-     * gives.** It returned whatever had been written, so `default-page="99"` on a
-     * ten-page result rendered page 10, marked page 10 with `aria-current`, and
-     * reported 99. A consumer syncing their query from this read a page that does
-     * not exist while the control in front of them said otherwise. Not a
+     * gives.** Returning whatever was written means `default-page="99"` on a
+     * ten-page result renders page 10, marks page 10 with `aria-current`, and
+     * reports 99, so a consumer syncing their query from this reads a page that
+     * does not exist while the control in front of them says otherwise. Not a
      * far-fetched value: it is a bookmarked link after the result shrank.
      *
      * Rounded here too, so `2.7` reads as the 2 it renders.
-     *
-     *
      */
     get page(): number;
     set page(next: number);
     /**
-     * Page to open on, where nothing declared one.
-     */
-    defaultPage: number;
-    /**
-     * How many pages to show either side of the current one.
+     * Accessible name for the control that jumps to the first page.
      */
-    siblings: number;
+    firstLabel: string;
     /**
-     * How many pages to show at each end, whatever the current one is.
+     * Accessible name for a gap, with `{page}` filled in as where it goes.
      */
-    boundaries: number;
+    gapLabel: string;
     /**
      * Address for a page, with `{page}` standing in for its number.
      *
@@ -178,22 +161,14 @@ export declare class HelixHeadlessPagination extends HelixElement {
      * one, and the back button works without the consumer wiring anything.
      */
     href: string;
-    /**
-     * Where the numbers are replaced by a reading of the two.
-     *
-     * A different structure rather than a different look, which is why it is
-     * here: the run of pages is gone and a single status line stands in its
-     * place. This is the shape a narrow screen wants, and the only shape possible
-     * where the total is large enough that no window over it is useful.
-     *
-     * Not reflected, for the reason `ends` is not: it decides what renders, so
-     * nothing has to select on it.
-     */
-    compact: boolean;
     /**
      * Accessible name for the navigation landmark.
      */
     label: string;
+    /**
+     * Accessible name for the control that jumps to the last page.
+     */
+    lastLabel: string;
     /**
      * Locale for the page numbers. Absent uses the runtime's own.
      *
@@ -208,39 +183,61 @@ export declare class HelixHeadlessPagination extends HelixElement {
      * different address from `?page=1234`.
      */
     locale: string;
+    /**
+     * Accessible name for the control that moves forward.
+     */
+    nextLabel: string;
     /**
      * Accessible name for one page, with `{page}` and `{pages}` filled in.
      */
     pageLabel: string;
     /**
-     * The reading shown in `compact`, with `{page}` and `{pages}` filled in.
+     * How many pages there are in total.
      *
-     * The word went: it read "Page 7 of 24" and the landmark it sits in is
-     * already named "Pagination", so the noun was said twice to a screen reader
-     * and took a third of the width from a control whose whole reason for
-     * existing is that the row is narrow. The numbers are the reading.
+     * Clamped to at least one wherever it is read, so a result that has not
+     * loaded yet renders a single page rather than an empty control that then
+     * appears and pushes the layout down.
+     *
+     * Left unset where `total` and `page-size` are both given, since the two of
+     * them already say it. A fallback rather than an override: writing this wins,
+     * so there is never a question of which of two sources is current.
      */
-    statusLabel: string;
+    pages: number;
     /**
-     * Accessible name for the control that moves back.
+     * How many items are on a page.
+     *
+     * Only arithmetic: this does not slice anything, because the component never
+     * sees the items. It is what turns `total` into a page count, and nothing
+     * else.
      */
-    previousLabel: string;
+    pageSize: number;
     /**
-     * Accessible name for the control that moves forward.
+     * Accessible name for the control that moves back.
      */
-    nextLabel: string;
+    previousLabel: string;
     /**
-     * Accessible name for the control that jumps to the first page.
+     * How many pages to show either side of the current one.
      */
-    firstLabel: string;
+    siblings: number;
     /**
-     * Accessible name for the control that jumps to the last page.
+     * The reading shown in `compact`, with `{page}` and `{pages}` filled in.
+     *
+     * No noun: the landmark this sits in is already named "Pagination", so
+     * "Page 7 of 24" says it twice to a screen reader and takes a third of the
+     * width from a control whose whole reason for existing is that the row is
+     * narrow. The numbers are the reading.
      */
-    lastLabel: string;
+    statusLabel: string;
     /**
-     * Accessible name for a gap, with `{page}` filled in as where it goes.
+     * How many items there are across every page.
+     *
+     * What `pages` falls back to together with `page-size`. Unset is the common
+     * case, where a consumer knows the page total and not the item total.
+     *
+     * Nothing is rendered from it. `Pagination.Summary` is what reads a total out
+     * to a reader, and takes its own.
      */
-    gapLabel: string;
+    total: number;
     /**
      * What the live region says, and nothing until the page has moved once.
      *
@@ -265,7 +262,7 @@ export declare class HelixHeadlessPagination extends HelixElement {
      * later and pushes the layout down.
      */
     private get count();
-    /** The page on show. `page` does the clamping now; this is the older name. */
+    /** The page on show, which `page` has already clamped. */
     private get current();
     /**
      * Which pages to show, and where the runs break.
@@ -285,9 +282,8 @@ export declare class HelixHeadlessPagination extends HelixElement {
      * Asks to move, and reports whether the request stood.
      *
      * Announced before it is applied, so `preventDefault()` is a refusal and
-     * nothing moves. In controlled mode nothing is written whatever the answer:
-     * the consumer holds the page and this is the element telling them a reader
-     * asked for another one.
+     * nothing moves. A consumer who holds the page refuses it and assigns their
+     * own.
      */
     private request;
     /**
@@ -333,17 +329,16 @@ export declare class HelixHeadlessPagination extends HelixElement {
      * at which it stops being possible. It would also make `Pagination` depend on
      * `Menu` and `Popover` for a case a button already covers.
      *
-     * So it is announced rather than hidden, which is the change from when it was
-     * a decoration: a control a reader can reach has to be in the tree, and the
-     * label naming its destination is the whole affordance.
+     * So it is announced rather than hidden: a control a reader can reach has to
+     * be in the tree, and the label naming its destination is the whole
+     * affordance.
      */
     private renderGap;
     /**
      * Everything a step needs, computed once, so the markup below is only markup.
      *
-     * Split out because the part name has to be a literal. `check:parts` reads
-     * `part="name"` out of the source, so a computed one is a part the tooling
-     * cannot see: nothing pairs it with its `@csspart` and a later rename takes
+     * Split out because the part name has to be a literal. A part name is read
+     * from the source, so a computed one is a part nothing can see: nothing pairs it with its `@csspart` and a later rename takes
      * the promise silently. With four controls and two shapes each that is eight
      * literals, and eight copies of the arithmetic behind them would be the
      * actual duplication. This is the arithmetic, written once.