@fusion.dev/helix-headless 0.218.0 → 0.220.0

package/dist/menu/section/menu-section.d.ts

@@ -23,6 +23,10 @@ import { nothing, type PropertyValues, type TemplateResult } from 'lit';
  *
  * @csspart heading - The words that name the section.
  * @csspart section - The group that holds the heading and the rows.
+ *
+ * @cssstate start - A row in the section has content before its label, so
+ * every row in it keeps the leading column. The menu decides it for each
+ * section, apart from the rows outside one.
  */
 export declare class HelixHeadlessMenuSection extends HelixElement {
     /**
@@ -35,6 +39,11 @@ export declare class HelixHeadlessMenuSection extends HelixElement {
      * property, because the menu writes it after the section upgrades.
      */
     onPage: boolean;
+    /**
+     * @internal Set by the menu: whether a row in the section has content
+     * before its label, so the section's rows keep the leading column.
+     */
+    startColumn: boolean;
     /** @internal What a menu reads to tell a section from a row. */
     readonly isMenuSection = true;
     /**
@@ -44,6 +53,7 @@ export declare class HelixHeadlessMenuSection extends HelixElement {
      */
     private heading;
     protected willUpdate(changed: PropertyValues): void;
+    protected updated(changed: PropertyValues): void;
     protected firstUpdated(changed: PropertyValues): void;
     private readonly readHeading;
     protected render(): TemplateResult | typeof nothing;

package/dist/menu/section/menu-section.js

@@ -7,6 +7,7 @@ let HelixHeadlessMenuSection = class HelixHeadlessMenuSection extends HelixEleme
         super(...arguments);
         this.label = '';
         this.onPage = true;
+        this.startColumn = false;
         this.isMenuSection = true;
         this.heading = false;
         this.readHeading = (event) => {
@@ -19,6 +20,12 @@ let HelixHeadlessMenuSection = class HelixHeadlessMenuSection extends HelixEleme
             this.heading = this.knownChildren.some((child) => child.slot === 'heading');
         }
     }
+    updated(changed) {
+        super.updated(changed);
+        if (changed.has('startColumn')) {
+            this.toggleState('start', this.startColumn);
+        }
+    }
     firstUpdated(changed) {
         super.firstUpdated(changed);
         this.finishHydration();
@@ -46,6 +53,9 @@ __decorate([
 __decorate([
     property({ attribute: false })
 ], HelixHeadlessMenuSection.prototype, "onPage", void 0);
+__decorate([
+    property({ attribute: false })
+], HelixHeadlessMenuSection.prototype, "startColumn", void 0);
 __decorate([
     state()
 ], HelixHeadlessMenuSection.prototype, "heading", void 0);

package/dist/meter/index.d.ts

@@ -1 +1,2 @@
 export * from './root/meter-root.js';
+export * from './segment/meter-segment.js';

package/dist/meter/index.js

@@ -1 +1,2 @@
 export * from './root/meter-root.js';
+export * from './segment/meter-segment.js';

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

@@ -6,7 +6,9 @@ export type MeterBand = 'fair' | 'good' | 'poor';
  * @summary A measurement in a known range, with optional bands that mark it good, fair, or poor.
  *
  * @description
- * A meter shows a level within a range. Use `Progress` to show how far along a
+ * A meter shows a level within a range, or how the level divides: write
+ * `Meter.Segment` inside it for each part of the whole, and the meter measures
+ * their sum. Use `Progress` to show how far along a
  * task is. A progress bar starts empty and ends full, and full is always the
  * good end. For a meter, which end is good depends on what is measured. There
  * is no `indeterminate`, because a meter always has a value.
@@ -31,6 +33,7 @@ export type MeterBand = 'fair' | 'good' | 'poor';
  * @aliases Gauge, Level, Capacity
  * @documentation https://fusion.dev/helix/components/meter
  *
+ * @slot - `Meter.Segment` elements, one for each share of the whole, drawn in the bar.
  * @slot label - A visible label. Its words name the meter in place of `label`.
  *
  * @event {HelixBandEvent} helix-band - Fired when the reading moves into another band, with the band it is in now, or `''` where it is in none. Not sent on the first render, since a meter that arrives in a band has not moved.
@@ -50,6 +53,7 @@ export type MeterBand = 'fair' | 'good' | 'poor';
  * @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-span - How much the range holds, `max` less `min`, which a segment divides its own value by to find its width.
  * @cssproperty --meter-sweep - How much of the circle the arc covers, as a path length.
  *
  * @cssstate fair - The reading is in a band next to the good band.
@@ -225,6 +229,17 @@ export declare class HelixHeadlessMeter extends HelixElement {
      * an empty string for none, and undefined before the first update.
      */
     private lastBand;
+    /**
+     * The segments written inside, where they can be known: none on a server or
+     * while hydrating what one sent, so the first render is the server's, and
+     * every one once the page has them.
+     */
+    private get segments();
+    /**
+     * What the meter measures: the sum of its segments where it has any, and its
+     * own `value` where it has none, so the two can never disagree.
+     */
+    private get amount();
     /** The range, clamped so `max` is never at or below `min`. */
     private get span();
     /** The reading, pulled into the range. */

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

@@ -21,6 +21,19 @@ let HelixHeadlessMeter = class HelixHeadlessMeter extends HelixElement {
         };
     }
     static { this.words = 'helix-meter'; }
+    get segments() {
+        return this.knownChildren.filter((child) => child.localName.endsWith('meter-segment'));
+    }
+    get amount() {
+        const segments = this.segments;
+        if (segments.length === 0) {
+            return this.value;
+        }
+        return segments.reduce((sum, segment) => {
+            const share = Number(segment.value ?? segment.getAttribute('value'));
+            return Number.isFinite(share) && share > 0 ? sum + share : sum;
+        }, 0);
+    }
     get span() {
         const min = Number.isFinite(this.min) ? this.min : 0;
         const max = Number.isFinite(this.max) && this.max > min ? this.max : min + 1;
@@ -28,7 +41,7 @@ let HelixHeadlessMeter = class HelixHeadlessMeter extends HelixElement {
     }
     get reading() {
         const { max, min } = this.span;
-        return Math.min(max, Math.max(min, Number.isFinite(this.value) ? this.value : min));
+        return Math.min(max, Math.max(min, Number.isFinite(this.amount) ? this.amount : min));
     }
     get fraction() {
         const { max, min } = this.span;
@@ -36,12 +49,12 @@ let HelixHeadlessMeter = class HelixHeadlessMeter extends HelixElement {
     }
     get ratio() {
         const { max, min } = this.span;
-        const raw = Number.isFinite(this.value) ? this.value : min;
+        const raw = Number.isFinite(this.amount) ? this.amount : min;
         return (raw - min) / (max - min);
     }
     get beyond() {
         const { max, min } = this.span;
-        const raw = Number.isFinite(this.value) ? this.value : min;
+        const raw = Number.isFinite(this.amount) ? this.amount : min;
         return raw > max ? 'over' : raw < min ? 'under' : undefined;
     }
     get thresholds() {
@@ -69,7 +82,7 @@ let HelixHeadlessMeter = class HelixHeadlessMeter extends HelixElement {
     }
     get text() {
         return (this.valueText ||
-            readingText(Number.isFinite(this.value) ? this.value : this.span.min, this.ratio, wordsLocale(this), this.formatOptions));
+            readingText(Number.isFinite(this.amount) ? this.amount : this.span.min, this.ratio, wordsLocale(this), this.formatOptions));
     }
     willUpdate(changed) {
         super.willUpdate(changed);
@@ -134,17 +147,20 @@ let HelixHeadlessMeter = class HelixHeadlessMeter extends HelixElement {
         const at = (value) => `${((value - min) / (max - min)) * 100}%`;
         return html `<slot name="label" @slotchange=${this.renamed}></slot>${this.shape
             ? this.renderRound()
-            : html `<div part="track">
+            : html `<div part="track" style="--meter-span: ${max - min}">
+            <slot @slotchange=${this.renamed}></slot>
             ${bounds
                 ? html `<span part="tick" style="--meter-at: ${at(bounds.low)}"></span>
                     <span part="tick" style="--meter-at: ${at(bounds.high)}"></span>`
                 : nothing}
-            <div
-              part="indicator${band ? { fair: ' indicator-fair', good: ' indicator-good', poor: ' indicator-poor' }[band] : ''}${beyond ? { over: ' indicator-over', under: ' indicator-under' }[beyond] : ''}"
-              data-band=${band ?? nothing}
-              data-beyond=${beyond ?? nothing}
-              style="--meter-fraction: ${this.fraction}"
-            ></div>
+            ${this.segments.length > 0
+                ? nothing
+                : html `<div
+                    part="indicator${band ? { fair: ' indicator-fair', good: ' indicator-good', poor: ' indicator-poor' }[band] : ''}${beyond ? { over: ' indicator-over', under: ' indicator-under' }[beyond] : ''}"
+                    data-band=${band ?? nothing}
+                    data-beyond=${beyond ?? nothing}
+                    style="--meter-fraction: ${this.fraction}"
+                  ></div>`}
           </div>`}
       ${this.showValue ? html `<span part="value">${this.text}</span>` : nothing}${drawStatus(this.status)}`;
     }

package/dist/meter/segment/meter-segment.d.ts

@@ -0,0 +1,74 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type PropertyValues, type TemplateResult } from 'lit';
+/**
+ * @summary One share of a meter's whole, drawn as a slice of its bar.
+ *
+ * @description
+ * A segment says how much of the range one part of the whole takes, such as the
+ * tokens a model's context holds for its tools, against the tokens it holds for
+ * the conversation. Write one for each part inside a `Meter`.
+ *
+ * **The meter's reading is the sum of its segments.** `value` on the meter is
+ * ignored while it has any, so the two cannot disagree, and the bands, the ticks
+ * and the reading answer to the total. A segment is drawn as wide as its `value`
+ * is of the meter's range, so segments that add up to less than the range leave
+ * the rest of the track empty, and ones that add up to more are cut at the end.
+ *
+ * **A meter's children are presentational to a screen reader**, so a segment
+ * reaches no one that cannot see the bar. Say the breakdown in text beside it,
+ * such as a list with the name and the amount of each part, which is also where a
+ * reader finds the exact figures.
+ *
+ * A segment draws only in the bar. A meter in `ring` or `arc` draws its total.
+ *
+ * @since 0.1.0
+ * @status experimental
+ * @category feedback
+ * @documentation https://fusion.dev/helix/components/meter
+ *
+ * @slot - Nothing. A segment draws its share and has no content.
+ *
+ * @csspart fill - The slice of the bar the segment takes.
+ *
+ * @cssproperty --meter-segment-value - How much of the range the segment takes, in the meter's own units.
+ */
+export declare class HelixHeadlessMeterSegment extends HelixElement {
+    /**
+     * What the segment is, such as "Tools", which names the slice when a pointer
+     * rests on it.
+     *
+     * Not announced: see the note on a meter's children above.
+     */
+    label: string;
+    /**
+     * What the segment means, as it does on a callout. Takes the tone's color in
+     * place of the next color in the series.
+     */
+    tone?: 'accent' | 'danger' | 'info' | 'neutral' | 'primary' | 'success' | 'warning';
+    /**
+     * How much of the meter's range the segment takes, in the units of the meter's
+     * `min` and `max`.
+     *
+     * A value that is not a number, or is below zero, draws nothing.
+     */
+    value: number;
+    /** The meter this is a segment of, which reads its sum. */
+    private get meter();
+    /** The amount drawn: never below zero, and never a number that is not one. */
+    private get amount();
+    /**
+     * The meter sums its segments, so it hears when one arrives or changes. The
+     * segment is the one that knows, so it reaches up by identity and the meter
+     * does not have to ask. A meter's own update never updates a segment, so this
+     * cannot loop.
+     */
+    protected updated(changed: PropertyValues): void;
+    /** A segment taken out leaves the meter with a smaller sum, which it reads again. */
+    disconnectedCallback(): void;
+    protected render(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-meter-segment': HelixHeadlessMeterSegment;
+    }
+}

package/dist/meter/segment/meter-segment.js

@@ -0,0 +1,47 @@
+import { __decorate } from "tslib";
+import { closestInstance, customElement, HelixElement, numberConverter, } from '@fusion.dev/helix-core';
+import { html, nothing } from 'lit';
+import { property } from 'lit/decorators.js';
+import { HelixHeadlessMeter } from '../root/meter-root.js';
+let HelixHeadlessMeterSegment = class HelixHeadlessMeterSegment extends HelixElement {
+    constructor() {
+        super(...arguments);
+        this.label = '';
+        this.value = 0;
+    }
+    get meter() {
+        return closestInstance(this, HelixHeadlessMeter);
+    }
+    get amount() {
+        return Number.isFinite(this.value) && this.value > 0 ? this.value : 0;
+    }
+    updated(changed) {
+        super.updated(changed);
+        this.meter?.requestUpdate();
+    }
+    disconnectedCallback() {
+        const meter = this.meter;
+        super.disconnectedCallback();
+        queueMicrotask(() => meter?.requestUpdate());
+    }
+    render() {
+        return html `<span
+      part="fill"
+      title=${this.label || nothing}
+      style="--meter-segment-value: ${this.amount}"
+    ></span>`;
+    }
+};
+__decorate([
+    property()
+], HelixHeadlessMeterSegment.prototype, "label", void 0);
+__decorate([
+    property({ reflect: true })
+], HelixHeadlessMeterSegment.prototype, "tone", void 0);
+__decorate([
+    property({ converter: numberConverter('value', 0) })
+], HelixHeadlessMeterSegment.prototype, "value", void 0);
+HelixHeadlessMeterSegment = __decorate([
+    customElement('helix-headless-meter-segment')
+], HelixHeadlessMeterSegment);
+export { HelixHeadlessMeterSegment };

package/dist/scroll-area/root/scroll-area-root.d.ts

@@ -35,6 +35,11 @@ declare const EDGES: readonly ['block-start', 'block-end', 'inline-start', 'inli
  * scrollbar, the browser's or the component's, and clips what is past it.
  * Leave it unset to scroll both ways.
  *
+ * **A mask on the viewport also masks the browser's scrollbar.** While a
+ * scrollbar takes room beside the content, the viewport carries its size in
+ * `--scroll-area-gutter-inline-end` or `--scroll-area-gutter-block-end`, so a
+ * mask can leave that room opaque. The styled tier's fades use them.
+ *
  * The viewport's `scroll` and `scrollend` are sent again from the host, which
  * is the element you hold. A thumb dragged across the content sends one
  * `scrollend`, once it is let go. In React, bind them with `onScroll` and
@@ -56,7 +61,7 @@ declare const EDGES: readonly ['block-start', 'block-end', 'inline-start', 'inli
  * @event {Event} scrollend - The content stopped scrolling. Sent from the host, as `scroll` is, and once for a thumb dragged across the content. Does not bubble.
  *
  * @csspart corner - The square where the two scrollbars meet, under `scrollbars`. Hidden unless both are drawn.
- * @csspart edges - The layer that draws the cues on the inline start and end edges.
+ * @csspart edges - The layer over the viewport. The styled tier draws the focus ring on it, and the painted fades at the inline start and end.
  * @csspart scrollbar - Each scrollbar, under `scrollbars`. Hidden on an axis that has none.
  * @csspart scrollbar-horizontal - The scrollbar along the inline axis, alongside `scrollbar`.
  * @csspart scrollbar-vertical - The scrollbar along the block axis, alongside `scrollbar`.
@@ -66,6 +71,8 @@ declare const EDGES: readonly ['block-start', 'block-end', 'inline-start', 'inli
  * @csspart thumb-vertical - The thumb of the vertical scrollbar, alongside `thumb`.
  * @csspart viewport - The scrolling box.
  *
+ * @cssproperty --scroll-area-gutter-block-end - The room the browser's horizontal scrollbar takes at the block end of the viewport, in pixels. Written on the `viewport` part while that scrollbar takes room, and absent while it draws over the content.
+ * @cssproperty --scroll-area-gutter-inline-end - The room the browser's vertical scrollbar takes at the inline end of the viewport, in pixels. Written on the `viewport` part while that scrollbar takes room, and absent while it draws over the content.
  * @cssproperty --scroll-area-scroll-fraction - How far along its axis the content is scrolled, from 0 at the start to 1 at the end. Written on each `scrollbar` part, so its thumb inherits it. Counted from the right on a right-to-left page.
  * @cssproperty --scroll-area-thumb-fraction - The share of the track the thumb covers, from 0 to 1, which is how much of the content is in view. Written on each `scrollbar` part.
  *
@@ -119,6 +126,12 @@ export declare class HelixHeadlessScrollArea extends HelixElement {
      * Whether there is anything to scroll at all, which decides the tab stop.
      */
     private scrolls;
+    /**
+     * The room the browser's own scrollbars take, in pixels: the vertical one at
+     * the inline end, and the horizontal one at the block end. Zero where they are
+     * drawn over the content.
+     */
+    private gutter;
     private watcher;
     /**
      * The element that scrolls. Use it to scroll the content from your code.
@@ -154,8 +167,12 @@ export declare class HelixHeadlessScrollArea extends HelixElement {
     private watchContent;
     protected updated(changed: PropertyValues): void;
     private readonly handleSlotChange;
-    /** The axis `orientation` takes away, clipped where the content would overflow it. */
-    private get clipped();
+    /**
+     * The viewport's inline style: the axis `orientation` takes away, clipped
+     * where the content would overflow it, and the room each of the browser's
+     * scrollbars takes.
+     */
+    private get viewportStyle();
     protected render(): TemplateResult;
     /**
      * The scrollbars, the thumbs in them and the corner.

package/dist/scroll-area/root/scroll-area-root.js

@@ -17,6 +17,7 @@ let HelixHeadlessScrollArea = class HelixHeadlessScrollArea extends HelixElement
         });
         this.more = [];
         this.scrolls = false;
+        this.gutter = { blockEnd: 0, inlineEnd: 0 };
         this.measure = () => {
             const box = this.scroller;
             if (!box) {
@@ -43,6 +44,11 @@ let HelixHeadlessScrollArea = class HelixHeadlessScrollArea extends HelixElement
             this.scrolls =
                 (block && box.scrollHeight > box.clientHeight) ||
                     (inline && box.scrollWidth > box.clientWidth);
+            const blockEnd = Math.max(0, box.offsetHeight - box.clientHeight);
+            const inlineEnd = Math.max(0, box.offsetWidth - box.clientWidth);
+            if (blockEnd !== this.gutter.blockEnd || inlineEnd !== this.gutter.inlineEnd) {
+                this.gutter = { blockEnd, inlineEnd };
+            }
             if (this.scrollbars) {
                 this.bars.read(box);
             }
@@ -118,17 +124,27 @@ let HelixHeadlessScrollArea = class HelixHeadlessScrollArea extends HelixElement
         this.toggleState('scrollbar-horizontal', drawn?.horizontal.drawn === true);
         this.toggleState('scrollbar-vertical', drawn?.vertical.drawn === true);
     }
-    get clipped() {
+    get viewportStyle() {
+        const rules = [];
         if (this.orientation === 'vertical') {
-            return 'overflow-x: hidden';
+            rules.push('overflow-x: hidden');
+        }
+        else if (this.orientation === 'horizontal') {
+            rules.push('overflow-y: hidden');
+        }
+        if (this.gutter.blockEnd > 0) {
+            rules.push(`--scroll-area-gutter-block-end: ${this.gutter.blockEnd}px`);
         }
-        return this.orientation === 'horizontal' ? 'overflow-y: hidden' : nothing;
+        if (this.gutter.inlineEnd > 0) {
+            rules.push(`--scroll-area-gutter-inline-end: ${this.gutter.inlineEnd}px`);
+        }
+        return rules.length > 0 ? rules.join('; ') : nothing;
     }
     render() {
         return html `<div
       data-scroller
       part="viewport"
-      style=${this.clipped}
+      style=${this.viewportStyle}
       role=${this.label ? 'region' : nothing}
       aria-label=${this.label || nothing}
       tabindex=${this.scrolls ? '0' : nothing}
@@ -211,6 +227,9 @@ __decorate([
 __decorate([
     state()
 ], HelixHeadlessScrollArea.prototype, "scrolls", void 0);
+__decorate([
+    state()
+], HelixHeadlessScrollArea.prototype, "gutter", void 0);
 HelixHeadlessScrollArea = __decorate([
     customElement('helix-headless-scroll-area')
 ], HelixHeadlessScrollArea);

package/dist/spatial-bar-chart/bars.d.ts

@@ -15,12 +15,21 @@ export interface BarCell {
     across: number;
     /** The column of the row the value was read from, which names its series. */
     column: number;
-    /** Which series it stands in, counting from zero. */
+    /** Which series it stands in, counting from zero, which colors it. */
     depth: number;
+    /**
+     * Where its block starts on the value axis: zero, or under `stacked` the
+     * readings of the series before it in its category, on its side of zero.
+     */
+    from: number;
     /** The row's own label, which names its category. */
     label: string;
+    /** Which row of the grid in depth it stands in: its series, or the one row of a stacked chart. */
+    lane: number;
     /** The row it was read from, counting from zero. */
     row: number;
+    /** The tone the cell names with `data-tone`, which colors its own bar, where it names one. */
+    tone?: string | undefined;
     /** The value, where the cell holds a number. */
     value?: number | undefined;
 }
@@ -44,10 +53,20 @@ export interface BarField {
      * series `depth` is at `across * series.length + depth`.
      */
     cells: BarCell[];
+    /** How many rows of bars stand in depth: one a series, or one in all when stacked. */
+    lanes: number;
     /** How many cells hold a value. */
     readings: number;
+    /**
+     * How far a `diagonal` row climbs on the page for each step across, where
+     * it climbs less than Switchyard's 15 for every 72: a long row in a short
+     * plot, whose climb would leave its bars no height.
+     */
+    climb?: number;
     /** Every series, in the table's order: each numeric column's heading. */
     series: string[];
+    /** Whether a category's series stand in one column, each on the ones before it. */
+    stacked: boolean;
 }
 /**
  * Reads the table as a bar chart does: **each row is a category, named by
@@ -59,10 +78,46 @@ export interface BarField {
  * **The value axis runs from zero**, whatever the values, so a bar's height
  * is its value: one twice as tall is twice as much. It widens to round
  * numbers past the highest value, and below zero where a value is negative.
+ *
+ * **`stacked` stands a category's series in one column**, each block on the
+ * ones before it, so the column is as tall as the category's total and the
+ * axis runs to the tallest total. A negative reading hangs below zero on the
+ * negatives before it, as a flat chart's stack does.
+ *
+ * `toneOf` gives the tone a cell names, by its row and its series.
+ */
+export declare const barsOf: (rows: readonly FieldRow[], columns: readonly number[], stacked?: boolean, toneOf?: (row: number, depth: number) => string | undefined) => BarField;
+/**
+ * How the bars stand: on the box's grid, in a row level across the page, or
+ * in a row that climbs to the right as it recedes.
  */
-export declare const barsOf: (rows: readonly FieldRow[], columns: readonly number[]) => BarField;
+export type BarLayout = 'diagonal' | 'grid' | 'row';
+/**
+ * How many categories a row has room for across `width` pixels with each bar
+ * `size` pixels wide: a bar covers `FOOTPRINT` of its place, so a place is
+ * that much wider than its bar. At least one.
+ */
+export declare const rowFits: (width: number, size: number) => number;
+/** How wide a bar is on the page, in the drawing's units. */
+export declare const widthOf: (bar: DrawnBar) => number;
+/**
+ * The field with its `diagonal` row climbing at most `rise` on the page over
+ * `length` across, so a long row keeps the height its bars need.
+ */
+export declare const climbing: (field: BarField, rise: number, length: number) => BarField;
+/**
+ * The most times taller a row's value axis may stand than it is drawn in
+ * `bars`, so the tallest bar is no taller than `ROW_TALL` times the row's
+ * length: each of its places is a bar's width over `FOOTPRINT`, the width
+ * `widthOf` gives on the page.
+ */
+export declare const tallestTimes: (field: BarField, projection: Projection, bars: readonly DrawnBar[]) => number;
+/** The field with its value axis `times` as tall, which stands every bar that much taller. */
+export declare const heightened: (field: BarField, times: number) => BarField;
 /** A bar as the chart's own drawing paints it. */
 export interface DrawnBar {
+    /** Where the block starts on the floor's way up, in the box's units. */
+    base: number;
     /** The block's eight corners on the page, which a drawing with no box is framed around. */
     corners: PagePoint[];
     drawn: Drawn;
@@ -73,7 +128,72 @@ export interface DrawnBar {
 }
 /**
  * Each bar with a value as a block, seen through `projection`: standing on
- * its place on the grid, from zero to its value, a little narrower than its
- * place so neighbors stand apart. A value below zero hangs from zero.
+ * its place on the grid, from where it starts to its value, a little
+ * narrower than its place so neighbors stand apart. A value below zero
+ * hangs from where it starts.
+ *
+ * **`row` lays the categories in a straight line across the page**, along
+ * the way the camera reads as level, and the series straight back from it,
+ * so the row stays level whichever way the camera turns, and each block,
+ * which keeps to the floor's grid, shows the turn: its top and two sides.
+ * Turned, a block is wider on the page than its footprint, so the footprint
+ * narrows by as much, and neighbors still stand apart. **`diagonal` lays the
+ * same row climbing to the right**, each place a step further back than the
+ * one before, at the same climb on the page from any turn.
+ *
+ * `grown` says how much of its height each bar has reached, from 0 to 1, as
+ * the chart grows its bars in.
+ */
+export declare const barsDrawn: (field: BarField, projection: Projection, layout?: BarLayout, grown?: (cell: BarCell) => number) => DrawnBar[];
+/**
+ * The bars in the order they are painted, back to front, and **a stacked
+ * column from the floor up**: its blocks share a place on the floor, which
+ * the order by depth cannot tell apart, and one painted under the block below
+ * it would show the lower block's top through the upper one.
+ */
+export declare const paintOrder: (projection: Projection, bars: readonly DrawnBar[]) => DrawnBar[];
+/** One place on the floor of a row, under a bar or where a bar would stand. */
+export interface FloorPlate {
+    /** Which category it stands under, counting from zero. */
+    across: number;
+    /** Its four corners on the page. */
+    corners: PagePoint[];
+    /** Its outline, as path data. */
+    d: string;
+    /** Its corner lowest on the page, nearest the reader, which its name is written under. */
+    front: PagePoint;
+}
+/**
+ * The places on the floor of a row, one for each category in each lane,
+ * whether a bar stands there or not: a square a little wider than a bar's
+ * footprint, turned as the bars are, where zero stands on the value axis,
+ * along the row `layout` lays.
+ */
+export declare const floorOf: (field: BarField, projection: Projection, layout?: Exclude<BarLayout, 'grid'>) => FloorPlate[];
+/** A category's name written under its place in a row. */
+export interface RowName {
+    across: number;
+    text: string;
+    /** Whether a bar of its category names a tone, which colors the name. */
+    tone?: string | undefined;
+    x: number;
+    /** The middle of the line of text. */
+    y: number;
+}
+/**
+ * The names written under a row's plates, `size` tall: each category's name
+ * under its plate nearest the reader, **and only the names that fit**, so
+ * none overlaps another. A name whose bar names a tone is written first,
+ * then every other name, or every second, third, and so on, at the smallest
+ * even step that fits, leaving out a name the toned one covers.
+ */
+export declare const namesOf: (field: BarField, plates: readonly FloorPlate[], size: number) => RowName[];
+/**
+ * How much of its height a bar of category `across` has reached `elapsed`
+ * milliseconds after the bars began to grow in, from 0 to 1. **In reading
+ * order**, each category a little after the one before it, and fast at first
+ * and slow to rest, never past its value.
  */
-export declare const barsDrawn: (field: BarField, projection: Projection) => DrawnBar[];
+export declare const grownAt: (across: number, categories: number, elapsed: number) => number;
+/** How long the bars of `categories` take to grow in, the last one included, in milliseconds. */
+export declare const growTime: (categories: number) => number;