@fusion.dev/helix-headless 0.2.0 → 0.4.0

package/dist/meter/root/meter-root.js

@@ -7,145 +7,39 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement, hostAria } from '@fusion.dev/helix-core';
 import { html, nothing, svg } from 'lit';
 import { property } from 'lit/decorators.js';
-/**
- * @summary A measurement in a known range, and whether it is where you want it.
- *
- * @description
- * **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.
- *
- * **`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.
- *
- * @since 0.1.0
- * @status stable
- * @category feedback
- * @aliases Gauge, Level, Capacity
- * @documentation https://helix.fusion.dev/components/meter
- *
- * @csspart groove - The unfilled circle, in `ring` and `arc`.
- * @csspart indicator - The part of it the value fills.
- * @csspart tick - A mark at `low` or at `high`.
- * @csspart track - The whole range, or the drawing in `ring` and `arc`.
- * @csspart value - The reading, under `show-value`.
- *
- * @cssproperty --meter-along - Where a bound sits on the arc, as a length along it.
- * @cssproperty --meter-at - Where a bound sits on a linear track, as a percentage.
- * @cssproperty --meter-fraction - The value as a fraction of the range, 0 to 1.
- * @cssproperty --meter-sweep - How much of the circle the arc covers, as a path length.
- */
 let HelixHeadlessMeter = class HelixHeadlessMeter extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * Accessible name for the reading.
-         */
         this.label = 'Meter';
-        /**
-         * Top of the range.
-         *
-         * A hundred rather than the platform's one, which is what `Progress` already
-         * takes and what a consumer writing `value="72"` means. A range of zero to one
-         * is a fraction, and a component that reads `value="72"` as seventy-two times
-         * over its maximum is a trap that costs nothing to avoid.
-         */
         this.max = 100;
-        /**
-         * Bottom of the range.
-         */
         this.min = 0;
-        /**
-         * Whether the reading is shown beside the bar.
-         */
         this.showValue = false;
-        /**
-         * Where the reading sits between `min` and `max`.
-         *
-         * Outside them, it clamps.
-         */
         this.value = 0;
-        /**
-         * What the reading says, where a number is not the whole story.
-         *
-         * `value-text="18 GB of 32 GB"` is announced and shown instead of `56%`. The
-         * same property `Progress` carries, for the same reason: a percentage is a
-         * fair summary of a task and a poor one of a quantity.
-         */
         this.valueText = '';
     }
-    /** The range, clamped so `max` is never at or below `min`. */
     get span() {
         const min = Number.isFinite(this.min) ? this.min : 0;
         const max = Number.isFinite(this.max) && this.max > min ? this.max : min + 1;
         return { max, min };
     }
-    /** The reading, pulled into the range. */
     get reading() {
         const { max, min } = this.span;
         return Math.min(max, Math.max(min, Number.isFinite(this.value) ? this.value : min));
     }
-    /**
-     * How much of the track is filled, from zero to one.
-     *
-     * Clamped, because a bar cannot draw past its own end. What the reading *says*
-     * is not clamped: see `ratio`.
-     */
     get fraction() {
         const { max, min } = this.span;
         return (this.reading - min) / (max - min);
     }
-    /**
-     * Where the value really sits, which is what the words report.
-     *
-     * **Unclamped, so a value past the end is not swallowed.** Clamped as well as
-     * the bar is, 110 and 250 read as exactly full, and a meter that cannot say
-     * "you are over" is worse than no meter for the one case anybody checks it in.
-     *
-     * The bar still stops at its end, because that is what an end is. The words
-     * and the accessible reading carry the truth, and `data-beyond` is on the fill
-     * so a consumer can say more about it.
-     */
     get ratio() {
         const { max, min } = this.span;
         const raw = Number.isFinite(this.value) ? this.value : min;
         return (raw - min) / (max - min);
     }
-    /** Whether the value is past an end, which the bar itself cannot show. */
     get beyond() {
         const { max, min } = this.span;
         const raw = Number.isFinite(this.value) ? this.value : min;
         return raw > max ? 'over' : raw < min ? 'under' : undefined;
     }
-    /**
-     * The thresholds, in order, or nothing where the consumer declared none.
-     *
-     * Both are clamped into the range and to each other, because a `low` above a
-     * `high` describes no bands at all and the spec's own answer is to raise the
-     * one that is out of order rather than to give up.
-     */
     get thresholds() {
         const { max, min } = this.span;
         if (this.low === undefined && this.high === undefined) {
@@ -155,14 +49,6 @@ let HelixHeadlessMeter = class HelixHeadlessMeter extends HelixElement {
         const high = Math.min(max, Math.max(low, this.high ?? max));
         return { high, low };
     }
-    /**
-     * Which band the reading is in, by the specification's rule.
-     *
-     * `optimum` names a point, and the band containing it is the good one. A
-     * reading in that band is good, one in a band beside it is fair, and one two
-     * bands away is poor. Undefined where nothing was declared, which is what
-     * keeps an unbanded meter from being painted as good news.
-     */
     get computedBand() {
         if (this.band) {
             return this.band;
@@ -177,47 +63,19 @@ let HelixHeadlessMeter = class HelixHeadlessMeter extends HelixElement {
         const distance = Math.abs(which(this.reading) - which(optimum));
         return distance === 0 ? 'good' : distance === 1 ? 'fair' : 'poor';
     }
-    /** What the reading says, which is the consumer's words or a percentage. */
     get text() {
         return this.valueText || `${Math.round(this.ratio * 100)}%`;
     }
     willUpdate(changed) {
         super.willUpdate(changed);
         const { max, min } = this.span;
-        /* On the host through internals, so the reading is the element itself and
-           an author's own `aria-label` beats it without anything being written onto
-           markup their server never had. `meter` is the ARIA role for exactly this
-           and is not `progressbar`: a progress bar promises it is going somewhere. */
         hostAria(this.internals, { label: this.label, role: 'meter' });
         this.internals.ariaValueMin = String(min);
         this.internals.ariaValueMax = String(max);
         this.internals.ariaValueNow = String(this.reading);
-        /* The consumer's words where they gave any, and otherwise nothing at all
-           *unless* the value is past an end. `ariaValueNow` has to sit inside the
-           range, so it is the only place a reader can be told that 250 is not 100. */
         this.internals.ariaValueText =
             this.valueText || (this.beyond ? `${Math.round(this.ratio * 100)}%` : null);
     }
-    /**
-     * The same reading, drawn round.
-     *
-     * `pathLength="100"` is what makes every number here a percentage: the path is
-     * declared a hundred units long, so nothing computes a circumference, a radius
-     * or pi, and a consumer changing the thickness moves the circle that carries
-     * it without this element recalculating anything. Progress does the same and
-     * for the same reason.
-     *
-     * The sweep is what separates the two shapes. A ring is the whole circle and
-     * an arc is three quarters of it, open at the bottom, which is where a gauge
-     * has always had its gap: the two ends need somewhere to be that is not each
-     * other, and the opening is where a reading of the value goes.
-     *
-     * Ticks are segments of the same circle rather than marks placed on it. One
-     * unit of a hundred, offset to where the threshold falls, which needs no
-     * trigonometry and stays correct at any radius or thickness. Placing them by
-     * hand would mean sine and cosine in a template and a second definition of
-     * where the arc starts.
-     */
     renderRound() {
         const bounds = this.thresholds;
         const { max, min } = this.span;
@@ -225,16 +83,7 @@ let HelixHeadlessMeter = class HelixHeadlessMeter extends HelixElement {
         const along = (value) => ((value - min) / (max - min)) * sweep;
         return html `<svg part="track" viewBox="0 0 100 100" aria-hidden="true">
       <circle part="groove" pathLength="100" style="--meter-sweep: ${sweep}" />
-      ${
-        /* `svg` and not `html`, which is the bug the sparkline records one
-           file over. A nested Lit template is parsed on its own, so a
-           `<circle>` written in one has no `<svg>` around it and lands in the
-           XHTML namespace: it takes the part, takes the style, inherits every
-           rule in the stylesheet, and draws nothing, because geometry belongs
-           to the namespace and not to the tag name. Both threshold ticks were
-           invisible in `shape="ring"` and `shape="arc"`, which is the whole of
-           what the round example shows. */
-        bounds
+      ${bounds
             ? svg `<circle
                 part="tick"
                 pathLength="100"

package/dist/navigation/root/navigation-root.js

@@ -7,90 +7,34 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, HelixElement, IndicatorController } from '@fusion.dev/helix-core';
 import { html } from 'lit';
 import { property } from 'lit/decorators.js';
-/**
- * @summary A set of destinations, with a marker on the current one.
- *
- * @description
- * Renders a real `<nav>`, which is the landmark a screen-reader user jumps to.
- * It exists as its own component rather than as a region of `AppHeader` because
- * a header is not inherently navigation, and navigation is not only ever in a
- * header: a footer and a sidebar hold the same thing.
- *
- * **It renders no links.** The consumer brings them, marked with
- * `aria-current="page"` and styled by the `data-navigation-item` recipe, for the same
- * reason nothing else here renders an anchor: a router renders its own, and
- * cannot render it inside this shadow root.
- *
- * What this owns is the marker that travels between them, and that is the whole
- * reason it is a component. A marker that moves needs something that knows
- * where every item is, and reading `aria-current` is how it knows which: the
- * thing that makes the page announce correctly is the same thing that puts the
- * marker in the right place.
- *
- * @since 0.1.0
- * @status experimental
- * @category navigation
- * @aliases Nav, NavList, Tabs
- * @documentation https://helix.fusion.dev/components/navigation
- *
- * @slot - The destinations, as the consumer's own links.
- *
- * @csspart indicator - The marker that travels to the current destination.
- * @csspart nav - The navigation landmark.
- */
 let HelixHeadlessNavigation = class HelixHeadlessNavigation extends HelixElement {
     constructor() {
         super(...arguments);
-        /* The controller carries the RTL sign and border correction: a distance
-           measured from the physical left and applied from the inline-start edge
-           travels the wrong way in a right-to-left document. */
         this.indicator = new IndicatorController(this, {
             active: () => this.items.find((item) => item.getAttribute('aria-current') === 'page'),
             indicator: () => this.renderRoot?.querySelector('[part="indicator"]'),
             surface: () => this.renderRoot?.querySelector('[part="nav"]'),
         });
-        /**
-         * Accessible name for the landmark.
-         */
         this.label = 'Main';
     }
-    /** The destinations the consumer slotted. */
     get items() {
         const slot = this.renderRoot.querySelector('slot');
         return (slot?.assignedElements() ?? []);
     }
-    /** Re-measures when the links change, move, or hand over the current page. */
     watch() {
         this.observer?.disconnect();
         this.current?.disconnect();
-        /* Nothing is written onto the items, and `data-navigation-item` must not be
-         * written here: it would land after upgrade, so a server-rendered nav would
-         * arrive unstyled and restyle itself a frame later, and a React consumer
-         * who wrote the attribute themselves gets `data-navigation-item="true"`
-         * from JSX, which overwriting reports as a hydration mismatch. The base
-         * layer selects `helix-navigation a`, so the styling is true the moment the
-         * markup is parsed, on the server and on the client. */
         this.indicator.place();
         this.observer = new ResizeObserver(() => this.indicator.place());
         this.observer.observe(this);
         for (const item of this.items) {
             this.observer.observe(item);
         }
-        // Client-side routing changes `aria-current` in place rather than
-        // reloading, so nothing else would tell the marker to move.
         this.current = new MutationObserver(() => this.indicator.place());
         for (const item of this.items) {
             this.current.observe(item, { attributeFilter: ['aria-current'] });
         }
     }
-    /* Rebuilt on reconnection, because nothing else does it.
-     *
-     * `firstUpdated` runs once for the life of the element and
-     * `disconnectedCallback` runs every time it moves, so a framework reordering
-     * a list left this permanently dead: the observer gone, nothing to rebuild
-     * it, and the component still rendering as though it were watching. Guarded
-     * on `hasUpdated`, because the first connection happens before the first
-     * render and there is nothing to watch yet. */
     connectedCallback() {
         super.connectedCallback();
         if (this.hasUpdated) {

package/dist/notifications/notification/notification.js

@@ -9,110 +9,18 @@ import { x } from '@fusion.dev/helix-icons';
 import { nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
-/* `lit/static-html.js`, because this template interpolates a tag name and the
-   plain `html` cannot: it renders the placeholder as the element instead, which
-   shifts every attribute after it by one. See `renderTime`. */
 import { html } from 'lit/static-html.js';
-/* Side-effect import, because this template interpolates the family's tag and a
-   custom element registers on import. Both tiers import it, the relative path
-   resolving to each tier's own element. */
 import '../../format-date/index.js';
-/**
- * @summary One thing that happened, which a reader may not have seen yet.
- *
- * @description
- * A notification is a toast that did not go away. `helix-toast` is deliberately
- * the opposite of this: a live region whose items carry a `duration` and whose
- * root never creates or destroys anything. What makes this its own family is the
- * state each item carries rather than the arrangement it sits in: read and
- * unread, a timestamp that has to stay correct, and an action a reader can take
- * later.
- *
- * **The row is a label, a caption under it, and one trailing column that holds
- * either the time or the controls.** A feed is scanned rather than read, so the
- * thing that happened gets the first line on its own and everything qualifying
- * it goes under. The time and the controls occupy the same place because a
- * reader wants exactly one of them at a time: the time while they are scanning,
- * and what they can do about it once they have stopped on a row.
- *
- * **The timestamp is `helix-format-date`**, which is where the reading, the
- * `<time datetime>` and the shared timer now live. It was implemented here, and
- * a component that formats a date is not a fact about notifications: Chat wanted
- * the same thing and had its own copy of half of it.
- *
- * **Read state is reported, not invented.** Marking something read is usually a
- * round trip, and a component that flips its own state and then hears the
- * request failed has told the reader something untrue. `helix-read` is
- * cancelable, and a `read` set by the consumer makes this element defer entirely.
- *
- * @since 0.1.0
- * @status experimental
- * @category feedback
- * @aliases Notification item, Inbox item
- * @documentation https://helix.fusion.dev/components/notifications
- *
- * @slot - What happened, in the consumer's own markup.
- * @slot actions - What a reader can do about it.
- * @slot caption - A second line qualifying it, quieter than the first. A bare
- * slot rather than a box, so an item without one pays nothing for it; style it
- * through `::slotted()`.
- * @slot media - An avatar or icon identifying who or what it came from.
- *
- * @event {HelixDismissEvent} helix-dismiss - Fired when a reader asks to remove it, and cancelable.
- * @event {HelixReadEvent} helix-read - Fired when the item is marked read or unread, and cancelable.
- *
- * @csspart actions - The trailing slot's box.
- * @csspart body - The label and the caption together.
- * @csspart controls - The actions and the dismiss, which replace the time.
- * @csspart dismiss - The control that removes it.
- * @csspart dismiss-mark - The glyph on that control, where none is slotted.
- * @csspart item - The whole notification.
- * @csspart label - What happened, on the first line.
- * @csspart media - The leading slot's box.
- * @csspart time - When it happened, read the way a person reads one.
- * @csspart trailing - The column holding the time and the controls.
- */
 let HelixHeadlessNotification = class HelixHeadlessNotification extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * When it happened, as anything `Date` parses.
-         *
-         * An ISO string is what an API sends and what `<time datetime>` takes, so it
-         * is the shape that needs no translation at either end. Left unset the item
-         * shows no timestamp rather than showing the epoch, which is what parsing an
-         * empty string would give.
-         */
         this.at = '';
-        /**
-         * State to open with, where nothing declared one.
-         */
         this.defaultRead = false;
-        /**
-         * Whether a reader may remove it.
-         */
         this.dismissible = false;
-        /**
-         * Accessible name for the dismiss control.
-         */
         this.dismissLabel = 'Dismiss';
-        /**
-         * Locale for the timestamp.
-         *
-         * Empty is the runtime's own.
-         */
         this.locale = '';
-        /**
-         * @internal Read by the list to identify its children across the light DOM,
-         * which is cheaper than `instanceof` and is why this is public rather than
-         * protected. Not a consumer's to read or set.
-         */
         this.isNotification = true;
         this.readState = undefined;
-        /* Content arriving from the light DOM changes no property here, so nothing
-           would schedule the re-read. Bound to the slot rather than to the host,
-           because `slotchange` bubbles and is not composed: it reaches the shadow root
-           that owns the slot and stops there. */
         this.handleActions = () => {
             this.markControls();
         };
@@ -123,21 +31,6 @@ let HelixHeadlessNotification = class HelixHeadlessNotification extends HelixEle
             }
         };
     }
-    /**
-     * Whether the reader has seen it.
-     *
-     * Set it and this element defers: a reader's click fires `helix-read` and
-     * changes nothing until a new value arrives. `default-read` seeds a state
-     * this element then owns.
-     *
-     * **Not reflected.** Unread is a visual state, which is why the four mixins
-     * mirror theirs, but the mirror may not be the property's own attribute:
-     * `<helix-notification default-read>` comes back from a server without `read`
-     * and would gain it on the first update, which React reports as a hydration
-     * mismatch, and which a copy of the serialized element re-parses as a
-     * declaration. `:state(read)` is what the stylesheet reads.
-     * `hydration.dom.spec.ts` holds it.
-     */
     get read() {
         return this.readState ?? this.defaultRead;
     }
@@ -146,13 +39,6 @@ let HelixHeadlessNotification = class HelixHeadlessNotification extends HelixEle
         this.readState = next;
         this.requestUpdate('read', previous);
     }
-    /**
-     * Asks to be marked read, and reports whether the request stood.
-     *
-     * Public because a consumer's own control is as likely to ask as this
-     * element's own markup is, and because a list marking everything read has to
-     * go through the same request rather than writing the property behind it.
-     */
     markRead(next = true) {
         if (next === this.read) {
             return false;
@@ -171,48 +57,16 @@ let HelixHeadlessNotification = class HelixHeadlessNotification extends HelixEle
     willUpdate(changed) {
         super.willUpdate(changed);
         hostAria(this.internals, { role: 'listitem' });
-        /* The mirror the stylesheet selects on, kept off the host's attributes for
-           the reason on `read` itself. */
         this.toggleState('read', this.read);
     }
     updated(changed) {
         super.updated(changed);
         this.markControls();
     }
-    /**
-     * Says whether there is anything for the time to make way for.
-     *
-     * The trailing column holds the time and the controls in one place and shows
-     * one of them, so a row with nothing to do about it would hide its timestamp
-     * on hover and put nothing there. `dismissible` this element knows on the
-     * server; whether a consumer filled the actions slot it can only find out from
-     * a DOM, so this runs after the render and the resting answer, no controls, is
-     * the one the server writes.
-     */
     markControls() {
         const slot = this.renderRoot?.querySelector('slot[name="actions"]');
         this.toggleState('controls', this.dismissible || slotFilled(slot));
     }
-    /**
-     * The control that removes the item, with the mark a consumer can replace.
-     *
-     * **A method rather than markup inside `render`, and the slot moves with
-     * it.** A fallback answers a consumer and a seam answers the tier above, which
-     * are different people: the styled tier wants an icon here, and with the slot
-     * written inline the only way to change it is to reimplement the whole
-     * template. Moving only the fallback out is not enough: the slot is the thing
-     * a tier redraws.
-     *
-     * **The mark is drawn rather than typed, which is what lets it align.** A
-     * character such as `&times;` is placed by its font rather than by its box:
-     * measured against the ghost button beside it at 8x, the cross carried 6
-     * pixels of ink to the label's 9.5 and sat 1.5 pixels below its center, in two
-     * boxes whose own centers agreed to a tenth of a pixel. No stylesheet can
-     * correct that, because the offset is inside the glyph. An `<svg>` is centered
-     * on its own viewBox, so it lands where the box says and takes the icon step
-     * the row is already set in. It is the `x` the Tag's dismiss draws, so two
-     * controls that mean "take this away" are one mark.
-     */
     renderDismiss() {
         if (!this.dismissible) {
             return nothing;
@@ -236,19 +90,6 @@ let HelixHeadlessNotification = class HelixHeadlessNotification extends HelixEle
       </slot>
     </button>`;
     }
-    /**
-     * When it happened, delegated whole.
-     *
-     * The tag is interpolated rather than written, so each tier renders its own:
-     * the base tier may not name a styled element, and a styled item inherits this
-     * template without having a tag of its own to remind anybody.
-     *
-     * `exportparts` and no `part` of its own, which is the rule about a part
-     * already named for its role: the child publishes `time`, the role here is
-     * `time`, and naming both would leave `::part(time)` matching two elements.
-     * What a consumer wants to reach is the `<time>`, so that is what the name
-     * reaches.
-     */
     renderTime() {
         const stamp = this.tag('format-date');
         return html `<${stamp}