@fusion.dev/helix-headless 0.104.1 → 0.106.0

package/dist/format-date/root/format-date-root.d.ts

@@ -1,33 +1,24 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 /**
- * @summary A timestamp, written the way the reader's locale writes one.
+ * @summary A timestamp, formatted for the user's locale.
  *
  * @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.
+ * Formats a date with `Intl` where it is shown, so you do not write the same
+ * `Intl` call and options in your own code.
  *
- * **`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.
+ * **`elapsed` shows compact relative time for a feed**, such as "42m", "3h", or
+ * "1d". After six days it shows a date. In en-US, `Intl.NumberFormat` narrow
+ * renders both `minute` and `month` as `m`, so a compact "3m" could mean three
+ * minutes or three months. `elapsedTime` in `helix/core` does 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.
+ * **The text refreshes on one timer shared by the page.** Each element
+ * schedules an update for when its current reading expires, and an element
+ * showing a date schedules none, so a long feed left open costs almost nothing.
  *
- * **`<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".
+ * **The output is always `<time datetime>`**, so screen readers, copy and
+ * paste, and scripts parsing the page get the exact instant, whatever the
+ * visible text says.
  *
  * @since 0.1.0
  * @status stable
@@ -35,11 +26,11 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
  * @aliases RelativeTime, Timestamp, TimeAgo
  * @documentation https://fusion.dev/helix/components/format-date
  *
- * @csspart time - The `<time>` element carrying the reading.
+ * @csspart time - The `<time>` element that holds the formatted text.
  */
 export declare class HelixHeadlessFormatDate extends HelixElement {
     /**
-     * The timestamp, as anything `Date` parses.
+     * The timestamp, in any format `Date` can parse.
      *
      * 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
@@ -61,7 +52,8 @@ export declare class HelixHeadlessFormatDate extends HelixElement {
      */
     day?: 'numeric' | '2-digit';
     /**
-     * Show how long ago it was, compactly, instead of the date.
+     * Shows how long ago the timestamp was, in a compact form such as "3h", in
+     * place 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
@@ -73,7 +65,7 @@ export declare class HelixHeadlessFormatDate extends HelixElement {
      */
     hour?: 'numeric' | '2-digit';
     /**
-     * Locale for the reading.
+     * The locale to format the timestamp in.
      *
      * Empty is the runtime's own.
      */
@@ -97,7 +89,7 @@ export declare class HelixHeadlessFormatDate extends HelixElement {
      */
     timeZone?: string;
     /**
-     * Whether to name the time zone, and how.
+     * Shows the name of the time zone, in its `long` or `short` form.
      */
     timeZoneName?: 'long' | 'short';
     /**

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

@@ -3,29 +3,28 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
 import '../../tooltip/index.js';
 declare const HelixHeadlessHeatmap_base: typeof HelixElement & (new (...args: any[]) => import("@fusion.dev/helix-core").MixinChartSourceInterface);
 /**
- * @summary A strip of cells colored by how each one went: uptime, contributions, activity.
+ * @summary A strip of cells, each colored by its reading, for uptime, contributions, or activity.
  *
  * @description
- * **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.
+ * A grid of cells, each colored by a tone. `rows="1"` makes a status strip, and
+ * `rows="7"` makes a contribution graph. GitHub's contribution graph uses five
+ * discrete levels, which a set of tones covers.
  *
- * **What it cannot be is a bar chart with flat values**, and the data model is
- * what closes that: chart color is per *series* everywhere else here, so ninety
- * differently colored cells would be ninety series.
+ * Color in a heatmap is per cell. In every other Helix chart, color is per
+ * series, so ninety differently colored cells would need ninety series.
  *
- * **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.
+ * **The data is a real `<table>` named by `for`**, as in every Helix chart, and
+ * the table is the accessible representation. Hide it with
+ * `data-hidden-visually`, and screen readers still read it.
  *
  * A cell takes its tone from its own `data-tone`, or from `thresholds` and
- * `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.
+ * `tones` applied to its value. `data-tone` wins, so when you already know a
+ * day was degraded, you can set the tone directly.
  *
- * **A tone is a name this tier never resolves.** `tone="success"` writes
- * `--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.
+ * **The headless tier does not resolve tone names.** A tone named `success`
+ * writes `--heatmap-tone: var(--heatmap-tone-success)`, and the styled tier or
+ * your own stylesheet defines that property. The headless tier does not use
+ * `var(--helix-color-*)`.
  *
  * @since 0.1.0
  * @status stable
@@ -35,12 +34,12 @@ declare const HelixHeadlessHeatmap_base: typeof HelixElement & (new (...args: an
  *
  * @slot end - Below the strip, at the trailing edge: usually the newest date.
  * @slot start - Below the strip, at the leading edge: usually the oldest date.
- * @slot summary - Below the strip, in the middle: the reading over the range drawn.
+ * @slot summary - Below the strip, in the middle: a summary of the range shown.
  *
- * @event {HelixResizeEvent} helix-resize - Fired when the number of cells drawn changes, carrying that number.
+ * @event {HelixResizeEvent} helix-resize - Fired when the number of cells drawn changes, with the new number.
  *
  * @csspart cell - One reading.
- * @csspart empty - Shown when the table has no readings in it, and not before the table can be read at all: on a server, and while hydrating what one sent, there is no document to resolve `for` in and nothing is known yet.
+ * @csspart empty - Shown when the table has no readings. It stays hidden until the table can be read: on the server and during hydration, there is no document to resolve `for` in.
  * @csspart end - The trailing slot's box.
  * @csspart footer - The three-slot row under the strip.
  * @csspart mark - The invisible point the tooltip is anchored to.
@@ -50,33 +49,33 @@ declare const HelixHeadlessHeatmap_base: typeof HelixElement & (new (...args: an
  * @csspart tooltip - The bubble, forwarded from `Tooltip`.
  * @csspart tooltip-anchor - The `Tooltip` element itself.
  * @csspart tooltip-arrow - The bubble's point, forwarded from `Tooltip`.
- * @csspart tooltip-arrow-bottom - The point while the bubble is below the reading, so on its top edge, beside `tooltip-arrow`.
- * @csspart tooltip-arrow-left - The point while the bubble is left of the reading, so on its right edge, beside `tooltip-arrow`.
- * @csspart tooltip-arrow-right - The point while the bubble is right of the reading, so on its left edge, beside `tooltip-arrow`.
- * @csspart tooltip-arrow-top - The point while the bubble is above the reading, so on its bottom edge, beside `tooltip-arrow`.
- * @csspart tooltip-bottom - The bubble while it is below the reading, beside `tooltip`.
+ * @csspart tooltip-arrow-bottom - The point while the bubble is below the reading, on its top edge. Set alongside `tooltip-arrow`.
+ * @csspart tooltip-arrow-left - The point while the bubble is left of the reading, on its right edge. Set alongside `tooltip-arrow`.
+ * @csspart tooltip-arrow-right - The point while the bubble is right of the reading, on its left edge. Set alongside `tooltip-arrow`.
+ * @csspart tooltip-arrow-top - The point while the bubble is above the reading, on its bottom edge. Set alongside `tooltip-arrow`.
+ * @csspart tooltip-bottom - The bubble while it is below the reading. Set alongside `tooltip`.
  * @csspart tooltip-cell - One column's name and value inside the tooltip.
  * @csspart tooltip-label - The reading's own name inside the tooltip.
- * @csspart tooltip-left - The bubble while it is left of the reading, beside `tooltip`.
+ * @csspart tooltip-left - The bubble while it is left of the reading. Set alongside `tooltip`.
  * @csspart tooltip-name - A column's name inside the tooltip.
- * @csspart tooltip-right - The bubble while it is right of the reading, beside `tooltip`.
- * @csspart tooltip-top - The bubble while it is above the reading, beside `tooltip`.
+ * @csspart tooltip-right - The bubble while it is right of the reading. Set alongside `tooltip`.
+ * @csspart tooltip-top - The bubble while it is above the reading. Set alongside `tooltip`.
  * @csspart tooltip-value - A column's value inside the tooltip.
  *
- * @cssproperty --heatmap-rows - How many rows the strip lays out. Written by the component from the data, read by the tier that draws it.
- * @cssproperty --heatmap-tone - The tone of the cell this is set on. Written by the component, read by the sheet that paints.
- * @cssproperty --heatmap-tone-1 - The quietest step of the magnitude ramp, reached by `tones="1 …"`.
+ * @cssproperty --heatmap-rows - How many rows the strip lays out. The component writes it from the data, and the stylesheet that draws the strip reads it.
+ * @cssproperty --heatmap-tone - The tone of the cell it is set on. The component writes it, and the stylesheet that paints the cell reads it.
+ * @cssproperty --heatmap-tone-1 - The weakest step of the magnitude ramp, used by `tones="1 …"`.
  * @cssproperty --heatmap-tone-2 - The second step of the magnitude ramp.
  * @cssproperty --heatmap-tone-3 - The third step of the magnitude ramp.
  * @cssproperty --heatmap-tone-4 - The fourth step of the magnitude ramp.
- * @cssproperty --heatmap-tone-5 - The loudest step of the magnitude ramp.
- * @cssproperty --heatmap-tone-accent - What `accent` is worth.
- * @cssproperty --heatmap-tone-danger - What `danger` is worth.
- * @cssproperty --heatmap-tone-info - What `info` is worth.
- * @cssproperty --heatmap-tone-muted - What `muted` is worth: the quiet ground, for a bucket that means nothing happened.
- * @cssproperty --heatmap-tone-primary - What `primary` is worth.
- * @cssproperty --heatmap-tone-success - What `success` is worth, as a name or a `data-tone`.
- * @cssproperty --heatmap-tone-warning - What `warning` is worth.
+ * @cssproperty --heatmap-tone-5 - The strongest step of the magnitude ramp.
+ * @cssproperty --heatmap-tone-accent - The color of the `accent` tone.
+ * @cssproperty --heatmap-tone-danger - The color of the `danger` tone.
+ * @cssproperty --heatmap-tone-info - The color of the `info` tone.
+ * @cssproperty --heatmap-tone-muted - The color of the `muted` tone: a quiet background, for a bucket that means nothing happened.
+ * @cssproperty --heatmap-tone-primary - The color of the `primary` tone.
+ * @cssproperty --heatmap-tone-success - The color of the `success` tone, named in `tones` or in `data-tone`.
+ * @cssproperty --heatmap-tone-warning - The color of the `warning` tone.
  */
 export declare class HelixHeadlessHeatmap extends HelixHeadlessHeatmap_base {
     /**
@@ -87,8 +86,8 @@ export declare class HelixHeadlessHeatmap extends HelixHeadlessHeatmap_base {
      */
     emptyText: string;
     /**
-     * Space between cells, in CSS pixels, for the same reason `min-cell` is a
-     * number.
+     * Space between cells, in CSS pixels. It is a number for the same reason
+     * `min-cell` is.
      */
     gap: number;
     /**
@@ -132,7 +131,7 @@ export declare class HelixHeadlessHeatmap extends HelixHeadlessHeatmap_base {
      */
     thresholds: string;
     /**
-     * Tone per bucket, in the same order as `thresholds`.
+     * The tone for each bucket, in the same order as `thresholds`.
      *
      * A name, resolved as `--heatmap-tone-<name>` by whichever tier answers.
      * **`"1"` through `"5"` are a ramp and everything else is a category**, which

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

@@ -2,31 +2,27 @@ import { HelixElement } from '@fusion.dev/helix-core';
 import { type HelixIcon } from '@fusion.dev/helix-icons';
 import { nothing, type TemplateResult } from 'lit';
 /**
- * @summary Renders a named icon from the Helix set.
+ * @summary A named icon from the Helix set.
  *
  * @description
- * The set is Phosphor, drawn on a 256 box at stroke-width 16, and each glyph is
- * rendered as its own inner markup rather than as a single path. Most icons are
- * several elements at once, each with its own stroke and fill, so a one-path
- * model would draw a fraction of the set and quietly drop the rest.
+ * The icons are Phosphor, drawn on a 256 box at stroke-width 16. Each glyph
+ * renders its full inner markup, because most icons are several elements, each
+ * with its own stroke and fill.
  *
- * **The markup is trusted by construction.** It is generated at build time from
- * SVG files in this repository, never from anything a user supplies, which is
- * what makes `unsafeSVG` the right tool rather than a risk.
+ * The markup is generated at build time from SVG files in this repository and
+ * never comes from user input, so rendering it with `unsafeSVG` is safe.
  *
- * The `<svg>` carries `fill="currentColor"` because the generator keeps only
- * the inner markup and discards the source's own root tag, and that tag is
- * where Phosphor puts its fill. Without it, every solid glyph in the set, 65 of
- * them, falls back to the SVG default of black and disappears on a dark page.
- * Shapes that set their own `fill` or `stroke` are unaffected, which is why the
- * outline icons looked fine and hid this.
+ * The `<svg>` carries `fill="currentColor"`. The generator keeps only the inner
+ * markup, and Phosphor sets its fill on the root tag that the generator
+ * discards. Without it, the 65 solid glyphs fall back to black and disappear on
+ * a dark background. Shapes that set their own `fill` or `stroke` are
+ * unaffected.
  *
- * A name with no match renders nothing at all instead of an empty box, so a
- * typo cannot leave a hole in a layout that looks deliberate.
+ * A name with no match renders nothing.
  *
- * An icon is decorative by default and hidden from assistive technology. Give
- * it a `label` only when the icon is the sole carrier of meaning, such as
- * inside a button with no text.
+ * An icon is decorative by default and hidden from assistive technology. Set
+ * `label` only when the icon is the only carrier of meaning, such as in a
+ * button with no text.
  *
  * @since 0.1.0
  * @status stable
@@ -38,7 +34,7 @@ import { nothing, type TemplateResult } from 'lit';
  */
 export declare class HelixHeadlessIcon extends HelixElement {
     /**
-     * The icon itself, for a consumer who imported one.
+     * The icon to draw, as an object you import.
      *
      * **The scalable door, and the one this library uses internally.** An icon is
      * data, `{ content, name, viewBox }`, so a value imported by name ships one
@@ -53,11 +49,13 @@ export declare class HelixHeadlessIcon extends HelixElement {
      */
     icon?: HelixIcon;
     /**
-     * Accessible name, for an icon that is not decorative.
+     * The icon's name, read by screen readers. Set it for an icon that is not
+     * decorative.
      */
     label: string;
     /**
-     * Turns the glyph round on a right-to-left page, for an arrow meaning forward or back.
+     * Flips the glyph on a right-to-left page. Use it for an arrow that means
+     * forward or back.
      *
      * Asked for rather than inferred from the name. The names are physical, and
      * `arrow-left` drawn pointing right on an Arabic page would be the icon
@@ -65,7 +63,7 @@ export declare class HelixHeadlessIcon extends HelixElement {
      */
     mirror: boolean;
     /**
-     * Name of the icon in the Helix set.
+     * The name of the icon in the Helix set.
      *
      * **A lookup, and the reason both this and `icon` exist.** A name is a string,
      * so it is what markup can carry, and resolving one means an index of the

package/dist/icon-button/root/icon-button-root.d.ts

@@ -1,23 +1,21 @@
 import { HelixHeadlessButton } from '../../button/root/button-root.js';
 /**
- * @summary A button whose content is an icon, and which must be named.
+ * @summary A button whose content is an icon, named by its `label`.
  *
  * @description
- * Everything a button does, with one thing added and it is the reason this is
- * an element rather than a note on `Button`: **an icon-only control has no
- * accessible name unless it is given one.** A button whose content is a glyph
- * announces as "button" and nothing else, which is the single most common way a
- * toolbar becomes unusable without sight. `label` is not optional in practice,
- * and having a component that says so is what makes it reviewable.
+ * A button with an icon for its content. Always set `label`: an icon-only
+ * control has no accessible name unless you give it one, and a button whose
+ * content is a glyph is announced as "button" and nothing else. A separate
+ * component with a `label` makes the name something a review can check.
  *
- * **Registered, so it can be rendered and not only subclassed.** Anything in
- * this tier needing an icon button, such as an announcement's dismiss control,
- * renders `helix-headless-icon-button` rather than reaching into the styled tier
- * for a tag that would never upgrade.
+ * The element is registered, so other headless components can render
+ * `helix-headless-icon-button`, for example as an announcement's dismiss
+ * control. They do not depend on a styled tag, which would never upgrade in
+ * this tier.
  *
- * Top-level rather than `Button.Icon`, because a namespace means composition
- * and an icon-only button is not part of a button. It is a button with
- * different content and a different shape, which makes it its own component.
+ * Icon Button is a top-level component. A namespace such as `Button.Icon` would
+ * mean a part of a button, and an icon-only button is a complete button with
+ * different content and a different shape.
  *
  * @since 0.1.0
  * @status stable

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

@@ -1,18 +1,16 @@
 import { HelixElement } from '@fusion.dev/helix-core';
 import { type PropertyValues, type TemplateResult } from 'lit';
 /**
- * @summary A picture that says whether it arrived.
+ * @summary An image that shows a placeholder while it loads and a fallback if it fails.
  *
  * @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. 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.
+ * Image handles the part CSS cannot: when the picture has loaded, or that it
+ * failed. `aspect-ratio` in your stylesheet reserves the box. The element
+ * tracks three states and relays 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 make this tier depend on a component it does not ship.
+ * The `placeholder` slot is empty by default, so the headless tier does not
+ * depend on `Skeleton`, which it does not ship.
  *
  * @since 0.1.0
  * @status stable
@@ -20,31 +18,31 @@ import { type PropertyValues, type TemplateResult } from 'lit';
  * @aliases Picture, Img, Figure
  * @documentation https://fusion.dev/helix/components/image
  *
- * @slot fallback - Shown instead of it, if it never does.
- * @slot placeholder - Shown until the picture arrives.
+ * @slot fallback - Shown in place of the image if it fails to load.
+ * @slot placeholder - Shown until the image loads.
  *
- * @event {Event} error - Relayed for the same reason.
- * @event {Event} load - Relayed, because the platform's own does not escape.
+ * @event {Event} error - The image failed to load. Relayed from the inner image, whose own event stays inside the shadow root.
+ * @event {Event} load - The image loaded. Relayed from the inner image, whose own event stays inside the shadow root.
  *
- * @csspart fallback - What stands in when it fails.
- * @csspart image - The picture itself.
- * @csspart placeholder - What stands in until it arrives.
+ * @csspart fallback - The fallback, shown when the image fails to load.
+ * @csspart image - The image itself.
+ * @csspart placeholder - The placeholder, shown until the image loads.
  */
 export declare class HelixHeadlessImage extends HelixElement {
     /**
-     * What it shows, for a reader who cannot see it.
+     * A text description of the image, read by screen readers.
      *
      * Empty is a real answer and means decoration. Omitting the attribute is not
      * the same thing: a reader with nothing to read announces the file name.
      */
     alt: string;
     /**
-     * How the picture is fetched across origins, which decides whether a canvas
-     * can read it.
+     * How the image is fetched across origins. It decides whether a canvas can
+     * read the image.
      */
     crossOrigin: 'anonymous' | 'use-credentials' | null;
     /**
-     * Whether the browser may decode off the main thread.
+     * Whether the browser may decode the image off the main thread.
      *
      * `async` is the resting value and right for a picture in a page. `sync` is
      * what a consumer reaches for when the picture is about to be composited with
@@ -52,7 +50,8 @@ export declare class HelixHeadlessImage extends HelixElement {
      */
     decoding: 'async' | 'auto' | 'sync';
     /**
-     * How urgently to fetch it, for the one picture that is the page.
+     * How urgently the browser fetches the image. Set `high` on the main image
+     * of a page.
      *
      * The hero of a page is usually its largest contentful paint, and the fix is
      * two attributes rather than one: `loading="eager"` stops it waiting for the
@@ -62,7 +61,8 @@ export declare class HelixHeadlessImage extends HelixElement {
      */
     fetchPriority: 'auto' | 'high' | 'low';
     /**
-     * Whether to wait until it is nearly on screen.
+     * Whether the image waits to load until it is nearly on screen. Defaults to
+     * `lazy`.
      *
      * `lazy` by default, which is the opposite of the platform's, because a
      * picture worth putting in a component is usually below the fold and the one
@@ -74,19 +74,19 @@ export declare class HelixHeadlessImage extends HelixElement {
      */
     referrerPolicy: string;
     /**
-     * How much of the line it will take, passed through to the picture.
+     * The width the image takes in the layout, passed through to the inner image.
      */
     sizes: string;
     /**
-     * Where the picture is.
+     * The URL of the image.
      */
     src: string;
     /**
-     * The candidate widths, passed through to the picture.
+     * The candidate files and their widths, passed through to the inner image.
      */
     srcset: string;
     /**
-     * Whether the picture is on its way, here, or never coming.
+     * The loading state: `loading`, `loaded`, or `error`.
      *
      * Read-only to a consumer: it is a report rather than a setting.
      *
@@ -185,13 +185,13 @@ export declare class HelixHeadlessImage extends HelixElement {
      * nowhere else on the page.
      */
     private get image();
-    /** Whether the picture has finished arriving, however it went. */
+    /** Whether the image has finished loading, successfully or not. */
     get complete(): boolean;
-    /** Which candidate the browser actually chose out of `srcset`. */
+    /** The candidate the browser chose from `srcset`. */
     get currentSrc(): string;
-    /** The picture's own height in pixels, and zero until it has arrived. */
+    /** The image's intrinsic height in pixels. Zero until the image loads. */
     get naturalHeight(): number;
-    /** The picture's own width in pixels, and zero until it has arrived. */
+    /** The image's intrinsic width in pixels. Zero until the image loads. */
     get naturalWidth(): number;
     protected render(): TemplateResult;
 }