@fusion.dev/helix-headless 0.4.2 → 0.4.3

package/dist/file-input/root/file-input-root.d.ts

@@ -10,29 +10,12 @@ declare const HelixHeadlessFileInput_base: (new (...args: any[]) => import("@fus
  * replaced.** It is the only way to open a file picker: the dialog is a
  * privileged action a script cannot start on its own, and it opens for a click
  * on the input or on a `<label>` pointing at it. A component that draws its own
- * button ends up calling `.click()` on a hidden input anyway, and then has two
- * things a screen reader can find where there is one control.
+ * button calls `.click()` on a hidden input anyway, and then has two things a
+ * screen reader can find where there is one control.
  *
- * So the input stays, holds the label, the name, the validity and the focus,
- * and the visible trigger is a `<label for>` rather than a button. A label is
- * not focusable and does not need to be: the input is, and Enter and Space on it
- * open the picker because that is what the platform does with a file input.
- *
- * **Dropping is why this is a component rather than an attribute.** A bare file
- * input accepts a drop only on the input itself, which is invisible here, so the
- * field is the drop target and it says when something is over it.
- *
- * **Files are not a value a consumer can hand back.** Every other control here
- * takes the controlled and uncontrolled pair, and this one does not: a `FileList`
- * cannot be constructed from markup, and browsers refuse a consumer writing
- * `value` on a file input outright, because a page that could name a file could
- * read it. So this element owns what was chosen, announces it, and offers
- * `clear()` for the one change a consumer can legitimately ask for.
- *
- * **The list under it is the control's own, not decoration.** A file input with
- * files chosen reports "3 files" and nothing else, which is unusable for
- * checking that the right ones were picked. The names are rendered, and each
- * carries the way to take it back out.
+ * So the input stays, holding the label, the name, the validity and the focus,
+ * and the visible trigger is a `<label for>`. A label is not focusable and does
+ * not need to be: the input is, and Enter and Space on it open the picker.
  *
  * @since 0.1.0
  * @status stable

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

@@ -6,49 +6,26 @@ declare const HelixHeadlessHeatmap_base: typeof HelixElement & (new (...args: an
  * @summary A strip of cells colored by how each one went: uptime, contributions, activity.
  *
  * @description
- * **One family covers both readings, and the split people expect does not
- * exist.** The argument for two is that a contribution graph needs a continuous
- * ramp where uptime needs a category. GitHub's contribution graph is five
- * discrete levels rather than a gradient, so a cell that takes a tone covers
- * both: `rows="1"` is a status strip, `rows="7"` is a contribution graph, and
- * heatmap is the name of that.
+ * **One family covers both readings.** `rows="1"` is a status strip, `rows="7"`
+ * is a contribution graph, and a cell that takes a tone covers both: GitHub's
+ * contribution graph is five discrete levels rather than a gradient.
  *
  * **What it cannot be is a bar chart with flat values**, and the data model is
- * what closes that rather than taste: chart color is per *series* everywhere
- * else here, `--chart-series-1` through `-15`, so ninety differently colored
- * cells would be ninety series.
+ * what closes that: chart color is per *series* everywhere else here, so ninety
+ * differently colored cells would be ninety series.
  *
- * The data is a real `<table>` named by `for`, the same convention every chart
- * in this library uses, which also answers the accessibility question without
- * inventing anything: **the table is the accessible representation**, it is
- * already in the markup, and the drawing is a picture of it. Hide it with
- * `data-hidden-visually` and the reading is still there for anyone who needs it.
+ * **The data is a real `<table>` named by `for`**, the convention every chart
+ * in this library uses, and it is the accessible representation. Hide it with
+ * `data-hidden-visually` and the reading is still there.
  *
  * A cell takes its tone from its own `data-tone`, or from `thresholds` and
- * `tones` bucketing its value. The first is what a status page wants and the
- * second is what a contribution graph wants; the cell's own wins, so a page that
- * already knows a day was degraded does not have to encode that as a number for
- * this component to decode again.
+ * `tones` bucketing its value. The cell's own wins, so a page that already
+ * knows a day was degraded does not encode that as a number to be decoded.
  *
  * **A tone is a name this tier never resolves.** `tone="success"` writes
- * `--heatmap-tone: var(--heatmap-tone-success)` onto the cell and stops there,
- * so what a name is worth is the answering tier's to say: `helix/styled` points
- * the semantic names at the theme's status colors and the numbered ones at a
- * ramp, and a consumer on `headless` declares the same names as whatever they
- * like. Reaching for `var(--helix-color-${tone})` here is the dependency the
- * tiers exist to prevent, and it fails loudly rather than quietly: off-tier that
- * property is not undefined, it is *invalid*, so
- * `background-color: var(--heatmap-tone, …)` declines its own fallback and every
- * cell comes out transparent, leaving a blank page under a row of footer text.
- * `shared/chart/series.css` records the same fault in Bar Chart.
- *
- * **On a narrow container it draws fewer cells rather than thinner ones.**
- * Ninety cells in 320 pixels is three and a half pixels each, which is a smear
- * and not a strip. The cells it drops are the oldest, and it reflects `visible`
- * and fires `helix-resize` when the number changes, because **a summary saying
- * "99.2% over 90 days" above a strip drawing 45 of them is telling the reader
- * something false about the picture in front of them** and nothing about the
- * picture says so.
+ * `--heatmap-tone: var(--heatmap-tone-success)` and stops, so what a name is
+ * worth is the answering tier's to say. Reaching for `var(--helix-color-*)`
+ * here is the dependency the tiers exist to prevent.
  *
  * @since 0.1.0
  * @status experimental

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

@@ -5,31 +5,14 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  *
  * @description
  * **An element rather than a recipe, because of the part CSS cannot do.**
- * Reserving the box is `aspect-ratio` and needs nothing from anybody; `Link` and
- * the megamenu row are recipes in `preview.css` for exactly that reason. What
- * cannot be written as a rule is *when the picture arrived*: a stylesheet has no
- * way to know, and no way to hear that it never will. So this owns three states
- * and the two events that move between them, and leaves the box to the
+ * Reserving the box is `aspect-ratio` and needs nothing from anybody. What
+ * cannot be written as a rule is *when the picture arrived*: a stylesheet has
+ * no way to know, and no way to hear that it never will. So this owns three
+ * states and the two events that move between them, and leaves the box to the
  * stylesheet.
  *
  * **The placeholder is a slot with nothing in it by default.** A default of
- * `Skeleton` would be right and is not written here: this tier renders no other
- * component, and reaching for one would make the headless package depend on the
- * styled one. The styled tier draws the resting placeholder instead, and a
- * consumer who wants a `Skeleton`, a blurred thumbnail or a solid color slots
- * it.
- *
- * **No source is a loading state, not a fourth one.** A picture whose `src` has
- * not arrived yet is the common case for anything drawn from data, and the
- * useful answer there is the same as for one still on the wire: stand something
- * in its place and keep the ground reserved. So an element with no `src` shows
- * its placeholder and waits, rather than resolving to an empty box that has to
- * be laid out twice.
- *
- * **`alt` is a property and not an afterthought.** An empty string is a real
- * answer, meaning the picture is decoration and a screen reader should skip it,
- * which is why the attribute is always written even when it is empty: omitting
- * it entirely makes a reader announce the file name instead.
+ * `Skeleton` would make this tier depend on a component it does not ship.
  *
  * @since 0.1.0
  * @status experimental

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

@@ -8,39 +8,21 @@ declare const HelixHeadlessInput_base: (new (...args: any[]) => import("@fusion.
  *
  * @description
  * Renders a real `<input>`, so the caret, selection, autofill, spellcheck, the
- * password manager, and the on-screen keyboard a phone chooses all come from the
- * platform. `delegatesFocus` puts focus on it, and it serializes into the
- * server's markup, so the field is usable before any script loads.
+ * password manager and the on-screen keyboard a phone chooses are all the
+ * platform's. It serializes into the server's markup, so the field is usable
+ * before any script loads.
  *
- * **The input inside a shadow root submits nothing**, because the form is on the
+ * **The input inside a shadow root submits nothing**, the form being on the
  * other side of the boundary. The host is form-associated instead and reports
- * its own value through `ElementInternals`, which is also what carries validity
- * and what answers a form reset.
+ * its own value through `ElementInternals`, which also carries validity and
+ * answers a form reset.
  *
- * `value` and `defaultValue` are separate for the reason `checked` and
- * `defaultChecked` are: `value` is what is in the field now and
- * `defaultValue` is what the markup asked for, which is where a reset returns
- * to and is gone the moment anyone types.
+ * `value` and `defaultValue` are separate the way `checked` and
+ * `defaultChecked` are: `value` is what is in the field now, `defaultValue` is
+ * what the markup asked for and where a reset returns to.
  *
- * **Validity is the platform's.** The `type` and `required` are set on the real
- * input and its `validity` is copied onto the host, so an email field rejects
- * what the browser says is not an email rather than what a regular expression
- * here guesses. What this adds is the anchor, so `reportValidity` points the
- * bubble at the input rather than at the host.
- *
- * `pattern`, `minlength` and `maxlength` are forwarded with them.
- *
- * **`clearable` and `reveal` are the field's, not the consumer's.** Neither is
- * a slot's worth of variation: one empties the value, the other flips the type,
- * and both want the same position, the same size and the same disabled
- * behavior. The `end` slot stays for what actually varies, a unit or a prefix.
- *
- * Both opt in rather than following from `type`, and are booleans that default
- * to false. A Lit boolean property that defaults to *true* cannot be turned off
- * from HTML at all, only from script, which is the wrong way round for
- * revealing a password: a consumer should have to ask for it. Drawer's `modal`
- * defaults true for the opposite reason, that losing a focus trap by forgetting
- * a word is worse than having to say so.
+ * **Validity is the platform's.** `type` and `required` are set on the real
+ * input and its `validity` is copied onto the host.
  *
  * @since 0.1.0
  * @status experimental

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

@@ -5,38 +5,20 @@ import { type TemplateResult } from 'lit';
  *
  * @description
  * Renders a real `<kbd>`, so the passage still means "press this" to anything
- * reading the markup rather than only to a reader looking at it.
+ * reading the markup.
  *
- * **One key per element, with `keys` as the stated exception.** A *sequence* is
+ * **One key per element, with `keys` as the stated exception.** A sequence is
  * several of these with the separator written between them as ordinary text,
- * because that separator is prose: it is "then" in a sequence and "plus" in a
- * simultaneous press, and a component that inserted one would have to guess
- * which. `keys` cannot be guessing, since a chord written `mod+k` has said
- * which it is.
+ * because that separator is prose: "then" in a sequence, "plus" in a chord, and
+ * a component inserting one would have to guess which.
  *
  * **`keys` exists because the glyphs were being typed by hand and were wrong.**
  * A literal `⌘K` in a template tells a reader on Windows to press a key their
- * keyboard does not have, and nothing catches it, a string being a string.
- * Given `mod` this renders `⌘K` on Apple and `Ctrl+K` everywhere else.
+ * keyboard does not have, and nothing catches it. Given `mod` this renders
+ * `⌘K` on Apple and `Ctrl+K` everywhere else.
  *
- * **`within` is what binds it, and it is absent by default.** Without it this
- * draws a key and listens for nothing, which is what every existing use of this
- * component wants. The two values are the two honest lifetimes:
- *
- * - `control` listens within the element's own parent, which is the case this
- *   is mostly for: a hint sitting inside the control it belongs to, where the
- *   shortcut should work while that control has focus and stop existing when
- *   the control does.
- * - `document` listens on the document, for a chord that works from anywhere.
- *
- * **A hidden `kbd` is a dead shortcut, and that is the point rather than a
- * trap.** Binding here ties the key to its own advertisement, so a hint that is
- * not rendered is a shortcut that is not offered. A chord that must outlive its
- * label is a chord whose owner is not a label: give it to whatever owns the
- * action and let this element only describe it.
- *
- * Nothing binds until this upgrades, so a shortcut is not available in the
- * moments before hydration.
+ * **`within` is what binds it, and it is absent by default**, so this draws a
+ * key and listens for nothing unless asked.
  *
  * @since 0.1.0
  * @status stable

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

@@ -6,32 +6,14 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @description
  * A legend is a list, so it is a list: not part of a chart, and shared by
  * whichever of them needs one. It takes its entries from the same table the
- * chart reads, through `for`, so the two cannot disagree about how many series
- * there are or what they are called.
+ * chart reads, through `for`, so the two cannot disagree.
  *
- * `entries` picks which way to read that table, and the two ways are the two
- * shapes a chart comes in. `series` is one entry per data column, named by the
- * header row, which is a line or a bar chart. `categories` is one entry per
- * body row, named by its row header, which is a donut: its slices are the rows,
- * and it has no axis to write their names along.
+ * `entries` picks which way to read that table. `series` is one entry per data
+ * column, named by the header row, which is a line or a bar chart.
+ * `categories` is one entry per body row, which is a donut: its slices are the
+ * rows and it has no axis to write their names along.
  *
- * **The table is resolved on the client and there is no server pass.** `for` is
- * an id and resolving it wants a document, which the server render does not
- * have, so a legend ships empty and fills in on hydration. The table itself is
- * ordinary markup and is served whole, so nothing is missing from the page
- * before then, only from this list.
- *
- * The table is watched, because a legend that goes stale when its data changes
- * is a legend that has to be told, and nothing else in the page would know to
- * tell it.
- *
- * **Not hidden from a screen reader, though the mapping it draws is a color
- * one.** The argument for hiding it is real: the colors mean nothing to a
- * reader who cannot see them, and the names are already in the table. It stays
- * because the cost of being wrong runs one way. A duplicated list of three
- * words is noise; a consumer who took the table out of the accessibility tree
- * and then found the legend hidden too has a chart nobody can read, and neither
- * decision announces itself.
+ * **The table is resolved on the client and there is no server pass.**
  *
  * @since 0.1.0
  * @status experimental

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

@@ -9,37 +9,15 @@ declare const HelixHeadlessListbox_base: (new (...args: any[]) => import("@fusio
  * **The listbox is the control and the options are its vocabulary.** A Select
  * is this with a trigger in front of it, a Combobox is this with a text input,
  * and a command palette is this again: they differ in what opens the list and
- * what filters it, not in what the list is. Building it as its own family is
- * what stops each of those reimplementing the keyboard and the filtering.
+ * what filters it, not in what the list is.
  *
  * **`value` is comma separated when `multiple` is set**, the way
  * `Checkbox.Group`'s is. It stays a string because that is what a form submits
- * and what `MixinControllerValue` holds; an array property would be a second
- * shape for the same fact, and the two would disagree the first time one was
- * set without the other.
+ * and what `MixinControllerValue` holds.
  *
  * **Chosen and active are two different things.** Chosen is the answer; active
- * is where the keyboard is. In a single-select list they move together, which
- * is the radio group pattern and is what a reader expects from arrow keys. With
- * `multiple` they come apart: the arrows move without choosing and Space
- * chooses, because a reader passing over four options on the way to the fifth
- * did not mean to pick all five.
- *
- * **This does not use `KeyboardNavigationController`, and the reason is where
- * focus lives rather than whether moving chooses.** The controller already
- * separates those, taking `origin: 'focus' | 'selection'`. What it cannot do is
- * leave focus alone: `NavigableItem.focusItem()` moves DOM focus to the item,
- * its model being a roving tab stop. A filterable list cannot have that, focus
- * having to stay in the field or typing stops, so what moves is a virtual
- * cursor and `aria-activedescendant` is what says where it is. No flag
- * reconciles the two.
- *
- * **Filtering hides rather than removes.** An option the filter has hidden is
- * still the consumer's element in the consumer's order, so a filter that clears
- * puts the list back exactly as it was with nothing re-rendered. What counts as
- * a match is a plain case-insensitive substring, and a consumer wanting more
- * hides options itself: `filter` is a convenience over the same `hidden` the
- * component uses.
+ * is where the keyboard is. Only the second moves with the arrows, and
+ * `aria-activedescendant` names it while focus stays on the list.
  *
  * @since 0.1.0
  * @status experimental

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

@@ -8,49 +8,17 @@ declare const HelixHeadlessMegamenu_base: (new (...args: any[]) => import("@fusi
  * **A disclosure, not a menu, and that is the whole design.** `role="menu"` and
  * `menuitem` are for an application's commands: they take over the arrow keys,
  * announce "menu" to a reader who asked for navigation, and put every link
- * inside a role that is not a link. What this is, is a button that shows and
- * hides a region of the consumer's own anchors, which is the pattern the APG
- * gives for site navigation and the one that leaves a middle click, a modified
+ * inside a role that is not a link. This is a button that shows and hides a
+ * region of the consumer's own anchors, which leaves a middle click, a modified
  * click and the status bar working. `Menu` remains right for a row of commands.
  *
- * **It renders no links**, for the reason `Navigation` gives: a router renders
- * its own anchor and cannot render one inside this shadow root. The panel is a
- * slot, and what goes in it is lists and headings the consumer wrote.
+ * **It renders no links.** A router renders its own anchor and cannot render
+ * one inside this shadow root, so the panel is a slot and what goes in it is
+ * the lists and headings the consumer wrote.
  *
  * **It opens on hover, and a press is always the fallback.** `open-on` says
- * which, and hover is the resting value because a nav bar is the one place a
- * reader expects to sweep along a row and see each section: making them click,
- * read, click again to compare two is the interaction hover exists to save.
- *
- * Hover is not the only way in, and the code is mostly about that. There is no
- * hover on a touch screen, so a tap opens the panel there whatever `open-on`
- * says, which is why the pointer type is checked rather than assumed. Focus
- * still opens nothing, for the same reason a tab through a nav bar should not
- * unfold it, but Enter on the trigger does, and a keyboard press arrives as a
- * click with no pointer behind it.
- *
- * A mouse click on a trigger the pointer is already sitting on is the case
- * worth naming: toggling there would close the panel and the pointer, still on
- * the trigger, would open it again, so the trigger would flicker and never
- * close. In hover mode the mouse's own clicks are left alone and hover governs
- * on its own. Escape and a click away still close it.
- *
- * The delays are intent, not decoration. Opening waits, so a pointer crossing
- * the bar on its way somewhere else opens nothing; closing waits longer, so the
- * diagonal from the trigger down into the panel does not pass through a gap and
- * shut it. Moving along a bar where a panel is already down opens the next one
- * at once, because at that point the reader is reading the bar, not crossing it.
- *
- * **Focus is not trapped and not moved.** A disclosure leaves the reader on the
- * trigger and the panel follows in the tab order, which is what the markup
- * already says, so Tab walks into the links and out the far side without
- * anything managing it. Escape closes and puts focus back, because Escape is
- * the one key that has to return the reader to where they were.
- *
- * The custom property below is written by this component and read by whoever
- * draws it. A consumer never sets it: it carries a number this element computed
- * and CSS cannot, which is what lets a stylesheet on this tier draw the thing
- * without measuring anything itself.
+ * which, and hover is the resting value because a nav bar is where a reader
+ * expects to sweep along a row and see each section.
  *
  * @since 0.1.0
  * @status experimental

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

@@ -9,31 +9,13 @@ export type MeterBand = 'fair' | 'good' | 'poor';
  * **Not `Progress`, and the difference is the whole component.** A progress bar
  * reports how far along a task is: it starts empty, ends full, and full is
  * always the good end. A meter reports a level in a range that is not going
- * anywhere, and which end is good is a fact about the thing being measured.
- * Disk usage, a battery, a score, a rate limit. So there is no `indeterminate`
- * here: a measurement whose value is unknown is not a measurement.
+ * anywhere, and which end is good is a fact about the thing measured. So there
+ * is no `indeterminate`: a measurement whose value is unknown is not one.
  *
- * **`low`, `high` and `optimum` are the reason it exists**, and they follow the
- * HTML specification's own rule. The three thresholds cut the range into a low
- * band, a middle and a high band, and `optimum` says which of the three is the
- * one to be in. The band the value falls in is then the good one, the one next
- * to it is fair, and the one two away is poor.
- *
- * **Without thresholds there are no bands, and this is where it parts company
- * with `<meter>`.** The platform defaults `optimum` to the midpoint and both
- * thresholds to the ends, so a bare `<meter value="20" max="100">` computes as
- * optimum and every browser paints it green. A gauge with nothing said about it
- * is not good news; it is a reading. Declared thresholds turn the color on.
- *
- * **And the bands are drawn as well as colored.** A tick sits at `low` and at
- * `high`, so the reading can be placed against them without seeing color at
- * all, which is the same call the carousel's current dot makes by lengthening
- * rather than only changing color.
- *
- * The properties below are written by this component and read by whoever draws
- * it. A consumer sets none of them: they carry a number this element computed
- * and CSS cannot, which is what lets a stylesheet on this tier draw the thing
- * without measuring anything itself.
+ * **`low`, `high` and `optimum` are the reason it exists**, following the HTML
+ * specification's own rule. The three cut the range into a low band, a middle
+ * and a high band, and `optimum` says which is the one to be in; the band next
+ * to it is fair and the one two away is poor.
  *
  * @since 0.1.0
  * @status stable

package/dist/number-input/root/number-input-root.d.ts

@@ -5,17 +5,13 @@ declare const HelixHeadlessNumberInput_base: (new (...args: any[]) => import("@f
  * @summary A number a reader types or steps to.
  *
  * @description
- * **A family rather than `Input`'s `type="number"`, and rather than a part of
- * it.** `Input` already takes that type and will keep it: a bare numeric field
- * in a form is a text field with a different keyboard, and that is all it needs
- * to be. This is a different control. It renders two buttons, binds four keys
- * that `Input` does not, and owns clamping and stepping, so it is an alternative
- * and not a variant. Namespacing it under `Input` would say it is contained by
- * one, which is what `IconButton` is top-level for.
+ * **A family rather than `Input`'s `type="number"`.** It renders two buttons,
+ * binds four keys `Input` does not, and owns clamping and stepping, so it is an
+ * alternative and not a variant.
  *
  * **The field is `type="text"` with `inputmode="decimal"`, and that is a
- * measurement rather than a preference.** Asked of a real browser, `type=number`
- * fails three ways this control cannot live with:
+ * measurement.** Asked of a real browser, `type=number` fails three ways this
+ * control cannot live with:
  *
  * ```
  * typed "12e" into type=number  → .value === ""
@@ -24,21 +20,16 @@ declare const HelixHeadlessNumberInput_base: (new (...args: any[]) => import("@f
  * same keystrokes into type=text → .value === "12e"
  * ```
  *
- * The first is fatal on its own: the element cannot see what the reader typed,
- * so a controlled value is destroyed by a keystroke and there is nothing left to
- * correct or to report. The second changes a value because a page scrolled past.
- * The third means the caret cannot be managed at all, which any correcting or
- * formatting field needs. `inputmode` is what keeps the phone keypad, which is
+ * The first is fatal alone: the element cannot see what the reader typed. The
+ * second changes a value because a page scrolled past. The third means the
+ * caret cannot be managed at all. `inputmode` keeps the phone keypad, which is
  * the one thing `type=number` was giving.
  *
  * Validity is still the platform's, through `min`, `max` and `step` mirrored
- * onto the host's own `setValidity`. What is not mirrored is the field's
- * `type`, because a text field has no opinion about numbers.
+ * onto the host's own `setValidity`.
  *
- * **Stepping is separate from typing.** A reader mid-way through "1" of "12"
- * has not asked for anything to be clamped, so the value is only pulled into
- * range when they step, blur, or the form asks. Clamping on every keystroke is
- * what makes a field that cannot be typed backwards into.
+ * **Stepping is separate from typing**, so a reader mid-way through a number is
+ * not corrected under their hands.
  *
  * @since 0.1.0
  * @status experimental

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

@@ -5,35 +5,16 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  *
  * @description
  * 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 same job at the other scale: one navigates a site, the other 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.
+ * **The links are the consumer's own anchors.** 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.
+ * **What is current is decided by position, not by intersection.** An
+ * `IntersectionObserver` with a band near the top fails in both directions:
+ * with headings far apart nothing is in the band and the marker goes out, and
+ * with headings close together several are in it at once.
  *
  * @since 0.1.0
  * @status experimental

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

@@ -4,67 +4,34 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @summary Moves between pages of a longer result.
  *
  * @description
- * The component is the truncation. Given a page and a total it works out which
- * numbers to show and where the runs break, which is the whole of what a
- * consumer would otherwise write by hand and get subtly wrong; everything else
- * here is markup around that. So this is data-driven rather than composed:
- * `<helix-pagination page="4" pages="12">` rather than twelve slotted children
- * a consumer has to keep in step with their own query.
+ * **The component is the truncation.** Given a page and a total it works out
+ * which numbers to show and where the runs break, so this is data-driven rather
+ * than composed: `<helix-pagination page="4" pages="12">` rather than twelve
+ * slotted children a consumer keeps in step with their own query.
  *
  * **The width does not change as you page.** The run around the current page is
- * `siblings` either side normally, and grows to absorb a gap slot when it meets
- * a boundary, so the control holds the same number of slots from the first page
- * to the last. Every arrangement that lets the count vary makes the buttons move
- * under the pointer between one click and the next.
+ * `siblings` either side, and grows to absorb a gap slot at a boundary, so the
+ * control holds the same number of slots from the first page to the last.
+ * Anything that lets the count vary moves the buttons under the pointer between
+ * one click and the next.
  *
- * **A gap is only drawn where it hides more than one page.** An ellipsis
- * standing in for a single number costs the same space as the number and tells
- * the reader less.
- *
- * **And a gap is a control.** It goes to the middle of the run it stands over,
- * which is the binary-search step: any page in a set of any size is a handful of
- * presses, where a jump of a fixed size would need forty of them on a set of a
- * hundred and twenty-eight. A menu listing the hidden pages was the other idea
- * and the arithmetic refuses it, for the reasons on `renderGap`.
+ * **A gap is only drawn where it hides more than one page, and a gap is a
+ * control.** It goes to the middle of the run it stands over, which is the
+ * binary-search step: any page in a set of any size is a handful of presses.
  *
  * **`href` is what makes these links.** Set it and every page renders an `<a>`
- * with `{page}` filled in, so the server's output is crawlable, a middle click
- * opens a tab, and the address bar is the state. Left unset they are buttons,
- * which is right for a table paging in place. Either way the click announces
- * `helix-navigate` first, and `preventDefault()` on it stops the navigation as
- * well as the change: that is how a router takes over without the page reloading
- * underneath it.
- *
- * **`helix-navigate` and not `helix-change`**, for the reason the calendar pages
- * with it too. Moving to page four chooses nothing; it moves the view over a
- * 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.** 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
- * space for a thing that cannot be used. Reported through
- * `ElementInternals.states` rather than an attribute on the host, because an
- * attribute written at upgrade is markup a server's output never had and a
- * framework reports the difference; a custom state carries the same fact to a
- * stylesheet and none of that to the DOM.
+ * with `{page}` filled in, so the output is crawlable, a middle click opens a
+ * tab, and the address bar is the state. Left unset they are buttons, which is
+ * right for a table paging in place. Either way the click announces
+ * `helix-navigate` first, and `preventDefault()` stops the navigation as well
+ * as the change, which is how a router takes over.
  *
- * **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.
+ * **`helix-navigate` and not `helix-change`.** Moving to page four chooses
+ * nothing; it moves the view over a result that has not changed.
  *
- * `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.
+ * **The count and the page-size control are their own elements.**
+ * `Pagination.Summary` and `Pagination.Size` sit beside this one, because a
+ * slot can only offer one place: at one end of one row, in one order.
  *
  * @since 0.1.0
  * @status experimental