@expressivecss/expressive 0.15.0 → 0.16.0

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

@@ -0,0 +1,72 @@
+import { LineChart, LineChartOptions } from './lineChart';
+export type SankeyChartOptions = LineChartOptions;
+/**
+ * Sankey chart. Each row of its <table> is a flow: the first cell names the
+ * source node, the second the target node, and the third holds the value.
+ * Nodes stand in columns, a node with no incoming flow in the first and any
+ * other one column past the furthest of its sources, and stack in the order
+ * their names first appear. Each link is as thick as its value, and each
+ * node as tall as the larger of its in and out totals, on one scale. A row
+ * without both names or a positive value, or whose link would close a
+ * cycle, draws nothing.
+ *
+ * Call `update()` after changing the table, or start it with `watch` or
+ * `data-watch`.
+ */
+export declare class SankeyChart extends LineChart {
+    private _nodes;
+    /** The drawn links, in table order. */
+    private _links;
+    /** The links' paths, in the same order. */
+    private _paths;
+    /** Each drawn shape's path data, by its link's source and target names or its node's name, which update() moves from. */
+    private _shapes;
+    protected get _type(): string;
+    /** The value column is the one series; the target column is read on its own. */
+    protected get _seriesFrom(): number;
+    protected get _seriesTo(): number;
+    /** The links carry the values, so there is no value axis. */
+    protected get _axis(): boolean;
+    static key: string;
+    /** The links the keys and pointer reach. */
+    protected get _count(): number;
+    /** Highlights one link, numbered in table order among those drawn. Pass -1 to hide the tooltip. */
+    show(index: number): void;
+    /**
+     * Fills the tooltip beside the link's middle: its source and target under
+     * their column headers, with their nodes' colors, and the value cell's
+     * text, as the author wrote them. Past the middle it opens back over the plot.
+     */
+    private _fill;
+    /** The link under the pointer, or -1 off every link. By position, since a touch keeps its first target as it drags. */
+    protected _indexAt(e: PointerEvent): number;
+    /**
+     * Steps through the links in table order. The arrows keep their meaning
+     * in a right-to-left chart, since table order is no direction on screen.
+     */
+    protected _keyTarget(key: string): number | undefined;
+    /** Reads the flows and lays out their nodes and links. Without a link to draw, the chart draws nothing. */
+    protected _read(): void;
+    /** An x position in hundredths of the plot, mirrored in a right-to-left chart. */
+    private _across;
+    /** A node as path data: a rectangle. */
+    private _nodePath;
+    /** A link as path data: two curves from the source's edge to the target's, closed between them. */
+    private _linkPath;
+    /**
+     * The links, then the nodes over their ends. Neither has a stroke, so the
+     * stretched SVG keeps their sizes. After update(), each shape still in the
+     * table moves from where it was: a link found by its source and target
+     * names, a node by its name.
+     */
+    protected _draw(): Element;
+    /**
+     * The node names, over the drawing, each level with its node and toward
+     * the plot's middle: after the node, or before it in the last column.
+     * They are placed from the inline start, so they need no mirroring.
+     */
+    protected _axes(): Element[];
+    private _name;
+    /** No row labels or legend: the nodes carry the names. */
+    protected _guides(): Element[];
+}

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

@@ -0,0 +1,102 @@
+import { LineChart, LineChartOptions, Series } from './lineChart';
+export interface ScatterChartOptions extends LineChartOptions {
+    /**
+     * Lowest value on the x axis. Defaults to the data minimum less 10% of
+     * the range. Overridden by `data-x-min` on the chart.
+     */
+    xMin: number | null;
+    /**
+     * Highest value on the x axis. Defaults to the data maximum plus 10% of
+     * the range. Overridden by `data-x-max` on the chart.
+     */
+    xMax: number | null;
+}
+/**
+ * Scatter chart. It reads its <table> like LineChart, but the first value
+ * column is the x axis: each row draws one point per later column, at the
+ * row's x value and that column's y value. A row without an x value, or a
+ * cell without a y value, draws no point.
+ *
+ * With `.bubble`, the last column sizes each row's points, so their areas
+ * follow its values, and a row without a positive size draws no point.
+ *
+ * Call `update()` after changing the table, or start it with `watch` or
+ * `data-watch`.
+ */
+export declare class ScatterChart extends LineChart {
+    /** Each row's x value, or null. */
+    private _xs;
+    /** Each row's size: 1 without .bubble, or the last cell's value, null unless positive. */
+    private _sizes;
+    /** The x scale. */
+    private _xFit;
+    /** The signs around the x column's numbers, which its axis labels repeat. */
+    private _xAffix;
+    /** The drawn points, row by row and within a row by series. */
+    private _marks;
+    /** During update(), the points drawn before it, which the new ones move from. */
+    private _drawn;
+    protected get _type(): string;
+    protected get _seriesFrom(): number;
+    protected get _seriesTo(): number;
+    private get _bubble();
+    static get defaults(): ScatterChartOptions;
+    static key: string;
+    /**
+     * Reads each row's x value into `_xs` and its size into `_sizes`, which
+     * the scales and the points use, and leaves out the values of rows
+     * without either, so they neither draw nor stretch a scale. Nothing stacks.
+     */
+    protected _arrange(series: Series[]): void;
+    /** A row's size: 1 without .bubble, or its last cell's value, null unless positive. */
+    private _size;
+    protected get _count(): number;
+    /** Highlights one point, numbered as `_marks` lists them. Pass -1 to hide the tooltip. */
+    show(index: number): void;
+    /**
+     * Puts the marker on a point, at a bubble's size, and fills the tooltip
+     * beside it: the row, its x header and text, the series and its text, and
+     * with .bubble the size header and text, as the author wrote them. Past
+     * the middle the tooltip opens back over the plot.
+     */
+    private _fill;
+    /** A column's header, without a swatch since it names no series, and the row's text in it. */
+    private _cellText;
+    /** The point nearest the pointer, or -1 with none. */
+    protected _indexAt(e: PointerEvent): number;
+    /**
+     * Steps through the points in table order. The arrows keep their meaning
+     * in a right-to-left chart, since table order is no direction on screen.
+     */
+    protected _keyTarget(key: string): number | undefined;
+    protected _read(): void;
+    /** The x scale over the rows with a point, between `xMin` and `xMax` where they are set. */
+    private _xScale;
+    /** The x values of the rows with a point, with 10% of their span to spare each side. */
+    private _xRange;
+    /** An x scale end from its data attribute or option, or null. */
+    private _xEnd;
+    /** A value's distance across the plot from its inline start, in percent. */
+    private _xAt;
+    /** Whether any series shown draws a point in a row. */
+    private _hasPoint;
+    /** The points, each diameter the square root of its row's share of the largest size drawn, so areas follow sizes. */
+    private _layout;
+    /** One group per series, its points round caps on zero-length lines, so CSS sizes them in pixels. */
+    protected _draw(): Element;
+    /**
+     * A series' points, in one path, or with .bubble one path each, largest
+     * first so smaller bubbles stay on top.
+     */
+    private _group;
+    /**
+     * A path of points. After update() each moves from where its row's point
+     * in the same column was drawn, or appears where it is.
+     */
+    private _pointPath;
+    /** With .axis, the y scale's labels, and the x scale's below the plot with a grid line at each. */
+    protected _axes(): Element[];
+    private _xAxis;
+    /** The legend only: the rows have no labels along an axis. */
+    protected _guides(): Element[];
+}

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

@@ -1,4 +1,4 @@
-import { Component, BaseOptions, InitElements, InitElement } from '../core/component';
+import { Component, BaseOptions } from '../core/component';
 export interface ScrollSpyOptions extends BaseOptions {
     /**
      * Offset used as IntersectionObserver rootMargin and as
@@ -39,9 +39,7 @@ export declare class ScrollSpy extends Component<ScrollSpyOptions> {
     private _offsetPriority;
     constructor(el: HTMLElement, options: Partial<ScrollSpyOptions>);
     static get defaults(): ScrollSpyOptions;
-    static init(el: HTMLElement, options?: Partial<ScrollSpyOptions>): ScrollSpy;
-    static init(els: InitElements<InitElement>, options?: Partial<ScrollSpyOptions>): ScrollSpy[];
-    static getInstance(el: HTMLElement): ScrollSpy;
+    static key: string;
     destroy(): void;
     private static _syncActive;
     private static _nearestAbove;
@@ -50,5 +48,5 @@ export declare class ScrollSpy extends Component<ScrollSpyOptions> {
      * Default lookup compares href attributes (no interpolated selector).
      * A custom getActiveElement still returns a selector.
      */
-    static _linkFor(id: string, options: ScrollSpyOptions): Element | null;
+    static _linkFor(id: string, options: ScrollSpyOptions, root?: ParentNode): Element | null;
 }

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

@@ -1,5 +1,5 @@
 import { Menu, MenuOptions } from './menu';
-import { Component, BaseOptions, InitElements, InitElement } from '../core/component';
+import { Component, BaseOptions } from '../core/component';
 export interface FormSelectOptions extends BaseOptions {
     /**
      * Classes to be added to the select wrapper element.
@@ -11,6 +11,12 @@ export interface FormSelectOptions extends BaseOptions {
      * @default {}
      */
     menuOptions: Partial<MenuOptions>;
+    /** Show a separate popup search field for supported select modes. */
+    searchable: boolean;
+    i18n: Partial<{
+        searchLabel: string;
+        noResults: string;
+    }>;
 }
 type ValueStruct = {
     el: HTMLOptionElement;
@@ -34,7 +40,7 @@ export declare class FormSelect extends Component<FormSelectOptions> {
     /** The field wrapper around the native select. */
     wrapper: HTMLDivElement;
     selectOptions: (HTMLOptionElement | HTMLOptGroupElement)[];
-    private _values;
+    protected _values: ValueStruct[];
     private _createdWrapper;
     private _originalLabels;
     private _labelPlaceholder;
@@ -42,21 +48,14 @@ export declare class FormSelect extends Component<FormSelectOptions> {
     private _resetTimer;
     private _validationMessage;
     nativeTabIndex: number;
-    constructor(el: HTMLSelectElement, options: FormSelectOptions);
+    private _searchable;
+    protected _searchInput: HTMLInputElement;
+    private _searchResults;
+    private _searchStatus;
+    constructor(el: HTMLSelectElement, options: Partial<FormSelectOptions>);
     static get defaults(): FormSelectOptions;
-    /**
-     * Initializes instance of FormSelect.
-     * @param el HTML element.
-     * @param options Component options.
-     */
-    static init(el: HTMLSelectElement, options?: Partial<FormSelectOptions>): FormSelect;
-    /**
-     * Initializes instances of FormSelect.
-     * @param els HTML elements.
-     * @param options Component options.
-     */
-    static init(els: InitElements<HTMLSelectElement | InitElement>, options?: Partial<FormSelectOptions>): FormSelect[];
-    static getInstance(el: HTMLElement): FormSelect;
+    static key: string;
+    protected _canSearch(): boolean;
     destroy(): void;
     /**
      * Re-read the native `<select>` and update the generated menu to match.
@@ -67,11 +66,10 @@ export declare class FormSelect extends Component<FormSelectOptions> {
      * rebuilt from the native list, the field and Menu instance stay put.
      */
     refresh(): void;
+    private _restoreOptionFocus;
     _setupEventHandlers(): void;
     private _bindForm;
-    _removeEventHandlers(): void;
-    private _setupOptionHandlers;
-    private _removeOptionHandlers;
+    protected _setupOptionHandlers(): void;
     _handleSelectChange: () => void;
     private _handleInvalid;
     private _handleNativeFocus;
@@ -81,30 +79,45 @@ export declare class FormSelect extends Component<FormSelectOptions> {
     _handleOptionKeydown: (e: KeyboardEvent) => void;
     _handleOptionClick: (e: MouseEvent | KeyboardEvent) => void;
     private _handleOptionFocus;
-    _arraysEqual<T, E>(a: T[], b: (E | T)[]): boolean;
     _selectOptionElement(virtualOption: HTMLElement): void;
     _handleInputClick: () => void;
+    private _closeSingleSelect;
     _setupMenu(): void;
     private _setupWrapper;
     private _hideNativeSelect;
     private _buildInput;
     private _buildCaret;
+    private _buildSearch;
+    protected _searchList(): HTMLElement;
+    private _nameSearch;
+    private _filterOptions;
+    protected _filterSearch(query: string): void;
+    private _filterGroups;
+    protected _searchRows(): HTMLElement[];
+    private _handleSearchKeydown;
+    private _searchDismissKey;
+    private _searchTab;
+    private _searchBackwardTab;
+    protected _searchNavigate(e: KeyboardEvent): void;
+    private _searchInputKey;
+    private _focusSearchRow;
+    private _searchRowKey;
+    private _clearSearch;
+    private _resetSearch;
+    private _bindSearchClose;
     private _initMenu;
-    private _nativeOptions;
-    private _buildOptions;
+    private _focusMenu;
+    /** Moves focus to the selected row of the opened menu, centred when it scrolls. */
+    protected _focusSelected(): void;
+    protected _nativeOptions(): (HTMLOptGroupElement | HTMLOptionElement)[];
+    private get _optionList();
+    protected _buildOptions(): void;
     private _rebuildOptions;
-    _addOptionToValues(realOption: HTMLOptionElement, virtualOption: HTMLElement): void;
     _removeMenu(): void;
     _createAndAppendOptionWithIcon(realOption: HTMLOptionElement | HTMLOptGroupElement, type: string): HTMLLIElement;
-    _selectValue(value: ValueStruct): void;
-    _deselectValue(value: ValueStruct): void;
-    _deselectAll(): void;
-    _isValueSelected(value: ValueStruct): boolean;
-    _toggleEntryFromArray(value: ValueStruct): void;
-    _getSelectedOptions(): HTMLOptionElement[];
     _setValueToInput(): void;
+    /** Shows each option's selection on its row and checkbox. */
     _setSelectedStates(): void;
-    _activateOption(ul: HTMLElement, li: HTMLElement): void;
     getSelectedValues(): string[];
 }
 export {};

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

@@ -0,0 +1,51 @@
+import { Component, BaseOptions } from "../core/component";
+export interface ShowMoreI18nOptions {
+    /** The button's label while the full text shows. */
+    showLess: string;
+}
+export interface ShowMoreOptions extends BaseOptions {
+    /** Called after the full text shows. */
+    onOpen: ((el: Element) => void) | null;
+    /** Called after the text is clamped again. */
+    onClose: ((el: Element) => void) | null;
+    /** The open label; `data-show-less` on the button overrides it. */
+    i18n: Partial<ShowMoreI18nOptions>;
+}
+/**
+ * Clamped text with a button that shows all of it. A `.show-more` holds text
+ * with a `line-clamp-1`, `-2` or `-3` class and a `<button>`. The button
+ * hides while the clamped text fits.
+ */
+export declare class ShowMore extends Component<ShowMoreOptions> {
+    static key: string;
+    isOpen: boolean;
+    private readonly text;
+    private readonly button;
+    private _initial;
+    private _initialId;
+    private _label;
+    private _moreLabel;
+    private _observer;
+    constructor(el: HTMLElement, options: Partial<ShowMoreOptions>);
+    static get defaults(): ShowMoreOptions;
+    /** Shows the full text. */
+    open: () => void;
+    /** Clamps the text again. */
+    close: () => void;
+    destroy(): void;
+    /** Records what destroy() restores, then points the button at the text. */
+    private _wire;
+    private _toggle;
+    /**
+     * Hides the button while the clamped text fits. Open text keeps it. So does
+     * focus, so a resize cannot hide the button someone is on and drop focus on
+     * the page. The check runs again on blur, which also hides a button whose
+     * text was collapsed after it widened to fit, since collapsing it then
+     * leaves the box the same size.
+     */
+    private _fit;
+    private _show;
+    private _lessLabel;
+    private _clamp;
+    private _restoreClamp;
+}

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

@@ -1,4 +1,4 @@
-import { Component, BaseOptions, InitElements, InitElement } from '../core/component';
+import { Component, BaseOptions } from '../core/component';
 export interface SliderOptions extends BaseOptions {
 }
 export declare class Slider extends Component<SliderOptions> {
@@ -9,23 +9,11 @@ export declare class Slider extends Component<SliderOptions> {
     thumb: HTMLElement;
     constructor(el: HTMLInputElement, options: Partial<SliderOptions>);
     static get defaults(): SliderOptions;
-    /**
-     * Initializes instance of Slider.
-     * @param el HTML element.
-     * @param options Component options.
-     */
-    static init(el: HTMLInputElement, options?: Partial<SliderOptions>): Slider;
-    /**
-     * Initializes instances of Slider.
-     * @param els HTML elements.
-     * @param options Component options.
-     */
-    static init(els: InitElements<HTMLInputElement | InitElement>, options?: Partial<SliderOptions>): Slider[];
-    static getInstance(el: HTMLInputElement): Slider;
+    static key: string;
     destroy(): void;
     _set(el: HTMLElement, name: string, value: string): void;
     _setupEventHandlers(): void;
-    _removeEventHandlers(): void;
+    _handleFormReset: () => void;
     _handleRangeChange: () => void;
     _handleRangePointerDown: (e: PointerEvent) => void;
     _handleRangeInput: () => void;

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

@@ -66,6 +66,12 @@ export interface SnackbarOptions extends BaseOptions {
      * @default null
      */
     root: HTMLElement;
+    /**
+     * Show at once, dismissing the snackbar on screen without its exit
+     * animation, instead of waiting in the queue behind it.
+     * @default false
+     */
+    replace: boolean;
 }
 export declare class Snackbar {
     /** The snackbar element. */
@@ -94,17 +100,54 @@ export declare class Snackbar {
     private _activationDistance;
     private _dismissed;
     private _returnFocus;
+    /** The document body or shadow root the snackbar renders into. */
+    private _portal;
     private _events;
     private _restoreElement;
     private _transitionTimer;
     private _dismissTimer;
     private _focusTimer;
+    /** The snackbar on screen, kept until its exit animation finishes. */
     static _snackbars: Snackbar[];
+    /** Snackbars waiting for the one on screen to leave, oldest first. */
+    static _queue: Snackbar[];
+    /** Set while a replacement clears the screen; the queue waits for it. */
+    private static _replacing;
     static _container: HTMLElement;
     static _draggedSnackbar: Snackbar;
     /** Which pointer owns the drag in flight; a second finger is ignored. */
     static _dragPointerId: number | null;
+    /**
+     * Whether a bar gets its close button when the page does not say. One with
+     * an action waits for it, and one that never times out waits for the
+     * reader; either way, swiping must not be the only way to send it off.
+     */
+    private static _needsClose;
     constructor(options?: Partial<SnackbarOptions>);
+    /**
+     * Lets go of snackbars a re-render took out of the page. A persistent one
+     * would otherwise hold the queue for good.
+     */
+    private static _dropDetached;
+    /** Throws now, rather than when the snackbar shows, if `snackbarId` names nothing. */
+    private _requireBody;
+    /** Whether the body a snackbar shows is still there: its own, or `snackbarId`'s. */
+    private _hasBody;
+    private _build;
+    /**
+     * Takes the snackbar on screen down at once, without starting the queue.
+     * Restoring focus can open another, which goes too.
+     */
+    private static _replaceShown;
+    /** Puts the snackbar on screen and starts its countdown. */
+    private _show;
+    /** The focused element, looking inside open shadow roots. */
+    private static _focused;
+    /**
+     * One container serves every snackbar, and only one snackbar shows at a
+     * time — so it is moved rather than duplicated when the root changes.
+     */
+    private static _containerIn;
     static get defaults(): SnackbarOptions;
     static getInstance(el: HTMLElement): Snackbar;
     static _createContainer(root?: HTMLElement | ShadowRoot): void;
@@ -123,8 +166,26 @@ export declare class Snackbar {
      * dismiss all snackbars.
      */
     static dismissAll(): void;
+    /**
+     * Whether dismiss() is done already: the snackbar was dismissed before, or
+     * never showed and is dropped from the queue. A dropped one reports through
+     * completeCallback but fires no events, never having been in the page.
+     */
+    private _leaveQueue;
+    private _drop;
     _createSnackbar(): HTMLElement;
     private _remove;
+    /** Shows the next queued snackbar once the screen is clear, or tidies up. */
+    private static _advance;
+    /**
+     * A queued snackbar completes without showing when the page it was for has
+     * gone: its `root`, such as a removed shadow host, or its authored body.
+     * Shown there, nothing could reach it to dismiss it, and the queue would stall.
+     */
+    private static _showOrDrop;
+    private static _canShow;
+    /** Removes the container once nothing is left in it. */
+    private static _tidy;
     _animateIn(): void;
     /**
      * Arm the dismissal timer.

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

@@ -0,0 +1,81 @@
+import { Component, BaseOptions } from '../core/component';
+/** What `expressive:swipetoggle` carries, and what `onToggle` receives. */
+export interface SwipeActionsDetail {
+    /** The row that opened or closed. */
+    row: HTMLElement;
+    /** Whether it is now open. */
+    open: boolean;
+}
+export interface SwipeActionsOptions extends BaseOptions {
+    /**
+     * Called when a row opens or closes, with the event's detail.
+     * @default null
+     */
+    onToggle: ((detail: SwipeActionsDetail) => void) | null;
+}
+/**
+ * Swipe actions. In a `.list.swipeable`, a touch swipe toward a row's inline
+ * start slides the row and reveals its `.swipe-actions` group at the inline
+ * end. A swipe only reveals; nothing runs until a person presses an action.
+ * The row's `[data-swipe-toggle]` button opens and closes it without a
+ * swipe, and focus on an action opens its row, so keyboard and single-pointer
+ * users reach the same actions. One row in the list is open at a time.
+ *
+ * Touch events rather than pointer events, as in PullToRefresh: a pointer
+ * drag the browser takes for a pan ends in `pointercancel`. A mouse never
+ * fires touch events, so it never swipes.
+ */
+export declare class SwipeActions extends Component<SwipeActionsOptions> {
+    static key: string;
+    /** The open row, if any. */
+    private _open;
+    /** The touch in progress, while it may still become a swipe or is one. */
+    private _swipe;
+    constructor(el: HTMLElement, options: Partial<SwipeActionsOptions>);
+    static get defaults(): SwipeActionsOptions;
+    /** Opens a row of this list, closing the one that was open. */
+    open(row: HTMLElement): void;
+    /** Closes the open row, if there is one. */
+    close(): void;
+    destroy(): void;
+    private _rows;
+    /** Whether `row` is a row of this list with actions. */
+    private _isRow;
+    private _rowFor;
+    private _toggleFor;
+    private _width;
+    /** -1 when rows open toward the left, 1 when they open toward the right. */
+    private _sign;
+    /** Slides a row `reveal` pixels open. */
+    private _place;
+    /** Puts a row back closed, without telling anyone. */
+    private _shut;
+    private _fire;
+    private _onStart;
+    private _onMove;
+    /**
+     * Swipes once the finger moves sideways, or leaves the touch to scrolling
+     * when it moves up or down first. Returns whether it is now a swipe.
+     */
+    private _decide;
+    /** Slides the row with the finger, no farther than its actions reach. */
+    private _drag;
+    private _onEnd;
+    /** Leaves a released row open or closed, putting its offset where that state has it. */
+    private _settle;
+    private _onCancel;
+    /** Ends a swipe without deciding anything: the row goes back to how it was. */
+    private _cancel;
+    private _onClick;
+    /** open() ignores anything that is not a row of this list. */
+    private _toggle;
+    /** Closes the open row from inside it, moving focus off an action so it does not stay on a hidden button. */
+    private _closeFrom;
+    private _focusToggle;
+    private _onKeydown;
+    /** Focus on an action opens its row; focus anywhere outside the open row closes it. */
+    private _onFocusin;
+    /** A tap or click outside the open row closes it. */
+    private _onPointerdown;
+    private _closeOutside;
+}