@fusion.dev/helix-headless 0.197.1 → 0.199.0

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

@@ -115,6 +115,12 @@ export declare class HelixHeadlessCarousel extends HelixElement {
     static shadowRootOptions: ShadowRootInit;
     /**
      * Whether the carousel advances on its own.
+     *
+     * **Not where the reader asked for less motion**, or where the page has
+     * paused its motion, through `pauseMotion` or `Motion Toggle`: the carousel
+     * starts still, and its rotation control starts it. A page that pauses its
+     * motion later stops the rotation, and one that lets it run again starts it
+     * again, unless the reader stopped it.
      */
     autoplay: boolean;
     /**
@@ -741,6 +747,14 @@ export declare class HelixHeadlessCarousel extends HelixElement {
     disconnectedCallback(): void;
     /** Pauses without forgetting that the reader wanted it running. */
     private readonly pause;
+    /** What stops hearing the page's pause. */
+    private unpaused;
+    /**
+     * The page paused its motion, which pauses the rotation, or let it run
+     * again, which starts it again where it was asked for and the reader has
+     * not stopped it.
+     */
+    private readonly handlePageMotion;
     protected willUpdate(changed: PropertyValues): void;
     protected firstUpdated(changed: PropertyValues): void;
     protected updated(changed: PropertyValues): void;

package/dist/carousel/root/carousel-root.js

@@ -1,5 +1,5 @@
 import { __decorate } from "tslib";
-import { ChildrenController, capturePointer, customElement, formatWords, HelixActivateEvent, HelixElement, HelixSelectEvent, hostAria, inlineStep, isRtl, MIRROR_RULE, requestChange, SCROLLER_RULE, words, } from '@fusion.dev/helix-core';
+import { ChildrenController, capturePointer, customElement, formatWords, HelixActivateEvent, HelixElement, HelixSelectEvent, hostAria, inlineStep, isRtl, MIRROR_RULE, motionPaused, onMotionChange, reducedMotion, requestChange, SCROLLER_RULE, words, } from '@fusion.dev/helix-core';
 import { caretLeft, caretRight, play, stop } from '@fusion.dev/helix-icons';
 import { html, nothing } from 'lit';
 import { property, state } from 'lit/decorators.js';
@@ -186,6 +186,14 @@ let HelixHeadlessCarousel = class HelixHeadlessCarousel extends HelixElement {
                 this.rotating = false;
             }
         };
+        this.handlePageMotion = (paused) => {
+            if (paused) {
+                this.pause();
+            }
+            else if (this.autoplay && !this.stopped) {
+                this.rotating = true;
+            }
+        };
     }
     static { this.markRules = [SCROLLER_RULE, MIRROR_RULE]; }
     static { this.words = 'helix-carousel'; }
@@ -385,6 +393,7 @@ let HelixHeadlessCarousel = class HelixHeadlessCarousel extends HelixElement {
         super.connectedCallback();
         this.addEventListener('focusin', this.pause);
         this.addEventListener('pointerenter', this.pause);
+        this.unpaused ??= onMotionChange(this.handlePageMotion);
         this.watchPane();
         if (this.hasUpdated) {
             this.runTimer();
@@ -398,6 +407,8 @@ let HelixHeadlessCarousel = class HelixHeadlessCarousel extends HelixElement {
         }
         this.removeEventListener('focusin', this.pause);
         this.removeEventListener('pointerenter', this.pause);
+        this.unpaused?.();
+        this.unpaused = undefined;
         this.sizes?.disconnect();
         this.sizes = undefined;
         this.watched = undefined;
@@ -428,6 +439,9 @@ let HelixHeadlessCarousel = class HelixHeadlessCarousel extends HelixElement {
         super.firstUpdated(changed);
         this.watchPane();
         this.finishHydration();
+        if (this.rotating && (reducedMotion() || motionPaused())) {
+            this.rotating = false;
+        }
     }
     updated(changed) {
         super.updated(changed);

package/dist/element-events.generated.js

@@ -212,6 +212,7 @@ registerElementEvents({
     ],
     'helix-headless-menu-item': ['helix-before-toggle', 'helix-select'],
     'helix-headless-meter': ['helix-band'],
+    'helix-headless-motion-toggle': ['change'],
     'helix-headless-notification': ['helix-dismiss', 'helix-read'],
     'helix-headless-notification-group': ['helix-before-close', 'helix-before-open', 'toggle'],
     'helix-headless-notifications': ['helix-dismiss', 'helix-load-more', 'helix-read'],
@@ -257,6 +258,12 @@ registerElementEvents({
     ],
     'helix-headless-slider': ['change', 'helix-before-change', 'input'],
     'helix-headless-sparkline': ['helix-reading-change', 'helix-reading-press'],
+    'helix-headless-spatial-bar-chart': [
+        'helix-plot-change',
+        'helix-plot-turn',
+        'helix-reading-change',
+        'helix-reading-press',
+    ],
     'helix-headless-spatial-heatmap': [
         'change',
         'helix-before-change',
@@ -266,6 +273,12 @@ registerElementEvents({
         'helix-reading-press',
         'helix-resize',
     ],
+    'helix-headless-spatial-ribbon-chart': [
+        'helix-plot-change',
+        'helix-plot-turn',
+        'helix-reading-change',
+        'helix-reading-press',
+    ],
     'helix-headless-spatial-scatter-chart': [
         'helix-plot-change',
         'helix-plot-turn',
@@ -278,6 +291,12 @@ registerElementEvents({
         'helix-reading-change',
         'helix-reading-press',
     ],
+    'helix-headless-spatial-treemap': [
+        'helix-plot-change',
+        'helix-plot-turn',
+        'helix-reading-change',
+        'helix-reading-press',
+    ],
     'helix-headless-speed-dial': [
         'helix-before-close',
         'helix-before-open',

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

@@ -118,7 +118,9 @@ declare const HelixHeadlessGraph_base: (new (...args: any[]) => import("@fusion.
  * @csspart region - The frame: the drawing, its controls and the list.
  * @csspart search - The bar holding the icon, the search field and the count.
  * @csspart search-field - The field that finds a note by its name.
+ * @csspart settling - What is said while a layout runs unseen, where the reader asked for less motion or the page paused its motion, over the hidden drawing.
  * @csspart stage - The drawing and its controls.
+ * @csspart stop-layout - The button that stops a layout that has run past five seconds, where the notes stand.
  * @csspart viewport - The box the renderer draws in.
  * @csspart zoom-in - The zoom in button.
  * @csspart zoom-out - The zoom out button.
@@ -132,6 +134,8 @@ declare const HelixHeadlessGraph_base: (new (...args: any[]) => import("@fusion.
  * @cssstate ready - The graph has been drawn whole, after `helix-graph-ready`.
  * @cssstate searching - The search field holds words, and the list holds only the notes they find.
  * @cssstate selected - A note is selected, in the list or in the drawing.
+ * @cssstate settling - A layout is running.
+ * @cssstate settling-unseen - A layout is running with the drawing hidden, where the reader asked for less motion or the page paused its motion.
  * @cssstate sharing - The page keeps the plain wheel and one finger, with `gestures="cooperative"` or while a graph with `gestures="activate"` waits to be pressed.
  * @cssstate using - A graph with `gestures="activate"` has been pressed and has the gestures.
  */
@@ -253,6 +257,13 @@ export declare class HelixHeadlessGraph extends HelixHeadlessGraph_base {
      * the list then holds, written with `count-label`.
      */
     selectionLabel: string;
+    /**
+     * What the `settling` part says while a layout runs unseen, where the reader
+     * asked for less motion or the page paused its motion.
+     */
+    settlingLabel: string;
+    /** What the button that stops a long layout says. */
+    stopLayoutLabel: string;
     /** The hint shown when one finger swipes over the graph with `gestures="cooperative"`. */
     twoFingerHintLabel: string;
     /** The line shown while the graph, with `gestures="activate"`, has the gestures. */
@@ -287,6 +298,12 @@ export declare class HelixHeadlessGraph extends HelixHeadlessGraph_base {
     private fieldKeys;
     /** Whether the list has the focus, so the drawing marks the note its keys are on. */
     private listKeys;
+    /** The layout running, what stops it, and whether it is shown, while one runs. */
+    private layout;
+    /** Whether the layout has run long enough to offer the button that stops it. */
+    private stoppable;
+    /** What offers the stop once the layout has run five seconds. */
+    private stopping;
     /**
      * The notes a walk along the links stepped from, by `id`, the last the one
      * the note the keys are on was reached from. Empty when the keys moved some
@@ -374,6 +391,22 @@ export declare class HelixHeadlessGraph extends HelixHeadlessGraph_base {
         y: number;
         z?: number | undefined;
     }>): void;
+    /**
+     * Says a layout is running, with what ends it where the notes stand, or
+     * with nothing, that it has ended. Called by `connectGraph`.
+     *
+     * **A layout that runs past five seconds offers a button that stops it**,
+     * the `stop-layout` part, as WCAG 2.2.2 asks of motion that starts by itself
+     * and runs that long. **`unseen` hides the drawing while the notes move**,
+     * which the connector asks for where the reader asked for less motion or
+     * the page paused its motion: the `settling` part says the notes are being
+     * placed, and the drawing shows them where they settle.
+     */
+    settling(stop?: () => void, unseen?: boolean): void;
+    /** The stop button ends the layout where the notes stand. */
+    private readonly handleStopLayout;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
     /**
      * Shows something passing from one note to another, such as a message, a
      * request or a payment, drawn traveling along the drawing and arriving with

package/dist/graph/root/graph-root.js

@@ -6,6 +6,7 @@ import { property, state } from 'lit/decorators.js';
 import { repeat } from 'lit/directives/repeat.js';
 import { unsafeSVG } from 'lit/directives/unsafe-svg.js';
 import { adjacencyOf, cursorAfter, entriesOf, groupsOf, nameOf, sortedOf, within, withoutGroups, } from './graph-model.js';
+const LONG_LAYOUT = 5000;
 let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinControllerActive(HelixElement)) {
     constructor() {
         super(...arguments);
@@ -36,6 +37,8 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
         this.searchLabel = 'Find a note';
         this.selectedLabel = 'Selected';
         this.selectionLabel = '{note}, selected. {count}';
+        this.settlingLabel = 'Placing the notes';
+        this.stopLayoutLabel = 'Stop the layout';
         this.twoFingerHintLabel = 'Use two fingers to move the graph';
         this.usingLabel = 'Using the graph. Press Escape to scroll the page again.';
         this.walkLabel = '{note}. {relation}. {index} of {count}';
@@ -47,6 +50,7 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
         this.panelOpen = false;
         this.fieldKeys = false;
         this.listKeys = false;
+        this.stoppable = false;
         this.trail = [];
         this.adjacency = new Map();
         this.sorted = [];
@@ -73,6 +77,11 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
                 index: Number(element.dataset.index),
             })),
         });
+        this.handleStopLayout = () => {
+            const stop = this.layout?.stop;
+            this.settling();
+            stop?.();
+        };
         this.handleListKeydown = (event) => {
             if (this.walk(event)) {
                 return;
@@ -190,6 +199,32 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
     laidOut(positions) {
         this.dispatchEvent(new HelixGraphLayoutEvent({ positions }));
     }
+    settling(stop, unseen = false) {
+        clearTimeout(this.stopping);
+        this.stopping = undefined;
+        this.stoppable = false;
+        this.layout = stop ? { stop, unseen } : undefined;
+        this.toggleState('settling', stop !== undefined);
+        this.toggleState('settling-unseen', stop !== undefined && unseen);
+        if (stop) {
+            this.stopping = setTimeout(() => {
+                this.stoppable = true;
+            }, LONG_LAYOUT);
+        }
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        if (this.layout && !this.stoppable && this.stopping === undefined) {
+            this.stopping = setTimeout(() => {
+                this.stoppable = true;
+            }, LONG_LAYOUT);
+        }
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        clearTimeout(this.stopping);
+        this.stopping = undefined;
+    }
     signal(from, to, options = {}) {
         this.dispatchEvent(new HelixGraphSignalEvent({ from, to, tone: options.tone }));
     }
@@ -606,6 +641,14 @@ let HelixHeadlessGraph = class HelixHeadlessGraph extends MixinViewport(MixinCon
           <div part="viewport">
             <slot></slot>
             ${this.renderGestures()}
+            ${this.layout?.unseen
+            ? html `<div part="settling" role="status">${this.settlingLabel}</div>`
+            : nothing}
+            ${this.stoppable
+            ? html `<button part="stop-layout" type="button" @click=${this.handleStopLayout}>
+                    ${this.stopLayoutLabel}
+                  </button>`
+            : nothing}
           </div>
           ${this.renderControls()} ${this.renderLegend()}
         </div>
@@ -780,6 +823,14 @@ __decorate([
     words,
     property({ attribute: 'selection-label' })
 ], HelixHeadlessGraph.prototype, "selectionLabel", void 0);
+__decorate([
+    words,
+    property({ attribute: 'settling-label' })
+], HelixHeadlessGraph.prototype, "settlingLabel", void 0);
+__decorate([
+    words,
+    property({ attribute: 'stop-layout-label' })
+], HelixHeadlessGraph.prototype, "stopLayoutLabel", void 0);
 __decorate([
     words,
     property({ attribute: 'two-finger-hint-label' })
@@ -819,6 +870,12 @@ __decorate([
 __decorate([
     state()
 ], HelixHeadlessGraph.prototype, "listKeys", void 0);
+__decorate([
+    state()
+], HelixHeadlessGraph.prototype, "layout", void 0);
+__decorate([
+    state()
+], HelixHeadlessGraph.prototype, "stoppable", void 0);
 __decorate([
     state()
 ], HelixHeadlessGraph.prototype, "said", void 0);

package/dist/index.d.ts

@@ -66,6 +66,7 @@ export * from './megamenu/index.js';
 export * from './menu/filter/index.js';
 export * from './menu/index.js';
 export * from './meter/index.js';
+export * from './motion-toggle/index.js';
 export * from './navigation/index.js';
 export * from './notifications/index.js';
 export * from './number-input/index.js';
@@ -87,9 +88,12 @@ export * from './skeleton/index.js';
 export * from './skip-link/index.js';
 export * from './slider/index.js';
 export * from './sparkline/index.js';
+export * from './spatial-bar-chart/index.js';
 export * from './spatial-heatmap/index.js';
+export * from './spatial-ribbon-chart/index.js';
 export * from './spatial-scatter-chart/index.js';
 export * from './spatial-surface-chart/index.js';
+export * from './spatial-treemap/index.js';
 export * from './speed-dial/index.js';
 export * from './splitter/index.js';
 export * from './stat/index.js';

package/dist/index.js

@@ -57,6 +57,7 @@ export * from './megamenu/index.js';
 export * from './menu/filter/index.js';
 export * from './menu/index.js';
 export * from './meter/index.js';
+export * from './motion-toggle/index.js';
 export * from './navigation/index.js';
 export * from './notifications/index.js';
 export * from './number-input/index.js';
@@ -78,9 +79,12 @@ export * from './skeleton/index.js';
 export * from './skip-link/index.js';
 export * from './slider/index.js';
 export * from './sparkline/index.js';
+export * from './spatial-bar-chart/index.js';
 export * from './spatial-heatmap/index.js';
+export * from './spatial-ribbon-chart/index.js';
 export * from './spatial-scatter-chart/index.js';
 export * from './spatial-surface-chart/index.js';
+export * from './spatial-treemap/index.js';
 export * from './speed-dial/index.js';
 export * from './splitter/index.js';
 export * from './stat/index.js';

package/dist/map/raster/map-raster.d.ts

@@ -13,9 +13,11 @@ import { nothing, type PropertyValues } from 'lit';
  * While `playing` is set, the layer shows the frames in order, `interval`
  * milliseconds each, and starts again from the first.
  *
- * The frames do not play while the user has asked for reduced motion, and the
- * layer shows its last frame. Content that moves for more than five seconds
- * needs a way to pause it, so give `playing` a control on your page.
+ * The frames do not play while the user has asked for reduced motion, or
+ * while the page has paused its motion, through `pauseMotion` or `Motion
+ * Toggle`, and the layer holds the frame it shows. Content that moves for more
+ * than five seconds needs a way to pause it, which `Motion Toggle` gives the
+ * whole page, or give `playing` a control of its own.
  *
  * Put the tile provider's credit in `attribution`. The frame shows it beside
  * the map's own credit.
@@ -79,6 +81,8 @@ export declare class HelixHeadlessMapRaster extends HelixElement {
     private timer;
     connectedCallback(): void;
     disconnectedCallback(): void;
+    /** What stops hearing the page's pause, which stops the frames and starts them again. */
+    private unpaused;
     private stopTimer;
     /** Starts or stops the timer when the frames, the interval, or `playing` change. */
     private schedule;

package/dist/map/raster/map-raster.js

@@ -1,5 +1,5 @@
 import { __decorate } from "tslib";
-import { customElement, HelixElement, HelixMapPartChangeEvent, words } from '@fusion.dev/helix-core';
+import { customElement, HelixElement, HelixMapPartChangeEvent, motionPaused, onMotionChange, reducedMotion, words, } from '@fusion.dev/helix-core';
 import { nothing } from 'lit';
 import { property } from 'lit/decorators.js';
 const framesConverter = {
@@ -20,12 +20,15 @@ let HelixHeadlessMapRaster = class HelixHeadlessMapRaster extends HelixElement {
     static { this.words = 'helix-map-raster'; }
     connectedCallback() {
         super.connectedCallback();
+        this.unpaused ??= onMotionChange(() => this.schedule());
         if (this.hasUpdated) {
             this.schedule();
         }
     }
     disconnectedCallback() {
         super.disconnectedCallback();
+        this.unpaused?.();
+        this.unpaused = undefined;
         this.stopTimer();
     }
     stopTimer() {
@@ -37,8 +40,7 @@ let HelixHeadlessMapRaster = class HelixHeadlessMapRaster extends HelixElement {
     schedule() {
         this.stopTimer();
         const count = this.frames?.length ?? 0;
-        const reduced = globalThis.matchMedia?.('(prefers-reduced-motion: reduce)').matches ?? false;
-        if (!this.playing || count < 2 || reduced) {
+        if (!this.playing || count < 2 || reducedMotion() || motionPaused()) {
             return;
         }
         this.timer = setInterval(() => {

package/dist/motion-toggle/index.d.ts

@@ -0,0 +1 @@
+export { HelixHeadlessMotionToggle } from './root/motion-toggle-root.js';

package/dist/motion-toggle/index.js

@@ -0,0 +1 @@
+export { HelixHeadlessMotionToggle } from './root/motion-toggle-root.js';

package/dist/motion-toggle/root/motion-toggle-root.d.ts

@@ -0,0 +1,77 @@
+import { HelixElement } from '@fusion.dev/helix-core';
+import { type TemplateResult } from 'lit';
+/**
+ * @summary A button that pauses every motion on the page that starts by itself, and lets it run again.
+ *
+ * @description
+ * WCAG 2.2.2 asks that motion which starts by itself and runs longer than
+ * five seconds can be paused. **This is one control for the whole page**: a
+ * press pauses every Helix component that moves by itself, and another lets
+ * them run again.
+ *
+ * - `Carousel` stops rotating under `autoplay`.
+ * - `Video` pauses a video that started itself under `autoplay`.
+ * - `Aura`, `Orb`, and `Strands` hold the frame they show.
+ * - A graph that `connectGraph` lays out stops where its notes stand, and its
+ *   three.js view stops turning.
+ * - A map layer's `frames` stop on the frame they show.
+ *
+ * **The choice is the page's**, held on the document element as
+ * `data-helix-motion="paused"`, so two of these on one page agree, and a page
+ * can set it in its markup or with `pauseMotion` from
+ * `@fusion.dev/helix-core`. A stylesheet can select on the attribute to
+ * pause motion of its own.
+ *
+ * It is a toggle button: a `<button>` that says whether motion is paused with
+ * `aria-pressed`. It keeps one name, `label`, whichever way it stands, as a
+ * toggle button does, and its icon shows what a press does next.
+ *
+ * Put it where a reader looks first, such as the page's header. Where the
+ * reader asked for reduced motion, nothing moves by itself to begin with.
+ *
+ * @since 0.199.0
+ * @status experimental
+ * @category actions
+ * @aliases Pause button, Pause animations, Stop motion, Motion control, Animation toggle
+ * @documentation https://fusion.dev/helix/components/motion-toggle
+ *
+ * @slot - The button's text, where it shows more than its icon. Defaults to nothing, the icon alone, named by `label`.
+ * @slot icon - Replaces the icon, which is pause while motion runs and play while it is paused.
+ *
+ * @event {Event} change - Fired after a press pauses the page's motion or lets it run.
+ *
+ * @csspart button - The toggle button, with `aria-pressed` while the page's motion is paused.
+ * @csspart icon - The icon inside the button.
+ *
+ * @cssstate paused - The page's motion is paused.
+ */
+export declare class HelixHeadlessMotionToggle extends HelixElement {
+    /**
+     * The key this family's words are registered under, its styled tag:
+     * `registerWords('de', { 'helix-motion-toggle': { label: 'Bewegung anhalten' } })`.
+     */
+    static words: string;
+    /** The button's name, which stays the same whichever way it stands. */
+    label: string;
+    /** Whether the page's motion is paused, kept with the document element's attribute. */
+    private paused;
+    /** What stops hearing the page's choice. */
+    private unpaused;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    protected updated(): void;
+    /** Pauses the page's motion, or lets it run again. */
+    private readonly toggle;
+    protected render(): TemplateResult;
+    /**
+     * The icon the `icon` slot falls back to: pause while motion runs, and play
+     * while it is paused, which is what a press does next. A tier above draws
+     * its own here.
+     */
+    protected renderIcon(): TemplateResult;
+}
+declare global {
+    interface HTMLElementTagNameMap {
+        'helix-headless-motion-toggle': HelixHeadlessMotionToggle;
+    }
+}

package/dist/motion-toggle/root/motion-toggle-root.js

@@ -0,0 +1,56 @@
+import { __decorate } from "tslib";
+import { customElement, drawIcon, HelixElement, motionPaused, onMotionChange, pauseMotion, words, } from '@fusion.dev/helix-core';
+import { pause, play } from '@fusion.dev/helix-icons';
+import { html } from 'lit';
+import { property, state } from 'lit/decorators.js';
+let HelixHeadlessMotionToggle = class HelixHeadlessMotionToggle extends HelixElement {
+    constructor() {
+        super(...arguments);
+        this.label = 'Pause motion';
+        this.paused = false;
+        this.toggle = () => {
+            pauseMotion(!motionPaused());
+            this.paused = motionPaused();
+            this.dispatchEvent(new Event('change', { bubbles: true }));
+        };
+    }
+    static { this.words = 'helix-motion-toggle'; }
+    connectedCallback() {
+        super.connectedCallback();
+        this.paused = motionPaused();
+        this.unpaused ??= onMotionChange((paused) => {
+            this.paused = paused;
+        });
+    }
+    disconnectedCallback() {
+        super.disconnectedCallback();
+        this.unpaused?.();
+        this.unpaused = undefined;
+    }
+    updated() {
+        this.toggleState('paused', this.paused);
+    }
+    render() {
+        return html `<button
+      aria-label=${this.label}
+      aria-pressed=${this.paused ? 'true' : 'false'}
+      part="button"
+      type="button"
+      @click=${this.toggle}
+    ><span part="icon">${this.renderIcon()}</span><slot></slot></button>`;
+    }
+    renderIcon() {
+        return html `<slot name="icon">${drawIcon(this.paused ? play : pause)}</slot>`;
+    }
+};
+__decorate([
+    words,
+    property()
+], HelixHeadlessMotionToggle.prototype, "label", void 0);
+__decorate([
+    state()
+], HelixHeadlessMotionToggle.prototype, "paused", void 0);
+HelixHeadlessMotionToggle = __decorate([
+    customElement('helix-headless-motion-toggle')
+], HelixHeadlessMotionToggle);
+export { HelixHeadlessMotionToggle };

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

@@ -0,0 +1,79 @@
+/**
+ * A 3D bar chart's table read as bars on a grid of names.
+ *
+ * Kept apart from the element because it is arithmetic a picture hides: a
+ * value put under the wrong name stands as tall as a real one, and a bar
+ * measured from anywhere but zero says one value is a multiple of another
+ * when it is not.
+ */
+import { type Drawn, type PagePoint, type Projection } from '@fusion.dev/helix-core';
+import { type FieldRow, type PlotAxis } from '../spatial-scatter-chart/field.js';
+import { type BoxExtent } from '../spatial-scatter-chart/view.js';
+/** One place on the grid: a category across, a series in depth, and its value, where the table has one. */
+export interface BarCell {
+    /** Which category it stands under, counting from zero: the row's place among the rows read. */
+    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. */
+    depth: number;
+    /** The row's own label, which names its category. */
+    label: string;
+    /** The row it was read from, counting from zero. */
+    row: number;
+    /** The value, where the cell holds a number. */
+    value?: number | undefined;
+}
+/** The table as a 3D bar chart reads it. */
+export interface BarField {
+    /**
+     * Across, the categories; up, the values; and in depth, the series. The
+     * box is as long along the floor as the grid, so every place on it is
+     * square, and one series is a long, low row of bars.
+     */
+    axes: {
+        extent: BoxExtent;
+        x: PlotAxis;
+        y: PlotAxis;
+        z: PlotAxis;
+    };
+    /** Every category, in the table's order: each row's label. */
+    categories: string[];
+    /**
+     * Every place on the grid, across first: the bar for category `across` in
+     * series `depth` is at `across * series.length + depth`.
+     */
+    cells: BarCell[];
+    /** How many cells hold a value. */
+    readings: number;
+    /** Every series, in the table's order: each numeric column's heading. */
+    series: string[];
+}
+/**
+ * Reads the table as a bar chart does: **each row is a category, named by
+ * its label, and each numeric column a series**, named by its heading. The
+ * bars stand on a grid of categories across and series in depth, so one
+ * series is a single row of bars. A cell with no number leaves its place on
+ * the grid empty.
+ *
+ * **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.
+ */
+export declare const barsOf: (rows: readonly FieldRow[], columns: readonly number[]) => BarField;
+/** A bar as the chart's own drawing paints it. */
+export interface DrawnBar {
+    /** The block's eight corners on the page, which a drawing with no box is framed around. */
+    corners: PagePoint[];
+    drawn: Drawn;
+    height: number;
+    index: number;
+    x: number;
+    y: number;
+}
+/**
+ * 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.
+ */
+export declare const barsDrawn: (field: BarField, projection: Projection) => DrawnBar[];