slim-select 3.6.1 → 4.0.1

package/README.md

@@ -1,51 +1,58 @@
 # Slim Select
 
-## [slimselectjs.com](https://slimselectjs.com)
+**The select dropdown, reimagined.**
+
+A lightweight, dependency-free replacement for the native `<select>` — single and multi-select, search, optgroups,
+remote data, modal mode on mobile, and full theming through CSS variables. Drop it into any stack, or use the official
+Vue and React wrappers.
 
-Advanced select dropdown
+## [slimselectjs.com](https://slimselectjs.com)
 
 [![NPM Downloads](https://img.shields.io/npm/dt/slim-select.svg)](https://www.npmjs.com/package/slim-select)
-![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/brianvoe/slim-select/vitest.yml?logo=vitest&label=unit%20tests) ![Tests](https://img.shields.io/badge/tests-314%20passing-brightgreen) [![slim-select](https://snyk.io/advisor/npm-package/slim-select/badge.svg)](https://snyk.io/advisor/npm-package/slim-select)
+![GitHub Actions Workflow Status](https://img.shields.io/github/actions/workflow/status/brianvoe/slim-select/vitest.yml?logo=vitest&label=unit%20tests)
+![Tests](https://img.shields.io/badge/tests-523%20passing-brightgreen)
 
-## Support
+![](https://raw.githubusercontent.com/brianvoe/slim-select/master/docs/slimselect.gif)
 
-[![](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&color=%23fe8e86)](https://github.com/sponsors/brianvoe)
+## Documentation
 
-<a href="https://www.buymeacoffee.com/brianvoe" target="_blank"><img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me A Coffee" style="height: auto !important;width: auto !important;" ></a>
+Full docs, live demos, and copy-paste examples: **[slimselectjs.com](https://slimselectjs.com)**
 
-## [Documentation and Examples](https://slimselectjs.com)
+- [Get started](https://slimselectjs.com/get-started)
+- [Settings](https://slimselectjs.com/settings)
+- [Methods](https://slimselectjs.com/methods)
+- [Events](https://slimselectjs.com/events)
+- [Styling](https://slimselectjs.com/style)
 
-See [website](https://slimselectjs.com) for the full list of [settings](https://slimselectjs.com/settings), [methods](https://slimselectjs.com/methods) and [event callbacks](https://slimselectjs.com/events)
+## Features
 
-![](https://raw.githubusercontent.com/brianvoe/slim-select/master/docs/slimselect.gif)
+**Select, upgraded**
 
-## Features
+- Single and multi-select with tags, placeholders, and deselect
+- Search with highlighting, remote/API search, and user-addable options
+- Optgroups with select-all and closable accordion groups
+- HTML options, tooltips, min/max selection limits, and disabled options
+- Modal mode (`off` | `on` | `mobile`) — centered panel with backdrop; mobile-friendly by default
+
+**Looks like your product**
+
+- Theme entirely with `--ss-*` CSS custom properties — no fighting class specificity
+- Import plain CSS or SCSS; inherit styles and classes from the native `<select>`
+
+**Built to ship**
+
+- Zero runtime dependencies
+- ~66KB JS (~16KB gzip) · ~12KB CSS (~2KB gzip)
+- TypeScript types included
+- WCAG 2.1 Level AA accessibility (ARIA, keyboard, screen reader support)
+- `prefers-reduced-motion` respected
+- 477 unit tests + 46 Playwright E2E tests
 
-- No Dependencies
-- JS: 48kb - 10kb gzip
-- CSS: 11kb - 2kb gzip
-- Single Select
-- Multi Select
-- User Addable Options
-- Html Options
-- Settable Data
-- Callback Events
-- Label Support
-- Placeholders
-- Search
-- Disable Options
-- Light CSS
-- Light Color Scheme
-- Style and Class Inheritance
-- Clean Animations
-- Performant
-- Typescript
-- ARIA Accessibility (WCAG 2.1 Level AA compliant)
-
-## Frameworks
-
-- [Vue](#vue)
-- [React](#react)
+**Framework ready**
+
+- Vanilla JS
+- [Vue 3](#vue) component with `v-model`
+- [React](#react) component with hooks and ref access
 
 ## Installation
 
@@ -53,19 +60,18 @@ See [website](https://slimselectjs.com) for the full list of [settings](https://
 npm install slim-select
 ```
 
-### or
+### CDN
 
 ```html
 <script src="https://unpkg.com/slim-select@latest/dist/slimselect.js"></script>
 <link rel="stylesheet" href="https://unpkg.com/slim-select@latest/dist/slimselect.css" />
 ```
 
-## Simple Usage
+## Quick start
 
 ```javascript
 import SlimSelect from 'slim-select'
-import 'slim-select/styles' // optional css import method
-import 'slim-select/scss' // optional scss import method
+import 'slim-select/styles' // or: import 'slim-select/scss'
 
 new SlimSelect({
   select: '#selectElement'
@@ -78,133 +84,151 @@ new SlimSelect({
 </select>
 ```
 
-## Data
+## Styling
 
-Data is an array of objects that represent both option and optgroups.
+Slim Select is styled with CSS variables. Set them on a wrapper around your select (or on `:root` for a global theme):
 
-See below for list of data types
+```css
+.my-form {
+  --ss-primary-color: #2563eb;
+  --ss-bg-color: #ffffff;
+  --ss-font-color: #1e293b;
+  --ss-border-color: #e2e8f0;
+  --ss-border-radius: 8px;
+  --ss-main-height: 44px;
+}
+```
+
+See the full token list and live themes on the [Style docs](https://slimselectjs.com/style).
+
+## Data
+
+Pass an array of options and optgroups instead of (or in addition to) native `<option>` elements:
 
 ```javascript
 new SlimSelect({
   select: '#selectElement',
 
-  // Array of Option objects
-  data: [{ text: 'Value 1', value: 'value1' }],
-
-  // or
-
-  // Array of Optgroups and/or Options
-  data: [{ label: 'Optgroup Label', options: { text: 'Value 1', value: 'value1' } }]
+  data: [
+    { text: 'Value 1', value: 'value1' },
+    {
+      label: 'Group label',
+      options: [
+        { text: 'Value 2', value: 'value2' },
+        { text: 'Value 3', value: 'value3' }
+      ]
+    }
+  ]
 })
 ```
 
-## Data Types
+### Data types
 
 ```javascript
 // <optgroup>
-var optgroup = {
+const optgroup = {
   label: 'label', // Required
-  selectAll: false, // Optional - default false
-  closable: 'off', // Optional - default 'off' - 'off', 'open', 'close'
-  options: [] // Required - value is an array of options
+  selectAll: false, // Optional — default false
+  closable: 'off', // Optional — 'off' | 'open' | 'close'
+  options: [] // Required — array of options
 }
 
 // <option>
-var option = {
+const option = {
   text: 'text', // Required
-  value: 'value', // Optional - value will be set by text if not set
-  html: '<b>Html</b>', // Optional - if set, used for display purposes
-  selected: false, // Optional - default is false
-  display: true, // Optional - default is true
-  disabled: false, // Optional - default is false
-  mandatory: false, // Optional - default is false
-  placeholder: false, // Optional - default is false
-  class: '', // Optional - default is not set
-  style: '', // Optional - default is not set
-  data: {} // Optional - If you have data attributes
+  value: 'value', // Optional — defaults to text
+  html: '<b>Html</b>', // Optional — used for display when set
+  selected: false,
+  display: true,
+  disabled: false,
+  mandatory: false,
+  placeholder: false,
+  class: '',
+  style: '',
+  data: {} // Plain object for data-* attributes
 }
 ```
 
 ## Settings
 
-Settings are optional fields that customize how SlimSelect operates. All values shown are defaults.
+All fields are optional. Values shown are defaults.
 
-[Full Settings Documentation](https://slimselectjs.com/settings)
+[Full settings documentation](https://slimselectjs.com/settings)
 
 ```javascript
 new SlimSelect({
   select: '#selectElement',
 
   settings: {
-    disabled: false, // Disable the select
-    alwaysOpen: false, // Keep dropdown always open
-    showSearch: true, // Show search input
-    focusSearch: true, // Auto focus search on open
-    keepSearch: false, // Keep search input value when dropdown closes
-    ariaLabel: 'Combobox', // ARIA label for accessibility
-    searchPlaceholder: 'Search', // Search input placeholder
-    searchText: 'No Results', // Text when no results found
-    searchingText: 'Searching...', // Text while searching
-    searchHighlight: false, // Highlight search terms
-    closeOnSelect: true, // Close dropdown after selection
-    contentLocation: document.body, // Where to append dropdown
-    contentPosition: 'absolute', // CSS position: absolute, relative, fixed
-    contentWidth: '', // Content width: "500px" exact, ">500px" min-width, "<500px" max-width
-    openPosition: 'auto', // Open direction: auto, up, down
-    placeholderText: 'Select Value', // Placeholder text
-    allowDeselect: false, // Allow deselecting in single select
-    hideSelected: false, // Hide selected options in dropdown
-    keepOrder: false, // Keep user click order (not DOM order) for getSelected
-    showOptionTooltips: false, // Show tooltips on options
-    minSelected: 0, // Minimum selections (multi-select)
-    maxSelected: 1000, // Maximum selections (multi-select)
-    timeoutDelay: 200, // Delay for callbacks (ms)
-    maxValuesShown: 20, // Max values shown before message
-    maxValuesMessage: '{number} selected', // Message when max values exceeded
-    addableText: 'Press "Enter" to add {value}' // Text for addable option
+    disabled: false,
+    alwaysOpen: false,
+    showSearch: true,
+    focusSearch: true,
+    keepSearch: false,
+    ariaLabel: 'Combobox',
+    searchPlaceholder: 'Search...',
+    searchText: 'No Results',
+    searchingText: 'Searching...',
+    resultsText: '{count} results available',
+    deselectText: 'Clear',
+    removeText: 'Remove',
+    searchHighlight: false,
+    closeOnSelect: true,
+    contentLocation: document.body,
+    contentPosition: 'absolute', // 'absolute' | 'relative' | 'fixed'
+    contentWidth: '', // e.g. '500px', '>500px', '<500px'
+    openPosition: 'auto', // 'auto' | 'up' | 'down'
+    placeholderText: 'Select Value',
+    allowDeselect: false,
+    hideSelected: false,
+    multiString: false,
+    keepOrder: false,
+    showOptionTooltips: false,
+    minSelected: 0,
+    maxSelected: 1000,
+    timeoutDelay: 200,
+    maxValuesShown: 20,
+    maxValuesMessage: '{number} selected',
+    addableText: 'Press "Enter" to add {value}',
+    modal: 'mobile', // 'off' | 'on' | 'mobile'
+    modalTitle: '' // Header above the option list in modal view
   }
 })
 ```
 
 ## Events
 
-Events are function callbacks for when certain actions happen
-
-[Full Events Documentation](https://slimselectjs.com/events)
+[Full events documentation](https://slimselectjs.com/events)
 
 ```javascript
 new SlimSelect({
   select: '#selectElement',
 
   events: {
-    // Custom search function - return Promise or data array
-    search: (searchValue: string, currentData: (Option | Optgroup)[]) => Promise<(Partial<Option> | Partial<Optgroup>)[]> | (Partial<Option> | Partial<Optgroup>)[],
-
-    // Filter function for search - return true to show option
+    // Remote/API search — return a Promise or data array
+    // searchValue: current input text
+    // selected: currently selected Option[]
+    // catalog: baseline list restored when search clears
+    search: (
+      searchValue: string,
+      selected: Option[],
+      catalog?: (Option | Optgroup)[]
+    ) =>
+      Promise<(Partial<Option> | Partial<Optgroup>)[]> |
+      (Partial<Option> | Partial<Optgroup>)[],
+
+    // Local filter when events.search is not set
     searchFilter: (option: Option, search: string) => boolean,
 
-    // Allow user to add options - return new option or error
+    // User-added options — return the new option or an Error
     addable: (value: string) => Promise<Partial<Option> | string> | Partial<Option> | string | Error,
 
-    // Before selection changes - return false to prevent change
     beforeChange: (newVal: Option[], oldVal: Option[]) => boolean | void,
-
-    // After selection changes
     afterChange: (newVal: Option[]) => void,
-
-    // Before dropdown opens
     beforeOpen: () => void,
-
-    // After dropdown opens
     afterOpen: () => void,
-
-    // Before dropdown closes
     beforeClose: () => void,
-
-    // After dropdown closes
     afterClose: () => void,
-
-    // Error handler
     error: (err: Error) => void
   }
 })
@@ -212,40 +236,34 @@ new SlimSelect({
 
 ## Methods
 
-SlimSelect provides methods to programmatically control the select
-
-[Full Methods Documentation](https://slimselectjs.com/methods)
+[Full methods documentation](https://slimselectjs.com/methods)
 
 ```javascript
 const slim = new SlimSelect({ select: '#selectElement' })
 
-slim.enable() // Enable the select
-slim.disable() // Disable the select
-slim.getData() // Get current data array
-slim.setData(data) // Set new data array
-slim.getSelected() // Get selected values as string[]
-slim.setSelected(['value1', 'value2']) // Set selected by values
-slim.addOption(option) // Add a single option
-slim.open() // Open the dropdown
-slim.close() // Close the dropdown
-slim.search('searchValue') // Programmatically search
-slim.destroy() // Destroy the instance
+slim.enable()
+slim.disable()
+slim.getData()
+slim.setData(data)
+slim.getSelected() // string[]
+slim.setSelected(['value1', 'value2'])
+slim.addOption(option)
+slim.open()
+slim.close()
+slim.search('searchValue')
+slim.destroy()
 ```
 
 ## Vue
 
-SlimSelect has official Vue 3 component support with full reactivity.
-
-For more Vue examples and advanced usage, see the [Vue documentation](https://slimselectjs.com/vue).
+Official Vue 3 component with `v-model` and full TypeScript support.
 
-### Installation
+[Vue documentation](https://slimselectjs.com/vue)
 
 ```bash
 npm install slim-select
 ```
 
-### Usage
-
 ```vue
 <script lang="ts">
 import SlimSelect from 'slim-select/vue'
@@ -271,20 +289,18 @@ export default {
 </template>
 ```
 
-## React
+> **Note:** Pass options via the `:data` prop. Native `<option>` slot children are not supported in the Vue wrapper.
 
-SlimSelect has official React component support with hooks.
+## React
 
-For more React examples and advanced usage, see the [documentation](https://slimselectjs.com).
+Official React component with hooks and ref access to the underlying instance.
 
-### Installation
+[React documentation](https://slimselectjs.com/react)
 
 ```bash
 npm install slim-select
 ```
 
-### Usage
-
 ```tsx
 import { useState } from 'react'
 import SlimSelect from 'slim-select/react'
@@ -302,7 +318,9 @@ function MyComponent() {
 }
 ```
 
-### Advanced Usage with Ref
+> **Note:** Pass options via the `data` prop. Native `<option>` children are not supported in the React wrapper.
+
+### Ref access
 
 ```tsx
 import { useRef } from 'react'
@@ -312,16 +330,17 @@ import 'slim-select/styles'
 function MyComponent() {
   const slimRef = useRef<SlimSelectRef>(null)
 
-  const handleClick = () => {
-    // Access SlimSelect methods via ref
-    slimRef.current?.slimSelect?.open()
-  }
-
   return (
     <>
       <SlimSelect ref={slimRef} data={options} />
-      <button onClick={handleClick}>Open Dropdown</button>
+      <button onClick={() => slimRef.current?.slimSelect?.open()}>Open</button>
     </>
   )
 }
 ```
+
+## Support
+
+[![](https://img.shields.io/static/v1?label=Sponsor&message=%E2%9D%A4&logo=GitHub&color=%23fe8e86)](https://github.com/sponsors/brianvoe)
+
+<a href="https://www.buymeacoffee.com/brianvoe" target="_blank"><img src="https://www.buymeacoffee.com/assets/img/custom_images/orange_img.png" alt="Buy Me A Coffee" style="height: auto !important;width: auto !important;" ></a>

package/dist/animations.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Animation timing helpers.
+ *
+ * CSS still runs the motion — these keep lifecycle and DOM cleanup aligned with
+ * --ss-animation-timing so we are not guessing with hardcoded setTimeout values.
+ */
+/** Extra ms added to CSS duration for transitionend/animationend safety-net timeouts. */
+export declare const ANIMATION_TIMEOUT_BUFFER_MS = 50;
+/** .ss-content open/close transitions — wait for both before lifecycle continues. */
+export declare const CONTENT_PANEL_TRANSITION_PROPERTIES: readonly ["transform", "opacity"];
+/** Parse a CSS time value (e.g. "0.2s", "200ms") into milliseconds. */
+export declare function parseAnimationDuration(cssValue: string, fallback?: number): number;
+/** Read --ss-animation-timing from an element's computed styles. */
+export declare function getAnimationDuration(element: HTMLElement, fallback?: number): number;
+/**
+ * Safety-net timeout for animation waits.
+ * Derived from --ss-animation-timing (+ buffer). An explicit settings.timeoutDelay
+ * is treated as a minimum — never shorter than the CSS-driven duration.
+ */
+export declare function getAnimationTimeout(element: HTMLElement, userTimeout?: number, fallback?: number): number;
+/** Respect user OS accessibility preference and jsdom (no matchMedia). */
+export declare function prefersReducedMotion(): boolean;
+/**
+ * Wait for CSS transition(s) to finish, with a timeout fallback.
+ *
+ * Pass a single property name to resolve on that transitionend, or an array to
+ * wait until every listed property has fired (e.g. transform + opacity on .ss-content).
+ * Optional AbortSignal cleans up listeners when lifecycle cancels a rapid toggle.
+ */
+export declare function waitForTransitionEnd(element: HTMLElement, propertyNames?: string | readonly string[], timeoutMs?: number, signal?: AbortSignal): Promise<void>;
+/**
+ * Wait for a CSS @keyframes animation to finish, with a timeout fallback.
+ *
+ * Used when removing multi-select value chips (.ss-value-out). jsdom does not
+ * fire animationend, so the timeout wins in unit tests.
+ */
+export declare function waitForAnimationEnd(element: HTMLElement, animationName?: string, timeoutMs?: number, signal?: AbortSignal): Promise<void>;

package/dist/classes.d.ts

@@ -36,6 +36,11 @@ export default class CssClasses {
     option: string;
     optionDelete: string;
     highlighted: string;
+    modalOverlay: string;
+    modalDialog: string;
+    modalTitle: string;
+    modalClose: string;
+    modalContent: string;
     mainOpen: string;
     close: string;
     selected: string;

package/dist/events.d.ts

@@ -0,0 +1,26 @@
+import { hasClassInTree } from './helpers';
+export interface GlobalEventHandlers {
+    onDocumentClick: (e: Event) => void;
+    onWindowResize: () => void;
+    onWindowScroll: () => void;
+    onVisibilityChange: () => void;
+}
+export default class GlobalEvents {
+    private handlers;
+    private attached;
+    constructor(handlers: GlobalEventHandlers);
+    /** Attach long-lived listeners for the SlimSelect instance lifetime. */
+    attach(options: {
+        listenScroll: boolean;
+    }): void;
+    /** Attached after open animation completes — closes on outside click. */
+    attachDocumentClick(): void;
+    detachDocumentClick(): void;
+    detach(options: {
+        listenScroll: boolean;
+    }): void;
+    private resizeHandler;
+    private scrollHandler;
+    private visibilityHandler;
+}
+export { hasClassInTree };

package/dist/helpers.d.ts

@@ -1,5 +1,24 @@
+import { Optgroup, Option } from './store';
+import { ModalSetting } from './settings';
+type DataItem = Partial<Option> | Partial<Optgroup>;
+/** Copy option data attributes into a plain object (not a live DOMStringMap). */
+export declare function copyOptionData(data?: {
+    [key: string]: string;
+} | DOMStringMap | null): {
+    [key: string]: string;
+};
+/** Label text only — excludes nested form controls (e.g. wrapped select options). */
+export declare function getLabelElementText(label: HTMLLabelElement): string;
+/** Associated label text for a select, or its aria-label when no label is linked. */
+export declare function getAssociatedLabelText(select: HTMLSelectElement): string;
 export declare function generateID(): string;
 export declare function hasClassInTree(element: HTMLElement, className: string): HTMLElement | null;
 export declare function debounce<T extends (...args: any[]) => void>(func: T, wait?: number, immediate?: boolean): () => void;
 export declare function isEqual(a: any, b: any): boolean;
+/** Compare selected id sets regardless of order (multi-select). */
+export declare function selectedIdsEqual(a: string[], b: string[]): boolean;
+/** Compare option/optgroup arrays without JSON.stringify. */
+export declare function dataStructureEqual(a: DataItem[], b: DataItem[]): boolean;
 export declare function kebabCase(str: string): string;
+export declare function shouldUseModalView(modal: ModalSetting, viewportWidth?: number): boolean;
+export {};

package/dist/index.d.ts

@@ -1,9 +1,12 @@
 import { default as CssClasses } from './classes';
+import { default as Lifecycle } from './lifecycle';
 import { default as Render } from './render';
 import { default as Select } from './select';
-import { default as Settings } from './settings';
+import { default as Settings, MODAL_MOBILE_BREAKPOINT } from './settings';
 import { default as Store, Option, Optgroup } from './store';
-export { Settings, Option, Optgroup };
+import { default as SyncCoordinator } from './sync';
+export { Settings, Option, Optgroup, MODAL_MOBILE_BREAKPOINT };
+export type { ModalSetting } from './settings';
 export type { Main, Content, Search } from './render';
 export interface Config {
     select: string | Element;
@@ -13,7 +16,7 @@ export interface Config {
     events?: Events;
 }
 export interface Events {
-    search?: (searchValue: string, currentData: (Option | Optgroup)[]) => Promise<(Partial<Option> | Partial<Optgroup>)[]> | (Partial<Option> | Partial<Optgroup>)[];
+    search?: (searchValue: string, selected: Option[], catalog?: (Option | Optgroup)[]) => Promise<(Partial<Option> | Partial<Optgroup>)[]> | (Partial<Option> | Partial<Optgroup>)[];
     searchFilter?: (option: Option, search: string) => boolean;
     addable?: (value: string) => Promise<Partial<Option> | string> | Partial<Option> | string | false | null | undefined | Error;
     beforeChange?: (newVal: Option[], oldVal: Option[]) => boolean | void;
@@ -31,8 +34,11 @@ export default class SlimSelect {
     select: Select;
     store: Store;
     render: Render;
-    private openTimeout;
-    private closeTimeout;
+    sync: SyncCoordinator;
+    lifecycle: Lifecycle;
+    private globalEvents;
+    /** Invalidates in-flight API search responses when the query changes or clears. */
+    private searchGeneration;
     events: Events;
     constructor(config: Config);
     enable(): void;
@@ -45,9 +51,9 @@ export default class SlimSelect {
     open(): void;
     close(eventType?: string | null): void;
     search(value: string): void;
+    private clearSearch;
+    private runLocalSearch;
+    private runApiSearch;
     destroy(): void;
-    private windowResize;
-    private windowScroll;
     private documentClick;
-    private windowVisibilityChange;
 }

package/dist/lifecycle.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Open/close state machine for SlimSelect.
+ *
+ * Replaces scattered openTimeout/closeTimeout in index.ts with a single flow:
+ *   closed → opening → open → closing → closed
+ *
+ * Maps to settings consumers expect:
+ *   - isOpen: true during opening + open
+ *   - isFullOpen: true only in open state (after animation / afterOpen)
+ *
+ * Lifecycle waits for render.waitForAnimation() before firing afterOpen/afterClose.
+ * When no animation waiter is provided, falls back to settings.timeoutDelay.
+ */
+export type LifecycleState = 'closed' | 'opening' | 'open' | 'closing';
+export interface LifecycleHandlers {
+    beforeOpen?: () => void;
+    afterOpen?: () => void;
+    beforeClose?: () => void;
+    afterClose?: () => void;
+    /** Fires when fully open — used to attach document click-outside listener. */
+    onOpenReady?: () => void;
+    /** Fires when fully closed — used to detach document click-outside listener. */
+    onCloseReady?: () => void;
+}
+export interface LifecycleOptions {
+    /** Fallback when waitForAnimation is not provided (no CSS element yet). */
+    timeoutDelay: number;
+    waitForAnimation?: (phase: 'open' | 'close', signal?: AbortSignal) => Promise<void>;
+}
+export default class Lifecycle {
+    private handlers;
+    private options;
+    state: LifecycleState;
+    private pendingTimer;
+    /** Resolvers for in-flight waitForPhase promises — cancelled on rapid toggle. */
+    private waitResolvers;
+    /** Incremented on cancelPending(); stale async completions check this before firing handlers. */
+    private generation;
+    private animationAbort;
+    constructor(handlers: LifecycleHandlers, options: LifecycleOptions);
+    get isOpen(): boolean;
+    get isFullOpen(): boolean;
+    requestOpen(): Promise<void>;
+    requestClose(): Promise<void>;
+    /** Cancel timers and resolve waiting phases — called when open/close race each other. */
+    cancelPending(): void;
+    destroy(): void;
+    /**
+     * Wait for the CSS animation to finish (or timeoutDelay when no waiter exists).
+     * cancelPending() resolves the wait early for rapid open/close toggles.
+     */
+    private waitForPhase;
+}