@pushwoosh/dumb-components 1.1.145 → 1.1.146

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.145",
+  "version": "1.1.146",
   "description": "React components to build Pushwoosh products",
   "main": "index.js",
   "module": "index.js",

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 = {