@pushwoosh/dumb-components 1.1.144 → 1.1.146

package/Calendar/CalendarDropdown/CalendarDropdown.js

@@ -1,13 +1,15 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useRef, useState } from 'react';
+import { autoUpdate, flip, offset, shift, useFloating } from '@floating-ui/react-dom';
+import { useEffect, useState } from 'react';
+import { createPortal } from 'react-dom';
 import { Color } from '@pushwoosh/kit-constants';
-import { Horizontal, useClickAway, Vertical } from '@pushwoosh/kit-helpers';
+import { Horizontal, Vertical } from '@pushwoosh/kit-helpers';
 import { CalendarIcon } from '@pushwoosh/kit-icons';
 import { stringifyValue } from './helpers';
 import { PopoverContent, PresetsContainer } from './styles';
 import { Button } from '../../Button';
 import { Chip } from '../../Chip';
-import { Popover } from '../../Popover';
+import { useLayer, useOnClickOutside } from '../../hooks';
 import { CalendarSuperForm } from '../CalendarSuperForm';
 import { Lang, useLang } from '../polyglot';
 export const CalendarDropdown = props => {
@@ -22,8 +24,6 @@ export const CalendarDropdown = props => {
   } = props;
   const isRangePicker = mode === 'range-date' || mode === 'range-datetime';
   const withTime = mode === 'single-datetime' || mode === 'range-datetime';
-  const buttonRef = useRef(null);
-  const popoverRef = useRef(null);
   const [isShaking, setIsShaking] = useState(false);
   const [isOpen, setIsOpen] = useState(false);
   const lang = useLang();
@@ -41,10 +41,31 @@ export const CalendarDropdown = props => {
     setValue(props.value ?? (isRangePicker ? [] : undefined));
     setTimezone(initialTimezone);
   };
-  useClickAway(isOpen, popoverRef, closePopover);
   const openPopover = () => {
     setIsOpen(true);
   };
+  const {
+    refs,
+    floatingStyles
+  } = useFloating({
+    open: isOpen,
+    strategy: 'fixed',
+    placement: 'bottom-start',
+    transform: false,
+    middleware: [offset(4), flip(), shift({
+      padding: 8
+    })],
+    whileElementsMounted: autoUpdate
+  });
+  const {
+    zIndex
+  } = useLayer({
+    isOpen,
+    onClose: closePopover
+  });
+  useOnClickOutside([refs.reference, refs.floating], () => {
+    if (isOpen) closePopover();
+  });
   const onChangeHandler = val => {
     var _props$onChange;
     setValue(val);
@@ -65,7 +86,7 @@ export const CalendarDropdown = props => {
   return _jsxs(Horizontal, {
     "$justifyContent": "start",
     children: [_jsx(Button, {
-      boxRef: buttonRef,
+      boxRef: refs.setReference,
       type: "button",
       view: buttonView,
       size: buttonSize,
@@ -77,108 +98,106 @@ export const CalendarDropdown = props => {
       onClick: () => isOpen ? closePopover() : openPopover(),
       isOpen: isOpen,
       children: buttonTextCustom ?? buttonText
-    }), _jsx(Popover, {
-      open: isOpen,
-      anchorEl: buttonRef,
-      internalWindowRef: popoverRef,
-      windowWidth: isRangePicker ? 500 : 260,
-      position: "bottom-start",
-      zIndex: 10010,
-      children: _jsx(PopoverContent, {
-        "$isShaking": isShaking,
-        onAnimationEnd: () => setIsShaking(false),
-        children: _jsxs(Vertical, {
-          children: [presets && presets.length > 0 && _jsx(PresetsContainer, {
-            children: presets.map((preset, i) => _jsx(Chip, {
-              onClick: () => onChangeHandler(preset.value),
-              children: preset.label
-            }, i))
-          }), _jsxs(Horizontal, {
-            "$padding": 16,
-            "$border": {
-              bottom: `1px solid ${Color.DIVIDER}`
+    }), isOpen && createPortal(_jsx(PopoverContent, {
+      ref: refs.setFloating,
+      style: {
+        ...floatingStyles,
+        zIndex
+      },
+      "$isShaking": isShaking,
+      "$width": isRangePicker ? 500 : 260,
+      onAnimationEnd: () => setIsShaking(false),
+      children: _jsxs(Vertical, {
+        children: [presets && presets.length > 0 && _jsx(PresetsContainer, {
+          children: presets.map((preset, i) => _jsx(Chip, {
+            onClick: () => onChangeHandler(preset.value),
+            children: preset.label
+          }, i))
+        }), _jsxs(Horizontal, {
+          "$padding": 16,
+          "$border": {
+            bottom: `1px solid ${Color.DIVIDER}`
+          },
+          children: [mode === 'single-date' && _jsx(CalendarSuperForm, {
+            mode: "single-date",
+            ...calendarProps,
+            value: value,
+            onChange: onChangeHandler
+          }), mode === 'single-datetime' && _jsx(CalendarSuperForm, {
+            mode: "single-datetime",
+            ...calendarProps,
+            value: value,
+            onChange: onChangeHandler,
+            timezone: timezone,
+            onChangeTimezone: val => {
+              setTimezone(val);
+              if ('onChangeTimezone' in calendarProps) {
+                calendarProps.onChangeTimezone(val);
+              }
+            }
+          }), mode === 'range-date' && _jsx(CalendarSuperForm, {
+            mode: "range-date",
+            ...calendarProps,
+            value: value,
+            onChange: onChangeHandler
+          }), mode === 'range-datetime' && _jsx(CalendarSuperForm, {
+            mode: "range-datetime",
+            ...calendarProps,
+            value: value,
+            onChange: onChangeHandler,
+            timezone: timezone,
+            onChangeTimezone: val => {
+              setTimezone(val);
+              if ('onChangeTimezone' in calendarProps) {
+                calendarProps.onChangeTimezone(val);
+              }
+            }
+          })]
+        }), _jsxs(Horizontal, {
+          "$padding": 16,
+          "$justifyContent": "end",
+          "$gap": 8,
+          children: [_jsx(Button, {
+            color: "secondary",
+            size: "compact",
+            onClick: () => {
+              if (noValue) {
+                closePopover();
+              } else {
+                setValue(isRangePicker ? [] : undefined);
+                setTimezone(initialTimezone);
+              }
             },
-            children: [mode === 'single-date' && _jsx(CalendarSuperForm, {
-              mode: "single-date",
-              ...calendarProps,
-              value: value,
-              onChange: onChangeHandler
-            }), mode === 'single-datetime' && _jsx(CalendarSuperForm, {
-              mode: "single-datetime",
-              ...calendarProps,
-              value: value,
-              onChange: onChangeHandler,
-              timezone: timezone,
-              onChangeTimezone: val => {
-                setTimezone(val);
-                if ('onChangeTimezone' in calendarProps) {
-                  calendarProps.onChangeTimezone(val);
-                }
+            children: noValue ? _jsx(Lang, {
+              message: "DUMB.CALENDAR.CANCEL"
+            }) : _jsx(Lang, {
+              message: "DUMB.CALENDAR.RESET"
+            })
+          }), _jsx(Button, {
+            color: "primary",
+            size: "compact",
+            onClick: () => {
+              let isInvalid;
+              if (isRangePicker) {
+                const range = value;
+                const length = (range === null || range === void 0 ? void 0 : range.length) ?? 0;
+                isInvalid = allowEmpty ? length === 1 : length !== 2;
+              } else {
+                isInvalid = allowEmpty ? false : !value;
               }
-            }), mode === 'range-date' && _jsx(CalendarSuperForm, {
-              mode: "range-date",
-              ...calendarProps,
-              value: value,
-              onChange: onChangeHandler
-            }), mode === 'range-datetime' && _jsx(CalendarSuperForm, {
-              mode: "range-datetime",
-              ...calendarProps,
-              value: value,
-              onChange: onChangeHandler,
-              timezone: timezone,
-              onChangeTimezone: val => {
-                setTimezone(val);
-                if ('onChangeTimezone' in calendarProps) {
-                  calendarProps.onChangeTimezone(val);
-                }
+              if (isInvalid) {
+                setIsShaking(true);
+              } else {
+                props.onSubmit(value, timezone);
+                closePopover();
               }
-            })]
-          }), _jsxs(Horizontal, {
-            "$padding": 16,
-            "$justifyContent": "end",
-            "$gap": 8,
-            children: [_jsx(Button, {
-              color: "secondary",
-              size: "compact",
-              onClick: () => {
-                if (noValue) {
-                  closePopover();
-                } else {
-                  setValue(isRangePicker ? [] : undefined);
-                  setTimezone(initialTimezone);
-                }
-              },
-              children: noValue ? _jsx(Lang, {
-                message: "DUMB.CALENDAR.CANCEL"
-              }) : _jsx(Lang, {
-                message: "DUMB.CALENDAR.RESET"
-              })
-            }), _jsx(Button, {
-              color: "primary",
-              size: "compact",
-              onClick: () => {
-                let isInvalid;
-                if (isRangePicker) {
-                  const range = value;
-                  const length = (range === null || range === void 0 ? void 0 : range.length) ?? 0;
-                  isInvalid = allowEmpty ? length === 1 : length !== 2;
-                } else {
-                  isInvalid = allowEmpty ? false : !value;
-                }
-                if (isInvalid) {
-                  setIsShaking(true);
-                } else {
-                  props.onSubmit(value, timezone);
-                  closePopover();
-                }
-              },
-              children: _jsx(Lang, {
-                message: "DUMB.CALENDAR.APPLY"
-              })
-            })]
+            },
+            children: _jsx(Lang, {
+              message: "DUMB.CALENDAR.APPLY"
+            })
           })]
-        })
+        })]
       })
-    })]
+    }), document.body)]
   });
 };

package/Calendar/CalendarDropdown/styles.d.ts

@@ -1,4 +1,5 @@
 export declare const PopoverContent: import("styled-components").StyledComponent<"div", any, {
     $isShaking?: boolean;
+    $width: number;
 }, never>;
 export declare const PresetsContainer: import("styled-components").StyledComponent<"div", any, {}, never>;

package/Calendar/CalendarDropdown/styles.js

@@ -1,10 +1,12 @@
 import styled, { keyframes, css } from 'styled-components';
-import { Shadow, Color } from '@pushwoosh/kit-constants';
+import { Shadow, Color, ShapeRadius } from '@pushwoosh/kit-constants';
 const shakeAnimation = keyframes(["0%,100%{transform:translateX(0);}10%,30%,50%,70%,90%{transform:translateX(-4px);}20%,40%,60%,80%{transform:translateX(4px);}"]);
 export const PopoverContent = styled.div.withConfig({
   displayName: "PopoverContent",
   componentId: "sc-h6jz87-0"
-})(["overflow:hidden;box-shadow:", ";background:", ";", ""], Shadow.REGULAR, Color.CLEAR, ({
+})(["width:", "px;overflow:hidden;border:1px solid ", ";border-radius:", ";box-shadow:", ";background:", ";", ""], ({
+  $width
+}) => $width, Color.FORM, ShapeRadius.DIALOG, Shadow.REGULAR, Color.CLEAR, ({
   $isShaking
 }) => $isShaking && css(["animation:", " 0.4s ease-in-out;"], shakeAnimation));
 export const PresetsContainer = styled.div.withConfig({

package/Calendar/CalendarSuperForm/components/CalendarTimezoneSelect.js

@@ -1,31 +1,24 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useMemo } from 'react';
-import { Select } from '../../../Select';
+import { Combobox } from '../../../Combobox';
 import { getSortedTimezones } from '../../helpers-tz';
 export const CalendarTimezoneSelect = ({
   timezone,
   onChange,
   isDisabled
 }) => {
-  const timezonesOptions = useMemo(() => {
-    return getSortedTimezones();
-  }, []);
-  return _jsx(Select, {
-    value: timezonesOptions.find(op => op.value === timezone),
-    onChange: value => onChange(value.value),
-    options: timezonesOptions,
-    isDisabled: isDisabled,
-    menuPortalTarget: document.body,
-    menuPosition: "fixed",
-    styles: {
-      menuPortal: base => ({
-        ...base,
-        zIndex: 10020
-      }),
-      menu: provided => ({
-        ...provided,
-        width: '300px'
-      })
-    }
+  const timezonesOptions = useMemo(() => getSortedTimezones(), []);
+  const value = useMemo(() => timezonesOptions.find(op => op.value === timezone) ?? null, [timezonesOptions, timezone]);
+  return _jsx(Combobox, {
+    select: true,
+    items: timezonesOptions,
+    value: value,
+    onChange: option => {
+      if (option) onChange(option.value);
+    },
+    getLabel: option => option.label,
+    getKey: option => option.value,
+    filter: (option, query) => option.label.toLowerCase().includes(query.toLowerCase()),
+    disabled: isDisabled
   });
 };

package/Combobox/Combobox.d.ts

@@ -1,4 +1,25 @@
 import { type ReactElement } from 'react';
 import { type FreeComboboxProps, type SelectComboboxProps } from './types';
+/**
+ * Free-text combobox: an input with optional sync or async suggestions. `value`
+ * is the string; `onChange` fires per keystroke and on pick (see `meta.source`).
+ *
+ * @example
+ * <Combobox value={text} onChange={setText} items={fruits} placeholder="Fruit" clearable />
+ */
 export declare function Combobox(props: FreeComboboxProps): ReactElement;
+/**
+ * Strict single-select combobox: pick one of `items` (or clear to `null`).
+ * Pass `select` to opt in; object items also need `getKey`.
+ *
+ * @example
+ * <Combobox<User>
+ *   select
+ *   items={users}
+ *   value={user}
+ *   onChange={setUser}
+ *   getLabel={(u) => u.name}
+ *   getKey={(u) => u.id}
+ * />
+ */
 export declare function Combobox<T>(props: SelectComboboxProps<T>): ReactElement;

package/Combobox/types.d.ts

@@ -1,47 +1,89 @@
 import type { ReactNode } from 'react';
 import type { DropdownText, GetKeyProp, ItemState, LoadItems } from '../shared/dropdownField';
 type ComboboxSource<T> = {
+    /** Static list of suggestions. */
     items?: T[];
     loadItems?: never;
     debounceMs?: never;
     minChars?: never;
 } | {
     items?: never;
+    /** Async loader; receives the query and a zero-based page index, returns one page. */
     loadItems: LoadItems<T>;
+    /** Debounce (ms) before calling `loadItems` after the query changes. */
     debounceMs?: number;
+    /** Don't call `loadItems` until the query has at least this many characters. */
     minChars?: number;
 };
+/**
+ * Origin of a free-mode `onChange`:
+ * - `'input'` — the user typed (or cleared the field);
+ * - `'select'` — the user picked a suggestion from the dropdown.
+ */
 export type ComboboxChangeSource = 'input' | 'select';
+/** Second argument of free-mode `onChange`, describing what caused the change. */
 export type ComboboxChangeMeta = {
     source: ComboboxChangeSource;
 };
 type CommonProps<T> = {
+    /** Predicate for filtering `items` by the query (default: case-insensitive label match). Sync items only. */
     filter?: (item: T, query: string) => boolean;
+    /** Render a custom option row; receives the item and its {@link ItemState}. */
     renderItem?: (item: T, state: ItemState) => ReactNode;
+    /** Content shown when no options match. A node, or `(query) => node`. */
     emptyText?: DropdownText;
+    /** Content shown while async items load. A node, or `(query) => node`. Defaults to "Loading…". */
     loadingText?: DropdownText;
+    /** Called whenever the dropdown closes for any reason (Escape, click-outside, blur, selection). */
     onClose?: () => void;
+    /** Focus the input and open the dropdown on mount. */
     autoFocus?: boolean;
+    /** Placeholder shown when the field is empty. */
     placeholder?: string;
+    /** Disable the field. */
     disabled?: boolean;
+    /** Force the loading state (on top of async loading). */
     loading?: boolean;
+    /** Show a clear (✕) button when there is a value. */
     clearable?: boolean;
+    /** Size the field to its content instead of filling the parent. */
     autosize?: boolean;
+    /** Render the error (red) state. */
     hasError?: boolean;
+    /** Fixed CSS width (e.g. `"240px"`); overrides the default parent-driven / autosize width. */
     width?: string;
+    /** Minimum CSS width, useful together with `autosize`. */
     minWidth?: string;
 };
+/**
+ * Free-text Combobox: the value is the typed string and `items`/`loadItems`
+ * are optional suggestions. `onChange` fires on every keystroke and on picking
+ * a suggestion — tell them apart via `meta.source`.
+ */
 export type FreeComboboxProps = ComboboxSource<string> & CommonProps<string> & {
+    /** Free-text mode (the default). */
     select?: false;
+    /** Current text value (controlled). */
     value: string;
+    /** Fires on every change; `meta.source` is `'input'` (typed/cleared) or `'select'` (picked a suggestion). */
     onChange: (value: string, meta: ComboboxChangeMeta) => void;
+    /** Map a suggestion to the text inserted on pick (default: identity). */
     getLabel?: (item: string) => string;
 };
+/**
+ * Strict single-select Combobox: the value is one of `items` (or `null`).
+ * Typing only filters — arbitrary text cannot be committed.
+ */
 export type SelectComboboxProps<T> = ComboboxSource<T> & GetKeyProp<T> & CommonProps<T> & {
+    /** Strict single-select mode. */
     select: true;
+    /** Currently selected item, or `null`. */
     value: T | null;
+    /** Fires when the selection changes (an item, or `null` when cleared). */
     onChange: (value: T | null) => void;
+    /** Map an item to its display label (required). */
     getLabel: (item: T) => string;
 };
+/** Props of {@link Combobox} — free-text by default, strict single-select with `select`. */
 export type ComboboxProps<T> = FreeComboboxProps | SelectComboboxProps<T>;
 export {};

package/ComboboxMulti/ComboboxMulti.d.ts

@@ -1,3 +1,16 @@
 import { type ReactElement } from 'react';
 import { type ComboboxMultiProps } from './types';
+/**
+ * Multi-select combobox: pick several items shown as removable chips, with
+ * optional creation of new values. Sync `items` or async `loadItems`.
+ *
+ * @example
+ * <ComboboxMulti<string>
+ *   items={fruits}
+ *   value={selected}
+ *   onChange={setSelected}
+ *   getLabel={(s) => s}
+ *   creatable
+ * />
+ */
 export declare function ComboboxMulti<T>({ items, loadItems, debounceMs, minChars, value, onChange, onClose, autoFocus, getLabel, getKey: getKeyProp, filter, renderItem, emptyText, loadingText, creatable, onCreate, canCreate, renderCreateLabel, maxValues, placeholder, disabled, loading, clearable, autosize, hasError, width, minWidth, }: ComboboxMultiProps<T>): ReactElement;

package/ComboboxMulti/ComboboxMulti.js

@@ -8,6 +8,19 @@ function defaultCanCreate(query, items, getLabel) {
   const lower = trimmed.toLowerCase();
   return !items.some(item => getLabel(item).toLowerCase() === lower);
 }
+/**
+ * Multi-select combobox: pick several items shown as removable chips, with
+ * optional creation of new values. Sync `items` or async `loadItems`.
+ *
+ * @example
+ * <ComboboxMulti<string>
+ *   items={fruits}
+ *   value={selected}
+ *   onChange={setSelected}
+ *   getLabel={(s) => s}
+ *   creatable
+ * />
+ */
 export function ComboboxMulti({
   items,
   loadItems,

package/ComboboxMulti/types.d.ts

@@ -1,5 +1,10 @@
 import type { ReactNode } from 'react';
 import type { DropdownText, GetKeyProp, ItemState, ItemsSource } from '../shared/dropdownField';
+/**
+ * Whether new values can be created from the typed query. For `string` items
+ * `onCreate` is optional (the trimmed query is used); for object items, enabling
+ * `creatable` requires `onCreate` to build the item.
+ */
 type CreatableProp<T> = [T] extends [string] ? {
     creatable?: boolean;
     onCreate?: (query: string) => T;
@@ -10,26 +15,47 @@ type CreatableProp<T> = [T] extends [string] ? {
     creatable: true;
     onCreate: (query: string) => T;
 };
+/** Props of {@link ComboboxMulti} — multi-select with chips and optional create. */
 export type ComboboxMultiProps<T> = ItemsSource<T> & GetKeyProp<T> & CreatableProp<T> & {
+    /** Selected items (controlled), rendered as removable chips. */
     value: T[];
+    /** Fires with the new selection whenever an item is added or removed. */
     onChange: (value: T[]) => void;
+    /** Called whenever the dropdown closes for any reason (Escape, click-outside, blur). */
     onClose?: () => void;
+    /** Focus the input and open the dropdown on mount. */
     autoFocus?: boolean;
+    /** Map an item to its chip/label text (required). */
     getLabel: (item: T) => string;
+    /** Predicate for filtering `items` by the query (default: case-insensitive label match). Sync items only. */
     filter?: (item: T, query: string) => boolean;
+    /** Render a custom option row; receives the item and its {@link ItemState}. */
     renderItem?: (item: T, state: ItemState) => ReactNode;
+    /** Content shown when no options match. A node, or `(query) => node`. */
     emptyText?: DropdownText;
+    /** Content shown while async items load. A node, or `(query) => node`. Defaults to "Loading…". */
     loadingText?: DropdownText;
+    /** Override whether the current query can be created (default: non-empty and not a duplicate label). */
     canCreate?: (query: string, items: T[]) => boolean;
+    /** Render the label of the "create" row (default: `Create "query"`). */
     renderCreateLabel?: (query: string) => ReactNode;
+    /** Maximum number of selected items. */
     maxValues?: number;
+    /** Placeholder shown when there are no chips. */
     placeholder?: string;
+    /** Disable the field. */
     disabled?: boolean;
+    /** Force the loading state (on top of async loading). */
     loading?: boolean;
+    /** Show a "clear all" (✕) button when there are chips. */
     clearable?: boolean;
+    /** Size the field to its content instead of filling the parent. */
     autosize?: boolean;
+    /** Render the error (red) state. */
     hasError?: boolean;
+    /** Fixed CSS width (e.g. `"240px"`); overrides the default parent-driven / autosize width. */
     width?: string;
+    /** Minimum CSS width, useful together with `autosize`. */
     minWidth?: string;
 };
 export {};

package/hooks/__tests__/useLayer.test.d.ts

@@ -0,0 +1 @@
+export {};

package/hooks/__tests__/useLayer.test.js

@@ -0,0 +1,71 @@
+import { render } from '@testing-library/react';
+import { createElement, Fragment } from 'react';
+import { useLayer } from '../useLayer';
+const GLOBAL_KEY = '__pushwoosh_dumb_components_layer_state__';
+function resetLayerState() {
+  delete window[GLOBAL_KEY];
+}
+function Layer({
+  index,
+  zIndex
+}) {
+  const resolved = useLayer({
+    isOpen: true,
+    zIndex
+  });
+  return createElement('div', {
+    'data-testid': `layer-${index}`,
+    'data-z': resolved.zIndex
+  });
+}
+function layersTree(zIndexes) {
+  const children = zIndexes.map((zIndex, index) => createElement(Layer, {
+    // eslint-disable-next-line react/no-array-index-key
+    key: index,
+    index,
+    zIndex
+  }));
+  return createElement(Fragment, null, ...children);
+}
+function readZIndexes(getByTestId, count) {
+  return Array.from({
+    length: count
+  }, (_, index) => Number(getByTestId(`layer-${index}`).getAttribute('data-z')));
+}
+function renderZIndexes(zIndexes) {
+  const {
+    getByTestId
+  } = render(layersTree(zIndexes));
+  return readZIndexes(getByTestId, zIndexes.length);
+}
+describe('useLayer z-index resolution', () => {
+  beforeEach(resetLayerState);
+  afterEach(resetLayerState);
+  it('puts a lone layer at the base z-index', () => {
+    expect(renderZIndexes([undefined])).toEqual([10000]);
+  });
+  it('stacks plain layers in registration order', () => {
+    expect(renderZIndexes([undefined, undefined])).toEqual([10000, 10100]);
+  });
+  it('keeps a layer opened on top of an explicit base above it', () => {
+    expect(renderZIndexes([100000, undefined])).toEqual([100000, 100100]);
+  });
+  it('propagates the base to every layer stacked above it', () => {
+    expect(renderZIndexes([100000, undefined, undefined])).toEqual([100000, 100100, 100200]);
+  });
+  it('renders a lone explicit base exactly at its value', () => {
+    expect(renderZIndexes([100000])).toEqual([100000]);
+  });
+  it('honors a higher base set by a layer above', () => {
+    expect(renderZIndexes([undefined, 999999])).toEqual([10000, 999999]);
+  });
+  it('re-resolves stacked layers when an open layer changes its base', () => {
+    const {
+      rerender,
+      getByTestId
+    } = render(layersTree([100000, undefined]));
+    expect(readZIndexes(getByTestId, 2)).toEqual([100000, 100100]);
+    rerender(layersTree([200000, undefined]));
+    expect(readZIndexes(getByTestId, 2)).toEqual([200000, 200100]);
+  });
+});

package/hooks/useLayer.js

@@ -67,8 +67,19 @@ function unregisterLayer(id) {
   teardownKeydownListener();
   notify();
 }
-function getDepth(id) {
-  return getState().stack.findIndex(entry => entry.id === id);
+function resolveZIndex(id, fallbackZIndex) {
+  const {
+    stack
+  } = getState();
+  let zIndexBelow = BASE_Z_INDEX - Z_INDEX_STEP;
+  for (const entry of stack) {
+    const layerZIndex = Math.max(entry.baseZIndex ?? 0, zIndexBelow + Z_INDEX_STEP);
+    if (entry.id === id) {
+      return layerZIndex;
+    }
+    zIndexBelow = layerZIndex;
+  }
+  return fallbackZIndex ?? BASE_Z_INDEX;
 }
 export function useLayer({
   isOpen,
@@ -78,6 +89,8 @@ export function useLayer({
   const id = useId();
   const onCloseRef = useRef(onClose);
   onCloseRef.current = onClose;
+  const zIndexRef = useRef(zIndex);
+  zIndexRef.current = zIndex;
   const [, forceRender] = useState(0);
   useEffect(() => {
     const subscriber = () => forceRender(value => value + 1);
@@ -95,13 +108,20 @@ export function useLayer({
       close: () => {
         var _onCloseRef$current;
         return (_onCloseRef$current = onCloseRef.current) === null || _onCloseRef$current === void 0 ? void 0 : _onCloseRef$current.call(onCloseRef);
-      }
+      },
+      baseZIndex: zIndexRef.current
     });
     forceRender(value => value + 1);
     return () => unregisterLayer(id);
   }, [isOpen, id]);
-  const depth = getDepth(id);
-  const resolvedZIndex = zIndex ?? BASE_Z_INDEX + Math.max(depth, 0) * Z_INDEX_STEP;
+  useLayoutEffect(() => {
+    const entry = getState().stack.find(item => item.id === id);
+    if (entry && entry.baseZIndex !== zIndex) {
+      entry.baseZIndex = zIndex;
+      notify();
+    }
+  }, [zIndex, id]);
+  const resolvedZIndex = resolveZIndex(id, zIndex);
   return {
     zIndex: resolvedZIndex
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pushwoosh/dumb-components",
-  "version": "1.1.144",
+  "version": "1.1.146",
   "description": "React components to build Pushwoosh products",
   "main": "index.js",
   "module": "index.js",

package/shared/dropdownField/SuggestionsDropdown.js

@@ -47,6 +47,8 @@ export function SuggestionsDropdown({
     id: listboxId,
     role: "listbox",
     onScroll: onScroll,
+    onMouseDown: event => event.stopPropagation(),
+    onTouchStart: event => event.stopPropagation(),
     children: [loading && _jsx(DropdownEmpty, {
       children: loadingText
     }), !loading && createLabel && _jsx(DropdownItem, {

package/shared/dropdownField/types.d.ts

@@ -1,28 +1,57 @@
 import type { ReactNode } from 'react';
+/**
+ * Dropdown text slot (e.g. `emptyText`, `loadingText`): either a static node,
+ * or a function of the current query so the message can include the search term.
+ */
 export type DropdownText = ReactNode | ((query: string) => ReactNode);
+/** State of an option row, passed to a custom `renderItem`. */
 export type ItemState = {
+    /** The row is selected (its key matches the current value). */
     selected: boolean;
+    /** The row is the active, keyboard-highlighted one. */
     active: boolean;
 };
+/**
+ * How to derive a stable key for an item. Optional for `string`/`number` items
+ * (the item is its own key); required for object items.
+ */
 export type GetKeyProp<T> = [T] extends [string | number] ? {
     getKey?: (item: T) => string | number;
 } : {
     getKey: (item: T) => string | number;
 };
+/** One page returned by an async {@link LoadItems} loader. */
 export type LoadItemsResult<T> = {
+    /** Items for the requested page. */
     items: T[];
+    /**
+     * Whether more pages are available. Defaults to `false` when omitted, so
+     * paging continues only while a page explicitly returns `true`.
+     */
     hasMore?: boolean;
 };
+/**
+ * Async item loader. Called with the current query and a zero-based page index;
+ * the component owns paging and accumulates results across pages.
+ */
 export type LoadItems<T> = (query: string, page: number) => Promise<LoadItemsResult<T>>;
+/**
+ * Where options come from: a static `items` array, or an async `loadItems`
+ * loader — mutually exclusive.
+ */
 export type ItemsSource<T> = {
+    /** Static list of options. */
     items: T[];
     loadItems?: never;
     debounceMs?: never;
     minChars?: never;
 } | {
     items?: never;
+    /** Async loader; receives the query and page index, returns one page. */
     loadItems: LoadItems<T>;
+    /** Debounce (ms) before calling `loadItems` after the query changes. */
     debounceMs?: number;
+    /** Don't call `loadItems` until the query has at least this many characters. */
     minChars?: number;
 };
 export type DropdownItemDescriptor = {