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

package/dist/pagination/root/pagination-root.js

@@ -64,13 +64,12 @@ const fill = (template, page, pages, format = String) => template.replaceAll('{p
  * 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
@@ -80,16 +79,16 @@ const fill = (template, page, pages, format = String) => template.replaceAll('{p
  * 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
@@ -120,35 +119,25 @@ let HelixHeadlessPagination = class HelixHeadlessPagination extends HelixElement
     constructor() {
         super(...arguments);
         /**
-         * 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.
          */
-        this.pages = 0;
+        this.boundaries = 1;
         /**
-         * 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.
          */
-        this.total = 0;
+        this.compact = false;
         /**
-         * 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.
          */
-        this.pageSize = 0;
+        this.defaultPage = 1;
         /**
          * Whether to offer a jump to the first and last pages.
          *
@@ -165,17 +154,13 @@ let HelixHeadlessPagination = class HelixHeadlessPagination extends HelixElement
          */
         this.ends = false;
         /**
-         * Page to open on, where nothing declared one.
-         */
-        this.defaultPage = 1;
-        /**
-         * How many pages to show either side of the current one.
+         * Accessible name for the control that jumps to the first page.
          */
-        this.siblings = 1;
+        this.firstLabel = 'First page';
         /**
-         * 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.
          */
-        this.boundaries = 1;
+        this.gapLabel = 'Skip to page {page}';
         /**
          * Address for a page, with `{page}` standing in for its number.
          *
@@ -184,22 +169,14 @@ let HelixHeadlessPagination = class HelixHeadlessPagination extends HelixElement
          * one, and the back button works without the consumer wiring anything.
          */
         this.href = '';
-        /**
-         * 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.
-         */
-        this.compact = false;
         /**
          * Accessible name for the navigation landmark.
          */
         this.label = 'Pagination';
+        /**
+         * Accessible name for the control that jumps to the last page.
+         */
+        this.lastLabel = 'Last page';
         /**
          * Locale for the page numbers. Absent uses the runtime's own.
          *
@@ -214,39 +191,61 @@ let HelixHeadlessPagination = class HelixHeadlessPagination extends HelixElement
          * different address from `?page=1234`.
          */
         this.locale = '';
+        /**
+         * Accessible name for the control that moves forward.
+         */
+        this.nextLabel = 'Next page';
         /**
          * Accessible name for one page, with `{page}` and `{pages}` filled in.
          */
         this.pageLabel = 'Page {page}';
         /**
-         * The reading shown in `compact`, with `{page}` and `{pages}` filled in.
+         * 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.
          *
-         * 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.
+         * 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.
          */
-        this.statusLabel = '{page} of {pages}';
+        this.pages = 0;
         /**
-         * 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.
          */
-        this.previousLabel = 'Previous page';
+        this.pageSize = 0;
         /**
-         * Accessible name for the control that moves forward.
+         * Accessible name for the control that moves back.
          */
-        this.nextLabel = 'Next page';
+        this.previousLabel = 'Previous page';
         /**
-         * Accessible name for the control that jumps to the first page.
+         * How many pages to show either side of the current one.
          */
-        this.firstLabel = 'First page';
+        this.siblings = 1;
         /**
-         * 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.
          */
-        this.lastLabel = 'Last page';
+        this.statusLabel = '{page} of {pages}';
         /**
-         * 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.
          */
-        this.gapLabel = 'Skip to page {page}';
+        this.total = 0;
         /**
          * What the live region says, and nothing until the page has moved once.
          *
@@ -277,19 +276,17 @@ let HelixHeadlessPagination = 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() {
         const asked = this.pageState ?? this.defaultPage;
@@ -322,7 +319,7 @@ let HelixHeadlessPagination = class HelixHeadlessPagination extends HelixElement
         }
         return 1;
     }
-    /** The page on show. `page` does the clamping now; this is the older name. */
+    /** The page on show, which `page` has already clamped. */
     get current() {
         return this.page;
     }
@@ -379,9 +376,8 @@ let HelixHeadlessPagination = 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.
      */
     request(next) {
         if (next === this.current || next < 1 || next > this.count) {
@@ -406,11 +402,9 @@ let HelixHeadlessPagination = class HelixHeadlessPagination extends HelixElement
            default name at all: an author's own `aria-label` is an attribute and
            beats internals, so naming it here costs them nothing. */
         hostAria(this.internals, { label: this.label, role: 'navigation' });
-        /* Through `toggleState`, which carries the feature test this wrote out
-           itself until every state in the library came through one door. An engine
-           without `CustomStateSet` gets a control that renders its one page instead
-           of disappearing, which is the behavior this had before and is not
-           broken. */
+        /* Through `toggleState`, which carries the feature test: an engine without
+           `CustomStateSet` gets a control that renders its one page instead of
+           disappearing, which is degraded rather than broken. */
         this.toggleState('empty', this.count <= 1);
     }
     /**
@@ -481,9 +475,9 @@ let HelixHeadlessPagination = 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.
      */
     renderGap(hidden) {
         const to = Math.round((hidden.from + hidden.to) / 2);
@@ -510,9 +504,8 @@ let HelixHeadlessPagination = class HelixHeadlessPagination extends HelixElement
     /**
      * 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.
@@ -631,13 +624,13 @@ let HelixHeadlessPagination = class HelixHeadlessPagination extends HelixElement
 };
 __decorate([
     property({ type: Number })
-], HelixHeadlessPagination.prototype, "pages", void 0);
+], HelixHeadlessPagination.prototype, "boundaries", void 0);
 __decorate([
-    property({ type: Number })
-], HelixHeadlessPagination.prototype, "total", void 0);
+    property({ type: Boolean })
+], HelixHeadlessPagination.prototype, "compact", void 0);
 __decorate([
-    property({ attribute: 'page-size', type: Number })
-], HelixHeadlessPagination.prototype, "pageSize", void 0);
+    property({ attribute: 'default-page', type: Number })
+], HelixHeadlessPagination.prototype, "defaultPage", void 0);
 __decorate([
     property({ type: Boolean })
 ], HelixHeadlessPagination.prototype, "ends", void 0);
@@ -645,47 +638,47 @@ __decorate([
     property({ type: Number })
 ], HelixHeadlessPagination.prototype, "page", null);
 __decorate([
-    property({ attribute: 'default-page', type: Number })
-], HelixHeadlessPagination.prototype, "defaultPage", void 0);
-__decorate([
-    property({ type: Number })
-], HelixHeadlessPagination.prototype, "siblings", void 0);
+    property({ attribute: 'first-label' })
+], HelixHeadlessPagination.prototype, "firstLabel", void 0);
 __decorate([
-    property({ type: Number })
-], HelixHeadlessPagination.prototype, "boundaries", void 0);
+    property({ attribute: 'gap-label' })
+], HelixHeadlessPagination.prototype, "gapLabel", void 0);
 __decorate([
     property()
 ], HelixHeadlessPagination.prototype, "href", void 0);
-__decorate([
-    property({ type: Boolean })
-], HelixHeadlessPagination.prototype, "compact", void 0);
 __decorate([
     property()
 ], HelixHeadlessPagination.prototype, "label", void 0);
+__decorate([
+    property({ attribute: 'last-label' })
+], HelixHeadlessPagination.prototype, "lastLabel", void 0);
 __decorate([
     property()
 ], HelixHeadlessPagination.prototype, "locale", void 0);
+__decorate([
+    property({ attribute: 'next-label' })
+], HelixHeadlessPagination.prototype, "nextLabel", void 0);
 __decorate([
     property({ attribute: 'page-label' })
 ], HelixHeadlessPagination.prototype, "pageLabel", void 0);
 __decorate([
-    property({ attribute: 'status-label' })
-], HelixHeadlessPagination.prototype, "statusLabel", void 0);
+    property({ type: Number })
+], HelixHeadlessPagination.prototype, "pages", void 0);
+__decorate([
+    property({ attribute: 'page-size', type: Number })
+], HelixHeadlessPagination.prototype, "pageSize", void 0);
 __decorate([
     property({ attribute: 'previous-label' })
 ], HelixHeadlessPagination.prototype, "previousLabel", void 0);
 __decorate([
-    property({ attribute: 'next-label' })
-], HelixHeadlessPagination.prototype, "nextLabel", void 0);
-__decorate([
-    property({ attribute: 'first-label' })
-], HelixHeadlessPagination.prototype, "firstLabel", void 0);
+    property({ type: Number })
+], HelixHeadlessPagination.prototype, "siblings", void 0);
 __decorate([
-    property({ attribute: 'last-label' })
-], HelixHeadlessPagination.prototype, "lastLabel", void 0);
+    property({ attribute: 'status-label' })
+], HelixHeadlessPagination.prototype, "statusLabel", void 0);
 __decorate([
-    property({ attribute: 'gap-label' })
-], HelixHeadlessPagination.prototype, "gapLabel", void 0);
+    property({ type: Number })
+], HelixHeadlessPagination.prototype, "total", void 0);
 __decorate([
     state()
 ], HelixHeadlessPagination.prototype, "announcement", void 0);

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

@@ -11,37 +11,26 @@ import '../../select/index.js';
  * consumer's, and a control that can only sit at one end of one row has taken
  * that decision for them.
  *
- * **`Select`, not a native `<select>`.** It was native first, on the argument
- * that the platform's own menu is a wheel on a phone and the widget a
- * screen-reader user already knows. What that argument leaves out is that the
- * library then has two dropdowns that are identical closed and different open,
- * and a reader meets both in the same footer as a table's filters. Consistency
- * is the whole product here, and it wins.
+ * **`Select`, not a native `<select>`.** Two dropdowns identical closed and
+ * different open meet each other in the same footer as a table's filters. The
+ * caret is `Select`'s rather than a color literal baked into a data URI,
+ * because a background image cannot read `currentColor`, and the label is a
+ * real `<label for>` against the trigger's own id.
  *
- * What it takes back with it: the caret is `Select`'s again rather than a color
- * literal baked into a data URI, because a background image cannot read
- * `currentColor`, and the label is a real `<label for>` against the trigger's
- * own id, which `Select` already renders and already tests.
+ * **The label sits on the row, not above it.** `Select`'s host is a column, and
+ * an outer-tree rule beats a `:host` rule, so turning it into a row needs no
+ * property on `Select` and nothing written into the consumer's markup.
  *
- * **The label sits on the row, not above it.** Every other field in the library
- * stacks its label because it stands in a column of fields; this one stands in a
- * footer beside a run of page numbers, and a two-line control there makes the
- * whole row two lines tall. `Select`'s host is a column, and an outer-tree rule
- * beats a `:host` rule, so turning it into a row needs no property on `Select`
- * and nothing written into the consumer's markup.
+ * **An empty `sizes` renders nothing**, rather than falling back to the
+ * built-in list, which would be a component overruling a consumer who said
+ * "none". Same rule as `Pagination` over a single page, and reported the same
+ * way, through `ElementInternals.states` rather than an attribute the server
+ * never wrote.
  *
- * **An empty `sizes` renders nothing.** A chooser with nothing to choose from
- * is a control a reader can operate and cannot use, which is worse than an
- * absence. Falling back to the built-in list was the other answer and it is a
- * component overruling a consumer who said "none". Same rule as `Pagination`
- * over a single page, and reported the same way, through
- * `ElementInternals.states` rather than an attribute the server never wrote.
- *
- * `value` is the controlled property and `default-value` seeds one this owns,
- * the same contract every other stateful element here carries. Changing it
- * announces `helix-before-change`; what a consumer does with that is re-query and move
- * back to page one, which is theirs to decide because only they know whether
- * the reader's position should survive it.
+ * `value` is the controlled property and `default-value` seeds one this owns.
+ * Changing it announces `helix-before-change`; re-querying and moving back to
+ * page one is the consumer's, because only they know whether the reader's
+ * position should survive it.
  *
  * @since 0.1.0
  * @status experimental
@@ -57,28 +46,18 @@ import '../../select/index.js';
  */
 export declare class HelixHeadlessPaginationSize extends HelixElement {
     /**
-     * The sizes offered, comma separated.
-     *
-     * A string rather than an array, so the whole control is expressible in
-     * markup and survives a server render. Anything that is not a positive number
-     * is dropped rather than rendered as an option that cannot mean anything.
+     * Size to start on, where nothing declared one.
      */
-    sizes: string;
+    defaultValue: number;
     /**
      * The size in force.
      *
      * Reading gives the real one; writing declares it the consumer's, and
      * `default-value` seeds one this element owns. Same accessor pair as
      * `Pagination.page` and the calendar's `month`.
-     *
-     *
      */
     get value(): number;
     set value(next: number);
-    /**
-     * Size to start on, where nothing declared one.
-     */
-    defaultValue: number;
     /**
      * The words beside the control.
      */
@@ -89,6 +68,14 @@ export declare class HelixHeadlessPaginationSize extends HelixElement {
      * Absent uses the runtime's own.
      */
     locale: string;
+    /**
+     * The sizes offered, comma separated.
+     *
+     * A string rather than an array, so the whole control is expressible in
+     * markup and survives a server render. Anything that is not a positive number
+     * is dropped rather than rendered as an option that cannot mean anything.
+     */
+    sizes: string;
     /** The size, whoever set it, and `undefined` until somebody has. */
     private valueState;
     /** Held across every component asking for the same locale. */
@@ -106,16 +93,10 @@ export declare class HelixHeadlessPaginationSize extends HelixElement {
      * wrap this one, pass it a property the base does not know about, or leave it
      * out, without reimplementing the whole template to do any of them.
      *
-     * **The tags are interpolated, so each tier renders its own.** They were
-     * written out as `<helix-select>` on the argument that each tier imports its
-     * own element under that name, which works and costs more than it looks: the
-     * name means two different things depending on what a consumer imported, this
-     * tier composes an element it does not ship, and the composition cannot be
-     * tested here at all, since there is no `helix-select` on this tier to test it
-     * against. `tier` resolves the name instead, and the styled subclass changes
-     * it in one line rather than reimplementing this method. A tier that renders
-     * its own elements is a tier that stands alone, which is the claim the package
-     * makes.
+     * **The tags are interpolated, so each tier renders its own.** Writing
+     * `<helix-select>` out would make this tier compose an element it does not
+     * ship and cannot test against, there being no `helix-select` here. `tier`
+     * resolves the name instead, and the styled subclass changes it in one line.
      */
     protected renderSelect(): TemplateResult;
     protected render(): TemplateResult | typeof nothing;