@expressivecss/expressive 0.13.1 → 0.14.1

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/particles.d.ts

@@ -0,0 +1,72 @@
+import { Component, BaseOptions, InitElements, InitElement } from '../core/component';
+export interface ParticlesOptions extends BaseOptions {
+    /**
+     * Number of particles.
+     * @default 100
+     */
+    quantity: number;
+    /**
+     * How firmly particles hold their place against the pointer. Lower
+     * follows the pointer further.
+     * @default 50
+     */
+    staticity: number;
+    /**
+     * Frames a particle takes to catch up with the pointer. Higher is slower.
+     * @default 50
+     */
+    ease: number;
+    /**
+     * Base radius in pixels. Each particle adds 0 or 1 to it.
+     * @default 0.4
+     */
+    size: number;
+    /**
+     * A CSS color. Empty uses the canvas's CSS `color`, which defaults to the
+     * theme's on-surface color.
+     * @default ''
+     */
+    color: string;
+    /**
+     * Horizontal drift in pixels per frame. Negative drifts left.
+     * @default 0
+     */
+    vx: number;
+    /**
+     * Vertical drift in pixels per frame. Negative drifts up.
+     * @default 0
+     */
+    vy: number;
+}
+/**
+ * Particles. A `<canvas class="particles">` covers its nearest positioned
+ * ancestor with slowly drifting dots that lean toward the pointer. Under
+ * reduced motion the dots are drawn once and stay still.
+ */
+export declare class Particles extends Component<ParticlesOptions> {
+    el: HTMLCanvasElement;
+    private _ctx;
+    private _style;
+    private _particles;
+    private _width;
+    private _height;
+    private _frame;
+    private _last;
+    private _mouse;
+    private _still;
+    private _resizeObserver;
+    private _visibility;
+    constructor(el: HTMLElement, options: Partial<ParticlesOptions>);
+    static get defaults(): ParticlesOptions;
+    static init(el: HTMLElement, options?: Partial<ParticlesOptions>): Particles;
+    static init(els: InitElements<InitElement>, options?: Partial<ParticlesOptions>): Particles[];
+    static getInstance(el: HTMLElement): Particles;
+    destroy(): void;
+    private _start;
+    private _stop;
+    private _onPointerMove;
+    private _reset;
+    private _particle;
+    private _draw;
+    private _paint;
+}

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

@@ -15,6 +15,8 @@ export declare class PieChart extends LineChart {
     /** Each row's color, or undefined for a row with no slice. */
     private _colors;
     private _slices;
+    /** Percent formatters by fraction digits, rebuilt once per legend. */
+    private _percents;
     protected get _type(): string;
     protected get _key(): string;
     protected get _points(): boolean;
@@ -27,6 +29,7 @@ export declare class PieChart extends LineChart {
     protected _place(index: number): void;
     /** The row's share of the whole as a percentage, or '' for none. */
     private _share;
+    private _percent;
     /** The legend: every row with its color, its cell and its share. */
     protected _guides(): Element[];
     /** The row under the pointer by its angle from the middle, or -1 off the slices. */

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

@@ -43,6 +43,14 @@ export declare const AUTO_INIT_COMPONENTS: {
         component: typeof Components.Chips;
         selector: string;
     };
+    Confetti: {
+        component: typeof Components.Confetti;
+        selector: string;
+    };
+    Particles: {
+        component: typeof Components.Particles;
+        selector: string;
+    };
     ColumnChart: {
         component: typeof Components.ColumnChart;
         selector: string;

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

@@ -28,7 +28,7 @@ export declare class Slider extends Component<SliderOptions> {
     _removeEventHandlers(): void;
     _handleRangeChange: () => void;
     _handleRangePointerDown: (e: PointerEvent) => void;
-    _handleRangeInputOrMove: (e: Event) => void;
+    _handleRangeInput: () => void;
     _handleRangePointerUp: (e: PointerEvent) => void;
     _handleRangeRelease: () => void;
     _setupThumb(): void;

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

@@ -90,6 +90,8 @@ export declare class Snackbar {
     time: number;
     deltaX: number;
     velocityX: number;
+    /** Swipe distance that dismisses, measured once when the drag starts. */
+    private _activationDistance;
     private _dismissed;
     private _returnFocus;
     private _events;

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

@@ -57,7 +57,7 @@ export declare class Tabs extends Component<TabsOptions> {
     get index(): number;
     _setupEventHandlers(): void;
     _removeEventHandlers(): void;
-    _handleWindowResize: () => void;
+    _handleWindowResize: (...args: unknown[]) => void;
     _queryTabLinks(): NodeListOf<HTMLAnchorElement>;
     _handleTabClick: (e: MouseEvent) => void;
     _createIndicator(): void;

package/dist/types/modular.d.ts

@@ -5,7 +5,7 @@ export { SideSheets } from './behaviors/sideSheets';
 export { Forms } from './behaviors/forms';
 export { AutoInit } from './components/registry';
 export type { AutoInitOptions } from './components/registry';
-export declare const version = "0.13.1";
+export declare const version = "0.14.1";
 export type * from './components/autocomplete';
 export type * from './components/appBar';
 export type * from './components/buttons';

package/dist/types/plugins/dockedDisplayPlugin.d.ts

@@ -24,9 +24,9 @@ export declare class DockedDisplayPlugin {
     constructor(el: HTMLElement, container: HTMLElement, options: Partial<DockedDisplayPluginOptions>);
     private _handleDocumentClick;
     /**
-     * Tears the plugin down. The document listener holds a reference to this
-     * instance - and through it the whole picker subtree - so the owning
-     * component must call this from its own destroy().
+     * Tears the plugin down. While shown, the document listener holds a
+     * reference to this instance - and through it the whole picker subtree - so
+     * the owning component must call this from its own destroy().
      */
     destroy: () => void;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expressivecss/expressive",
-  "version": "0.13.1",
+  "version": "0.14.1",
   "description": "ExpressiveCSS - a Material Design 3 front-end framework.",
   "license": "MIT",
   "author": "BaezFJ <baezdevs@gmail.com>",
@@ -137,6 +137,7 @@
     "esbuild": "^0.28.2",
     "fallow": "^3.23.0",
     "jsdom": "^30.0.1",
+    "maplibre-gl": "^6.13.0",
     "npm-run-all2": "^9.0.3",
     "sass": "^1.102.0",
     "smol-toml": "^1.8.0",

package/src/sass/components/_buttons.scss

@@ -51,7 +51,7 @@
 // specificity; `.chip .close` would make it two and shift every button rule.
 // The delete button needs no entry: `.chip .close` is already two classes, so
 // it ties the state rules and wins on order.
-$_not-btn: ".datepicker-day-button, .date-picker-day-button, .month-prev, .month-next, .chip, .icon-button";
+$_not-btn: ".datepicker-day-button, .date-picker-day-button, .month-prev, .month-next, .chip, .icon-button, .map-marker, .maplibregl-popup-close-button, .maplibregl-ctrl-attrib-button";
 
 // `label.button` is here for the file input: the control has to be a <label>
 // so that clicking it reaches the <input type="file"> it wraps, but it is a

package/src/sass/components/_confetti.scss

@@ -0,0 +1,14 @@
+@use "../abstracts" as *;
+
+// Confetti. A <canvas class="confetti"> covers its nearest positioned
+// ancestor and lets clicks through to what is under it. The Confetti script
+// draws on it. A burst over the whole viewport needs no markup; the script
+// styles its own canvas inline.
+
+canvas.confetti {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  pointer-events: none;
+}

package/src/sass/components/_index.scss

@@ -50,6 +50,7 @@
 @forward "message";
 @forward "message-scroller";
 @forward "rich-text-editor";
+@forward "map";
 @forward "accordion";
 @forward "data-table";
 @forward "avatar";
@@ -74,3 +75,5 @@
 @forward "aura";
 @forward "kpi";
 @forward "marquee";
+@forward "confetti";
+@forward "particles";

package/src/sass/components/_map.scss

@@ -0,0 +1,188 @@
+@use "sass:map";
+@use "../abstracts" as *;
+
+// Map. A MapLibre map in a .map frame. The page loads maplibre-gl.css; these
+// rules restyle what MapLibre draws and add the ExpressiveCSS parts:
+//
+//   .map-marker    a point at data-lng-lat. With no content of its own it is
+//                  a primary dot; anything else inside replaces the dot.
+//                  A .map-marker-label shows below it (.top: above), and a
+//                  child .tooltip works as on any button.
+//   .map-popup     moved into a MapLibre popup, drawn as a surface card.
+//   .map-controls  a corner stack of .icon-button controls, top right
+//                  unless .top-left, .bottom-left or .bottom-right. A
+//                  .map-control-group joins buttons on one surface.
+//
+// Until the script starts the map, markers, popups and controls are hidden.
+// MapLibre moves markers and popups out of the frame, so the hiding rules
+// stop matching them once the map runs.
+//
+// Tokens:
+//   --md-comp-map-height              400px
+//   --md-comp-map-shape               16px
+//   --md-comp-map-marker-color        primary
+//   --md-comp-map-marker-ring-color   surface
+//   --md-comp-map-route-color         primary
+//   --md-comp-map-arc-color           tertiary
+//   --md-comp-map-cluster-color       primary
+//   --md-comp-map-cluster-label-color on-primary
+//   --md-comp-map-popup-max-width     280px
+//   --md-comp-map-control-offset      12px
+//
+// The script sets --md-comp-map-bearing, so a [data-action="compass"] icon
+// points north.
+
+.map {
+  --md-comp-map-height: 400px;
+  --md-comp-map-shape: 16px;
+  --md-comp-map-marker-color: var(--md-sys-color-primary);
+  --md-comp-map-marker-ring-color: var(--md-sys-color-surface);
+  --md-comp-map-route-color: var(--md-sys-color-primary);
+  --md-comp-map-arc-color: var(--md-sys-color-tertiary);
+  --md-comp-map-cluster-color: var(--md-sys-color-primary);
+  --md-comp-map-cluster-label-color: var(--md-sys-color-on-primary);
+  --md-comp-map-popup-max-width: 280px;
+  --md-comp-map-control-offset: 12px;
+
+  position: relative;
+  overflow: hidden;
+  block-size: var(--md-comp-map-height);
+  border-radius: var(--md-comp-map-shape);
+  background-color: var(--md-sys-color-surface-container);
+
+  &:fullscreen {
+    border-radius: 0;
+  }
+
+  > :is(.map-marker, .map-popup),
+  &:not(.maplibregl-map) > .map-controls {
+    display: none;
+  }
+}
+
+// Absolute, as MapLibre places it; a child .tooltip would otherwise make
+// the marker relative.
+.map .map-marker {
+  position: absolute;
+  display: grid;
+  place-items: center;
+  padding: 0;
+  border: none;
+  background: none;
+  color: inherit;
+  cursor: pointer;
+  @include focus-visible;
+
+  &:not(:has(> :not(.tooltip, .map-marker-label))) {
+    inline-size: 16px;
+    block-size: 16px;
+    border: 2px solid var(--md-comp-map-marker-ring-color);
+    border-radius: 50%;
+    background-color: var(--md-comp-map-marker-color);
+    @include z-depth(1);
+  }
+
+  &.location {
+    --md-comp-map-marker-color: var(--md-sys-color-tertiary);
+
+    box-shadow: 0 0 0 8px color-mix(in srgb, var(--md-comp-map-marker-color) 24%, transparent);
+    cursor: default;
+  }
+}
+
+.map-marker-label {
+  position: absolute;
+  inset-block-start: calc(100% + 4px);
+  padding: 2px 8px;
+  border-radius: 8px;
+  background-color: var(--md-sys-color-surface-container-highest);
+  color: var(--md-sys-color-on-surface);
+  @include typescale("label-medium");
+  white-space: nowrap;
+  pointer-events: none;
+
+  &.top {
+    inset-block: auto calc(100% + 4px);
+  }
+}
+
+// MapLibre's popup, as an M3 surface card. The tip is dropped; the offset
+// keeps the card clear of its marker.
+//
+// maplibre-gl.css is unlayered, so it beats this layer wherever both set a
+// property. Those declarations are !important; an important declaration in
+// a layer outranks a normal unlayered one.
+.map {
+  .maplibregl-popup-content {
+    max-inline-size: var(--md-comp-map-popup-max-width);
+    padding: 12px 16px !important;
+    border-radius: 12px !important;
+    background: var(--md-sys-color-surface-container-low) !important;
+    color: var(--md-sys-color-on-surface);
+    @include typescale("body-medium");
+    box-shadow: map.get($elevations, "2") !important;
+
+    &:has(> .maplibregl-popup-close-button) {
+      padding-inline-end: 44px;
+    }
+
+    :is(h1, h2, h3, h4, h5, h6) {
+      margin: 0 0 4px;
+      @include typescale("title-small");
+    }
+
+    p {
+      margin: 0;
+      font: inherit;
+    }
+  }
+
+  .maplibregl-popup-tip {
+    display: none;
+  }
+
+  .maplibregl-popup-close-button {
+    inset: 4px 4px auto auto !important;
+    inline-size: 32px;
+    block-size: 32px;
+    border-radius: 50% !important;
+    color: var(--md-sys-color-on-surface-variant);
+    font-size: 20px;
+    line-height: 1;
+
+    &:hover {
+      background-color: color-mix(in srgb, currentColor 8%, transparent) !important;
+    }
+
+    @include focus-visible;
+  }
+}
+
+.map-controls {
+  position: absolute;
+  inset: var(--md-comp-map-control-offset) var(--md-comp-map-control-offset) auto auto;
+  z-index: 2;
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+
+  &.top-left { inset: var(--md-comp-map-control-offset) auto auto var(--md-comp-map-control-offset); }
+  &.bottom-left { inset: auto auto var(--md-comp-map-control-offset) var(--md-comp-map-control-offset); }
+  &.bottom-right { inset: auto var(--md-comp-map-control-offset) var(--md-comp-map-control-offset) auto; }
+
+  > .icon-button,
+  > .map-control-group {
+    border-radius: 9999px;
+    background-color: var(--md-sys-color-surface-container-low);
+    @include z-depth(2);
+  }
+
+  [data-action="compass"] > .material-symbols {
+    rotate: var(--md-comp-map-bearing, 0deg);
+  }
+}
+
+.map-control-group {
+  display: flex;
+  flex-direction: column;
+}

package/src/sass/components/_particles.scss

@@ -0,0 +1,14 @@
+@use "../abstracts" as *;
+
+// Particles. A <canvas class="particles"> covers its nearest positioned
+// ancestor and lets clicks through to what is under it. The Particles script
+// paints the dots in the canvas's `color`.
+
+canvas.particles {
+  position: absolute;
+  inset: 0;
+  width: 100%;
+  height: 100%;
+  color: var(--md-sys-color-on-surface);
+  pointer-events: none;
+}

package/src/sass/components/_table_of_contents.scss

@@ -7,11 +7,13 @@
 //   --md-comp-toc-label-color
 //   --md-comp-toc-active-color
 //   --md-comp-toc-indicator
+//   --md-comp-toc-item-height   48px, the Material touch target
 
 .table-of-contents {
   --md-comp-toc-label-color: var(--md-sys-color-on-surface-variant);
   --md-comp-toc-active-color: var(--md-sys-color-primary);
   --md-comp-toc-indicator: 2px;
+  --md-comp-toc-item-height: 48px;
 
   list-style: none;
   margin: 0;
@@ -29,7 +31,7 @@
     display: inline-flex;
     align-items: center;
     box-sizing: border-box;
-    min-height: 2rem;
+    min-height: var(--md-comp-toc-item-height);
     padding-inline-start: 16px;
     border-inline-start: var(--md-comp-toc-indicator) solid transparent;
     color: var(--md-comp-toc-label-color);

package/src/sass/components/forms/_checkboxes.scss

@@ -210,11 +210,16 @@ label:has(> [type="checkbox"]:disabled):not(.switch),
 // 18dp anatomy. Exclude .switch — that file paints the track on a span.
 $_cb-span: "*:not(.switch) > [type='checkbox'] + span:not(.lever, .supporting-text, .character-counter, .file-path)";
 
+// inline-block, not inline-flex: a flex span turns each text run and link
+// inside it into its own item, which drops the spaces around a link and
+// splits "I agree to the <a>Terms</a>" into columns. The block padding
+// centers one line in the 48px target, as align-items did.
 #{$_cb-span} {
   position: relative;
-  display: inline-flex;
-  align-items: center;
+  display: inline-block;
+  box-sizing: border-box;
   min-height: 48px;
+  padding-block: calc((48px - 1lh) / 2);
   padding-left: 30px;
   cursor: pointer;
   user-select: none;