@fusion.dev/helix 0.105.0 → 0.106.0

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

@@ -2,20 +2,19 @@ import { HelixHeadlessHeatmap } from '@fusion.dev/helix-headless/heatmap';
 import type { CSSResultGroup } from 'lit';
 import '../../tooltip/index.js';
 /**
- * @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 grid, filled down the column then across: a week is a column, so the strip
- * reads left to right in weeks and top to bottom in days. `rows="1"` makes it a
+ * Cells fill down each column, then across. A column is a week, so the strip
+ * reads left to right in weeks and top to bottom in days. `rows="1"` makes a
  * single row.
  *
- * An empty cell takes the palette's quietest ground rather than being
- * transparent, so a gap reads as a period with nothing in it rather than as a
- * hole in the picture.
+ * An empty cell takes the palette's quietest background color, so a gap shows
+ * as a period with no data.
  *
- * `tones="success"` and `data-tone="danger"` reach the theme's status colors;
- * `tones="1 2 3 4 5"` reaches a five-step ramp of one hue, which is the only
- * thing two cells can be compared by.
+ * `tones="success"` and `data-tone="danger"` use the theme's status colors.
+ * `tones="1 2 3 4 5"` uses a five-step ramp of one hue, so cells can be
+ * compared by value.
  *
  * @since 0.1.0
  * @status stable
@@ -33,42 +32,43 @@ import '../../tooltip/index.js';
  * @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-cell-height - How tall a cell is. A row of a tall thin cell is what a status page draws.
+ * @cssproperty --heatmap-cell-height - How tall a cell is. One row of tall, narrow cells looks like a status page.
  * @cssproperty --heatmap-cell-inline-size - How wide a cell is. The strip fits as many as the container allows.
  * @cssproperty --heatmap-cell-radius - How far a cell's corners are rounded.
- * @cssproperty --heatmap-cell-size - The size a cell wants on both axes, where neither is given its own.
- * @cssproperty --heatmap-gap - Space between cells. Zero is a continuous field rather than a grid of tiles.
- * @cssproperty --heatmap-tone-1 - The quietest step of the magnitude ramp, reached by `tones="1 …"`.
+ * @cssproperty --heatmap-cell-size - The size of a cell on both axes, used where neither axis has its own size set.
+ * @cssproperty --heatmap-gap - Space between cells. Zero draws one continuous field.
+ * @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 HelixHeatmap extends HelixHeadlessHeatmap {
     static tier: string;
     static styles: CSSResultGroup;
     /**
-     * The first guess at what this sheet draws, before it has been measured.
+     * The starting estimate of the gap this stylesheet draws, used until the
+     * strip is measured.
      *
      * **Not a contract.** `fits()` reads the strip back rather than being told a
      * cell size by hand, so nothing has to be kept in step and
@@ -83,7 +83,10 @@ export declare class HelixHeatmap extends HelixHeadlessHeatmap {
      * not move.
      */
     gap: number;
-    /** The drawn cell width, for the reason `gap` is the drawn gap. `0.75rem` at the root font size. */
+    /**
+     * The starting estimate of the cell width this stylesheet draws, for the
+     * same reason as `gap`. `0.75rem` at the root font size.
+     */
     minCell: number;
 }
 declare global {

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

@@ -1,13 +1,13 @@
 import { HelixHeadlessIcon } from '@fusion.dev/helix-headless/icon';
 import type { CSSResultGroup } from 'lit';
 /**
- * @summary Renders a named icon from the Helix set.
+ * @summary A named icon from the Helix set.
  *
  * @description
- * Draws in `currentColor` and sizes from `--icon-size`, so an icon inherits the
- * color of the text it sits in and a container can resize it without reaching
- * for a prop. Inside a button that hook is set in `em`, which keeps the icon in
- * proportion as the button's own size changes.
+ * Draws in `currentColor` and sizes from `--icon-size`, so an icon takes the
+ * color of the text around it and a container can resize it without a property.
+ * Inside a button, `--icon-size` is set in `em`, so the icon scales with the
+ * button.
  *
  * @since 0.1.0
  * @status stable
@@ -17,7 +17,7 @@ import type { CSSResultGroup } from 'lit';
  *
  * @csspart svg - The rendered SVG.
  *
- * @cssproperty --icon-size - Edge length of the icon's box.
+ * @cssproperty --icon-size - The width and height of the icon's box.
  */
 export declare class HelixIcon extends HelixHeadlessIcon {
     static styles: CSSResultGroup;

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

@@ -5,14 +5,13 @@ declare const HelixIconButton_base: (new (...args: any[]) => import("../../share
  * @summary A square button whose content is an icon.
  *
  * @description
- * Top-level rather than `Button.Icon`, because a namespace means composition:
- * `Tabs.Tab` is part of a tab set, 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 `Tabs.Tab` is for a
+ * part of a larger component, and an icon-only button is a complete button with
+ * different content and a different shape.
  *
- * `label` is not optional in practice. An icon-only control with no accessible
- * name is announced as "button" and nothing else, which is the single most
- * common way a toolbar becomes unusable without sight.
+ * Always set `label`. An icon-only control with no accessible name is announced
+ * as "button" and nothing else, which is the most common way a toolbar becomes
+ * unusable without sight.
  *
  * @since 0.1.0
  * @status stable
@@ -25,12 +24,12 @@ declare const HelixIconButton_base: (new (...args: any[]) => import("../../share
  * @csspart button - The inner button or anchor.
  *
  * @cssproperty --icon-button-radius - Corner radius of the control, which a group flattens through `--button-radius-start` and `--button-radius-end`.
- * @cssproperty --icon-button-shadow - What it casts, where it is raised off the page.
+ * @cssproperty --icon-button-shadow - Shadow of a raised icon button.
  * @cssproperty --icon-button-size - Edge length of the control.
  */
 export declare class HelixIconButton extends HelixIconButton_base {
     /**
-     * Whether it is raised off the page it sits on.
+     * Raises the button off the page with a shadow.
      *
      * Separate from `shape`, because they are separate facts: a docked control is
      * raised whatever its outline, and a circle inside a toolbar is not raised at
@@ -39,7 +38,7 @@ export declare class HelixIconButton extends HelixIconButton_base {
      */
     raised: boolean;
     /**
-     * The outline it is cut to, which is an axis of its own and not a value on one.
+     * The button's shape. Leave it unset for a rounded square, or set `circle`.
      *
      * `emphasis` says how filled it is and `tone` says what it means; neither of
      * them says what shape it is, and folding a shape into either would put a

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

@@ -1,12 +1,12 @@
 import { HelixHeadlessImage } from '@fusion.dev/helix-headless/image';
 import type { CSSResultGroup } 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
- * Presentation only: the box the picture is given, how it fills it, and the
- * fade when it lands. What the three states are and when they change is the
- * base class.
+ * The styled tier adds presentation only: the box the picture is given, how the
+ * picture fills it, and the fade when it loads. The base class defines the
+ * three states and when they change.
  *
  * @since 0.1.0
  * @status stable
@@ -14,16 +14,16 @@ import type { CSSResultGroup } from 'lit';
  * @aliases Picture, Img, Figure
  * @documentation https://fusion.dev/helix/components/image
  *
- * @cssproperty --image-aspect - The ratio of the box, as `16 / 9`.
- * @cssproperty --image-fit - How the picture fills it.
- * @cssproperty --image-placeholder-color - The resting surface behind both stand-ins.
- * @cssproperty --image-position - Which part survives a crop.
- * @cssproperty --image-radius - Corner radius, under `shape="rounded"`.
+ * @cssproperty --image-aspect - The aspect ratio of the box, such as `16 / 9`.
+ * @cssproperty --image-fit - How the image fills the box, as an `object-fit` value.
+ * @cssproperty --image-placeholder-color - The background behind the placeholder and the fallback.
+ * @cssproperty --image-position - Which part of the image stays in view when it is cropped, as an `object-position` value.
+ * @cssproperty --image-radius - The corner radius when `shape` is `rounded`.
  */
 export declare class HelixImage extends HelixHeadlessImage {
     static styles: CSSResultGroup;
     /**
-     * Whether the corners are cut.
+     * The shape of the corners. `rounded` rounds them.
      *
      * The axis and not a boolean, because `rounded` is a registered word and a
      * private spelling of a registry question is what `appearance` was retired

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

@@ -2,23 +2,20 @@ import { HelixHeadlessInput } from '@fusion.dev/helix-headless/input';
 import type { CSSResultGroup } from 'lit';
 import '../../icon/index.js';
 /**
- * @summary A single line of text a reader types into.
+ * @summary A field for a single line of text.
  *
  * @description
- * The frame is the field rather than the input, so anything slotted at either
- * end sits inside the same box as the text and the focus ring is drawn once,
- * around the whole control, instead of around a smaller box within it.
+ * The frame wraps the whole field, so anything slotted at either end sits in
+ * the same box as the text, and the focus ring goes around the whole control.
  *
- * The input itself is the native one, stripped rather than replaced, so the
- * caret, the selection, the autofill, and the keyboard a phone chooses are all
- * the platform's.
+ * The inner input is the native one with its styling removed, so the caret,
+ * selection, autofill, and a phone's keyboard all work natively.
  *
- * Height comes from the region, like every other control: `data-density` on
- * whatever holds it, not a `size` here. Invalid styling waits for the `invalid`
- * custom state, because a field is not wrong before anyone has filled it in and
- * `:user-invalid` cannot answer that here: it tracks the control the reader is
- * in, which is inside this shadow root, so it never reaches the host the rule
- * selects on.
+ * Height comes from `data-density` on a containing element, like every other
+ * control. There is no `size` property. Invalid styling applies only with the
+ * `invalid` custom state, so an empty field is not marked wrong before anyone
+ * fills it in. `:user-invalid` cannot be used here, because it matches the
+ * input inside the shadow root and never the host.
  *
  * @since 0.1.0
  * @status stable

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

@@ -4,12 +4,11 @@ import type { CSSResultGroup } from 'lit';
  * @summary A keyboard key or chord, set inline with text.
  *
  * @description
- * Drawn as a physical key: a hairline, a sunken fill, and one inset shadow
- * along the bottom edge that reads as depth without becoming a picture of a
- * key.
+ * Drawn as a physical key, with a hairline border, a sunken fill, and one inset
+ * shadow along the bottom edge.
  *
- * Sized in `em`, so it stays proportional to whatever it is set inside rather
- * than holding one size and looking wrong in a heading.
+ * Sized in `em`, so it stays in proportion with the text around it, including
+ * in a heading.
  *
  * @since 0.1.0
  * @status stable
@@ -17,8 +16,8 @@ import type { CSSResultGroup } from 'lit';
  * @aliases Key, Shortcut, Hotkey
  * @documentation https://fusion.dev/helix/components/kbd
  *
- * @cssproperty --kbd-background-color - Fill of the key.
- * @cssproperty --kbd-border-color - Color of the hairline and the edge.
+ * @cssproperty --kbd-background-color - The fill of the key.
+ * @cssproperty --kbd-border-color - The color of the key's border and its bottom edge.
  */
 export declare class HelixKbd extends HelixHeadlessKbd {
     static styles: CSSResultGroup;

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

@@ -1,19 +1,18 @@
 import { HelixHeadlessLegend } from '@fusion.dev/helix-headless/legend';
 import type { CSSResultGroup, PropertyValues } from 'lit';
 /**
- * @summary The names a chart draws, each beside the color it is drawn in.
+ * @summary A list of the series in a chart, each name beside the color it is drawn in.
  *
  * @description
- * A row that wraps, because a legend sits under a chart as wide as the chart
- * and there is no arrangement of eight names that fits every width. Set
- * `--legend-direction` to `column` where it sits beside one instead.
+ * Entries are laid out in a row that wraps, because a legend under a chart is
+ * as wide as the chart, and its names have to fit any width. Set
+ * `--legend-direction` to `column` when the legend sits beside a chart.
  *
- * The series colors are mapped on this tier rather than in the one below, which
- * carries the index and holds no tokens. `shared/chart/series.css` is where the
- * mapping lives, because an index in markup cannot select a token and a custom
- * property set inline would be the headless tier naming a color, and it is
- * shared because a chart and the legend keying it have to reach the same
- * twenty-four names.
+ * Series colors are mapped in this tier. The headless tier carries the index
+ * and holds no tokens. The mapping is in `shared/chart/series.css`, because an
+ * index in markup cannot select a token, and an inline custom property would
+ * put a color in the headless tier. Charts and legends share the file, so both
+ * use the same twenty-four color names.
  *
  * @since 0.1.0
  * @status stable
@@ -22,16 +21,16 @@ import type { CSSResultGroup, PropertyValues } from 'lit';
  * @aliases Key, Series Key
  * @documentation https://fusion.dev/helix/components/legend
  *
- * @cssproperty --legend-direction - `row`, which wraps, or `column`.
- * @cssproperty --legend-gap - Space between entries.
- * @cssproperty --legend-swatch-size - Size of the color patch.
- * @cssproperty --legend-swatch-stroke - Width of the edge an `outlined` or
+ * @cssproperty --legend-direction - The direction the entries run: `row`, which wraps, or `column`.
+ * @cssproperty --legend-gap - The space between entries.
+ * @cssproperty --legend-swatch-size - The size of the color swatch.
+ * @cssproperty --legend-swatch-stroke - The width of the edge an `outlined` or
  *   `subtle` swatch is drawn with.
  */
 export declare class HelixLegend extends HelixHeadlessLegend {
     static styles: CSSResultGroup;
     /**
-     * How much ink the swatches claim.
+     * How the swatches are drawn: `outlined`, `subtle`, or `solid`.
      *
      * **The same axis as the chart's, with the same values, because a legend that
      * does not match its chart is worse than no legend.** A key whose swatches are
@@ -50,13 +49,13 @@ export declare class HelixLegend extends HelixHeadlessLegend {
      */
     emphasis?: 'outlined' | 'solid' | 'subtle';
     /**
-     * Which entries are glass rather than solid, by name.
+     * The names of the entries whose swatches are drawn as glass.
      *
      * Matched as `outlined` is.
      */
     glass?: string;
     /**
-     * What the swatches are made of.
+     * The material of the swatches: `glass` or `frosted`. Unset is opaque.
      *
      * `glass` thins whatever emphasis drew, the way it does on a column, so a
      * legend beside a glass chart is in the same substance as the chart. Scaled by
@@ -77,7 +76,7 @@ export declare class HelixLegend extends HelixHeadlessLegend {
      */
     material?: 'frosted' | 'glass';
     /**
-     * Which entries are drawn as an outline rather than a fill, by name.
+     * The names of the entries whose swatches are drawn as an outline.
      *
      * Space or comma separated and matched against the names this legend is
      * showing, which are the same names the chart matches its own `outlined`
@@ -86,7 +85,7 @@ export declare class HelixLegend extends HelixHeadlessLegend {
      */
     outlined?: string;
     /**
-     * Where the legend sits and which way its entries run.
+     * Sets which way the entries run, to suit where you place the legend.
      *
      * Absent is a wrapping row, which is what sits under a chart. `start` and
      * `end` stack the entries in a column, for a legend beside one.
@@ -104,7 +103,7 @@ export declare class HelixLegend extends HelixHeadlessLegend {
      */
     placement?: 'end' | 'start';
     /**
-     * Which entries are drawn as a wash of their color, by name.
+     * The names of the entries whose swatches are drawn as a wash of their color.
      *
      * Matched as `outlined` is.
      */

package/dist/lightbox/item/lightbox-item.d.ts

@@ -1,13 +1,12 @@
 import { HelixHeadlessLightboxItem } from '@fusion.dev/helix-headless/lightbox';
 import type { CSSResultGroup } from 'lit';
 /**
- * @summary One thing a lightbox can show.
+ * @summary One item a lightbox can show, such as a picture, a video frame, or a chart.
  *
  * @description
- * Presentation only: the box centers what it was given and holds it inside the
- * viewport rather than sizing it, because what is in here is the consumer's and
- * may be a picture, a frame of video or a chart. Which item is shown, and the
- * arithmetic that decides, is the base class.
+ * Presentation only. The box centers its content and keeps it within the
+ * viewport without setting its size, because the content may be a picture, a
+ * video frame, or a chart. The base class decides which item is shown.
  *
  * @since 0.100.0
  * @status stable

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

@@ -1,22 +1,19 @@
 import { HelixHeadlessLightbox } from '@fusion.dev/helix-headless/lightbox';
 import type { CSSResultGroup } from 'lit';
 /**
- * @summary A viewer that opens one thing over the page.
+ * @summary A viewer that shows one item at a time over the page.
  *
  * @description
- * **A takeover rather than a panel, which is the whole difference from
- * `Dialog`.** A dialog is a thing over the page and stops short of the edges to
- * say so; a lightbox is the page for as long as it is open. The scrim is heavier
- * for the same reason: what is behind it is not meant to be read.
+ * A lightbox fills the viewport while it is open. A `Dialog` stops short of the
+ * edges because it sits over the page. The scrim is heavier than a dialog's,
+ * because the content behind it is not meant to be read.
  *
- * **A dark region that says so once**, with `color-scheme: dark` on the host,
- * which is `Video`'s answer to the same problem: the chrome is the consumer's
- * own components and they resolve their own tokens, so without a scheme on the
- * region they draw page-colored ink on a black room and disappear into it.
+ * The host sets `color-scheme: dark`, as `Video` does. The components in the
+ * chrome are yours and resolve their own tokens, so without a scheme on the
+ * region they would draw page-colored text on the black background.
  *
- * The chrome fades rather than leaves while the reader is still, because a bar
- * that is removed from the layout takes the picture's size with it and the
- * reader watches it jump every time they stop moving.
+ * When there is no input, the chrome fades out and keeps its place in the
+ * layout, so the picture does not change size.
  *
  * @since 0.100.0
  * @status stable
@@ -24,12 +21,12 @@ import type { CSSResultGroup } from 'lit';
  * @aliases Photo viewer, Image viewer, Gallery overlay
  * @documentation https://fusion.dev/helix/components/lightbox
  *
- * @event {HelixActivateEvent} helix-activate - Fired once the shown item has moved, so the element already holds it.
+ * @event {HelixActivateEvent} helix-activate - Fired after the shown item changes, when the element already holds the new item.
  *
- * @cssproperty --lightbox-foreground - Color of the chrome drawn over the content.
- * @cssproperty --lightbox-gap - Space between the chrome and the content.
+ * @cssproperty --lightbox-foreground - Color of the controls and text drawn over the content.
+ * @cssproperty --lightbox-gap - Space between the header or footer and the content.
  * @cssproperty --lightbox-padding - Inset from the edges of the screen.
- * @cssproperty --lightbox-scrim - The wash over the page behind the viewer. Set on the host, where a token still resolves: a `var()` written inside `::backdrop` cannot see one.
+ * @cssproperty --lightbox-scrim - The overlay color on the page behind the viewer. Set it on the host, because a `var()` inside `::backdrop` cannot resolve a token.
  */
 export declare class HelixLightbox extends HelixHeadlessLightbox {
     static styles: CSSResultGroup;

package/dist/line-chart/root/line-chart-root.d.ts

@@ -2,26 +2,24 @@ import { HelixHeadlessLineChart } from '@fusion.dev/helix-headless/line-chart';
 import type { CSSResultGroup } from 'lit';
 import '../../tooltip/index.js';
 /**
- * @summary A series over time as a line, read from a table.
+ * @summary A chart that draws series over time as lines, read from a table.
  *
  * @description
- * The lines take the series palette in order, so a chart of one is series one
- * and a chart of four is the first four, and a legend beside it maps the same
- * twenty-four.
+ * The lines take the series palette in order. A chart of one series uses series
+ * one, a chart of four uses the first four, and a legend beside it maps the
+ * same twenty-four.
  *
- * The stroke does not scale with the box. `preserveAspectRatio="none"` is what
- * lets one drawing fill a narrow card and a wide panel, and without
- * `vector-effect: non-scaling-stroke` the same line comes out hairline in the
- * first and heavy in the second. It rescues strokes and not geometry, which is
- * why nothing inside the drawing marks a reading: a circle in a stretched
- * coordinate space is an ellipse, and there is no vector-effect that answers
- * for a shape.
+ * The stroke width stays the same at any size. The drawing uses
+ * `preserveAspectRatio="none"` to fill a narrow card or a wide panel, and
+ * `vector-effect: non-scaling-stroke` keeps the line from turning hairline in
+ * one and heavy in the other. That applies to strokes only: a circle in the
+ * stretched drawing becomes an ellipse, so nothing inside the drawing marks a
+ * reading.
  *
- * **The last reading of each series is marked, and that is the same rule rather
- * than an exception to it.** `terminus` draws an HTML element placed over the
- * plot by percentage instead of a shape inside it, so it keeps its shape at any
- * width. It is on by default, as a dot, because the column of marks at the far
- * edge is where a reader looks for "and what is it now".
+ * `terminus` marks the last reading of each series with an HTML element placed
+ * over the plot by percentage, so it keeps its shape at any width. It is on by
+ * default, as a dot, because the far edge is where you look for the current
+ * value.
  *
  * @since 0.1.0
  * @status stable
@@ -30,21 +28,22 @@ import '../../tooltip/index.js';
  * @aliases Time Series, Trend Chart, Multi-line Chart
  * @documentation https://fusion.dev/helix/components/line-chart
  *
- * @cssproperty --chart-stroke - Thickness of a series drawn as a line, one name across this
+ * @cssproperty --chart-stroke - Thickness of a series drawn as a line. Line Chart, Area Chart's top edge, and Bar Chart's `lines` all read this one property. Each family's own width property overrides it.
  *   family, Area Chart's top edge and Bar Chart's `lines`, since the three read one shared
  *   rule. Each family's own width hook overrides it.
- * @cssproperty --chart-terminus-hole - A fill for the middle of a `ring` terminus, which is otherwise open. One name across this family and Sparkline, the two reading one shared sheet.
- * @cssproperty --chart-terminus-size - Size of the mark on each series' last reading. One name across this family and Sparkline, the two reading one shared sheet.
+ * @cssproperty --chart-terminus-hole - Fill for the middle of a `ring` terminus, which is otherwise open. Line Chart and Sparkline share this property.
+ * @cssproperty --chart-terminus-size - Size of the mark on each series' last reading. Line Chart and Sparkline share this property.
  * @cssproperty --line-chart-area-opacity - How much of a line's color its wash takes.
- * @cssproperty --line-chart-band-color - The slot the pointer is resting in.
+ * @cssproperty --line-chart-band-color - Color of the band around the reading under the pointer.
  * @cssproperty --line-chart-block-size - Height of the drawing.
  * @cssproperty --line-chart-gap - Space between the drawing and its labels.
- * @cssproperty --line-chart-gridline-color - One rule across the plot, under `gridlines`.
- * @cssproperty --line-chart-width - Thickness of a line, over `--chart-stroke`.
+ * @cssproperty --line-chart-gridline-color - Color of the rules drawn across the plot under `gridlines`.
+ * @cssproperty --line-chart-width - Thickness of a line. Overrides `--chart-stroke`.
  */
 export declare class HelixLineChart extends HelixHeadlessLineChart {
     /**
-     * **The styled tier, so the tooltip this renders is the styled one.**
+     * The tag prefix for child elements. Set to the styled tier, so the chart
+     * renders the styled tooltip.
      *
      * `tag()` builds a child's tag name from this prefix, and the base declares
      * `helix-headless-`. Every other styled component that renders a child
@@ -62,7 +61,7 @@ export declare class HelixLineChart extends HelixHeadlessLineChart {
      */
     static tier: string;
     /**
-     * How much ink the lines claim.
+     * How strongly the lines and their washes are drawn.
      *
      * `subtle` mixes each series toward the page, so a chart that is context stays
      * legible without competing. Toward the page rather than translucent, because a
@@ -83,7 +82,7 @@ export declare class HelixLineChart extends HelixHeadlessLineChart {
      */
     emphasis?: 'outlined' | 'solid' | 'subtle';
     /**
-     * What the lines are made of.
+     * How translucent the lines are, as a material: `glass` or `frosted`.
      *
      * `glass` lets the gridlines read through them, which is what translucency is
      * for on a chart rather than decoration.

package/dist/list/item/list-item.d.ts

@@ -4,21 +4,20 @@ import { type CSSResultGroup, type TemplateResult } from 'lit';
  * @summary One row of a list.
  *
  * @description
- * A grid rather than a flex row, so the supporting text lines up under the
- * label rather than under the leading icon. The leading and trailing regions
- * hold their own width and the middle takes the rest.
+ * Laid out as a grid, so supporting text lines up under the label. The leading
+ * and trailing regions keep their own width, and the middle takes the rest.
  *
  * @since 0.1.0
  * @status stable
  * @aliases Row, Entry
  * @documentation https://fusion.dev/helix/components/list
  *
- * @csspart rail - The cell a railed list draws its number in.
+ * @csspart rail - The cell that holds the number in a railed list.
  *
- * @cssproperty --list-item-padding - Padding inside the row.
- * @cssproperty --list-item-rail-content - What the rail cell shows. Written by the list.
- * @cssproperty --list-item-rail-display - Whether there is a rail at all. Written by the list.
- * @cssproperty --list-item-term-weight - Weight of a description list's term.
+ * @cssproperty --list-item-padding - The padding inside the row.
+ * @cssproperty --list-item-rail-content - What the rail cell shows. The list sets it.
+ * @cssproperty --list-item-rail-display - Whether the row has a rail. The list sets it.
+ * @cssproperty --list-item-term-weight - The font weight of a term in a description list.
  */
 export declare class HelixListItem extends HelixHeadlessListItem {
     static styles: CSSResultGroup;

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

@@ -1,13 +1,11 @@
 import { HelixHeadlessList } from '@fusion.dev/helix-headless/list';
 import type { CSSResultGroup } from 'lit';
 /**
- * @summary A set of rows, read as a set.
+ * @summary A set of rows, announced as a list.
  *
  * @description
- * Rules between rows rather than around each one, so a list reads as one object
- * with divisions instead of as a stack of cards. `divided` is off by default,
- * because space alone separates rows perfectly well and a rule at every seam is
- * decoration doing what emptiness already does.
+ * `divided` draws rules between rows, so the list reads as one object with
+ * divisions. It is off by default, and space alone separates the rows.
  *
  * @since 0.1.0
  * @status stable
@@ -15,14 +13,14 @@ import type { CSSResultGroup } from 'lit';
  * @aliases Rows, Stack, Menu
  * @documentation https://fusion.dev/helix/components/list
  *
- * @cssproperty --list-gap - Space between rows.
- * @cssproperty --list-marker-gutter - Room the ordered and unordered markers hang into.
+ * @cssproperty --list-gap - The space between rows.
+ * @cssproperty --list-marker-gutter - The space that the markers of ordered and unordered lists sit in.
  * @cssproperty --list-rail-inline-size - The width of the rail's track.
- * @cssproperty --list-rail-style - What a rail counts with. Any `list-style-type`.
+ * @cssproperty --list-rail-style - The counter style of the rail's numbers. Takes any `list-style-type`.
  */
 export declare class HelixList extends HelixHeadlessList {
     /**
-     * Whether a rule sits between rows.
+     * Draws a line between rows.
      */
     divided: boolean;
     /**