@expressivecss/expressive 0.2.0 → 0.3.0

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

@@ -6,54 +6,33 @@ export interface FloatingActionButtonOptions extends BaseOptions {
      */
     direction: 'top' | 'right' | 'bottom' | 'left';
     /**
-     * true: FAB menu appears on hover, false: FAB menu appears on click.
+     * true: FAB menu appears on hover (CSS, when the pointer can hover).
+     * false: FAB menu toggles on click. `.click-to-toggle` is the markup switch.
      * @default true
      */
     hoverEnabled: boolean;
     /**
-     * Enable transit the FAB into a toolbar on click.
+     * Expand the FAB into a toolbar on click. Prefer a hover or click menu.
+     * `.toolbar` on the element is the markup switch.
      * @default false
      */
     toolbarEnabled: boolean;
 }
+/**
+ * Speed dial around a FAB. Open/close is the `.active` class; motion is
+ * CSS. Hover is CSS (`:hover` when the pointer can hover). This class
+ * toggles the class, wires keyboard / click-outside, and stamps direction.
+ */
 export declare class FloatingActionButton extends Component<FloatingActionButtonOptions> implements Openable {
-    /**
-     * Describes open/close state of FAB.
-     */
     isOpen: boolean;
     private _anchor;
     private _menu;
-    private _floatingBtns;
-    private _floatingBtnsReverse;
-    /** Toolbar-mode backdrop, kept so closing can take it back out. */
-    private _backdrop;
-    offsetY: number;
-    offsetX: number;
-    btnBottom: number;
-    btnLeft: number;
-    btnWidth: number;
     constructor(el: HTMLElement, options: Partial<FloatingActionButtonOptions>);
     static get defaults(): FloatingActionButtonOptions;
-    /**
-     * Initializes instance of FloatingActionButton.
-     * @param el HTML element.
-     * @param options Component options.
-     */
     static init(el: HTMLElement, options?: Partial<FloatingActionButtonOptions>): FloatingActionButton;
-    /**
-     * Initializes instances of FloatingActionButton.
-     * @param els HTML elements.
-     * @param options Component options.
-     */
     static init(els: InitElements<MElement>, options?: Partial<FloatingActionButtonOptions>): FloatingActionButton[];
     static getInstance(el: HTMLElement): FloatingActionButton;
     destroy(): void;
-    _setupEventHandlers(): void;
-    _removeEventHandlers(): void;
-    _handleFABClick: () => void;
-    _handleFABKeyPress: (e: any) => void;
-    _handleFABToggle: () => void;
-    _handleDocumentClick: (e: MouseEvent) => void;
     /**
      * Open FAB.
      */
@@ -62,15 +41,12 @@ export declare class FloatingActionButton extends Component<FloatingActionButton
      * Close FAB.
      */
     close: () => void;
-    _animateInFAB(): void;
-    _animateOutFAB(): void;
-    _animateInToolbar(): void;
-    /**
-     * Reverse {@link _animateInToolbar}.
-     *
-     * Closing used to only unbind the listeners, leaving the FAB stretched
-     * across the viewport with its backdrop still in the DOM - and a fresh
-     * backdrop appended on every subsequent open.
-     */
-    _animateOutToolbar(): void;
+    private _directionFromClass;
+    private _setupEventHandlers;
+    private _removeEventHandlers;
+    private _handleFABClick;
+    private _handleAnchorKeydown;
+    private _handleDocumentKeydown;
+    private _handleDocumentClick;
+    private _toggle;
 }

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

@@ -1,47 +1,49 @@
 import { Component, BaseOptions, InitElements, MElement } from '../core/component';
 export interface CarouselOptions extends BaseOptions {
     /**
-     * Transition duration in milliseconds.
+     * Transition duration in milliseconds (coverflow). Snap mode uses CSS.
      * @default 200
      */
     duration: number;
     /**
-     * Perspective zoom. If 0, all items are the same size.
+     * Perspective zoom. If 0, all items are the same size. Coverflow only.
      * @default -100
      */
     dist: number;
     /**
-     * Set the spacing of the center item.
+     * Extra spacing on the center item. Coverflow only.
      * @default 0
      */
     shift: number;
     /**
-     * Set the padding between non center items.
+     * Padding between items that are not in the center. Coverflow only.
      * @default 0
      */
     padding: number;
     /**
-     * Set the number of visible items.
+     * How many items stay visible. Coverflow only.
      * @default 5
      */
     numVisible: number;
     /**
-     * Make the carousel a full width slider like the second example.
+     * Linear snap track instead of 3D coverflow.
+     * Also implied by `.flat` / `.carousel-slider`.
      * @default false
      */
     fullWidth: boolean;
     /**
-     * Set to true to show indicators.
+     * Show paging dots. Only drawn when there is more than one item.
      * @default false
      */
     indicators: boolean;
     /**
-     * Don't wrap around and cycle through items.
+     * Stop at the first and last items instead of wrapping. Coverflow only.
+     * Snap tracks do not wrap.
      * @default false
      */
     noWrap: boolean;
     /**
-     * Callback for when a new slide is cycled to.
+     * Called when a new item becomes the center.
      * @default null
      */
     onCycleTo: (current: Element, dragged: boolean) => void;
@@ -50,9 +52,7 @@ export declare class Carousel extends Component<CarouselOptions> {
     hasMultipleSlides: boolean;
     showIndicators: boolean;
     noWrap: boolean;
-    /** If the carousel is being clicked or tapped. */
     pressed: boolean;
-    /** If the carousel is currently being dragged. */
     dragged: boolean;
     offset: number;
     target: number;
@@ -60,7 +60,7 @@ export declare class Carousel extends Component<CarouselOptions> {
     itemWidth: number;
     itemHeight: number;
     dim: number;
-    _indicators: HTMLUListElement;
+    _indicators: HTMLUListElement | HTMLElement;
     count: number;
     verticalDragged: boolean;
     reference: number;
@@ -68,63 +68,57 @@ export declare class Carousel extends Component<CarouselOptions> {
     velocity: number;
     frame: number;
     timestamp: number;
-    ticker: ReturnType<typeof setTimeout>;
     amplitude: number;
-    /** The index of the center carousel item. */
     center: number;
     imageHeight: number;
     scrollingTimeout: ReturnType<typeof setTimeout>;
     oneTimeCallback: (current: Element, dragged: boolean) => void | null;
+    private _flat;
+    private _ownIndicators;
+    private _trackEl;
+    private _ignoreScroll;
+    private _trackRaf;
+    private _started;
+    private get _scroller();
+    private static _live;
+    private static _resizeListening;
+    private static _onResize;
     constructor(el: HTMLElement, options: Partial<CarouselOptions>);
     static get defaults(): CarouselOptions;
-    /**
-     * Initializes instance of Carousel.
-     * @param el HTML element.
-     * @param options Component options.
-     */
     static init(el: HTMLElement, options?: Partial<CarouselOptions>): Carousel;
-    /**
-     * Initializes instances of Carousel.
-     * @param els HTML elements.
-     * @param options Component options.
-     */
     static init(els: InitElements<MElement>, options?: Partial<CarouselOptions>): Carousel[];
     static getInstance(el: HTMLElement): Carousel;
     destroy(): void;
+    private _collectItems;
+    private _setupIndicators;
     _setupEventHandlers(): void;
     _removeEventHandlers(): void;
+    private _teardown;
     _handleThrottledResize: (...args: unknown[]) => any;
-    _handleCarouselTap: (e: MouseEvent | TouchEvent) => void;
-    _handleCarouselDrag: (e: MouseEvent | TouchEvent) => boolean;
-    _handleCarouselRelease: (e: MouseEvent | TouchEvent) => boolean;
-    _handleCarouselClick: (e: MouseEvent | TouchEvent) => boolean;
+    _handleCarouselTap: (e: PointerEvent) => void;
+    _handleCarouselDrag: (e: PointerEvent) => void;
+    _handleCarouselRelease: (e: PointerEvent) => void;
+    _handleCarouselClick: (e: MouseEvent) => void;
     _handleIndicatorClick: (e: Event) => void;
-    _handleIndicatorKeyPress: (e: KeyboardEvent) => void;
-    _handleIndicatorInteraction: (e: Event) => void;
+    _handleKeydown: (e: KeyboardEvent) => void;
+    _handleFlatScroll: () => void;
     _handleResize: () => void;
-    _setCarouselHeight(imageOnly?: boolean): void;
-    _xpos(e: MouseEvent | TouchEvent): number;
-    _ypos(e: MouseEvent | TouchEvent): number;
+    _xpos(e: PointerEvent | MouseEvent | TouchEvent): number;
+    _ypos(e: PointerEvent | MouseEvent | TouchEvent): number;
     _wrap(x: number): any;
     _track: () => void;
     _autoScroll: () => void;
     _scroll(x?: number): void;
     _updateItemStyle(el: HTMLElement, opacity: number, zIndex: number, transform: string): void;
+    private _paintIndicators;
+    private _syncA11y;
+    private _syncActive;
+    private _wrapTrack;
+    private _unwrapTrack;
+    private _nearestIndex;
+    private _scrollToIndex;
     _cycleTo(n: number, callback?: CarouselOptions['onCycleTo']): void;
-    /**
-     * Move carousel to next slide or go forward a given amount of slides.
-     * @param n How many times the carousel slides.
-     */
     next(n?: number): void;
-    /**
-     * Move carousel to previous slide or go back a given amount of slides.
-     * @param n How many times the carousel slides.
-     */
     prev(n?: number): void;
-    /**
-     * Move carousel to nth slide.
-     * @param n Index of slide.
-     * @param callback "onCycleTo" optional callback.
-     */
     set(n: number, callback?: CarouselOptions['onCycleTo']): void;
 }

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

@@ -46,8 +46,8 @@ export interface ChipsOptions extends BaseOptions {
      */
     limit: number;
     /**
-     * Specifies class to be used in "close" button (useful when working with Material Symbols icon set).
-     * @default 'material-icons'
+     * Specifies class to be used in "close" button.
+     * @default 'material-symbols'
      */
     closeIconClass: string;
     /**

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

@@ -1,17 +1,22 @@
 import { Component, BaseOptions, InitElements, MElement } from '../core/component';
 export interface CollapsibleOptions extends BaseOptions {
     /**
-     * If accordion versus collapsible.
+     * If accordion versus collapsible. When omitted, `.expandable` on the
+     * element turns accordion off. `<details>` with the same `name` already
+     * exclusive-open in the browser; this option is the switch for the
+     * `<ul>/<li>` alias and assigns `name` when it is missing.
      * @default true
      */
     accordion: boolean;
     /**
-     * Transition in duration in milliseconds.
+     * @deprecated Duration is CSS (`--md-comp-collapsible-duration`).
+     * Accepted so existing init calls keep compiling, and ignored.
      * @default 300
      */
     inDuration: number;
     /**
-     * Transition out duration in milliseconds.
+     * @deprecated Duration is CSS (`--md-comp-collapsible-duration`).
+     * Accepted so existing init calls keep compiling, and ignored.
      * @default 300
      */
     outDuration: number;
@@ -36,8 +41,16 @@ export interface CollapsibleOptions extends BaseOptions {
      */
     onCloseEnd: (el: Element) => void;
 }
+/**
+ * Collapsible. Open/close is HTML (`<details>` / `[open]`, or `.active` on
+ * the `<li>` alias). Height is CSS. This class is the public API, accordion
+ * for the alias, and aria on non-native headers.
+ */
 export declare class Collapsible extends Component<CollapsibleOptions> {
-    private _headers;
+    private _items;
+    private _groupName;
+    private _endTimers;
+    private _wrappedBodies;
     constructor(el: HTMLElement, options: Partial<CollapsibleOptions>);
     static get defaults(): CollapsibleOptions;
     /**
@@ -54,21 +67,30 @@ export declare class Collapsible extends Component<CollapsibleOptions> {
     static init(els: InitElements<MElement>, options?: Partial<CollapsibleOptions>): Collapsible[];
     static getInstance(el: HTMLElement): Collapsible;
     destroy(): void;
-    _setupEventHandlers(): void;
-    _removeEventHandlers(): void;
-    _handleCollapsibleClick: (e: MouseEvent | KeyboardEvent) => void;
-    _handleCollapsibleKeydown: (e: KeyboardEvent) => void;
-    private _setExpanded;
-    _animateIn(index: number): void;
-    _animateOut(index: number): void;
     /**
      * Open collapsible section.
-     * @param n Nth section to open.
+     * @param index 0-based index of the section to open.
      */
     open: (index: number) => void;
     /**
      * Close collapsible section.
-     * @param n Nth section to close.
+     * @param index 0-based index of the section to close.
      */
     close: (index: number) => void;
+    private _collectItems;
+    private _setupItems;
+    private _isOpen;
+    private _setOpen;
+    private _headerOf;
+    private _wrapDetailsBodies;
+    private _unwrapDetailsBodies;
+    private _bodyOf;
+    private _syncAria;
+    private _setupEventHandlers;
+    private _removeEventHandlers;
+    private _handleClick;
+    private _handleKeydown;
+    private _handleToggle;
+    private _notify;
+    private _durationMs;
 }

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

@@ -1,46 +1,22 @@
 import { Component, BaseOptions, InitElements, MElement } from '../core/component';
 export interface ParallaxOptions extends BaseOptions {
     /**
-     * The minimum width of the screen, in pixels, where the parallax functionality starts working.
+     * @deprecated Motion is CSS (`animation-timeline: view()`). This value
+     * is accepted so existing AutoInit calls keep compiling, and is ignored.
      * @default 0
      */
     responsiveThreshold: number;
 }
+/**
+ * Parallax. The effect is CSS (see components/_parallax.scss). This class
+ * exists so AutoInit / getInstance / destroy keep working; it does not
+ * attach scroll or resize listeners.
+ */
 export declare class Parallax extends Component<ParallaxOptions> {
-    private _enabled;
-    private _img;
-    static _parallaxes: Parallax[];
-    static _handleWindowResizeThrottled: (...args: unknown[]) => void;
-    private static _scrollFrame;
     constructor(el: HTMLElement, options: Partial<ParallaxOptions>);
     static get defaults(): ParallaxOptions;
-    /**
-     * Initializes instance of Parallax.
-     * @param el HTML element.
-     * @param options Component options.
-     */
     static init(el: HTMLElement, options?: Partial<ParallaxOptions>): Parallax;
-    /**
-     * Initializes instances of Parallax.
-     * @param els HTML elements.
-     * @param options Component options.
-     */
     static init(els: InitElements<MElement>, options?: Partial<ParallaxOptions>): Parallax[];
     static getInstance(el: HTMLElement): Parallax;
     destroy(): void;
-    static _handleScroll(): void;
-    /**
-     * Coalesce scroll events onto animation frames.
-     *
-     * The handler reads layout and then writes a transform, so running it more
-     * than once per frame is wasted work - and the 5ms throttle it replaces was
-     * short enough to let several run per frame anyway.
-     */
-    static _requestScrollUpdate: () => void;
-    static _handleWindowResize(): void;
-    _setupEventHandlers(): void;
-    _removeEventHandlers(): void;
-    _setupStyles(): void;
-    _handleImageLoad: () => void;
-    _updateParallax(): void;
 }

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

@@ -11,42 +11,29 @@ export interface TapTargetOptions extends BaseOptions {
      */
     onClose: (origin: HTMLElement) => void;
 }
+/**
+ * Tap target (Feature Discovery). Placement is CSS custom properties;
+ * the wrapper is a popover when the platform has one. This class is
+ * open/close, origin lookup, and the two geometry variables.
+ */
 export declare class TapTarget extends Component<TapTargetOptions> implements Openable {
-    /**
-     * If the tap target is open.
-     */
     isOpen: boolean;
+    originEl: HTMLElement | null;
     static _taptargets: TapTarget[];
     private wrapper;
-    private originEl;
     private waveEl;
     private contentEl;
+    private _createdWrapper;
+    private _createdWave;
+    private _usePopover;
+    private _liftedStatic;
+    private _opening;
     constructor(el: HTMLElement, options: Partial<TapTargetOptions>);
     static get defaults(): TapTargetOptions;
-    /**
-     * Initializes instance of TapTarget.
-     * @param el HTML element.
-     * @param options Component options.
-     */
     static init(el: HTMLElement, options?: Partial<TapTargetOptions>): TapTarget;
-    /**
-     * Initializes instances of TapTarget.
-     * @param els HTML elements.
-     * @param options Component options.
-     */
     static init(els: InitElements<MElement>, options?: Partial<TapTargetOptions>): TapTarget[];
     static getInstance(el: HTMLElement): TapTarget;
     destroy(): void;
-    _setupEventHandlers(): void;
-    _removeEventHandlers(): void;
-    _handleThrottledResize: (...args: unknown[]) => any;
-    _handleKeyboardInteraction: (e: KeyboardEvent) => void;
-    _handleTargetToggle: () => void;
-    _handleResize: () => void;
-    _handleDocumentClick: (e: MouseEvent | TouchEvent | KeyboardEvent) => void;
-    _setup(): void;
-    private _offset;
-    _calculatePositioning(): void;
     /**
      * Open Tap Target.
      */
@@ -55,4 +42,16 @@ export declare class TapTarget extends Component<TapTargetOptions> implements Op
      * Close Tap Target.
      */
     close: () => void;
+    private _setup;
+    private _ensureId;
+    private _labelFromHeading;
+    private _teardownDom;
+    private _setupEventHandlers;
+    private _removeEventHandlers;
+    private _handleThrottledResize;
+    private _handleOriginKeydown;
+    private _handleTargetToggle;
+    private _handleResize;
+    private _handlePopoverToggle;
+    private _calculatePositioning;
 }

package/dist/types/index.d.ts

@@ -4,4 +4,4 @@ export { Forms } from './behaviors/forms';
 export { Waves } from './behaviors/waves';
 export { AutoInit } from './components/registry';
 export type { AutoInitOptions } from './components/registry';
-export declare const version = "0.2.0";
+export declare const version = "0.3.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expressivecss/expressive",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "ExpressiveCSS - a Material Design 3 front-end framework.",
   "license": "MIT",
   "author": "BaezFJ <baezdevs@gmail.com>",

package/src/sass/README.md

@@ -195,6 +195,7 @@ unlayered declaration. Drop the flag from `.hide` and it stops beating a
 consumer's own `display` — silently, and in the common case. Classes whose whole
 job is to be unconditional (`.hide`, `.m-3`, the palette classes) keep it.
 
-The `!important` in `components/` is a different thing again: `.pushpin`,
-`.tap-target` and the preloader set JS-driven geometry that must not be
-overridable. Those stay too.
+The `!important` in `components/` is a different thing again: `.pushpin`
+and the preloader set JS-driven geometry that must not be overridable.
+Those stay. Tap target placement is custom properties now, so it no
+longer needs the flag.

package/src/sass/components/_badges.scss

@@ -48,9 +48,10 @@ header:has(> nav) nav a span.badge {
   -webkit-font-smoothing: auto;
 }
 
-// Line height centering
-.collection-item span.badge {
-  margin-top: calc(calc(1.5rem * 0.5) - calc(var(--bagde-height) * 0.5));
+.collection span.badge {
+  float: none;
+  margin-block: 0;
+  margin-inline-start: auto;
 }
 
 .collapsible span.badge {
@@ -62,7 +63,7 @@ header:has(> nav) nav a span.badge {
   }
 }
 
-.collapsible .active span.badge:not(.new) {
+.collapsible :is(.active, [open]) span.badge:not(.new) {
   color: var(--md-sys-color-on-surface-variant);
 }
 

package/src/sass/components/_breadcrumb.scss

@@ -1,29 +1,106 @@
 @use "../abstracts" as *;
 
+// Breadcrumbs. Anatomy is the HTML: a <nav> whose child is an <ol> of
+// links. The last crumb is the current page (aria-current="page").
+// .breadcrumb / .breadcrumb-wrapper stay as aliases.
+//
+// Tokens:
+//   --md-comp-breadcrumb-label-color      ancestors
+//   --md-comp-breadcrumb-current-color    current page
+//   --md-comp-breadcrumb-separator        "/"
+//   --md-comp-breadcrumb-gap              8px
+//
+// Nest descendants inside this block. `#{$_crumb} > ol` would only attach
+// `> ol` to the last item in the list (same bug as the icon size classes).
+
+nav:has(> ol):not(.pagination),
+nav:has(> .breadcrumb),
 .breadcrumb-wrapper {
+  --md-comp-breadcrumb-label-color: var(--md-sys-color-on-surface-variant);
+  --md-comp-breadcrumb-current-color: var(--md-sys-color-on-surface);
+  --md-comp-breadcrumb-separator: "/";
+  --md-comp-breadcrumb-gap: 8px;
+
   display: flex;
+  flex-wrap: wrap;
   align-items: center;
-}
+  margin: 0;
+  padding: 0;
+  color: var(--md-comp-breadcrumb-label-color);
+  @include typescale("body-small");
 
-.breadcrumb {
-  display: inline-flex;
-  align-items: center;
+  &.nowrap {
+    flex-wrap: nowrap;
+    overflow-x: auto;
+    scrollbar-width: none;
+
+    &::-webkit-scrollbar {
+      display: none;
+    }
+  }
+
+  > ol {
+    display: flex;
+    flex-wrap: inherit;
+    align-items: center;
+    list-style: none;
+    min-width: 0;
+    margin: 0;
+    padding: 0;
+
+    > li {
+      display: inline-flex;
+      align-items: center;
+      min-width: 0;
+    }
 
-  i,
-  i.material-icons, i.material-symbols-outlined,
-  i.material-symbols-rounded, i.material-symbols-sharp,
-  &:before {
-    font-weight: normal;
-    font-style: normal;
-    font-size: 24px;
+    > li:has(> [aria-current="page"]) {
+      flex-shrink: 0;
+    }
+
+    // Separator before every crumb after the first. A real character, not
+    // a private-use icon-font slot — no Symbols file required.
+    > li + li::before {
+      content: var(--md-comp-breadcrumb-separator);
+      margin-inline: var(--md-comp-breadcrumb-gap);
+      color: var(--md-comp-breadcrumb-label-color);
+    }
+  }
+
+  > .breadcrumb + .breadcrumb::before {
+    content: var(--md-comp-breadcrumb-separator);
+    margin-inline: var(--md-comp-breadcrumb-gap);
+    color: var(--md-comp-breadcrumb-label-color);
+  }
+
+  :is(a, .breadcrumb) {
+    display: inline-flex;
+    align-items: center;
+    min-height: 32px;
+    color: var(--md-comp-breadcrumb-label-color);
+    text-decoration: none;
+    @include focus-visible;
+
+    &:hover {
+      color: var(--md-comp-breadcrumb-current-color);
+    }
   }
 
-  &:before {
-    content: '\E5CC';
-    font-family: 'Material Symbols Outlined', 'Material Symbols Rounded', 'Material Symbols Sharp', 'Material Icons';
+  [aria-current="page"] {
+    color: var(--md-comp-breadcrumb-current-color);
   }
 
-  &:first-child:before {
-    visibility: hidden;
+  i {
+    font-size: 1.125em;
+    margin-inline-end: 4px;
   }
 }
+
+// Inside a top app bar the trail follows the bar, not the muted ancestor
+// pair. Loose .breadcrumb links in the bar are already excluded from
+// destination styling in _navbar.scss.
+header:has(> nav) > nav:has(> ol):not(.pagination),
+header:has(> nav) > nav:has(> .breadcrumb) {
+  --md-comp-breadcrumb-label-color: inherit;
+  --md-comp-breadcrumb-current-color: inherit;
+}