@fusion.dev/helix-core 0.1.0 → 0.3.0

package/dist/utils/draw-tooltip/draw-tooltip.js

@@ -2,43 +2,6 @@ import { nothing } from 'lit';
 import { styleMap } from 'lit/directives/style-map.js';
 import { html } from 'lit/static-html.js';
 import { seriesIndex } from '../../mixins/mixin-chart-source/mixin-chart-source.js';
-/**
- * What a pointer resting on a reading shows, as `Tooltip` pointed at a mark.
- *
- * **A chart does not draw its own tooltip, and the top layer is why.** `Tooltip`
- * renders `popover="manual"` through `PopoverController`, so it clears every
- * stacking context and every `overflow` on the page. A box drawn by the chart is
- * `position: absolute` inside the plot and is confined to the chart's own
- * context, so it is clipped by, or layered under, whatever sits beside the
- * chart. Escaping that means reimplementing `PopoverController`, which is
- * `Tooltip` with extra steps and a second copy of the hard part.
- *
- * **`for` was already the anchor and needed nothing added.** It resolves through
- * `getRootNode().getElementById()`, and a chart's shadow root *is* a
- * `ShadowRoot`, so a chart names an element inside itself and `Tooltip` finds
- * it. What the chart provides is an invisible mark at the reading's point.
- *
- * **An HTML mark rather than the `<rect>` or `<circle>` already there.**
- * `FloatingController` types its anchor as `HTMLElement` and an SVG element is
- * not one; and a slice's `<circle>` has the bounding box of the whole ring
- * rather than of its arc, so anchoring to it would point at the ring's center
- * for every slice.
- *
- * **And the arrow now follows from placement rather than from a compass.** The
- * chart says which side it prefers and `FloatingController` moves it if that
- * side does not fit, which is how a slice at any bearing gets a bubble that
- * points at it. Four hard-coded sides could not express a bearing, which is what
- * made the donut's arrow miss its own ring.
- *
- * **It shows the table's text and not the chart's numbers.** `$128k` is what the
- * cell says and `128000` is what the drawing measured. Every cell of the row is
- * here, including columns nothing was plotted from, because a note beside the
- * figures is most of the reason to want a tooltip.
- *
- * **Hidden from assistive technology, on purpose.** The table is the accessible
- * representation and the drawing is `aria-hidden`; a reader on a keyboard gets
- * the table, which they can reach, rather than a tooltip which they cannot.
- */
 export const drawTooltip = (rows, at, tag, where) => {
     const row = rows[at];
     if (!row || rows.length === 0) {
@@ -50,10 +13,6 @@ export const drawTooltip = (rows, at, tag, where) => {
         x: `${at * slot + slot / 2}%`,
         y: '0%',
     };
-    /* The mark and the bubble are siblings, and the id is fixed rather than
-       generated: it is scoped to this chart's shadow root, where it is the only
-       one, so nothing can collide with it and nothing has to be threaded through
-       a render to stay in step. */
     return html `<div
       id="helix-chart-mark"
       part="mark"
@@ -69,15 +28,7 @@ export const drawTooltip = (rows, at, tag, where) => {
     >
       <div aria-hidden="true" slot="content">
         <span part="tooltip-label">${row.label}</span>
-        ${row.cells.map((cell, index) => 
-    /* A palette color only where something was plotted in it.
-     *
-     * A cell with no number is a column no chart drew: a note, a status,
-     * a name. Given `data-series` anyway it takes a series color and the
-     * stylesheet draws a dot, so a row reading `Note  Outage` arrived
-     * wearing series three's green while the legend beside the chart said
-     * series three was something else. */
-    html `<span
+        ${row.cells.map((cell, index) => html `<span
               data-series=${cell.value === undefined ? nothing : seriesIndex(index)}
               part="tooltip-cell"
             >

package/dist/utils/elapsed-time/elapsed-time.js

@@ -1,35 +1,10 @@
-/**
- * A timestamp read the way a feed reads one: short, and a date once short stops
- * meaning anything.
- *
- * **The compact form is ambiguous past a week, and that is why it stops.**
- * `Intl.NumberFormat` with `unitDisplay: 'narrow'` is the only locale-aware way
- * to get "42m" rather than "42 minutes ago", and measured across locales it
- * renders both `minute` and `month` as `m` in en-US: "3m" is three minutes or
- * three months and a reader cannot tell which. `Intl.RelativeTimeFormat` in its
- * narrow style disambiguates the month as "3mo" and keeps an affix that cannot
- * be removed across locales, German prefixing "vor" and Japanese suffixing 前.
- *
- * So the compact form covers the range where it is unambiguous, the units up to
- * a week, and past that this returns a date. Nothing is guessed and nothing is
- * hand-written: the short units come from `Intl.NumberFormat`, the dates from
- * `Intl.DateTimeFormat`, and both answer to the caller's locale.
- *
- * Cached per locale for the reason `relativeTime` and `formatNumbers` are: the
- * constructors are expensive, the calls are cheap, and a feed of fifty items
- * formats fifty times per update.
- */
 const held = new Map();
 const dated = new Map();
-/** The units the compact form covers, largest last. `week` is deliberately not
-    among them: past six days this returns a date instead, which is both shorter
-    to read and the only reading that cannot be mistaken for minutes. */
 const UNITS = [
     { ms: 60_000, unit: 'minute' },
     { ms: 3_600_000, unit: 'hour' },
     { ms: 86_400_000, unit: 'day' },
 ];
-/** Where the compact form gives out, in milliseconds. Seven days. */
 const HORIZON = 604_800_000;
 const compact = (locale) => {
     let found = held.get(locale);
@@ -43,9 +18,6 @@ const compact = (locale) => {
     }
     return found;
 };
-/** Same day and month for a timestamp inside the year, month and year outside
-    it: "12 Mar" says everything while the year is understood, and "Mar 2023" is
-    what a reader wants once it is not. */
 const calendar = (locale) => {
     let found = dated.get(locale);
     if (!found) {
@@ -57,21 +29,9 @@ const calendar = (locale) => {
     }
     return found;
 };
-/**
- * A formatter for one locale, kept.
- *
- * `now` is a parameter rather than read from the clock, for the reason
- * `relativeTime` gives: a function that reads `Date.now()` internally can only
- * be tested by waiting or by replacing a global, and both produce specs that
- * fail on a slow machine.
- */
 export const elapsedTime = (locale) => {
     const short = compact(locale);
     const dates = calendar(locale);
-    /* "now" rather than a count of seconds, and taken from `Intl` rather than
-       written here so it is a word in the reader's language. Under a minute a feed
-       that reports 3, then 4, then 5 seconds is a feed moving under somebody
-       trying to read it, and nobody acts differently at seven seconds than four. */
     const zero = new Intl.RelativeTimeFormat(locale || undefined, { numeric: 'auto' });
     return (from, now) => {
         const elapsed = now.getTime() - from.getTime();
@@ -80,14 +40,8 @@ export const elapsedTime = (locale) => {
         }
         const size = Math.abs(elapsed);
         if (size < 60_000) {
-            /* Floored like every other branch. At 59,999 milliseconds the remainder is
-               one, and a caller handed a one is re-armed inside the callback that
-               fired it. */
             return { next: Math.max(1000, 60_000 - size), text: zero.format(0, 'second') };
         }
-        /* A date, and it will not change again. `Infinity` is the whole point of
-           saying so: the caller schedules nothing, so a feed of old notifications
-           left open overnight wakes for none of them. */
         if (size >= HORIZON) {
             const sameYear = from.getFullYear() === now.getFullYear();
             const format = sameYear ? dates[0] : dates[1];
@@ -101,11 +55,6 @@ export const elapsedTime = (locale) => {
         }
         const chosen = UNITS[index];
         const count = Math.trunc(size / chosen.ms);
-        /* Time until the count ticks over, which is the remainder of the current
-           unit rather than the whole of one: read at 90 seconds an item is "1m" for
-           another 30 seconds, not another 60. Capped where `relativeTime` caps it,
-           and floored at a second so nobody is handed a zero and schedules a busy
-           loop. */
         const remaining = Math.min(chosen.ms - (size % chosen.ms), HORIZON - size);
         return {
             next: Math.max(1000, Math.min(remaining, 3_600_000)),

package/dist/utils/focusable-elements/focusable-elements.js

@@ -1,11 +1,3 @@
-/**
- * Elements the platform will focus, without naming a single component.
- *
- * Custom elements are covered separately below: one with `delegatesFocus` is
- * focusable as a host, and that is readable from outside through `shadowRoot`.
- * Listing tag names instead would mean a utility in `core` that only worked for
- * the components `core` happens to know about.
- */
 const NATIVE_FOCUSABLE = [
     'a[href]',
     'button:not([disabled])',
@@ -15,40 +7,8 @@ const NATIVE_FOCUSABLE = [
     '[contenteditable]:not([contenteditable="false"])',
     '[tabindex]:not([tabindex="-1"])',
 ].join(',');
-/**
- * Everything inside `root` the reader can reach with Tab, in document order.
- *
- * Separate from the focus trap because finding is the half most callers want:
- * roving tabindex, arrow-key navigation and "focus the first thing" all need
- * this list and none of them traps anything.
- *
- * Visibility is tested with `getClientRects()` rather than `offsetParent`,
- * which is null for anything inside a `position: fixed` container. A drawer is
- * exactly that, so the `offsetParent` test excluded every control in the thing
- * being trapped.
- */
-export const focusableElements = (root) => 
-/* One pass asking both questions, rather than two passes concatenated.
- *
- * Two lists joined end to end is not document order: every native element
- * followed by every delegating host comes out `b d a c` for a tree holding
- * `a b c d`, measured. The trap reads `items[0]` and `items.at(-1)` as its
- * boundaries, so a surface whose last control is a plain `<button>` and whose
- * first is a Helix component has a last that is not last, forward Tab off the
- * real end does not wrap, and focus leaves the dialog.
- *
- * It is invisible in a set that is all one kind, which is what every example
- * and every spec had. A single filtered walk cannot express the fault, and
- * dedup comes free with it: a delegating host that also matches the native
- * selector is visited once because it is one node. */
-[...root.querySelectorAll('*')].filter((node) => (node.matches(NATIVE_FOCUSABLE) || node.shadowRoot?.delegatesFocus === true) &&
+export const focusableElements = (root) => [...root.querySelectorAll('*')].filter((node) => (node.matches(NATIVE_FOCUSABLE) || node.shadowRoot?.delegatesFocus === true) &&
     node.getClientRects().length > 0);
-/**
- * The truly focused element, following shadow roots down.
- *
- * `document.activeElement` stops at the outermost host, so a button inside two
- * shadow roots reports as the component rather than as itself.
- */
 export const deepActiveElement = () => {
     let active = document.activeElement;
     while (active?.shadowRoot?.activeElement) {
@@ -56,24 +16,6 @@ export const deepActiveElement = () => {
     }
     return active;
 };
-/**
- * Whether `node` sits inside `root`, following shadow boundaries upward.
- *
- * `Node.contains` walks `parentNode` and a shadow root's `parentNode` is null,
- * so it answers false for anything inside a component. Paired with
- * `deepActiveElement`, which returns exactly such a node, that pairing is a trap
- * of its own: the two look like they belong together and one of them crosses.
- *
- * `contains(deepActiveElement())` is the shape to avoid: focus on a
- * `helix-button` reports as the `<button>` in its shadow root, which is in no
- * light-DOM container anywhere, so a trap written that way reads every reader
- * as already outside it.
- *
- * `host` is reached without naming `ShadowRoot`, which the server has no global
- * for. This runs from a keydown handler and would never execute there, but a
- * bare reference is the kind that surfaces as a crash in Lit's result collector
- * the first time something calls it early.
- */
 export const deepContains = (root, node) => {
     let current = node;
     while (current) {

package/dist/utils/format-numbers/format-numbers.js

@@ -1,19 +1,3 @@
-/**
- * A number formatter for a locale, built once and kept.
- *
- * `Intl.NumberFormat` is expensive to construct and cheap to call, and a
- * pagination renders its count on every update, so building one per render is
- * the whole cost of the component.
- *
- * Keyed on the locale, so a component that never changes locale builds one
- * formatter for its life and one that does builds a second and drops the first.
- * Shared across components rather than per instance: a table of a hundred rows
- * asking for the same locale gets the same object, which is what a cache is
- * for and what a private field per element cannot do.
- *
- * An empty string means the runtime's own, which is what every caller was
- * already passing `|| undefined` to say.
- */
 const held = new Map();
 export const formatNumbers = (locale) => {
     let format = held.get(locale);

package/dist/utils/host-aria/host-aria.js

@@ -1,29 +1,3 @@
-/**
- * Writes a host's semantics onto its `ElementInternals`.
- *
- * Onto internals rather than onto the host, which is the whole point: an
- * attribute written at upgrade is markup a React consumer's server output never
- * had, and hydration reports the difference. Internals carry the same meaning
- * to the accessibility tree and leave the element as the consumer wrote it.
- *
- * **Empty means absent, and that is the trap this exists for.** Assigning `''`
- * to `ariaLabel` is not the same as not naming the element: it is a name of no
- * characters, which a screen reader announces as an unnamed control while every
- * check for "is it labeled" passes. Clearing is `null`, and this is the one
- * place that has to remember it.
- *
- * **Element references are feature-tested rather than assumed.** They are the
- * only way a host in the light DOM can point at a node in its own shadow root,
- * an IDREF cannot cross that boundary, and the plain `element.aria*Elements`
- * reflection drops the reference where `ElementInternals` keeps it. Older
- * engines have neither, and assigning to a property they do not implement is a
- * silent no-op rather than an error, so the guard is what makes the absence
- * visible to anything reading this.
- *
- * Omitted keys are left alone, so a component that sets its role once in
- * `willUpdate` and its references later in `updated` does not have to repeat
- * itself or risk clearing what the other call wrote.
- */
 export const hostAria = (internals, semantics) => {
     if (semantics.role !== undefined) {
         internals.role = semantics.role === '' ? null : semantics.role;

package/dist/utils/inherit-disabled/inherit-disabled.js

@@ -1,31 +1,4 @@
-/**
- * What each item declared for itself, before any group wrote to it.
- *
- * A `WeakMap` because the alternative is reading the attribute back, and the
- * attribute is the thing being written: `disabled` reflects, so the second pass
- * would read what the first pass wrote and the item would never come back.
- */
 const own = new WeakMap();
-/**
- * Disables a group's members without forgetting what they said themselves.
- *
- * A group and its members are two sources for one fact: a member is out of play
- * if either says so. Written the obvious way that is
- * `item.disabled = group || item.disabled`, and it latches. The first pass with
- * the group disabled writes `true` onto every member; the next pass reads its
- * own writing back as the member's own answer; and enabling the group leaves
- * every member disabled for good. Nothing about it is visible until something
- * re-enables a group, which is rare enough to ship and miserable to find.
- *
- * So what a member said itself is recorded before it is first overridden, and
- * given back when the group lets go. Restoring is the half that matters: a
- * version that only recorded would read the overridden value as the member's
- * own the moment the group was enabled, which is the same latch by a longer
- * route.
- *
- * Once given back, the record is dropped, so a consumer disabling a member
- * afterwards is its own answer again and is left alone.
- */
 export const inheritDisabled = (disabled, items) => {
     for (const item of items) {
         if (disabled) {
@@ -35,21 +8,12 @@ export const inheritDisabled = (disabled, items) => {
             item.disabled = true;
             continue;
         }
-        /* Only where this held it down. An item nothing overrode is the consumer's
-           business and is not touched, which is what keeps a group that was never
-           disabled from writing to its members at all. */
         if (own.has(item)) {
             item.disabled = own.get(item) ?? false;
             own.delete(item);
         }
     }
 };
-/**
- * Forgets what a group recorded about an item.
- *
- * For an item leaving a group, which would otherwise carry the group's last
- * word into wherever it goes next.
- */
 export const forgetDisabled = (item) => {
     own.delete(item);
 };

package/dist/utils/line-path/line-path.js

@@ -1,21 +1,4 @@
-/** Two decimals, which is more than a 100 unit view box can show. */
 const round = (value) => Math.round(value * 100) / 100;
-/**
- * Tangents that cannot overshoot, by Fritsch and Carlson.
- *
- * **The reason `smooth` is monotone cubic and not a Catmull-Rom spline, which
- * is the shorter code.** A spline through the points is free to bulge past them
- * between two of them, so a series whose lowest reading is 40 draws a curve
- * that dips to 32 on the way there. Every value on that curve is a claim about
- * a measurement, and the ones between the readings are the chart's own
- * invention either way; a curve that stays inside the data at least invents
- * nothing the data contradicts.
- *
- * Two rules do it. A tangent at a turning point is flat, so the curve arrives
- * and leaves level rather than carrying on past the peak; and where a tangent
- * is steep enough relative to its neighbors to bulge anyway, the pair is
- * scaled back until it cannot.
- */
 const tangents = (xs, ys) => {
     const count = xs.length;
     const secant = [];
@@ -29,7 +12,6 @@ const tangents = (xs, ys) => {
     for (let index = 1; index < count - 1; index += 1) {
         const before = secant[index - 1];
         const after = secant[index];
-        // Flat at a turning point, which is what keeps the curve off the outside.
         slope[index] = before * after <= 0 ? 0 : (before + after) / 2;
     }
     for (let index = 0; index < count - 1; index += 1) {
@@ -50,24 +32,6 @@ const tangents = (xs, ys) => {
     }
     return slope;
 };
-/**
- * Builds an SVG path through a set of points.
- *
- * Shared by every chart that draws a line, so the choice of curve is one
- * implementation rather than one per chart. Pure: it takes points and returns a
- * string, and knows nothing about elements or lifecycles.
- *
- * `straight` joins the readings and claims nothing between them, which is why
- * it is the default. `smooth` is easier to follow across a long series and
- * invents the values in between, so it is a reading aid rather than a neutral
- * one. `step` claims the opposite, that a reading holds until the next one, and
- * changes at the midpoint rather than at either end, since a chart's x axis is
- * an order and neither neighbor has a better claim on the moment it moved.
- *
- * Fewer than two points is an empty string rather than a partial path: one
- * reading is not a line, and `M0,0` alone draws nothing while still being a
- * path element that looks like it should.
- */
 export const linePath = (points, curve = 'straight') => {
     if (points.length < 2) {
         return '';

package/dist/utils/on-unless-false/on-unless-false.js

@@ -1,27 +1,4 @@
-/**
- * For a boolean property that is on unless a consumer says otherwise.
- *
- * **Lit's boolean converter cannot express false, and that is the whole
- * problem.** It answers `value !== null`, so an attribute is true by being
- * there: `modal` is true, `modal=""` is true, and `modal="false"` is true as
- * well, because it is present. A property defaulting to `true` therefore has no
- * attribute that turns it off at all, and a consumer who writes the obvious
- * thing gets the opposite of what they asked for, silently.
- *
- * So: absent is the default, present is on, and the one string that means off
- * is the one a consumer would write. `"false"` only, and not `"0"` or `"no"`,
- * because a converter that accepts a vocabulary invites a consumer to guess at
- * it, and the one they guess wrong is the one that silently means on.
- *
- * **The other answer is to invert the property, and it is worse.** `Drawer`
- * would take `modeless`, absent meaning modal, which satisfies the rule that a
- * reflected property takes no default. It also renames the thing every consumer
- * already writes, to a word nobody reaches for, so that markup can express a
- * state that is rare. The name stays and the attribute learns to say no.
- */
 export const onUnlessFalse = {
     fromAttribute: (value) => value !== null && value !== 'false',
-    /* Written out so it survives being reflected later. `''` rather than
-       `'true'`, which is what a boolean attribute looks like everywhere else. */
     toAttribute: (value) => (value ? '' : 'false'),
 };

package/dist/utils/read-series/read-series.js

@@ -1,32 +1,9 @@
-/* A grid's own rows and cells, by role and by tag.
- *
- * **Both, because `helix-table` sets its roles through `ElementInternals`.**
- * That writes no attribute at all, which is the whole point of it: the
- * semantics reach the accessibility tree and never the DOM. So a selector of
- * `[role="row"]` matches a hand-rolled grid and matches nothing at all in this
- * library's own table, and a selector of the tag matches ours and nothing
- * anybody else builds. Neither alone is the answer. */
 const ROWS = 'helix-table-row, helix-headless-table-row, [role="row"]';
 const CELLS = 'helix-table-cell, helix-headless-table-cell, [role="cell"], [role="gridcell"], [role="rowheader"]';
 const COLUMNS = 'helix-table-column, helix-headless-table-column, [role="columnheader"]';
-/** Whether an element is a grid rather than a document table. */
 const isGrid = (element) => element.getAttribute('role') === 'table' ||
     element.getAttribute('role') === 'grid' ||
     /^helix-(headless-)?table$/i.test(element.tagName);
-/**
- * Reads a grid built from roles rather than from table markup.
- *
- * The shape is the same question asked of different elements: a first row of
- * column headers naming the series, a first cell per row labeling it, and
- * numbers in the rest. `helix-table` puts its columns beside its rows rather
- * than inside a header row, so the columns are looked for in the whole grid and
- * the rows are read separately.
- *
- * **A paginated grid reads as the page it is showing.** That is worth knowing
- * before pointing a chart at one: a table element holds every row it has, and a
- * grid may be holding twenty of two thousand. The chart is not wrong, the
- * question was.
- */
 const readGrid = (grid) => {
     const columns = [...grid.querySelectorAll(COLUMNS)];
     const rows = [...grid.querySelectorAll(ROWS)];
@@ -59,36 +36,7 @@ const readGrid = (grid) => {
         }),
     }));
 };
-/* A column with no numbers in it is not a series.
- *
- * Both readers build one entry per data column and then drop the rows whose
- * cells will not parse, so a column of notes arrives here as a series with a
- * name and no points. Nothing draws it, so it is invisible until `Legend` names
- * it anyway: a swatch in the palette against a column no chart plotted, and
- * every series after it shifted a color. */
 const plotted = (series) => series.filter((one) => one.points.length > 0);
-/**
- * Reads a table as series, one per data column.
- *
- * **The table is the chart's accessible representation, not a fallback for
- * one.** Every chart here takes its numbers from real markup rather than from a
- * property, so the page is readable with no script at all, sortable by anything
- * that sorts tables, and correct in a screen reader without a parallel
- * description that has to be kept in step by hand. A `values` array would be
- * easier to pass and would make the accessible version the thing nobody
- * maintains.
- *
- * The shape is the ordinary one: a header row naming the series, a first column
- * of row headers, and numbers in the rest. A single-column table has one series
- * and takes its name from the caption, since a header row of one is usually
- * absent.
- *
- * `data-value` wins over the cell's text, because `$1.2k` is what a reader
- * should see and is not a number. `Number()` rather than `parseFloat`, because
- * the second reads `12abc` as 12: a value that is nearly a number is a mistake
- * worth dropping rather than rounding off, and a dropped point is visible where
- * a silently truncated one is not.
- */
 export const readSeries = (table) => {
     if (isGrid(table)) {
         return plotted(readGrid(table));
@@ -124,25 +72,6 @@ export const readSeries = (table) => {
         }),
     })));
 };
-/**
- * Reads a table as rows rather than as columns.
- *
- * **Everything `readSeries` throws away on purpose, a tooltip needs.** That
- * function answers "what should I draw", so it keeps the parsed number and
- * discards the cell's text, and it drops a column whose cells are not numbers
- * at all. A chart drawing `128000` and a tooltip saying `128000` would be the
- * chart overruling the table, which already decided that number reads `$128k`;
- * and a column of notes beside the figures is exactly the extra a reader wants
- * when their pointer is resting on a reading.
- *
- * So this keeps both, and keeps the columns nothing plotted. A chart of two
- * series over a table of four columns still has four columns to show.
- *
- * The traversal is the same shape as `readSeries` and deliberately separate.
- * Folding them into one pass returning both would make every caller who wants
- * one build the other, and the two are asked for at different moments: series
- * on render, rows only where a pointer has stopped.
- */
 export const readRows = (table) => {
     const cell = (name, element) => {
         if (!element) {

package/dist/utils/relative-time/relative-time.js

@@ -1,21 +1,4 @@
-/**
- * A timestamp read the way a person reads one, and the moment it stops being true.
- *
- * **The second half is the point.** "2 minutes ago" is correct for sixty seconds
- * and wrong for the rest of the session, and a feed a user leaves open is
- * exactly where that shows: every item drifts, quietly, and the panel ends up
- * describing when the page loaded rather than when anything happened. So this
- * returns the text and the milliseconds until that text changes, which is what
- * lets a caller schedule one update instead of polling and lets a page hold one
- * timer instead of one per item.
- *
- * `Intl.RelativeTimeFormat` with `numeric: 'auto'` is what produces "yesterday"
- * rather than "1 day ago", which is what a reader would say. Cached per locale
- * for the reason `formatNumbers` is: the constructor is expensive, the call is
- * cheap, and a feed of fifty items formats fifty times per update.
- */
 const held = new Map();
-/** How long each unit lasts, in milliseconds, largest last. */
 const UNITS = [
     { ms: 1000, unit: 'second' },
     { ms: 60_000, unit: 'minute' },
@@ -25,14 +8,6 @@ const UNITS = [
     { ms: 2_629_800_000, unit: 'month' },
     { ms: 31_557_600_000, unit: 'year' },
 ];
-/**
- * A formatter for one locale, kept.
- *
- * `now` is a parameter rather than read from the clock, which is what makes this
- * testable at all: a function that reads `Date.now()` internally can only be
- * tested by waiting or by replacing a global, and both produce specs that fail
- * on a slow machine.
- */
 export const relativeTime = (locale) => {
     let format = held.get(locale);
     if (!format) {
@@ -41,27 +16,12 @@ export const relativeTime = (locale) => {
     }
     const found = format;
     return (from, now) => {
-        /* Signed from the timestamp's point of view, not the reader's:
-           `Intl.RelativeTimeFormat` takes a negative count for the past, so
-           `format(-2, 'minute')` is "2 minutes ago" and `format(2, 'minute')` is "in
-           2 minutes". Computed as `now - from` the sign is backwards and every past
-           item reads as the future, which is the shape of it that looks like a
-           working feed until you read one. */
         const elapsed = from.getTime() - now.getTime();
         if (!Number.isFinite(elapsed)) {
             return { next: Number.POSITIVE_INFINITY, text: '' };
         }
-        /* Under a minute is "now" rather than a count of seconds. A feed that
-           reports 3, then 4, then 5 seconds ago is a feed that moves under the
-           reader while they are trying to read it, and the precision is worth
-           nothing: nobody acts differently at seven seconds than at four. */
         const size = Math.abs(elapsed);
         if (size < 60_000) {
-            /* Floored, as `Relative.next` says every branch is: at 59,999
-               milliseconds the remainder is one, so a caller scheduling for itself is
-               re-armed inside the callback that fired it. The shared ticker's own
-               `Math.max(1000, ...)` hides this from the two readers that go through
-               it. */
             return { next: Math.max(1000, 60_000 - size), text: found.format(0, 'second') };
         }
         let chosen = UNITS[1];
@@ -71,9 +31,6 @@ export const relativeTime = (locale) => {
             }
         }
         const count = Math.trunc(elapsed / chosen.ms);
-        /* Time until the count ticks over, which is the remainder of the current
-           unit rather than the whole of one: an item read at 90 seconds is "1 minute
-           ago" for another 30 seconds, not another 60. */
         const remaining = chosen.ms - (size % chosen.ms);
         return {
             next: Math.max(1000, Math.min(remaining, 3_600_000)),

package/dist/utils/resolve-active-item/resolve-active-item.js

@@ -1,21 +1 @@
-/**
- * Which item a value names, or the first that could stand in for it.
- *
- * `items.find(match) ?? items[0]` was written by hand in four components and it
- * is not the obvious line it looks like. It is what makes a set whose `value`
- * names nothing still show something, which is every set before its consumer
- * has chosen and every set whose current item has just been removed.
- *
- * The fallback skips disabled items and the match does not. A consumer who
- * names a disabled item meant it, and quietly moving to another would be the
- * component overruling them; but falling back *onto* a disabled item is the
- * component choosing, and it should not choose something out of play. Taking
- * `items[0]` either way opens a set on a disabled first item and shows it as
- * current.
- *
- * A plain function rather than only a method on `MixinControllerActive`,
- * because the components that need it are split across two mixins: a set whose
- * value is submitted takes `MixinControllerValue` and cannot also take the
- * active one without two properties called `value`.
- */
 export const resolveActiveItem = (value, items) => items.find((item) => item.value === value) ?? items.find((item) => !item.disabled);