@expressivecss/expressive 0.12.0 → 0.14.1

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

@@ -0,0 +1,96 @@
+import { Component, BaseOptions, InitElements, InitElement, Openable } from '../core/component';
+export interface CommandPaletteOptions extends BaseOptions {
+    /**
+     * Letter that toggles the palette together with Command on Apple platforms
+     * or Ctrl elsewhere. A key event the page has already handled is left
+     * alone. `null` turns the shortcut off. `data-shortcut` on the dialog sets
+     * it; an empty `data-shortcut` turns it off.
+     * @default 'k'
+     */
+    shortcut: string | null;
+    /**
+     * If true, the palette closes after a command runs.
+     * @default true
+     */
+    closeOnRun: boolean;
+}
+/**
+ * A command palette: a native modal <dialog class="command-palette"> holding
+ * a search input and a list of commands. Typing filters the list; the arrow
+ * keys move through what is left and Enter runs it, while focus stays in the
+ * input. The dialog owns modality, Escape and returning focus.
+ *
+ * The input is a combobox and the list a listbox of options, with the active
+ * option reported through aria-activedescendant. A command is the link or
+ * button inside an option; running it clicks that element, so a page wires
+ * commands with ordinary hrefs and click handlers.
+ */
+export declare class CommandPalette extends Component<CommandPaletteOptions> implements Openable {
+    el: HTMLDialogElement;
+    /** The search input. */
+    input: HTMLInputElement;
+    /** The list of commands. */
+    list: HTMLElement;
+    private _active;
+    private _generatedIds;
+    /** Wires and refilters commands the page adds or removes later. */
+    private _observer;
+    constructor(el: HTMLDialogElement, options: Partial<CommandPaletteOptions>);
+    static get defaults(): CommandPaletteOptions;
+    /**
+     * Initializes instance of CommandPalette.
+     * @param el HTML element.
+     * @param options Component options.
+     */
+    static init(el: HTMLElement, options?: Partial<CommandPaletteOptions>): CommandPalette;
+    /**
+     * Initializes instances of CommandPalette.
+     * @param els HTML elements.
+     * @param options Component options.
+     */
+    static init(els: InitElements<InitElement>, options?: Partial<CommandPaletteOptions>): CommandPalette[];
+    static getInstance(el: HTMLElement): CommandPalette;
+    /** If the palette is open. */
+    get isOpen(): boolean;
+    /** Opens the palette as a modal dialog with the search input focused. */
+    open: () => void;
+    /** Closes the palette. The dialog returns focus to where it was. */
+    close: () => void;
+    destroy(): void;
+    private _items;
+    private _labels;
+    private _empty;
+    private _action;
+    private _ensureId;
+    private _setupAccessibility;
+    /** Every command, including ones added since the last pass, is an option. */
+    private _wireItems;
+    /** Commands on screen: neither hidden by the page nor filtered out. */
+    private _shown;
+    /** Shown commands the arrows and Enter can reach: disabled ones are skipped. */
+    private _visible;
+    /** A disabled link or button cannot run, so its option says so. */
+    private _isDisabled;
+    private _setActive;
+    /**
+     * Shows the commands matching the query. Filtering marks rows with
+     * data-filtered rather than hidden, so a command the page hides stays
+     * hidden. `keepActive` holds the active command while it is still
+     * reachable, for list changes the user did not make.
+     */
+    private _filter;
+    private _move;
+    /** Runs a command by clicking its link or button; the click handler closes. */
+    private _run;
+    _handleInput: () => void;
+    _handleKeydown: (e: KeyboardEvent) => void;
+    _handleListClick: (e: MouseEvent) => void;
+    _handlePointerMove: (e: PointerEvent) => void;
+    /**
+     * Each opening starts from the full list. The close event is queued, so a
+     * palette reopened straight away may already be open again; its new search
+     * is left alone.
+     */
+    _handleClose: () => void;
+    _handleShortcut: (e: KeyboardEvent) => void;
+}

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

@@ -0,0 +1,103 @@
+import { Component, BaseOptions, InitElements, InitElement } from '../core/component';
+export type ConfettiShape = 'square' | 'circle' | 'star';
+export interface ConfettiOptions extends BaseOptions {
+    /**
+     * Pieces per burst.
+     * @default 50
+     */
+    particleCount: number;
+    /**
+     * Launch direction in degrees. 90 is straight up, 0 is right.
+     * @default 90
+     */
+    angle: number;
+    /**
+     * How far the pieces fan out from the angle, in degrees.
+     * @default 45
+     */
+    spread: number;
+    /**
+     * Launch speed in pixels per frame.
+     * @default 45
+     */
+    startVelocity: number;
+    /**
+     * Share of its speed a piece keeps each frame.
+     * @default 0.9
+     */
+    decay: number;
+    /**
+     * Pull toward the bottom. 0 floats, 1 is normal.
+     * @default 1
+     */
+    gravity: number;
+    /**
+     * Sideways push per frame. Negative drifts left.
+     * @default 0
+     */
+    drift: number;
+    /**
+     * Frames a piece lives while it fades out.
+     * @default 200
+     */
+    ticks: number;
+    /**
+     * Launch point as fractions of the canvas, 0 to 1. A missing side is
+     * 0.5. A trigger element ignores it and launches from its own center.
+     * @default { x: 0.5, y: 0.5 }
+     */
+    origin: {
+        x?: number;
+        y?: number;
+    };
+    /**
+     * CSS colors. Empty uses the theme's primary, secondary and tertiary
+     * colors and their containers.
+     * @default []
+     */
+    colors: string[];
+    /**
+     * @default ['square', 'circle']
+     */
+    shapes: ConfettiShape[];
+    /**
+     * Piece size multiplier.
+     * @default 1
+     */
+    scalar: number;
+    /**
+     * On a canvas, wait for `fire()` instead of bursting once at init.
+     * @default false
+     */
+    manualStart: boolean;
+}
+/**
+ * Confetti. Bursts of theme-colored pieces drawn on a canvas.
+ *
+ * - `Confetti.fire(options)` bursts over the whole viewport.
+ * - Any other `.confetti` element bursts from its center when clicked.
+ * - A `<canvas class="confetti">` bursts inside its own box, once at init
+ *   unless `manualStart`, and again on each `fire()`.
+ *
+ * The viewport canvas is a manual popover, so it draws above an open modal
+ * dialog, and it ignores the pointer. Nothing is drawn when the reader
+ * prefers reduced motion.
+ */
+export declare class Confetti extends Component<ConfettiOptions> {
+    private _onClick;
+    constructor(el: HTMLElement, options: Partial<ConfettiOptions>);
+    static get defaults(): ConfettiOptions;
+    static init(el: HTMLElement, options?: Partial<ConfettiOptions>): Confetti;
+    static init(els: InitElements<InitElement>, options?: Partial<ConfettiOptions>): Confetti[];
+    static getInstance(el: HTMLElement): Confetti;
+    /**
+     * Bursts over the whole viewport. Resolves when the last piece is gone.
+     */
+    static fire(options?: Partial<ConfettiOptions>): Promise<void>;
+    /**
+     * Bursts on this canvas, or from this element's center over the viewport.
+     * Resolves when the last piece is gone.
+     */
+    fire(options?: Partial<ConfettiOptions>): Promise<void>;
+    destroy(): void;
+}

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

@@ -209,6 +209,8 @@ export declare class Datepicker extends Component<DatepickerOptions> {
     private _y;
     private _m;
     private displayPlugin;
+    /** Rows renderRow has already checked, so renderBody does not parse them again. */
+    private _checkedRows;
     private footer;
     /** Nesting depth of {@link _batchDraws}; > 0 means draws are being collected. */
     private _drawDepth;

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

@@ -0,0 +1,49 @@
+import { InitElements, InitElement } from '../core/component';
+import { LineChart, LineChartOptions } from './lineChart';
+export type HeatmapChartOptions = LineChartOptions;
+/**
+ * Heatmap chart. It reads its <table> like LineChart, but draws every cell
+ * as a square of the grid, shaded from the lowest value to the highest, with
+ * the row headers beside it and the column headers below. A `data-label` on
+ * a header cell replaces its text on the grid; an empty one hides it. The
+ * tooltip shows one cell, and the arrow keys move round the grid.
+ *
+ * Re-run `HeatmapChart.init(el)` after changing the table.
+ */
+export declare class HeatmapChart extends LineChart {
+    /** Every cell, row by row. */
+    private _cells;
+    /** Each cell's shade from 0 to 1, or null for a gap. */
+    private _levels;
+    /** The text of the lowest and highest cells, for the legend. */
+    private _ends;
+    /** The shades of the lowest and highest cells, where the legend's gradient runs. */
+    private _endLevels;
+    protected get _type(): string;
+    protected get _key(): string;
+    static init(el: HTMLElement, options?: Partial<HeatmapChartOptions>): HeatmapChart;
+    static init(els: InitElements<InitElement>, options?: Partial<HeatmapChartOptions>): HeatmapChart[];
+    static getInstance(el: HTMLElement): HeatmapChart;
+    /** Highlights one cell, numbered row by row. Pass -1 to hide the tooltip. */
+    show(index: number): void;
+    /** Arrows move the way they point, so left and right swap in RTL. */
+    protected _keyTarget(key: string): number | undefined;
+    /**
+     * The cell under the pointer by its position, or -1 off the grid. A touch
+     * keeps its first target while it drags, so the target cannot be used. The
+     * cells and gaps are even, so each band's edge falls in a gap and a gap
+     * counts as the nearer cell.
+     */
+    protected _indexAt(e: PointerEvent): number;
+    /**
+     * The legend: a gradient from the lowest cell's shade to the highest's,
+     * labelled with their text. A fixed scale wider than the data shows only
+     * the part the data uses.
+     */
+    protected _guides(): Element[];
+    /**
+     * A grid of the row headers and cells, row by row, with the column headers
+     * below. Each cell's --level shades it in CSS.
+     */
+    protected _draw(): Element;
+}

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

@@ -6,9 +6,24 @@ export { Cards } from "./cards";
 export { ExpandingCard } from "./expandingCard";
 export { Carousel } from "./carousel";
 export { CharacterCounter } from "./characterCounter";
+export { Confetti } from "./confetti";
+export { Particles } from "./particles";
 export { Chips } from "./chips";
+export { CommandPalette } from "./commandPalette";
+export { Questionnaire } from "./questionnaire";
+export { LineChart } from "./lineChart";
+export { ColumnChart } from "./columnChart";
+export { BarChart } from "./barChart";
+export { PieChart } from "./pieChart";
+export { HeatmapChart } from "./heatmapChart";
+export { RadarChart } from "./radarChart";
+export { RadialChart } from "./radialChart";
+export { MixedChart } from "./mixedChart";
 export { Datepicker } from "./datepicker";
 export { Menu } from "./menu";
+export { MessageScroller } from "./messageScroller";
+export { RichTextEditor } from "./richTextEditor";
+export { MapView } from "./mapView";
 export { Lightbox } from "./lightbox";
 export { Slider } from "./slider";
 export { ScrollSpy } from "./scrollspy";

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

@@ -0,0 +1,134 @@
+import { Component, BaseOptions, InitElements, InitElement } from '../core/component';
+export interface LineChartOptions extends BaseOptions {
+    /**
+     * Lowest value on the y axis. Defaults to the data minimum less 10% of
+     * the range; a stacked chart starts at zero or its lowest total, and a
+     * column chart always includes zero. Overridden by `data-min` on the chart.
+     */
+    min: number | null;
+    /**
+     * Highest value on the y axis. Defaults to the data maximum plus 10% of
+     * the range. Overridden by `data-max` on the chart.
+     */
+    max: number | null;
+}
+export declare const COLORS = 4;
+/** An SVG element with its attributes. */
+export declare function svgNode(name: string, attributes?: Record<string, string>): SVGElement;
+export interface Series {
+    name: string;
+    /** Header cell classes, such as `dashed`. */
+    className: string;
+    /** Cell text, shown in the tooltip as the author formatted it. */
+    text: string[];
+    values: (number | null)[];
+    /**
+     * Where each value is drawn: the value, or in a stacked chart the running
+     * total, which is unknown (null) above a gap.
+     */
+    tops: (number | null)[];
+    /** In a stacked chart, the total of the series below, which this area fills down to. */
+    base?: (number | null)[];
+    /** The series' y scale: a value's distance down the plot, in percent. */
+    y: (value: number) => number;
+}
+/**
+ * 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.
+ */
+export declare class LineChart extends Component<LineChartOptions> {
+    /** The values' x positions and series, read from the table. */
+    labels: string[];
+    series: Series[];
+    /** The highlighted row, or -1. */
+    activeIndex: number;
+    private _generated;
+    /** The table's header cells and body rows, as read. */
+    protected _header: HTMLTableCellElement[];
+    protected _rows: HTMLTableRowElement[];
+    protected _plot: HTMLElement;
+    protected _cursor: HTMLElement;
+    protected _tooltip: HTMLElement;
+    protected _y: (value: number) => number;
+    /**
+     * Whether the rows run right to left: a horizontal row axis in a
+     * right-to-left context, like the labels. Bar chart rows keep their order.
+     */
+    protected _reversed: boolean;
+    /** The class prefix of the generated parts; ColumnChart reuses this class. */
+    protected get _type(): string;
+    /** Whether the y axis always includes zero, as columns grow from it. */
+    protected get _fromZero(): boolean;
+    /**
+     * Whether the rows run down the plot and the values across it, as in a
+     * bar chart. The rows then keep their order in a right-to-left context.
+     */
+    protected get _horizontal(): boolean;
+    /**
+     * Whether the rows go round a circle, as in a pie or radar chart. The
+     * arrows then step round it, wrapping from the last row to the first.
+     */
+    protected get _circular(): boolean;
+    /** Whether the cursor marks each series with a point. */
+    protected get _points(): boolean;
+    protected get _key(): string;
+    constructor(el: HTMLElement, options: Partial<LineChartOptions>);
+    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;
+    destroy(): void;
+    /**
+     * Highlights one row: moves the cursor and fills the tooltip.
+     * Pass -1 to hide them. Does nothing for a chart without data.
+     */
+    show(index: number): void;
+    /**
+     * Moves the filled cursor and tooltip to a row: beside its band, with the
+     * tooltip opening back over the plot past the middle.
+     */
+    protected _place(index: number): void;
+    private _read;
+    /** A number from one of the chart's data attributes, or null. */
+    protected _number(name: string): number;
+    /**
+     * Fits a y scale to the series' tops, between `min` and `max` where they
+     * are set, and gives it to each series.
+     */
+    protected _scale(series: Series[], min: number | null, max: number | null, fromZero?: boolean): (value: number) => number;
+    /** Each row sits in the middle of an equal band, beside its label. */
+    private _x;
+    private _render;
+    /**
+     * The <tfoot> row as a total to show over the plot, its value over its
+     * label, or null without one.
+     */
+    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. */
+    protected _legend(): Element[];
+    /** Draws the series, which fill the plot. */
+    protected _draw(drawn?: Series[]): Element;
+    private _onPointerMove;
+    /** The row under the pointer, or -1. */
+    protected _indexAt(e: PointerEvent): number;
+    /**
+     * For a circular chart, the pointer's position from the plot's middle: a
+     * fraction of a turn clockwise from the top, and its distance as a share
+     * of the plot's width.
+     */
+    protected _polarAt(e: PointerEvent): [turn: number, distance: number];
+    /** The keys that move to the next row and to the one before. */
+    protected get _arrows(): [string[], string[]];
+    private _onFocus;
+    private _onLeave;
+    /** The browser took the touch to scroll the page. */
+    private _onCancel;
+    /** The index a key moves to, or undefined for a key the chart ignores. */
+    protected _keyTarget(key: string): number | undefined;
+    private _onKeyDown;
+}

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

@@ -0,0 +1,151 @@
+import { Component, BaseOptions, InitElements, InitElement } from '../core/component';
+/** `[longitude, latitude]`, MapLibre's order. */
+export type LngLat = [number, number];
+/**
+ * The parts of the `maplibre-gl` module this component uses. Declared here so
+ * the published types do not depend on MapLibre.
+ */
+export interface MapLibre {
+    Map: new (options: object) => any;
+    Marker: new (options: object) => any;
+    Popup: new (options: object) => any;
+}
+/** A style for each color scheme. The map follows the page's theme. */
+export interface MapThemedStyle {
+    light: string | object;
+    dark: string | object;
+}
+export interface MapViewOptions extends BaseOptions {
+    /**
+     * The `maplibre-gl` module. ExpressiveCSS does not bundle MapLibre, so the
+     * page imports it and passes it in.
+     * @default null
+     */
+    maplibregl: MapLibre | null;
+    /**
+     * A MapLibre style URL or object, or `{ light, dark }` to follow the theme.
+     * @default OpenFreeMap Positron and Dark
+     */
+    style: string | object | MapThemedStyle;
+    /**
+     * Starting `[longitude, latitude]`.
+     * @default [0, 20]
+     */
+    center: LngLat;
+    /**
+     * Starting zoom level.
+     * @default 1
+     */
+    zoom: number;
+    /**
+     * More MapLibre `Map` options, such as `maxZoom` or `bearing`.
+     * @default {}
+     */
+    mapOptions: object;
+}
+export interface MapLineOptions {
+    /** CSS color. Defaults to the route or arc color token. */
+    color?: string;
+    /** Width in pixels. Routes default to 4, arcs to 2. */
+    width?: number;
+    /** 0 to 1. */
+    opacity?: number;
+    /** Dash and gap lengths in line widths, such as `[2, 2]`. */
+    dashArray?: number[];
+}
+export interface MapArc {
+    from: LngLat;
+    to: LngLat;
+}
+export interface MapClusterOptions {
+    /** CSS color. Defaults to the cluster color token. */
+    color?: string;
+    /**
+     * Pixels within which points join a cluster.
+     * @default 50
+     */
+    radius?: number;
+    /**
+     * Last zoom level that clusters points.
+     * @default 14
+     */
+    maxZoom?: number;
+}
+/**
+ * An interactive map built on MapLibre: a `.map` holding `.map-marker`,
+ * `.map-popup` and `.map-controls` children.
+ *
+ * Each marker sits at its `data-lng-lat`. A marker button with
+ * `aria-controls` opens the `.map-popup` it names; a popup with its own
+ * `data-lng-lat` and no marker opens at init. Buttons in `.map-controls`
+ * run their `data-action`: `zoom-in`, `zoom-out`, `compass`, `locate` or
+ * `fullscreen`. Routes, arcs and clusters are data, so they are added from
+ * script. The default style follows the page's light or dark theme, and
+ * line and cluster colors come from the theme.
+ *
+ * The class is `MapView` rather than `Map` so importing it does not shadow
+ * JavaScript's `Map`.
+ */
+export declare class MapView extends Component<MapViewOptions> {
+    /** The MapLibre map. */
+    map: any;
+    /** The MapLibre markers made from `.map-marker` children, in order. */
+    markers: any[];
+    private _children;
+    private _popups;
+    private _markerPopups;
+    private _overlays;
+    private _styleReady;
+    private _dark;
+    private _location;
+    private _media;
+    private _observer;
+    private _zoomIn;
+    private _zoomOut;
+    constructor(el: HTMLElement, options: Partial<MapViewOptions>);
+    static get defaults(): MapViewOptions;
+    /**
+     * Initializes instance of MapView.
+     * @param el HTML element.
+     * @param options Component options.
+     */
+    static init(el: HTMLElement, options?: Partial<MapViewOptions>): MapView;
+    /**
+     * Initializes instances of MapView.
+     * @param els HTML elements.
+     * @param options Component options.
+     */
+    static init(els: InitElements<InitElement>, options?: Partial<MapViewOptions>): MapView[];
+    static getInstance(el: HTMLElement): MapView;
+    destroy(): void;
+    /** Draws a line through `[longitude, latitude]` points. Replaces an overlay with the same id. */
+    addRoute(id: string, coordinates: LngLat[], options?: MapLineOptions): void;
+    /** Draws a curved line for each `{ from, to }`. Replaces an overlay with the same id. */
+    addArcs(id: string, arcs: MapArc[], options?: MapLineOptions): void;
+    /**
+     * Draws GeoJSON points, or the URL of a GeoJSON file, as clusters that
+     * show their count and zoom in when clicked. The layers are
+     * `${id}-clusters`, `${id}-count` and `${id}-points`.
+     */
+    addClusters(id: string, data: object | string, options?: MapClusterOptions): void;
+    /** Removes a route, arcs or clusters added with this id. */
+    removeOverlay(id: string): void;
+    private _line;
+    private _draw;
+    private _addMarker;
+    private _popup;
+    private _toggle;
+    private _buttons;
+    private _locate;
+    private _color;
+    private _isDark;
+    private _themed;
+    private _style;
+    private _handleStyleLoad;
+    private _handleScheme;
+    private _sync;
+    private _handleFullscreen;
+    private _handleClick;
+    private _handleMapClick;
+    private _handleKeydown;
+}

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

@@ -40,6 +40,13 @@ export interface MenuOptions extends BaseOptions {
      * @default false
      */
     hover: boolean;
+    /**
+     * If true, the trigger is a region and the menu is its context menu: it
+     * opens at the pointer on right-click, long-press or the keyboard context
+     * menu key instead of on click. `data-context-menu` on the trigger sets it.
+     * @default false
+     */
+    contextMenu: boolean;
     /**
      * The duration of the transition enter in milliseconds.
      * @default 150
@@ -95,6 +102,14 @@ export declare class Menu extends Component<MenuOptions> implements Openable {
     private _transition;
     private _originalInert;
     private _menuClickTargets;
+    /**
+     * Viewport point the open context menu belongs to. Null outside a
+     * right-click, so a keyboard or programmatic open uses the region's corner
+     * rather than an old pointer position.
+     */
+    private _contextPoint;
+    /** What had focus when a context menu opened; focus goes back there. */
+    private _contextReturn;
     constructor(el: HTMLElement, options: Partial<MenuOptions>);
     static get defaults(): MenuOptions;
     /**
@@ -115,6 +130,8 @@ export declare class Menu extends Component<MenuOptions> implements Openable {
     _removeEventHandlers(): void;
     _setupTemporaryEventHandlers(): void;
     _removeTemporaryEventHandlers(): void;
+    _handleContextMenu: (e: MouseEvent) => void;
+    _handleDocumentContextMenu: (e: MouseEvent) => void;
     _handleClick: (e: MouseEvent) => void;
     _handleMouseEnter: () => void;
     _handleMouseLeave: (e: MouseEvent) => void;
@@ -157,6 +174,20 @@ export declare class Menu extends Component<MenuOptions> implements Openable {
     _animateOut(): void;
     private _getClosestAncestor;
     _placeMenu(): void;
+    /** Where a context menu opens without a pointer: the region's start corner. */
+    private _regionCorner;
+    /**
+     * Places a context menu with its start corner on the point, flipping to
+     * the other side of the point where it would not fit. The bounds are the
+     * viewport, narrowed to a scrolling or clipping ancestor the menu sits in;
+     * a menu taller than them gets their height and scrolls.
+     *
+     * The menu rests at left/top 0 of its containing block, so its rect is the
+     * offset to subtract - the same trick _getMenuPosition uses. It is measured
+     * without the entry animation's scale, which a second right-click can catch.
+     */
+    private _placeMenuAtPoint;
+    private _setExpanded;
     /**
      * Open menu.
      */