@expressivecss/expressive 0.15.0 → 0.17.0

package/dist/types/components/keypad.d.ts

@@ -1,4 +1,4 @@
-import { Component, BaseOptions, InitElements, InitElement } from '../core/component';
+import { Component, BaseOptions } from '../core/component';
 export interface KeypadOptions extends BaseOptions {
     /**
      * Called after every key press with the text typed ('7', 'A', ' ') or the
@@ -6,29 +6,61 @@ export interface KeypadOptions extends BaseOptions {
      * @default null
      */
     onKey: ((key: string) => void) | null;
+    /** Text the keypad writes. */
+    i18n: Partial<KeypadI18n>;
+}
+export interface KeypadI18n {
+    /**
+     * The validation message for a field whose keypad-typed value is shorter
+     * than its minlength, which the browser only checks after typing.
+     */
+    tooShort: (minLength: number) => string;
 }
 type Field = HTMLInputElement | HTMLTextAreaElement;
 type Root = Document | ShadowRoot;
 /**
  * Keypad and keyboard. A `.keypad` or `.keyboard` whose `aria-controls`
  * names a text field types into it: a key's `value` is inserted at the caret,
- * and `data-key="Backspace"`, `"Enter"` and `"Shift"` edit, submit and
- * capitalize. The field receives the same `input` event typing would fire.
+ * and `data-key="Backspace"`, `"Enter"`, `"Shift"` and `"CapsLock"` edit,
+ * submit and capitalize. A `data-key="Layer"` key shows the elements whose
+ * `data-layer` matches its `value` and hides the other layers. The field
+ * receives the same `input` event typing would fire.
  */
 export declare class Keypad extends Component<KeypadOptions> {
     /** @internal */
     _root: Root | null;
+    /** Fields this keypad typed into, whose messages it clears on destroy. */
+    private _fields;
     constructor(el: HTMLElement, options: Partial<KeypadOptions>);
+    private _attach;
+    private _waitForInsertion;
+    private _listen;
     static get defaults(): KeypadOptions;
-    static init(el: HTMLElement, options?: Partial<KeypadOptions>): Keypad;
-    static init(els: InitElements<InitElement>, options?: Partial<KeypadOptions>): Keypad[];
-    static getInstance(el: HTMLElement): Keypad;
+    static key: string;
     destroy(): void;
     /** The text field named by `aria-controls`, if there is one. */
     get target(): Field | null;
     private _shared;
     /** @internal */
     _press(key: HTMLButtonElement): void;
+    /** Runs a key and returns what onKey hears: the typed text or the function key's name. */
+    private _act;
+    /** Shift and Caps Lock latch: pressed until pressed again, or for Shift until the next character. */
+    private _latch;
+    /** Shows the layer the key names and hides the others. */
+    private _layer;
+    private _type;
+    /** A character as Shift or Caps Lock writes it. Shift is one-shot: it releases after one character. */
+    private _case;
+    /** The target field, unless it is disabled or read-only. */
+    private get _editable();
+    private _apply;
+    /** Enter submits an input's form and starts a new line in a textarea. */
+    private _enter;
+    /** @internal Lights or clears every key a hardware key matches. */
+    _light(name: string, on: boolean): void;
+    /** @internal A non-empty value shorter than minlength is invalid, as typing would make it. */
+    _checkLength(field: Field): void;
     private _edit;
 }
 export {};

package/dist/types/components/lightbox.d.ts

@@ -1,4 +1,4 @@
-import { BaseOptions, Component, InitElements, InitElement } from '../core/component';
+import { BaseOptions, Component } from '../core/component';
 export interface LightboxOptions extends BaseOptions {
     /**
      * Transition in duration in milliseconds.
@@ -44,9 +44,6 @@ export declare class Lightbox extends Component<LightboxOptions> {
     originalHeight: number;
     private originInlineStyles;
     private placeholder;
-    /** Ancestors forced to `overflow: visible`, with the inline value to put back. */
-    private _changedAncestorList;
-    private static _overflow;
     private newHeight;
     private newWidth;
     private windowWidth;
@@ -61,35 +58,32 @@ export declare class Lightbox extends Component<LightboxOptions> {
     private _motion;
     private _isOpen;
     private _destroyed;
+    /** Removes the listeners that close an open lightbox. */
+    private _windowEvents;
     private _revision;
+    private _phase;
     constructor(el: HTMLElement, options: Partial<LightboxOptions>);
     static get defaults(): LightboxOptions;
-    /**
-     * Initializes instance of Lightbox.
-     * @param el HTML element.
-     * @param options Component options.
-     */
-    static init(el: HTMLElement, options?: Partial<LightboxOptions>): Lightbox;
-    /**
-     * Initializes instances of Lightbox.
-     * @param els HTML elements.
-     * @param options Component options.
-     */
-    static init(els: InitElements<InitElement>, options?: Partial<LightboxOptions>): Lightbox[];
-    static getInstance(el: HTMLElement): Lightbox;
+    static key: string;
     destroy(): void;
+    private _restoreFocus;
     private _reset;
     private _cancel;
     private _schedule;
     private _handleMotionChange;
     private _setupEventHandlers;
-    private _removeEventHandlers;
     private _handleLightboxKeypress;
     private _handleLightboxToggle;
     private _handleWindowChange;
     private _handleWindowEscape;
-    private _makeAncestorsOverflowVisible;
-    private _offset;
+    private _handleWindowTab;
+    /**
+     * Shows `el` as a manual popover, so it is in the top layer: no ancestor
+     * clips or covers it, and it stacks above what was shown before it.
+     */
+    private _showOnTop;
+    /** The placeholder's document position, where the image rests. */
+    private _restingPlace;
     private _updateVars;
     private _animateImageIn;
     private _animateImageOut;

package/dist/types/components/lineChart.d.ts

@@ -1,4 +1,4 @@
-import { Component, BaseOptions, InitElements, InitElement } from '../core/component';
+import { Component, BaseOptions } from '../core/component';
 export interface LineChartOptions extends BaseOptions {
     /**
      * Lowest value on the y axis. Defaults to the data minimum less 10% of
@@ -11,18 +11,94 @@ export interface LineChartOptions extends BaseOptions {
      * the range. Overridden by `data-max` on the chart.
      */
     max: number | null;
+    /**
+     * Redraws the chart whenever its table changes, once for the edits a
+     * script makes in one run, so page script need not call `update()`.
+     * `data-watch` on the chart turns it on too. Read when the chart starts.
+     */
+    watch: boolean;
 }
 export declare const COLORS = 4;
-/** An SVG element with its attributes. */
-export declare function svgNode(name: string, attributes?: Record<string, string>): SVGElement;
+/** Charts that color each row, not each series, cycle through six colors. */
+export declare const ROW_COLORS = 6;
+/**
+ * The legend of a pie or radial chart: an item per row, colored as
+ * `colors[i]` when that is set, holding a span for each of `rows[i]`.
+ */
+export declare function rowLegend(className: string, colors: (string | undefined)[], rows: string[][]): HTMLUListElement;
 /** A point at a turn clockwise from the top and a distance from the middle, as "x,y". */
 export declare function polarPoint(turn: number, r: number): string;
-/** A series' color number, for its `data-series`. */
-export declare const seriesColor: (i: number) => string;
+/** A series' color number, for its `data-series`, from a palette of `colors`. */
+export declare const seriesColor: (i: number, colors?: number) => string;
+/** The rows of a series split at each null into runs of indexes, empty runs included. */
+export declare function splitRuns(values: (number | null)[]): number[][];
+/** An axis of tick labels, each placed by --at, its distance along the plot. */
+export declare function tickAxis(className: string, ticks: number[], text: (tick: number) => string, at: (tick: number) => number): HTMLOListElement;
+/**
+ * The timing of the paths' motion after update(), from the chart's motion
+ * tokens, as the columns' CSS transition reads them. Null for a zero
+ * duration, which SVG would take as indefinite and hold the old shape.
+ * ponytail: a curve that overshoots is not a valid SVG spline, so the
+ * paths then skip their motion; a linear() token gets the standard curve.
+ */
+export declare function pace(el: Element): {
+    dur: string;
+    keySplines: string;
+};
+/**
+ * Moves a path from the path data `from` to its own. SVG animation rather
+ * than a CSS transition, since WebKit cannot transition the d property.
+ */
+export declare function morph(path: SVGElement, from: string, timing: Pace): void;
+/** The paths' motion timing. */
+type Pace = NonNullable<ReturnType<typeof pace>>;
+/** A round step that cuts `span` into at most `parts` pieces. A reversed span, as an author's `data-min` above the data gives, is measured by its size. */
+export declare function niceStep(span: number, parts?: number): number;
+/** The multiples of `step` from `low` to `high`, without float error. */
+export declare function steps(low: number, high: number, step: number): number[];
+/** A number format in the element's language, or the browser's for an invalid lang attribute. */
+export declare function numberFormat(el: Element, options: Intl.NumberFormatOptions): Intl.NumberFormat;
+/**
+ * A compact format that gives each tick its own label: three significant
+ * digits, or more when two ticks would read the same, as 10,050 and 10,100
+ * both do at "10.1K". 21 is the most Intl allows.
+ */
+export declare function tickFormat(el: Element, ticks: number[]): Intl.NumberFormat;
+/**
+ * A share of a whole as a percentage: whole numbers, with a tenth below 10%
+ * so a small part is not 0%. A chart that writes many keeps `formats` and
+ * clears it when the language may have changed.
+ */
+export declare function percentLabel(el: Element, share: number, formats?: Intl.NumberFormat[]): string;
+/** Whether a series header cell has a class. */
+export declare const hasClass: (series: Series, name: string) => boolean;
+/** Colors the tooltip's swatches like a mark; no color leaves the default. */
+export declare function tintTooltip(tooltip: HTMLElement, color?: string): void;
+/** A span holding `text`. */
+export declare const textSpan: (text: string) => HTMLSpanElement & {
+    textContent: string;
+};
+/**
+ * The mark a key moves to among marks `0` to `last` in table order, from
+ * `active`. The arrows keep their meaning in a right-to-left chart, since
+ * table order is no direction on screen. With nothing shown, Escape is left
+ * to a dialog or sheet around the chart.
+ */
+export declare function linearKey(key: string, active: number, last: number): number | undefined;
+/** A y scale's ends, and with .axis the values its labels mark. */
+export interface ChartScale {
+    min: number;
+    max: number;
+    ticks: number[];
+}
 export interface Series {
     name: string;
     /** Header cell classes, such as `dashed`. */
     className: string;
+    /** The series' column in the table, from 1, which tells apart two of one name. */
+    column: number;
+    /** The `data-series` color number, by its column, so hiding a series shifts none. */
+    color: string;
     /** Cell text, shown in the tooltip as the author formatted it. */
     text: string[];
     values: (number | null)[];
@@ -35,13 +111,33 @@ export interface Series {
     base?: (number | null)[];
     /** The series' y scale: a value's distance down the plot, in percent. */
     y: (value: number) => number;
+    scale: ChartScale;
+    /**
+     * The currency, percent or spacing around the first number written as
+     * cell text, such as ['$', ''], which the axis labels repeat.
+     */
+    affix: [string, string];
 }
+/**
+ * Reads a cell as a number. `data-value` wins over the text, which may carry
+ * currency or percent signs, grouping commas and a typographic minus around
+ * one number. Anything else, such as "(1,200)" or "3–5", is a gap rather
+ * than a guess.
+ */
+export declare function cellValue(cell: Element | undefined): number | null;
+/** An axis label: the tick in `format`, with the column's signs after any minus. */
+export declare function tickText(format: Intl.NumberFormat, tick: number, [prefix, suffix]: [string, string]): string;
+/** The currency, percent and spacing around a cell's number, as [prefix, suffix]. */
+export declare function signs(text: string): [string, string];
+/** The signs around the first value a column spells out in its text. */
+export declare function affix(cells: (Element | undefined)[]): [string, string];
 /**
  * Line chart. The data is the chart's <table>; this class draws it as an SVG
  * with x labels, a legend for more than one series, and a cursor and tooltip
  * that follow the pointer or the arrow keys. Styling is CSS.
  *
- * Re-run `LineChart.init(el)` after changing the table.
+ * Call `update()` after changing the table, or start it with `watch` or
+ * `data-watch`.
  */
 export declare class LineChart extends Component<LineChartOptions> {
     /** The values' x positions and series, read from the table. */
@@ -50,6 +146,19 @@ export declare class LineChart extends Component<LineChartOptions> {
     /** The highlighted row, or -1. */
     activeIndex: number;
     private _generated;
+    /** Watches the row labels' width, to thin them on a narrow chart. */
+    private _labelSizes;
+    /** With `watch`, redraws the chart when its table changes. */
+    private _tableWatch;
+    /** Every series in the table, shown or not, as the legend lists them. */
+    protected _all: Series[];
+    /**
+     * During update(), the series drawn before it, which the new marks move
+     * from. Empty otherwise, and when the reader prefers less motion.
+     */
+    protected _before: Series[];
+    /** The columns of the series a .toggle legend hid, kept through update(). */
+    private _hidden;
     /** The table's header cells and body rows, as read. */
     protected _header: HTMLTableCellElement[];
     protected _rows: HTMLTableRowElement[];
@@ -64,6 +173,10 @@ export declare class LineChart extends Component<LineChartOptions> {
     protected _reversed: boolean;
     /** The class prefix of the generated parts; ColumnChart reuses this class. */
     protected get _type(): string;
+    /** The column the series start at; a scatter chart's first value column is its x axis. */
+    protected get _seriesFrom(): number;
+    /** The column the series end before, as slice() takes it; a bubble chart's last column holds sizes. */
+    protected get _seriesTo(): number | undefined;
     /** Whether the y axis always includes zero, as columns grow from it. */
     protected get _fromZero(): boolean;
     /**
@@ -76,15 +189,34 @@ export declare class LineChart extends Component<LineChartOptions> {
      * arrows then step round it, wrapping from the last row to the first.
      */
     protected get _circular(): boolean;
+    /** Whether .axis labels the value scale, which a sparkline never does. */
+    protected get _axis(): boolean;
     /** Whether the cursor marks each series with a point. */
     protected get _points(): boolean;
-    protected get _key(): string;
+    /** How many rows `show()` can highlight. */
+    protected get _count(): number;
     constructor(el: HTMLElement, options: Partial<LineChartOptions>);
+    /**
+     * Observes the table as it is now, and the chart for a table added or
+     * replaced. Reconnecting drops the changes already queued, which the
+     * caller has just drawn.
+     */
+    private _watch;
+    /** Reads the table and draws it, when it has data. */
+    private _build;
+    /** Whether the pointer and keys pick rows, which a sparkline's do not. */
+    private get _interactive();
+    /** Lets the pointer and keys pick rows on the plot. */
+    private _listen;
     static get defaults(): LineChartOptions;
-    static init(el: HTMLElement, options?: Partial<LineChartOptions>): LineChart;
-    static init(els: InitElements<InitElement>, options?: Partial<LineChartOptions>): LineChart[];
-    static getInstance(el: HTMLElement): LineChart;
+    static key: string;
     destroy(): void;
+    /**
+     * Redraws the chart from its table as it is now. Focus stays on the chart,
+     * on the same legend button when one had it, and the highlighted row stays
+     * where the table still has it.
+     */
+    update(): void;
     /**
      * Highlights one row: moves the cursor and fills the tooltip.
      * Pass -1 to hide them. Does nothing for a chart without data.
@@ -95,7 +227,22 @@ export declare class LineChart extends Component<LineChartOptions> {
      * tooltip opening back over the plot past the middle.
      */
     protected _place(index: number): void;
-    private _read;
+    protected _read(): void;
+    /**
+     * The series to draw, arranged: those the legend has not hidden, or none
+     * without data. When the ones shown hold no data, as after the table
+     * changed, the hidden ones come back, so the legend never hides the only
+     * data there is.
+     */
+    private _shown;
+    /** Turns the values read into what is drawn: with .stacked, running totals. */
+    protected _arrange(series: Series[]): void;
+    /**
+     * Stacks each series on the ones before it: its tops become running
+     * totals and its base the total below. A gap leaves the total unknown, so
+     * the series above break there too.
+     */
+    protected _stack(series: Series[]): void;
     /** A number from one of the chart's data attributes, or null. */
     protected _number(name: string): number;
     /**
@@ -103,6 +250,13 @@ export declare class LineChart extends Component<LineChartOptions> {
      * are set, and gives it to each series.
      */
     protected _scale(series: Series[], min: number | null, max: number | null, fromZero?: boolean): (value: number) => number;
+    /**
+     * With .axis, widens each end the chart chose to a round step and lists
+     * the steps for the labels. An end set by the author stays where it is.
+     */
+    protected _fit(min: number, max: number, [fixedMin, fixedMax]: readonly boolean[]): ChartScale;
+    /** Gives the series a scale and the y function it draws with. */
+    protected _apply(series: Series[], scale: ChartScale): (value: number) => number;
     /** Each row sits in the middle of an equal band, beside its label. */
     private _x;
     private _render;
@@ -113,10 +267,55 @@ export declare class LineChart extends Component<LineChartOptions> {
     protected _total(className: string): HTMLElement | null;
     /** The parts below the plot: the row labels and the legend. */
     protected _guides(): Element[];
-    /** The series legend, for more than one series. */
+    /**
+     * Thins the column labels in container whenever its width changes. A bar
+     * chart's labels run down instead, and no labels leaves nothing to watch.
+     */
+    protected _observeLabels(container: HTMLElement, items: Element[]): void;
+    /**
+     * With .axis, the value labels, behind the marks: the start scale's with
+     * a grid line at each, and a mixed chart's end scale on the far side.
+     */
+    protected _axes(): Element[];
+    /** One scale's labels, each placed by --at, its value's distance down the plot. */
+    private _valueAxis;
+    /**
+     * The series legend, for more than one series. With .toggle each item is
+     * a button that shows or hides its series, and the scale refits.
+     */
     protected _legend(): Element[];
+    /** A button that shows or hides a series, though never the last one shown. */
+    private _toggle;
     /** Draws the series, which fill the plot. */
     protected _draw(drawn?: Series[]): Element;
+    /**
+     * A row's share of the whole, written after its first value in the
+     * tooltip, or undefined. Pie, funnel and treemap charts give one.
+     */
+    protected _share(_index: number): string | undefined;
+    /** The series as lines and areas, which a chart that overrides _draw can still call. */
+    protected _drawLines(drawn?: Series[]): Element;
+    /**
+     * After update(), the shape each series moves from: where it was drawn,
+     * and for a row it had no value at, its base. That is the plot bottom,
+     * or in a stack where the series below starts, so the stack stays joined.
+     */
+    private _starts;
+    /** Where a series drew each row before update(), or its base for a row it had no value at. */
+    private _was;
+    /** Where a stacked area's base runs: the series below, or the plot bottom when zero is off the scale. */
+    private _baseY;
+    /**
+     * A series' paths, with its rows at `top` and a stacked area's base at
+     * `base`. The line is smooth, or with .straight straight, and a gap in the
+     * data breaks it into runs.
+     */
+    private _shape;
+    /**
+     * One series' group: its line, the fill under it, and with .points a dot
+     * at each value. After update() each path moves from its `from` shape.
+     */
+    private _line;
     private _onPointerMove;
     /** The row under the pointer, or -1. */
     protected _indexAt(e: PointerEvent): number;
@@ -136,3 +335,4 @@ export declare class LineChart extends Component<LineChartOptions> {
     protected _keyTarget(key: string): number | undefined;
     private _onKeyDown;
 }
+export {};

package/dist/types/components/loadingOverlay.d.ts

@@ -0,0 +1,42 @@
+import { Component, BaseOptions } from '../core/component';
+/** What the status region announces. */
+export interface LoadingOverlayI18nOptions {
+    /** Announced when the region becomes busy. */
+    loading: string;
+    /** Announced when it clears. */
+    loaded: string;
+}
+export interface LoadingOverlayOptions extends BaseOptions {
+    /** What the status region announces when the region becomes busy and when it clears. */
+    i18n: Partial<LoadingOverlayI18nOptions>;
+}
+/**
+ * Loading overlay. While the page sets `aria-busy="true"` on the region, the
+ * region is inert, so nothing inside it takes a click, a tap or keyboard
+ * focus, and the stylesheet shows a scrim and the author's loading indicator
+ * over it. The page clears the region by removing the attribute or setting it
+ * to anything else; there is no method for either.
+ *
+ * Inert content leaves the accessibility tree, the indicator's status
+ * included, so the start and the finish are announced from a status region
+ * the script adds after the region.
+ */
+export declare class LoadingOverlay extends Component<LoadingOverlayOptions> {
+    static key: string;
+    private _status;
+    private _observer;
+    private _busy;
+    /** The region's own `inert`, put back when it clears. */
+    private _wasInert;
+    /** The element inside the region that had focus when it became busy. */
+    private _focus;
+    constructor(el: HTMLElement, options: Partial<LoadingOverlayOptions>);
+    static get defaults(): LoadingOverlayOptions;
+    destroy(): void;
+    /** Follows `aria-busy`. Other values than "true" clear, as ARIA treats them. */
+    private _sync;
+    private _start;
+    private _clear;
+    /** The deferred first announcement, unless the region cleared or the instance went first. */
+    private _announceStart;
+}