@fusion.dev/helix-headless 0.2.0 → 0.3.0

package/dist/file-input/root/file-input-root.js

@@ -10,19 +10,6 @@ import { nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { html } from 'lit/static-html.js';
 import '../../tag/index.js';
-/**
- * A file's size, at the largest unit that leaves a number worth reading.
- *
- * Binary steps, because that is what a file system reports and what the number
- * beside it in a finder will say. One decimal place from kilobytes up and none
- * for bytes: `1.2 MB` is the reading, `1.23 MB` is noise, and `1.5 bytes` is not
- * a thing.
- *
- * `Intl.NumberFormat` for the number rather than `toFixed`, so a decimal comma
- * lands where a decimal comma belongs. The unit is not localized with it: `MB`
- * is written the same way in the places this ships, and `Intl`'s own byte units
- * carry no scale to pick from.
- */
 const size = (bytes, locale) => {
     const units = ['bytes', 'KB', 'MB', 'GB', 'TB'];
     let value = bytes;
@@ -34,19 +21,9 @@ const size = (bytes, locale) => {
     const written = new Intl.NumberFormat(locale || undefined, {
         maximumFractionDigits: step === 0 ? 0 : 1,
     }).format(value);
-    // One byte is a byte. The plural is only wrong at exactly one and it is the
-    // size an empty-ish file has, so it is the one a reader sees while testing.
     const unit = step === 0 && value === 1 ? 'byte' : units[step];
     return `${written} ${unit}`;
 };
-/**
- * What kind of file it is, in the shortest honest form.
- *
- * The subtype of the MIME type, so `image/png` reads `PNG`, which is the word a
- * reader already has for it. A browser leaves `type` empty for anything it does
- * not recognize, so the extension is the fallback: it is what the name already
- * shows, which makes it a poor label and a better one than nothing.
- */
 const kind = (file) => {
     const subtype = file.type.split('/')[1];
     if (subtype) {
@@ -55,131 +32,22 @@ const kind = (file) => {
     const extension = file.name.includes('.') ? file.name.split('.').pop() : '';
     return extension ? extension.toUpperCase() : 'File';
 };
-/**
- * @summary A control for choosing files, by pointer or by dropping them on it.
- *
- * @description
- * **A real `<input type="file">`, kept and made invisible rather than
- * 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.
- *
- * 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.
- *
- * @since 0.1.0
- * @status stable
- * @category forms
- * @aliases FileUpload, FilePicker, Dropzone, InputFile
- * @documentation https://helix.fusion.dev/components/file-input
- *
- * @slot feedback - What is wrong with it.
- * @slot hint - Help under the field.
- * @slot trigger - What the reader presses to open the picker.
- *
- * @event {Event} change - Announced once the value has moved.
- * @event {HelixBeforeChangeEvent} helix-before-change - Fired before the chosen files change, with their names. Cancelable: refusing it takes the decision and nothing moves.
- * @event {Event} input - Announced once the value has moved.
- *
- * @csspart control - The file input itself, which carries the label and validity.
- * @csspart detail - Its name and its reading, stacked.
- * @csspart feedback - What is wrong with it.
- * @csspart field - The box that is pressed and dropped on.
- * @csspart file - One chosen file.
- * @csspart hint - Help under the field, while nothing is wrong.
- * @csspart kind - What kind of file it is.
- * @csspart kind-dismiss - The remove button, when `dismissible`.
- * @csspart kind-dismiss-mark - The glyph on the dismiss control, where none is slotted.
- * @csspart kind-prefix - The category before the label.
- * @csspart label - The question, over the field.
- * @csspart list - The chosen files.
- * @csspart meta - The row holding its size and kind.
- * @csspart name - Its name.
- * @csspart remove - The control that takes it back out.
- * @csspart size - How big it is.
- * @csspart size-dismiss - The remove button, when `dismissible`.
- * @csspart size-dismiss-mark - The glyph on the dismiss control, where none is slotted.
- * @csspart size-prefix - The category before the label.
- * @csspart trigger - The label that opens the picker.
- */
 let HelixHeadlessFileInput = class HelixHeadlessFileInput extends MixinField(HelixFormElement) {
     constructor() {
         super(...arguments);
-        /* A consumer's `aria-describedby` names ids in their own tree and the control
-           is in this shadow root, so the reference has to be carried down as an
-           element rather than copied as an id. See `AriaForwardController`: measured
-           in Chrome's own tree, the host held the description and the control the
-           reader is actually on was exposed without it. */
         this.aria = new AriaForwardController(this, {
             target: () => this.renderRoot?.querySelector('[part="control"]') ?? null,
         });
-        /**
-         * Which files the picker offers, as a native `accept` list.
-         */
         this.accept = '';
-        /**
-         * Language tag the sizes are written in.
-         *
-         * Absent uses the runtime's own.
-         */
         this.locale = '';
-        /**
-         * Whether more than one file can be chosen.
-         */
         this.multiple = false;
-        /**
-         * What the control removing one file is called, per file.
-         */
         this.removeLabel = 'Remove';
-        /**
-         * What the trigger reads, where nothing is slotted into it.
-         */
         this.triggerLabel = 'Choose files';
-        /**
-         * Whether something is being dragged over the field.
-         *
-         * State rather than a property: it is a fact about a gesture in progress and
-         * nothing a consumer sets. It reaches the stylesheet as `data-dropping` on an
-         * element in this shadow root, never on the host, which is markup a consumer
-         * rendered.
-         */
         this.dropping = false;
         this.handleChange = (event) => {
-            // The native `change` is relayed under this element's own name, so a
-            // consumer hears one event from one element rather than two from two.
             event.stopPropagation();
             this.announce();
         };
-        /*
-         * Takes a drop, which a bare file input can only do on itself.
-         *
-         * The input is invisible here, so the field is the target and the files are
-         * put into the input afterwards: that keeps one source of truth, and it is
-         * what makes a dropped file and a picked file indistinguishable to a form.
-         *
-         * `preventDefault` on dragover as well as on drop, because without it the
-         * browser navigates to the file and the page is gone.
-         */
         this.handleDragOver = (event) => {
             if (this.isDisabled) {
                 return;
@@ -202,8 +70,6 @@ let HelixHeadlessFileInput = class HelixHeadlessFileInput extends MixinField(Hel
                 return;
             }
             const keeping = new DataTransfer();
-            // A single-file control takes the last thing dropped, the way choosing
-            // again in the picker replaces rather than adds.
             for (const file of this.multiple ? [...this.files, ...dropped] : dropped.slice(-1)) {
                 keeping.items.add(file);
             }
@@ -217,38 +83,15 @@ let HelixHeadlessFileInput = class HelixHeadlessFileInput extends MixinField(Hel
             }
         };
     }
-    /**
-     * The files chosen, which is the element's own and never assigned.
-     *
-     * Read from the input rather than mirrored into a field. The input is what
-     * the picker filled and what a form submits, so a copy here could only ever
-     * disagree with it.
-     */
     get files() {
         return [...(this.control?.files ?? [])];
     }
-    /**
-     * The input, or nothing where there is no tree to ask.
-     *
-     * The guard is for the server, whose element shim carries attributes but not
-     * traversal: `render` reads `files`, `files` reads this, and an unguarded
-     * `querySelector` threw before a single character of markup came out. Nothing
-     * is lost by answering `null` there, because a file only ever arrives through
-     * a reader and a server has never met one.
-     */
     get control() {
         if (typeof this.renderRoot?.querySelector !== 'function') {
             return null;
         }
         return this.renderRoot.querySelector('[part="control"]');
     }
-    /**
-     * Takes every file back out.
-     *
-     * The one change a consumer can ask for. Setting a `FileList` is refused by
-     * every browser for a reason worth keeping, but emptying one is not: nothing
-     * about the page learns anything it did not already have.
-     */
     clear() {
         const control = this.control;
         if (!control) {
@@ -257,17 +100,6 @@ let HelixHeadlessFileInput = class HelixHeadlessFileInput extends MixinField(Hel
         control.value = '';
         this.announce();
     }
-    /**
-     * Drops one file, by index.
-     *
-     * `removeAt` rather than `remove`, which is `Element`'s own and takes no
-     * arguments: shadowing it would break every caller who meant the node.
-     *
-     * Through `DataTransfer`, which is the only way to build a `FileList`: the
-     * type has no constructor and `input.files` takes nothing else. It is the same
-     * mechanism a drop uses, so a file put in by dragging and one put in by the
-     * picker come back out the same way.
-     */
     removeAt(at) {
         const control = this.control;
         if (!control || typeof DataTransfer === 'undefined') {
@@ -282,32 +114,15 @@ let HelixHeadlessFileInput = class HelixHeadlessFileInput extends MixinField(Hel
         control.files = keeping.files;
         this.announce();
     }
-    /** Says what is now chosen, by name, and puts it in the form. */
     announce() {
         this.sync();
         this.requestUpdate();
         this.dispatchEvent(new HelixBeforeChangeEvent({
             value: this.files.map((file) => file.name).join(', '),
         }));
-        /* And under the platform's own names, which is what `onChange` and `onInput`
-           bind and what a native file input sends when the chosen files move: both,
-           in that order, the way every other control here does.
-    
-           Without the explicit `input`, the only one a consumer receives is the
-           inner `<input type="file">`'s own, composed out of this shadow root, so
-           the documented event does not exist and an undocumented one arrives in
-           its place. */
         this.dispatchEvent(new Event('input', { bubbles: true, composed: true }));
         this.dispatchEvent(new Event('change', { bubbles: true, composed: false }));
     }
-    /**
-     * Reports the files and the validity the host stands behind.
-     *
-     * `FormData` rather than a string, because a file input submits the file
-     * itself and several of them under one name. The anchor on `setValidity` is
-     * the input, so the browser's own bubble points at something a reader can see
-     * rather than at a host with no text in it.
-     */
     sync() {
         const data = new FormData();
         if (this.name) {
@@ -315,18 +130,6 @@ let HelixHeadlessFileInput = class HelixHeadlessFileInput extends MixinField(Hel
                 data.append(this.name, file);
             }
         }
-        /* **An empty one contributes no entry, and the native control contributes an
-           empty file.** Measured, one form holding both: `<input type="file"
-           name="nf">` with nothing chosen submits `nf=` carrying a `File` of zero
-           bytes and no name, and this submits nothing at all.
-    
-           Kept, as a decision rather than an omission. A phantom entry naming a file
-           that does not exist is a thing every server reading this form has to know
-           to discard, and the reason the platform sends one is compatibility with
-           form encodings that predate `FormData`. `value` is excused on this family
-           already, for the neighboring reason that the native one is
-           `C:\fakepath\name`; this is the same component declining to reproduce a
-           lie, one level down. */
         this.internals.setFormValue(data);
         const control = this.control;
         if (!control) {
@@ -337,52 +140,17 @@ let HelixHeadlessFileInput = class HelixHeadlessFileInput extends MixinField(Hel
     }
     firstUpdated(changed) {
         super.firstUpdated(changed);
-        // Whatever the markup arrived with, so a form knows before anything is
-        // touched. `willUpdate` is too early: there is no control to read yet.
         this.sync();
     }
-    /** Puts focus on the input, the way a label pointing at one would. */
     focus(options) {
         this.control?.focus(options);
     }
-    /** Empties it, which is what a form reset means for a file input. */
     formResetCallback() {
         if (this.control) {
             restoreValue(this.control, '');
         }
         this.announce();
     }
-    /*
-     * The hint goes under the field, and the list after both.
-     *
-     * A hint is instruction for the next action rather than a note about the
-     * result: "up to 10MB each" is a rule for what may be added, and a rule read
-     * after the outcome is a rule read too late. Its position also has to be
-     * stable, and under the list it travels down the page as files are added, a
-     * card's height at a time. Every other field here puts it immediately under
-     * the control.
-     *
-     * Feedback stands in place of the hint rather than beside it, so wherever the
-     * hint is, an error is. An error about a file that was refused belongs
-     * against the control that refused it, not below a list of the ones that were
-     * not.
-     */
-    /**
-     * What is known about a chosen file, as tags, behind a seam the styled tier
-     * can move.
-     *
-     * One method for both the size and the kind, because they are the same
-     * element saying two things and two methods would be two places to keep in
-     * step. Both parts are written out rather than passed in, and that is not
-     * style: a part name behind an interpolation is a part the manifest cannot
-     * see, so a stylesheet targeting it matches nothing.
-     *
-     * A method rather than a fragment inline, so a tier above can render its own,
-     * wrap this one, or leave it out without reimplementing the whole template.
-     * The tag is interpolated rather than written, so `tier` resolves it: this
-     * renders the headless element, and a styled subclass that sets `tier`
-     * renders the styled one from the same template.
-     */
     renderMeta(file) {
         return html `<${this.tag('tag')} part="size"
     exportparts="dismiss: size-dismiss, dismiss-mark: size-dismiss-mark, prefix: size-prefix">${size(file.size, this.locale)}</${this.tag('tag')}>

package/dist/format-date/root/format-date-root.js

@@ -7,93 +7,17 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
 import { customElement, elapsedTime, HelixElement, subscribe } from '@fusion.dev/helix-core';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
-/**
- * @summary A timestamp, written the way the reader's locale writes one.
- *
- * @description
- * A date in a page is almost never wanted as an ISO string, and formatting one
- * in the consumer's own code means every consumer ships a copy of the same
- * `Intl` call and a different set of options. This is that call, as an element,
- * so a date is written where it is shown.
- *
- * **`elapsed` is the mode a feed wants, and it stops being relative on
- * purpose.** "42m", "3h", "1d" is what a row of activity reads as, and past a
- * week the compact form is a lie: `Intl.NumberFormat` narrow renders both
- * `minute` and `month` as `m` in en-US, so "3m" is three minutes at the top of a
- * feed and three months further down it. Past six days this shows a date, which
- * is shorter to read and impossible to misread. `elapsedTime` in `helix/core`
- * carries the measurement.
- *
- * **The reading refreshes itself, from one timer the page shares.** A relative
- * timestamp is correct for as long as its unit lasts and wrong afterwards, and a
- * page left open is exactly where that shows. Each element asks to be woken when
- * its own reading expires rather than polling, and an element showing a date
- * asks for nothing at all: fifty rows and fifty intervals is fifty wakeups a
- * second where one will do, and a feed of last month's notifications should cost
- * nothing to leave open.
- *
- * **`<time datetime>` whatever the text says**, so a screen reader, a copy and
- * paste, and anything parsing the page all get the real instant rather than
- * "yesterday".
- *
- * @since 0.1.0
- * @status experimental
- * @category typography
- * @aliases RelativeTime, Timestamp, TimeAgo
- * @documentation https://helix.fusion.dev/components/format-date
- *
- * @csspart time - The `<time>` element carrying the reading.
- */
 let HelixHeadlessFormatDate = class HelixHeadlessFormatDate extends HelixElement {
     constructor() {
         super(...arguments);
-        /**
-         * The timestamp, 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 this
-         * renders nothing rather than the epoch, which is what parsing an empty string
-         * would give.
-         *
-         * **The element's own text is read as a fallback, and only in a browser.**
-         * `<helix-format-date elapsed>2026-08-27T01:00:00Z</helix-format-date>` is the
-         * spelling that reads best in markup, and it cannot be the only one: measured
-         * against Lit's server shim, `textContent`, `children`, `firstChild` and
-         * `querySelector` are all `undefined` there, so a server has no way to see it.
-         * An element rendered on a server needs the attribute; one rendered in a
-         * browser may use either.
-         */
         this.date = '';
-        /**
-         * Show how long ago it was, compactly, instead of the date.
-         *
-         * Reflected, because it is the one property that decides which of two readings
-         * this is and a stylesheet has a reason to know: a compact reading is a fixed
-         * few characters and a date is not.
-         */
         this.elapsed = false;
-        /**
-         * Locale for the reading.
-         *
-         * Empty is the runtime's own.
-         */
         this.locale = '';
-        /**
-         * The clock this element last drew against.
-         *
-         * A state field and not a read of `Date.now()` inside `render`, which would
-         * make the template a function of something Lit cannot see change: the element
-         * would draw the right text once and never notice it had gone stale.
-         */
         this.clock = undefined;
-        /**
-         * The date read out of the light DOM, where no attribute carried one.
-         */
         this.written = '';
         this.stopTicking = undefined;
         this.watching = undefined;
     }
-    /** The timestamp, or nothing where there is not one to read. */
     get moment() {
         const source = this.date || this.written;
         if (source === '') {
@@ -102,7 +26,6 @@ let HelixHeadlessFormatDate = class HelixHeadlessFormatDate extends HelixElement
         const parsed = new Date(source);
         return Number.isNaN(parsed.getTime()) ? undefined : parsed;
     }
-    /** Every `Intl.DateTimeFormat` option a consumer set, and none they did not. */
     get options() {
         const asked = {};
         if (this.day) {
@@ -137,20 +60,12 @@ let HelixHeadlessFormatDate = class HelixHeadlessFormatDate extends HelixElement
     connectedCallback() {
         super.connectedCallback();
         this.tick();
-        /* Rebuilt on every connection rather than built once, because
-           `disconnectedCallback` takes it down and a framework moves nodes for
-           ordinary reasons: built in `firstUpdated` alone this comes back
-           permanently dead the first time a list is reordered. Guarded on
-           `hasUpdated` because the first connection happens before there is anything
-           to watch. */
         if (this.hasUpdated) {
             this.watch();
         }
     }
     disconnectedCallback() {
         super.disconnectedCallback();
-        /* Both outlive the element otherwise, and a page that mounts and unmounts a
-           feed leaks one of each every time it opens. */
         this.stopTicking?.();
         this.stopTicking = undefined;
         this.watching?.disconnect();
@@ -167,7 +82,6 @@ let HelixHeadlessFormatDate = class HelixHeadlessFormatDate extends HelixElement
             this.tick();
         }
     }
-    /** The light DOM's own text, which is the other way to write the value. */
     read() {
         if (this.date !== '') {
             return;
@@ -183,15 +97,6 @@ let HelixHeadlessFormatDate = class HelixHeadlessFormatDate extends HelixElement
         this.watching = new MutationObserver(() => this.read());
         this.watching.observe(this, { characterData: true, childList: true, subtree: true });
     }
-    /**
-     * Schedules the next reading, and only the next one.
-     *
-     * The formatter says when its own answer expires, so this asks for exactly
-     * that moment rather than polling: an item minutes old wakes once a minute, an
-     * item hours old once an hour, and an item showing a date never, which is the
-     * difference between a feed that costs nothing to leave open and one that
-     * does.
-     */
     tick() {
         this.stopTicking?.();
         this.stopTicking = undefined;

package/dist/heatmap/root/buckets.js

@@ -1,28 +1,3 @@
-/**
- * Which tone a reading gets, and how many readings fit.
- *
- * Kept apart from the element because both answers are arithmetic and both are
- * easy to get subtly wrong in ways a picture hides: a threshold comparison off
- * by one boundary colors a handful of cells wrong out of ninety, and a fit
- * calculation off by one drops a day silently. Neither is visible in a
- * screenshot of a strip.
- */
-/**
- * The tone for one reading, from its own `data-tone` or from the thresholds.
- *
- * **The cell's own tone wins**, and that ordering is the whole reason both
- * exist. A status page already knows a day was degraded; making it encode that
- * as a number so a component can decode it again is work for nothing, and the
- * encoding would have to agree with the thresholds or the colors would drift
- * from the truth. A contribution graph has only counts and wants the buckets.
- *
- * Thresholds are read as lower bounds, in the order given, and the last one that
- * a value reaches wins. `thresholds="0,1,3,6"` with `tones="muted,info,accent,success"`
- * puts 0 in `muted`, 1 and 2 in `info`, 3 to 5 in `accent`, and 6 upward in
- * `success`. A value below the first bound gets no tone rather than the first
- * one: an empty cell in a contribution graph is a day with nothing in it, and
- * painting it as the lowest bucket claims a reading that does not exist.
- */
 export const toneOf = (reading, thresholds, tones) => {
     if (reading.tone) {
         return reading.tone;
@@ -38,48 +13,16 @@ export const toneOf = (reading, thresholds, tones) => {
     }
     return chosen;
 };
-/** A comma or space separated list of numbers, in the order written. */
 export const numbers = (source) => source
     .split(/[\s,]+/)
     .filter((one) => one !== '')
     .map(Number)
     .filter((one) => Number.isFinite(one));
-/** A comma or space separated list of names, in the order written. */
 export const words = (source) => source.split(/[\s,]+/).filter((one) => one !== '');
-/**
- * How many readings fit across a given width, and which ones they are.
- *
- * **Ninety cells in 320 pixels is three and a half pixels each**, which is not a
- * strip, it is a smear. So a narrow container shows fewer cells rather than
- * thinner ones, and it shows the *most recent* ones, because a status strip that
- * drops the newest days to keep the oldest is answering a question nobody asked.
- *
- * **The count it returns is what the summary has to be recomputed against.** A
- * strip labeled "99.2% over 90 days" that is drawing 45 of them is telling the
- * reader something false about the picture in front of them, and nothing about
- * the picture says so. That is the one fault in this component that a screenshot
- * cannot show, which is why the element reflects the number and announces it.
- *
- * **What crosses the width is a column, and `rows` is how many cells are in
- * one.** Counting cells is the same number only while `rows` is 1. Divide by
- * the wrong thing at `rows="7"` and a ten week graph comes back as fifty-nine
- * readings in a 592px box: eleven days dropped to fit a strip that wanted 156
- * pixels, and fifty-nine is not a multiple of seven, so every column after the
- * cut is offset by a day and the day-of-week rows stop meaning anything. A
- * calendar heatmap that silently rotates its own weekdays is worse than one
- * that drops a week.
- *
- * The count is therefore always a whole number of columns, which is what keeps
- * the tail slice aligned.
- */
 export const fits = (total, width, minimum, gap, rows = 1) => {
     if (!Number.isFinite(width) || width <= 0 || minimum <= 0) {
         return total;
     }
-    /* n columns need n widths and n-1 gaps, so solving for n gives the +gap on
-       both sides. Written as `width / (minimum + gap)` it is short by one column
-       at every size, which is the off-by-one that reads as "the strip has a
-       margin". */
     const columns = Math.max(1, Math.floor((width + gap) / (minimum + gap)));
     return Math.min(total, columns * Math.max(1, rows));
 };