@expressivecss/expressive 0.3.0 → 0.5.0

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

@@ -1,12 +1,8 @@
-import { Component, BaseOptions, InitElements, MElement } from '../core/component';
+import { Component, BaseOptions, InitElements, InitElement } from '../core/component';
 export interface ScrollSpyOptions extends BaseOptions {
     /**
-     * Throttle of scroll handler.
-     * @default 100
-     */
-    throttle: number;
-    /**
-     * Offset for centering element when scrolled to.
+     * Offset used as IntersectionObserver rootMargin and as
+     * `--md-comp-scrollspy-offset` (scroll-margin on the section).
      * @default 200
      */
     scrollOffset: number;
@@ -16,62 +12,42 @@ export interface ScrollSpyOptions extends BaseOptions {
      */
     activeClass: string;
     /**
-     * Used to find active element.
+     * Returns a CSS selector for the TOC link. The default is unused: links
+     * are found by comparing `a[href^="#"]` to `#id`. A custom function
+     * still runs through `querySelector` (escape any author id yourself).
      * @default id => 'a[href="#' + id + '"]'
      */
     getActiveElement: (id: string) => string;
     /**
-     * Used to keep last top element active even if
-     * scrollbar goes outside of scrollspy elements.
-     *
-     * If there is no last top element,
-     * then the active one will be the first element.
-     *
+     * If true, keep the last section above the viewport active when nothing
+     * intersects. If there is no such section, the first one stays active.
      * @default false
      */
     keepTopElementActive: boolean;
-    /**
-     * Used to set scroll animation duration in milliseconds.
-     * @default null (browser's native animation implementation/duration)
-     */
-    animationDuration: number | null;
 }
+/**
+ * ScrollSpy. IntersectionObserver decides which section is current.
+ * Hash links are left to the browser (`scroll-margin` + `scroll-behavior`).
+ */
 export declare class ScrollSpy extends Component<ScrollSpyOptions> {
     static _elements: ScrollSpy[];
-    static _count: number;
-    static _increment: number;
-    static _elementsInView: ScrollSpy[];
-    static _visibleElements: HTMLElement[];
-    static _ticks: number;
-    static _keptTopActiveElement: HTMLElement | null;
-    private static _throttledScroll;
-    private static _throttledResize;
-    private tickId;
-    private id;
+    private static _observer;
+    private static _ratios;
+    private static _active;
     constructor(el: HTMLElement, options: Partial<ScrollSpyOptions>);
     static get defaults(): ScrollSpyOptions;
-    /**
-     * Initializes instance of ScrollSpy.
-     * @param el HTML element.
-     * @param options Component options.
-     */
     static init(el: HTMLElement, options?: Partial<ScrollSpyOptions>): ScrollSpy;
-    /**
-     * Initializes instances of ScrollSpy.
-     * @param els HTML elements.
-     * @param options Component options.
-     */
-    static init(els: InitElements<MElement>, options?: Partial<ScrollSpyOptions>): ScrollSpy[];
+    static init(els: InitElements<InitElement>, options?: Partial<ScrollSpyOptions>): ScrollSpy[];
     static getInstance(el: HTMLElement): ScrollSpy;
     destroy(): void;
-    _setupEventHandlers(): void;
-    _removeEventHandlers(): void;
-    static _handleTriggerClick: (e: MouseEvent) => void;
-    static _handleWindowScroll: () => void;
-    static _findElements(top: number, right: number, bottom: number, left: number): ScrollSpy[];
-    _enter(): void;
-    _exit(): void;
-    private static _resetKeptTopActiveElement;
-    private static _getDistanceToViewport;
-    private static _smoothScrollIntoView;
+    private static _ensureObserver;
+    private static _onIntersect;
+    private static _syncActive;
+    private static _nearestAbove;
+    private static _clearActive;
+    /**
+     * Default lookup compares href attributes (no interpolated selector).
+     * A custom getActiveElement still returns a selector.
+     */
+    static _linkFor(id: string, options: ScrollSpyOptions): Element | null;
 }

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

@@ -1,5 +1,5 @@
-import { Dropdown, DropdownOptions } from './dropdown';
-import { Component, BaseOptions, InitElements, MElement } from '../core/component';
+import { Menu, MenuOptions } from './menu';
+import { Component, BaseOptions, InitElements, InitElement } from '../core/component';
 export interface FormSelectOptions extends BaseOptions {
     /**
      * Classes to be added to the select wrapper element.
@@ -7,10 +7,10 @@ export interface FormSelectOptions extends BaseOptions {
      */
     classes: string;
     /**
-     * Pass options object to select dropdown initialization.
+     * Pass options object to select menu initialization.
      * @default {}
      */
-    dropdownOptions: Partial<DropdownOptions>;
+    menuOptions: Partial<MenuOptions>;
 }
 type ValueStruct = {
     el: HTMLOptionElement;
@@ -25,16 +25,18 @@ export declare class FormSelect extends Component<FormSelectOptions> {
      * Is "null", if not detected.
      */
     labelEl: HTMLLabelElement;
-    /** Dropdown UL element. */
-    dropdownOptions: HTMLUListElement;
+    /** The generated menu element. */
+    menuEl: HTMLElement;
     /** Text input that shows current selected option. */
     input: HTMLInputElement;
-    /** Instance of the dropdown plugin for this select. */
-    dropdown: Dropdown;
-    /** The select wrapper element. */
+    /** Instance of the menu plugin for this select. */
+    menu: Menu;
+    /** The field wrapper around the native select. */
     wrapper: HTMLDivElement;
     selectOptions: (HTMLOptionElement | HTMLOptGroupElement)[];
     private _values;
+    private _createdWrapper;
+    private _originalLabelFor;
     nativeTabIndex: number;
     constructor(el: HTMLSelectElement, options: FormSelectOptions);
     static get defaults(): FormSelectOptions;
@@ -49,28 +51,40 @@ export declare class FormSelect extends Component<FormSelectOptions> {
      * @param els HTML elements.
      * @param options Component options.
      */
-    static init(els: InitElements<HTMLSelectElement | MElement>, options?: Partial<FormSelectOptions>): FormSelect[];
+    static init(els: InitElements<HTMLSelectElement | InitElement>, options?: Partial<FormSelectOptions>): FormSelect[];
     static getInstance(el: HTMLElement): FormSelect;
     destroy(): void;
     /**
-     * Re-read the native `<select>` and update the generated dropdown to match.
+     * Re-read the native `<select>` and update the generated menu to match.
      *
      * Assigning `select.value` from script fires no `change` event, so nothing
      * else syncs the visible input text or the `.selected` state on the virtual
-     * options. Call this after mutating the underlying select programmatically.
+     * options. Adding or removing `<option>`s also requires this — the menu is
+     * rebuilt from the native list, the field and Menu instance stay put.
      */
     refresh(): void;
     _setupEventHandlers(): void;
     _removeEventHandlers(): void;
+    private _setupOptionHandlers;
+    private _removeOptionHandlers;
     _handleSelectChange: () => void;
     _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;
-    _setupDropdown(): void;
+    _setupMenu(): void;
+    private _setupWrapper;
+    private _hideNativeSelect;
+    private _buildInput;
+    private _buildCaret;
+    private _initMenu;
+    private _nativeOptions;
+    private _buildOptions;
+    private _rebuildOptions;
     _addOptionToValues(realOption: HTMLOptionElement, virtualOption: HTMLElement): void;
-    _removeDropdown(): void;
+    _removeMenu(): void;
     _createAndAppendOptionWithIcon(realOption: HTMLOptionElement | HTMLOptGroupElement, type: string): HTMLLIElement;
     _selectValue(value: ValueStruct): void;
     _deselectValue(value: ValueStruct): void;

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

@@ -1,4 +1,4 @@
-import { Component, BaseOptions, InitElements, MElement, Openable } from '../core/component';
+import { Component, BaseOptions, InitElements, InitElement, Openable } from '../core/component';
 export interface SidenavOptions extends BaseOptions {
     /**
      * Side of screen on which Sidenav appears.
@@ -15,21 +15,6 @@ export interface SidenavOptions extends BaseOptions {
      * @default '10px'
      */
     dragTargetWidth: string;
-    /**
-     * Length in ms of enter transition.
-     * @default 250
-     */
-    inDuration: number;
-    /**
-     * Length in ms of exit transition.
-     * @default 200
-     */
-    outDuration: number;
-    /**
-     * Prevent page from scrolling while sidenav is open.
-     * @default true
-     */
-    preventScrolling: boolean;
     /**
      * Function called when sidenav starts entering.
      */
@@ -47,27 +32,30 @@ export interface SidenavOptions extends BaseOptions {
      */
     onCloseEnd: (elem: HTMLElement) => void;
 }
+/**
+ * Navigation drawer. Overlay is a modal <dialog>; fixed is a breakpoint.
+ * JS opens/closes, handles the trigger, and writes --md-comp-nav-drawer-shift
+ * while dragging. CSS owns the slide, the scrim, and the large-screen dock.
+ */
 export declare class Sidenav extends Component<SidenavOptions> implements Openable {
     id: string;
-    /** Describes open/close state of Sidenav. */
+    /** Describes open/close state of the overlay drawer. */
     isOpen: boolean;
-    /** Describes if sidenav is fixed. */
+    /** Describes if sidenav has sidenav-fixed. */
     isFixed: boolean;
     /** Describes if Sidenav is being dragged. */
     isDragged: boolean;
-    lastWindowWidth: number;
-    lastWindowHeight: number;
     static _sidenavs: Sidenav[];
-    private _overlay;
-    dragTarget: Element;
+    dragTarget: HTMLElement | null;
+    private _dialog;
+    private _createdDialog;
+    private _closing;
+    private _mql;
     private _startingXpos;
     private _xPos;
-    private _time;
     private _width;
     private _initialScrollTop;
     private _verticallyScrolling;
-    private deltaX;
-    private velocityX;
     private percentOpen;
     constructor(el: HTMLElement, options: Partial<SidenavOptions>);
     static get defaults(): SidenavOptions;
@@ -82,44 +70,41 @@ export declare class Sidenav extends Component<SidenavOptions> implements Openab
      * @param els HTML elements.
      * @param options Component options.
      */
-    static init(els: InitElements<MElement>, options?: Partial<SidenavOptions>): Sidenav[];
+    static init(els: InitElements<InitElement>, options?: Partial<SidenavOptions>): Sidenav[];
     static getInstance(el: HTMLElement): Sidenav;
     destroy(): void;
-    private _createOverlay;
+    /**
+     * Opens the overlay drawer. No-op while the sidenav is docked
+     * (sidenav-fixed at the large breakpoint).
+     */
+    open: () => void;
+    /**
+     * Closes the overlay drawer. No-op while the sidenav is docked.
+     */
+    close: () => void;
+    private _beginClose;
+    private _finishClose;
+    private _onDialogClose;
+    private _onBreakpointChange;
+    private _setupDialog;
+    private _unwrapDialog;
+    private _createDragTarget;
+    private _removeDragTarget;
+    private _setupClasses;
     private _setupEventHandlers;
     private _removeEventHandlers;
-    private _handleTriggerClick;
+    private static _handleTriggerClick;
+    private _handleCloseTriggerClick;
+    private _isDraggable;
+    private _isCurrentlyFixed;
     private _startDrag;
     private _dragMoveUpdate;
+    private _rawDelta;
+    private _applyShift;
+    private _clearShift;
     private _handleDragTargetDrag;
     private _handleDragTargetRelease;
     private _handleCloseDrag;
-    private _calculateDelta;
     private _handleCloseRelease;
-    private _handleCloseTriggerClick;
-    private _handleWindowResize;
-    private _setupClasses;
-    private _removeClasses;
-    private _setupFixed;
-    private _isDraggable;
-    private _isCurrentlyFixed;
-    private _createDragTarget;
-    private _preventBodyScrolling;
-    private _enableBodyScrolling;
-    /**
-     * Opens Sidenav.
-     */
-    open: () => void;
-    /**
-     * Closes Sidenav.
-     */
-    close: () => void;
-    private _animateIn;
-    private _animateOut;
-    private _animateSidenavIn;
-    private _animateSidenavOut;
-    private _animateOverlayIn;
-    private _animateOverlayOut;
-    private _setAriaHidden;
-    private _setTabIndex;
+    private _syncTriggers;
 }

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

@@ -1,4 +1,4 @@
-import { Component, BaseOptions, InitElements, MElement } from '../core/component';
+import { Component, BaseOptions, InitElements, InitElement } from '../core/component';
 export interface SliderOptions extends BaseOptions {
     /**
      * Set to false to hide slide indicators.
@@ -65,7 +65,7 @@ export declare class Slider extends Component<SliderOptions> {
      * @param els HTML elements.
      * @param options Component options.
      */
-    static init(els: InitElements<MElement>, options?: Partial<SliderOptions>): Slider[];
+    static init(els: InitElements<InitElement>, options?: Partial<SliderOptions>): Slider[];
     static getInstance(el: HTMLElement): Slider;
     destroy(): void;
     private _setupEventHandlers;

package/dist/types/components/{toasts.d.ts → snackbar.d.ts}

@@ -1,7 +1,7 @@
 import { BaseOptions } from '../core/component';
-export interface ToastOptions extends BaseOptions {
+export interface SnackbarOptions extends BaseOptions {
     /**
-     * The content of the Toast.
+     * The content of the Snackbar.
      * @default ""
      */
     text: string;
@@ -11,7 +11,7 @@ export interface ToastOptions extends BaseOptions {
      */
     action: string;
     /**
-     * Called when the action button is pressed. The toast still dismisses.
+     * Called when the action button is pressed. The snackbar still dismisses.
      * @default null
      */
     onAction: () => void;
@@ -21,12 +21,14 @@ export interface ToastOptions extends BaseOptions {
      */
     dismissible: boolean;
     /**
-     * Element Id for the tooltip.
+     * Element id of a `<template>` (or another element) used as the snackbar body.
      * @default ""
      */
-    toastId?: string;
+    snackbarId?: string;
     /**
-     * Length in ms the Toast stays before dismissal.
+     * Length in ms the Snackbar stays before dismissal.
+     * `Infinity` keeps it on screen until the user acts.
+     * When `action` is set and this is omitted, the default is 10000.
      * @default 4000
      */
     displayLength: number;
@@ -41,38 +43,38 @@ export interface ToastOptions extends BaseOptions {
      */
     outDuration: number;
     /**
-     * Classes to be added to the toast element.
+     * Classes to be added to the snackbar element.
      * @default ""
      */
     classes: string;
     /**
-     * Callback function called when toast is dismissed.
+     * Callback function called when the snackbar is dismissed.
      * @default null
      */
     completeCallback: () => void;
     /**
-     * The percentage of the toast's width it takes fora drag
-     * to dismiss a Toast.
+     * The percentage of the snackbar's width it takes for a drag
+     * to dismiss a Snackbar.
      * @default 0.8
      */
     activationPercent: number;
 }
-export declare class Toast {
-    /** The toast element. */
+export declare class Snackbar {
+    /** The snackbar element. */
     el: HTMLElement;
     /**
-     * The remaining amount of time in ms that the toast
+     * The remaining amount of time in ms that the snackbar
      * will stay before dismissal.
      */
     timeRemaining: number;
     /**
-     * Describes the current pan state of the Toast.
+     * Describes the current pan state of the Snackbar.
      */
     panning: boolean;
-    options: ToastOptions;
+    options: SnackbarOptions;
     message: string;
     counterTimeout: ReturnType<typeof setTimeout>;
-    /** Wall-clock time the toast is due to dismiss, for pause/resume. */
+    /** Wall-clock time the snackbar is due to dismiss, for pause/resume. */
     private _deadline;
     wasSwiped: boolean;
     startingXPos: number;
@@ -80,12 +82,13 @@ export declare class Toast {
     time: number;
     deltaX: number;
     velocityX: number;
-    static _toasts: Toast[];
+    private _dismissed;
+    static _snackbars: Snackbar[];
     static _container: HTMLElement;
-    static _draggedToast: Toast;
-    constructor(options: Partial<ToastOptions>);
-    static get defaults(): ToastOptions;
-    static getInstance(el: HTMLElement): Toast;
+    static _draggedSnackbar: Snackbar;
+    constructor(options?: Partial<SnackbarOptions>);
+    static get defaults(): SnackbarOptions;
+    static getInstance(el: HTMLElement): Snackbar;
     static _createContainer(): void;
     static _removeContainer(): void;
     static _onDragStart(e: TouchEvent | MouseEvent): void;
@@ -93,16 +96,16 @@ export declare class Toast {
     static _onDragEnd(): void;
     static _xPos(e: TouchEvent | MouseEvent): number;
     /**
-     * dismiss all toasts.
+     * dismiss all snackbars.
      */
     static dismissAll(): void;
-    _createToast(): HTMLElement;
+    _createSnackbar(): HTMLElement;
     _animateIn(): void;
     /**
      * Arm the dismissal timer.
      *
      * One timeout, not a 20ms interval ticking a counter down: the old form woke
-     * the page up 50 times a second per toast purely to subtract 20 from a
+     * the page up 50 times a second per snackbar purely to subtract 20 from a
      * number. Dragging pauses the countdown via _pauseTimer/_resumeTimer instead.
      */
     _setTimer(): void;
@@ -111,7 +114,7 @@ export declare class Toast {
     /** Restart a countdown stopped by {@link _pauseTimer}. */
     _resumeTimer(): void;
     /**
-     * Dismiss toast with animation.
+     * Dismiss snackbar with animation.
      */
     dismiss(): void;
 }

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

@@ -1,5 +1,5 @@
 import { Carousel } from './carousel';
-import { Component, BaseOptions, InitElements, MElement } from '../core/component';
+import { Component, BaseOptions, InitElements, InitElement } from '../core/component';
 export interface TabsOptions extends BaseOptions {
     /**
      * Transition duration in milliseconds.
@@ -46,7 +46,7 @@ export declare class Tabs extends Component<TabsOptions> {
      * @param els HTML elements.
      * @param options Component options.
      */
-    static init(els: InitElements<MElement>, options?: Partial<TabsOptions>): Tabs[];
+    static init(els: InitElements<InitElement>, options?: Partial<TabsOptions>): Tabs[];
     static getInstance(el: HTMLElement): Tabs;
     destroy(): void;
     /**

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

@@ -1,4 +1,4 @@
-import { Component, BaseOptions, InitElements, MElement, I18nOptions } from '../core/component';
+import { Component, BaseOptions, InitElements, InitElement, I18nOptions } from '../core/component';
 export type Views = 'hours' | 'minutes';
 export interface TimepickerOptions extends BaseOptions {
     /**
@@ -158,7 +158,7 @@ export declare class Timepicker extends Component<TimepickerOptions> {
      * @param els HTML elements.
      * @param options Component options.
      */
-    static init(els: InitElements<HTMLInputElement | MElement>, options?: Partial<TimepickerOptions>): Timepicker[];
+    static init(els: InitElements<HTMLInputElement | InitElement>, options?: Partial<TimepickerOptions>): Timepicker[];
     static _addLeadingZero(num: number): string;
     static _createSVGEl(name: string): SVGElement;
     static _Pos(e: TouchEvent | MouseEvent): Point;
@@ -209,7 +209,5 @@ export declare class Timepicker extends Component<TimepickerOptions> {
     confirm: () => void;
     cancel: () => void;
     clear: () => void;
-    open(): this;
-    close(): this;
 }
 export {};

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

@@ -1,4 +1,4 @@
-import { Component, BaseOptions, InitElements, MElement } from '../core/component';
+import { Component, BaseOptions, InitElements, InitElement } from '../core/component';
 export type TooltipPosition = 'top' | 'right' | 'bottom' | 'left';
 export interface TooltipOptions extends BaseOptions {
     /**
@@ -84,7 +84,7 @@ export declare class Tooltip extends Component<TooltipOptions> {
      * @param els HTML elements.
      * @param options Component options.
      */
-    static init(els: InitElements<MElement>, options?: Partial<TooltipOptions>): Tooltip[];
+    static init(els: InitElements<InitElement>, options?: Partial<TooltipOptions>): Tooltip[];
     static getInstance(el: HTMLElement): Tooltip;
     destroy(): void;
     _appendTooltipEl(): void;

package/dist/types/core/component.d.ts

@@ -3,8 +3,8 @@
  */
 export interface BaseOptions {
 }
-export type MElement = HTMLElement | Element;
-export type InitElements<T extends MElement> = NodeListOf<T> | HTMLCollectionOf<T>;
+export type InitElement = HTMLElement | Element;
+export type InitElements<T extends InitElement> = NodeListOf<T> | HTMLCollectionOf<T>;
 type ComponentConstructor<T extends Component<O>, O extends BaseOptions> = {
     new (el: HTMLElement, options: Partial<O>): T;
 };
@@ -48,14 +48,14 @@ export declare class Component<O extends BaseOptions> {
      * @param options Component options.
      * @param classDef Class definition.
      */
-    protected static init<I extends MElement, O extends BaseOptions, C extends Component<O>>(els: InitElements<I>, options: Partial<O>, classDef: ComponentType<C, O>): C[];
+    protected static init<I extends InitElement, O extends BaseOptions, C extends Component<O>>(els: InitElements<I>, options: Partial<O>, classDef: ComponentType<C, O>): C[];
     /**
      * Initializes component instances.
      * @param els HTML elements.
      * @param options Component options.
      * @param classDef Class definition.
      */
-    protected static init<I extends MElement, O extends BaseOptions, C extends Component<O>>(els: I | InitElements<I>, options: Partial<O>, classDef: ComponentType<C, O>): C | C[];
+    protected static init<I extends InitElement, O extends BaseOptions, C extends Component<O>>(els: I | InitElements<I>, options: Partial<O>, classDef: ComponentType<C, O>): C | C[];
     /**
      * @returns default options for component instance.
      */

package/dist/types/index.d.ts

@@ -1,7 +1,9 @@
 export * from './components';
 export { Dialogs } from './behaviors/dialogs';
+export { BottomSheets } from './behaviors/bottomSheets';
+export { SideSheets } from './behaviors/sideSheets';
 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.3.0";
+export declare const version = "0.5.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@expressivecss/expressive",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "ExpressiveCSS - a Material Design 3 front-end framework.",
   "license": "MIT",
   "author": "BaezFJ <baezdevs@gmail.com>",
@@ -50,7 +50,8 @@
   },
   "files": [
     "dist",
-    "src/sass"
+    "src/sass",
+    "CHANGELOG.md"
   ],
   "publishConfig": {
     "access": "public"
@@ -69,7 +70,7 @@
     "build:js:iife-min": "esbuild src/ts/index.ts --bundle --format=iife --global-name=Expressive --target=es2020 --outfile=dist/js/expressive.min.js --minify --sourcemap",
     "build:types": "tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "run-s build:js test:run",
+    "test": "run-s build:js build:css test:run",
     "test:run": "node --test",
     "test:watch": "node --test --watch",
     "watch": "run-p watch:css watch:js",

package/src/sass/README.md

@@ -65,7 +65,7 @@ fine — it crosses no boundary.
 
 ## Breakpoints
 
-Three of them, in `abstracts/_breakpoints.scss`, reached through mixins:
+Four of them, in `abstracts/_breakpoints.scss`, reached through mixins:
 
 ```scss
 @include bp-up("small")   { }   // @media (width >= 601px)
@@ -73,14 +73,13 @@ Three of them, in `abstracts/_breakpoints.scss`, reached through mixins:
 @include bp-between("small", "large") { }
 ```
 
-Names are `small` (601px), `large` (993px), `xlarge` (1201px) — the boundary a
-query sits on, not the size of the screen it targets. Range syntax has an
-exclusive comparator, so the old `600.99px` / `992.99px` values used to stop
-`max-width` and `min-width` both matching on the boundary pixel are gone, and
-each boundary is written once.
-
-The interpolated-string form (`@media #{$medium-and-up}`) still compiles and now
-produces the same range queries, but it is deprecated and unused in here.
+Names are `small` (601px), `large` (993px), `xlarge` (1201px), `xxlarge`
+(1601px) — the boundary a query sits on, not the size of the screen it
+targets. `xxlarge` is M3 extra-large (desktop / widescreen); the 12-column
+grid grows a `.xxl` prefix there, and `.container` lifts its 1280px cap to
+1920px. Range syntax has an exclusive comparator, so the old `600.99px` /
+`992.99px` values used to stop `max-width` and `min-width` both matching on
+the boundary pixel are gone, and each boundary is written once.
 
 ## Theming
 
@@ -162,7 +161,7 @@ A rule is a **utility** when it is one job, one class, and independent of any
 component (`.hide`, `.m-3`, `.truncate`). It belongs in **base** when it styles
 bare elements (`a`, `table`, `blockquote`), and in **components** when it only
 exists to serve one widget — including widgets whose CSS is driven by
-JavaScript rather than by a user-applied class (`.pinned`, `.display-docked`,
+JavaScript rather than by a user-applied class (`.display-docked`,
 `ul.staggered-list li`). If a selector in `base/` names a component, it is in
 the wrong file.
 | A colour/type token | `tokens/_reference.scss` | wire it up in `tokens/_theme.scss` |
@@ -180,7 +179,7 @@ from every other index file.
 Three consequences worth knowing:
 
 **Utilities beat components, without specificity.** Layer order outranks
-specificity entirely, so `.hide` wins over `.collection .collection-item` even
+specificity entirely, so `.hide` wins over `.list > li` even
 though it is less specific. Utilities used to be emitted *before* components and
 had to out-shout them; they are now last.
 
@@ -195,7 +194,6 @@ 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`
-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.
+A few rules in `components/` still use `!important` for UA resets
+(modal float, staggered-list transitions, textarea padding), not for
+JS-driven geometry. Tap target and the preloader no longer need the flag.