@pushwoosh/dumb-components 1.1.148 → 1.1.149

package/Tooltip/types.d.ts

@@ -1,14 +1,26 @@
 import type { RefObject, ReactElement, ReactNode } from 'react';
+/** Placement of a {@link Tooltip} relative to its anchor (side + alignment). */
 export type TooltipPosition = 'top-start' | 'top-middle' | 'top-end' | 'right-start' | 'right-middle' | 'right-end' | 'bottom-start' | 'bottom-middle' | 'bottom-end' | 'left-start' | 'left-middle' | 'left-end';
+/** Props of {@link Tooltip}. */
 export type TooltipProps = {
+    /** Tooltip content. */
     readonly content: ReactNode;
+    /** Placement relative to the anchor (default `top-start`). */
     readonly position?: TooltipPosition;
+    /** Tippy `[skidding, distance]` offset; defaults per position. */
     readonly offset?: [number, number];
+    /** CSS offset of the arrow along its edge. */
     readonly arrowOffset?: string;
+    /** Max width in pixels, or `'none'` (default `240`). */
     readonly maxWidth?: number | 'none';
+    /** Stacking z-index. */
     readonly zIndex?: number;
+    /** Disable the tooltip (never shows). */
     readonly isDisabled?: boolean;
+    /** Controlled visibility; omit for hover/focus behavior. */
     readonly isVisible?: boolean;
+    /** External anchor ref to attach to instead of wrapping `children`. */
     readonly reference?: RefObject<Element>;
+    /** The anchor element the tooltip wraps. */
     readonly children?: ReactElement<unknown>;
 };

package/hooks/useElementWidth.d.ts

@@ -2,10 +2,11 @@ import { type RefObject } from 'react';
 type ForceUpdate = () => void;
 type ElementWidth = number | null;
 /**
- * Хук для получения размера элемента
+ * Tracks the measured width of an element.
  *
- * @param { RefObject<HTMLElement> } ref - ссылка на элемент
- * @return { [ElementWidth, ForceUpdate] } - размер элемента и функция для принудительного пересчета
+ * @param ref - ref to the element to measure
+ * @returns a tuple of the current width (`null` before first measure) and a
+ *   `forceUpdate` callback to re-measure on demand
  */
 export declare function useElementWidth(ref: RefObject<HTMLElement>): [ElementWidth, ForceUpdate];
 export {};

package/hooks/useElementWidth.js

@@ -1,9 +1,10 @@
 import { useCallback, useEffect, useState } from 'react';
 /**
- * Хук для получения размера элемента
+ * Tracks the measured width of an element.
  *
- * @param { RefObject<HTMLElement> } ref - ссылка на элемент
- * @return { [ElementWidth, ForceUpdate] } - размер элемента и функция для принудительного пересчета
+ * @param ref - ref to the element to measure
+ * @returns a tuple of the current width (`null` before first measure) and a
+ *   `forceUpdate` callback to re-measure on demand
  */
 export function useElementWidth(ref) {
   const [elementWidth, setElementWidth] = useState(null);

package/hooks/useLayer.d.ts

@@ -6,5 +6,12 @@ type UseLayerParams = {
 type UseLayerResult = {
     zIndex: number;
 };
+/**
+ * Manages a stacked overlay layer (modals, drawers, popovers): registers while
+ * `isOpen`, computes a stacking `zIndex` above lower layers, and calls `onClose` on
+ * Escape when this layer is on top.
+ *
+ * @returns the resolved `zIndex` to apply to the layer
+ */
 export declare function useLayer({ isOpen, onClose, zIndex }: UseLayerParams): UseLayerResult;
 export {};

package/hooks/useLayer.js

@@ -81,6 +81,13 @@ function resolveZIndex(id, fallbackZIndex) {
   }
   return fallbackZIndex ?? BASE_Z_INDEX;
 }
+/**
+ * Manages a stacked overlay layer (modals, drawers, popovers): registers while
+ * `isOpen`, computes a stacking `zIndex` above lower layers, and calls `onClose` on
+ * Escape when this layer is on top.
+ *
+ * @returns the resolved `zIndex` to apply to the layer
+ */
 export function useLayer({
   isOpen,
   onClose,

package/hooks/useOnClickOutside.d.ts

@@ -1,4 +1,11 @@
 import { type RefObject } from 'react';
 type Ref = RefObject<HTMLElement> | RefObject<HTMLElement>[];
+/**
+ * Calls `handler` on a mousedown/touchstart outside the referenced element(s).
+ * Pass a single ref or an array of refs to treat several elements as "inside".
+ *
+ * @param ref - element ref, or array of refs, considered "inside"
+ * @param handler - called when a click/tap lands outside all refs
+ */
 export declare function useOnClickOutside(ref: Ref, handler: () => void): void;
 export {};

package/hooks/useOnClickOutside.js

@@ -1,4 +1,11 @@
 import { useEffect } from 'react';
+/**
+ * Calls `handler` on a mousedown/touchstart outside the referenced element(s).
+ * Pass a single ref or an array of refs to treat several elements as "inside".
+ *
+ * @param ref - element ref, or array of refs, considered "inside"
+ * @param handler - called when a click/tap lands outside all refs
+ */
 export function useOnClickOutside(ref, handler) {
   useEffect(() => {
     const references = Array.isArray(ref) ? ref : [ref];

package/native/Input.d.ts

@@ -1,4 +1,7 @@
+/** Style props for {@link NativeInput}. */
 export type NativeInputProps = {
+    /** Render the error (red) border. */
     $isErrored?: boolean;
 };
+/** Styled native `<input>` with the Pushwoosh form look (focus, disabled, error states). */
 export declare const NativeInput: import("styled-components").StyledComponent<"input", any, NativeInputProps, never>;

package/native/Input.js

@@ -1,5 +1,6 @@
 import styled from 'styled-components';
 import { Color, FontSize, LineHeight, ShapeRadius, UnitSize } from '@pushwoosh/kit-constants';
+/** Styled native `<input>` with the Pushwoosh form look (focus, disabled, error states). */
 export const NativeInput = styled.input.withConfig({
   displayName: "NativeInput",
   componentId: "sc-oqkcxd-0"

package/native/NativeTimeInput.d.ts

@@ -1,3 +1,4 @@
+/** Styled native `<input type="time">` with the Pushwoosh form look and the default picker indicator hidden. Pass `$isErrored` for the error state. */
 export declare const NativeTimeInput: import("styled-components").StyledComponent<"input", any, {
     type: "time";
 } & {

package/native/NativeTimeInput.js

@@ -1,5 +1,6 @@
 import styled from 'styled-components';
 import { Color, FontSize, LineHeight, ShapeRadius, UnitSize } from '@pushwoosh/kit-constants';
+/** Styled native `<input type="time">` with the Pushwoosh form look and the default picker indicator hidden. Pass `$isErrored` for the error state. */
 export const NativeTimeInput = styled.input.attrs({
   type: 'time'
 }).withConfig({

package/native/Select.d.ts

@@ -1,3 +1,4 @@
+/** Styled native `<select>` with the Pushwoosh form look and a custom dropdown arrow. Pass `$isErrored` for the error state. */
 export declare const NativeSelect: import("styled-components").StyledComponent<"select", any, {
     $isErrored?: boolean;
 }, never>;

package/native/Select.js

@@ -1,5 +1,6 @@
 import styled from 'styled-components';
 import { Color, FontSize, ShapeRadius, UnitSize } from '@pushwoosh/kit-constants';
+/** Styled native `<select>` with the Pushwoosh form look and a custom dropdown arrow. Pass `$isErrored` for the error state. */
 export const NativeSelect = styled.select.withConfig({
   displayName: "NativeSelect",
   componentId: "sc-1fsh619-0"

package/native/Textarea.d.ts

@@ -1,3 +1,4 @@
+/** Styled native `<textarea>` with the Pushwoosh form look. Pass `$width` to fix the width and `$isErrored` for the error state. */
 export declare const NativeTextarea: import("styled-components").StyledComponent<"textarea", any, {
     $width?: string;
     $isErrored?: boolean;

package/native/Textarea.js

@@ -1,5 +1,6 @@
 import styled from 'styled-components';
 import { Color, FontSize, LineHeight, ShapeRadius } from '@pushwoosh/kit-constants';
+/** Styled native `<textarea>` with the Pushwoosh form look. Pass `$width` to fix the width and `$isErrored` for the error state. */
 export const NativeTextarea = styled.textarea.withConfig({
   displayName: "NativeTextarea",
   componentId: "sc-1xe83i4-0"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pushwoosh/dumb-components",
-  "version": "1.1.148",
+  "version": "1.1.149",
   "description": "React components to build Pushwoosh products",
   "main": "index.js",
   "module": "index.js",
@@ -8,8 +8,7 @@
   "sideEffects": false,
   "scripts": {
     "start": "npm --prefix ./storybook run storybook",
-    "build": "pushwoosh-engine lib:build && npm run copy-docs",
-    "copy-docs": "node scripts/copy-docs.js",
+    "build": "pushwoosh-engine lib:build",
     "check": "npm run check:lint && npm run check:types",
     "check:lint": "echo \"Run check:lint\" && eslint src",
     "check:lint-fix": "echo \"Run check:lint\" && eslint src --fix",

package/polyglot/react.d.ts

@@ -6,14 +6,33 @@ type LangProviderProps = {
     language: string;
     languages: LanguagesMap;
 };
+/**
+ * Provides the active `language`/`timezone` and a base message catalogue to the
+ * polyglot context for {@link LangBase}/{@link useLangBase} and library messages.
+ *
+ * @example
+ * <LangProvider language="en" timezone="UTC" languages={messages}><App /></LangProvider>
+ */
 export declare const LangProvider: FC<PropsWithChildren<LangProviderProps>>;
+/** Renders a message from the provider's catalogue as React nodes; takes `{ message, ...params }`. */
 export declare const LangBase: FC;
+/** Returns a function that renders a message from the provider's catalogue to a plain string. */
 export declare const useLangBase: () => (allProps: any) => string;
 type LangLibProps = {
     $languages: LanguagesMap;
 } & Record<string, any>;
+/** Renders a message from a self-supplied catalogue (`$languages`); registers it on first use. Prefer {@link createLang}. */
 export declare const LangLib: FC<LangLibProps>;
+/** Registers a catalogue and returns a function that renders its messages to strings. Prefer {@link createLang}. */
 export declare const useLangLib: (languages: LanguagesMap) => (allProps: any) => string;
+/**
+ * Builds a typed `{ Lang, useLang }` pair bound to a message catalogue — the
+ * recommended way to add i18n to a component or library.
+ *
+ * @example
+ * const { Lang, useLang } = createLang({ en: { HELLO: 'Hello {{name}}' } });
+ * <Lang message="HELLO" name="World" />;
+ */
 export declare const createLang: <M>(languages: Record<string, LangMessages<M>>) => {
     Lang: FC<LangProps<M>>;
     useLang: () => (props: LangProps<M>) => string;

package/polyglot/react.js

@@ -58,6 +58,13 @@ const createLangPack = (language, timezone) => {
   };
 };
 const LangContext = createContext(createLangPack('en', 'UTC'));
+/**
+ * Provides the active `language`/`timezone` and a base message catalogue to the
+ * polyglot context for {@link LangBase}/{@link useLangBase} and library messages.
+ *
+ * @example
+ * <LangProvider language="en" timezone="UTC" languages={messages}><App /></LangProvider>
+ */
 export const LangProvider = ({
   timezone,
   language,
@@ -74,10 +81,13 @@ export const LangProvider = ({
     children: children
   });
 };
+/** Renders a message from the provider's catalogue as React nodes; takes `{ message, ...params }`. */
 export const LangBase = props => {
   return useContext(LangContext).langReact(props);
 };
+/** Returns a function that renders a message from the provider's catalogue to a plain string. */
 export const useLangBase = () => useContext(LangContext).lang;
+/** Renders a message from a self-supplied catalogue (`$languages`); registers it on first use. Prefer {@link createLang}. */
 export const LangLib = ({
   $languages,
   ...props
@@ -86,11 +96,20 @@ export const LangLib = ({
   useMemo(() => ctx.register($languages), [ctx, $languages]);
   return ctx.langReact(props);
 };
+/** Registers a catalogue and returns a function that renders its messages to strings. Prefer {@link createLang}. */
 export const useLangLib = languages => {
   const ctx = useContext(LangContext);
   useMemo(() => ctx.register(languages), [ctx, languages]);
   return ctx.lang;
 };
+/**
+ * Builds a typed `{ Lang, useLang }` pair bound to a message catalogue — the
+ * recommended way to add i18n to a component or library.
+ *
+ * @example
+ * const { Lang, useLang } = createLang({ en: { HELLO: 'Hello {{name}}' } });
+ * <Lang message="HELLO" name="World" />;
+ */
 export const createLang = languages => ({
   Lang: props => _jsx(LangLib, {
     "$languages": languages,

package/polyglot/types.d.ts

@@ -1,10 +1,14 @@
+/** A message catalogue: maps each message key of `T` to its (Liquid) template string. */
 export type LangMessages<T> = {
     [K in keyof T]: string;
 };
+/** Props for rendering one message: `{ message: key }` plus that key's interpolation params. */
 export type LangProps<M> = {
     [K in keyof M]: {
         message: K;
     } & M[K];
 }[keyof M];
+/** Type of the `useLang` hook produced by {@link createLang} for a message map `M`. */
 export type UseLangHook<M> = () => (props: LangProps<M>) => string;
+/** Marker for a message that takes no interpolation parameters. */
 export type NoParams = Record<never, never>;

package/shared/dropdownField/FieldInput.d.ts

@@ -1,4 +1,5 @@
 import { type InputHTMLAttributes } from 'react';
+/** Internal text input shared by the Combobox family, with optional content-fit (`autosize`) width. */
 export declare const FieldInput: import("react").ForwardRefExoticComponent<InputHTMLAttributes<HTMLInputElement> & {
     value: string;
     autosize?: boolean;

package/shared/dropdownField/FieldInput.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import { forwardRef, useLayoutEffect, useRef, useState } from 'react';
 import { AutosizeMirror, Input } from './styles';
+/** Internal text input shared by the Combobox family, with optional content-fit (`autosize`) width. */
 export const FieldInput = forwardRef(({
   autosize,
   value,

package/shared/dropdownField/FieldShell.d.ts

@@ -29,5 +29,9 @@ type FieldShellProps = {
     listboxId?: string;
     createId?: string;
 };
+/**
+ * Internal field wrapper shared by the Combobox family: renders the input area with
+ * its border/error/loading states and hosts the {@link SuggestionsDropdown}.
+ */
 export declare function FieldShell({ children, isOpen, dropdownOpen, isErrored, disabled, loading, width, minWidth, autosize, tightLeft, onShellMouseDown, onClose, showClear, onClear, clearLabel, showChevron, onToggle, dropdownItems, emptyText, loadingText, loadingMore, onLoadMore, createLabel, createActive, onCreate, listboxId, createId, }: FieldShellProps): ReactElement;
 export {};

package/shared/dropdownField/FieldShell.js

@@ -4,6 +4,10 @@ import { IndicatorButton, Indicators, Shell, ShellInner } from './styles';
 import { SuggestionsDropdown } from './SuggestionsDropdown';
 import { useDropdownPosition } from './useDropdownPosition';
 import { useLayer } from '../../hooks';
+/**
+ * Internal field wrapper shared by the Combobox family: renders the input area with
+ * its border/error/loading states and hosts the {@link SuggestionsDropdown}.
+ */
 export function FieldShell({
   children,
   isOpen,

package/shared/dropdownField/SuggestionsDropdown.d.ts

@@ -16,5 +16,9 @@ type SuggestionsDropdownProps = {
     createId?: string;
     zIndex?: number;
 };
+/**
+ * Internal floating option list shared by the Combobox family: renders the rows,
+ * empty/loading text, an optional "create" row and load-more support.
+ */
 export declare function SuggestionsDropdown({ floatingRef, floatingStyles, items, emptyText, loading, loadingText, loadingMore, onLoadMore, createLabel, createActive, onCreate, listboxId, createId, zIndex, }: SuggestionsDropdownProps): ReactElement | null;
 export {};

package/shared/dropdownField/SuggestionsDropdown.js

@@ -5,6 +5,10 @@ import { CreateItemLabel, Dropdown, DropdownEmpty, DropdownItem, DropdownLoading
 import { Spinner } from '../../Spinner';
 const LOAD_MORE_THRESHOLD = 24;
 const CREATE_KEY = '__create__';
+/**
+ * Internal floating option list shared by the Combobox family: renders the rows,
+ * empty/loading text, an optional "create" row and load-more support.
+ */
 export function SuggestionsDropdown({
   floatingRef,
   floatingStyles,

package/shared/dropdownField/constants.d.ts

@@ -3,4 +3,5 @@ export declare const LOADING_BORDER_COLORS: readonly [Color.PRIMARY, Color.BRIGH
 export declare const LOADING_BORDER_ANIMATION_MS = 3000;
 export declare const DROPDOWN_MAX_HEIGHT = 280;
 export declare const DROPDOWN_MAX_WIDTH = 320;
+/** Default debounce (ms) before an async `loadItems` call fires after the query changes. */
 export declare const DEFAULT_DEBOUNCE_MS = 250;

package/shared/dropdownField/constants.js

@@ -3,4 +3,5 @@ export const LOADING_BORDER_COLORS = [Color.PRIMARY, Color.BRIGHT, Color.BRAND_G
 export const LOADING_BORDER_ANIMATION_MS = 3000;
 export const DROPDOWN_MAX_HEIGHT = 280;
 export const DROPDOWN_MAX_WIDTH = 320;
+/** Default debounce (ms) before an async `loadItems` call fires after the query changes. */
 export const DEFAULT_DEBOUNCE_MS = 250;

package/shared/dropdownField/shared.d.ts

@@ -1,6 +1,13 @@
 import { type MouseEvent, type ReactNode, type RefObject } from 'react';
 import { type DropdownText } from './types';
+/** Resolves a {@link DropdownText} slot to a node, calling it with `query` if it's a function. */
 export declare function resolveDropdownText(text: DropdownText, query: string): ReactNode;
+/** Default key extractor — returns the item itself (for `string`/`number` items). */
 export declare function defaultGetKey<T>(item: T): string | number;
+/** Default item filter — case-insensitive substring match of the item's label against the query. */
 export declare function defaultLabelFilter<T>(item: T, query: string, getLabel: (item: T) => string): boolean;
+/**
+ * Mousedown handler for the field shell: refocuses the input and opens the dropdown,
+ * while letting clicks on the input itself or on inner buttons through.
+ */
 export declare function useShellMouseDown(inputRef: RefObject<HTMLInputElement>, isOpen: boolean, open: () => void): (event: MouseEvent<HTMLDivElement>) => void;

package/shared/dropdownField/shared.js

@@ -1,13 +1,20 @@
 import { useCallback } from 'react';
+/** Resolves a {@link DropdownText} slot to a node, calling it with `query` if it's a function. */
 export function resolveDropdownText(text, query) {
   return typeof text === 'function' ? text(query) : text;
 }
+/** Default key extractor — returns the item itself (for `string`/`number` items). */
 export function defaultGetKey(item) {
   return item;
 }
+/** Default item filter — case-insensitive substring match of the item's label against the query. */
 export function defaultLabelFilter(item, query, getLabel) {
   return getLabel(item).toLowerCase().includes(query.toLowerCase());
 }
+/**
+ * Mousedown handler for the field shell: refocuses the input and opens the dropdown,
+ * while letting clicks on the input itself or on inner buttons through.
+ */
 export function useShellMouseDown(inputRef, isOpen, open) {
   return useCallback(event => {
     var _inputRef$current;

package/shared/dropdownField/types.d.ts

@@ -54,11 +54,18 @@ export type ItemsSource<T> = {
     /** Don't call `loadItems` until the query has at least this many characters. */
     minChars?: number;
 };
+/** Normalized descriptor for one row rendered by {@link SuggestionsDropdown}. */
 export type DropdownItemDescriptor = {
+    /** Stable unique key. */
     key: string | number;
+    /** Optional DOM id (used for ARIA active-descendant). */
     id?: string;
+    /** Rendered row content. */
     label: ReactNode;
+    /** Row is the keyboard-highlighted one. */
     active?: boolean;
+    /** Row is the selected value. */
     selected?: boolean;
+    /** Called when the row is chosen. */
     onSelect?: () => void;
 };

package/shared/dropdownField/useActiveIndex.d.ts

@@ -1,2 +1,6 @@
 import { type Dispatch, type SetStateAction } from 'react';
+/**
+ * Holds the active (highlighted) row index, clamping it to `total` and resetting to
+ * `resetIndex` when the list changes.
+ */
 export declare function useActiveIndex(total: number, resetIndex: number): [number, Dispatch<SetStateAction<number>>];

package/shared/dropdownField/useActiveIndex.js

@@ -1,4 +1,8 @@
 import { useEffect, useState } from 'react';
+/**
+ * Holds the active (highlighted) row index, clamping it to `total` and resetting to
+ * `resetIndex` when the list changes.
+ */
 export function useActiveIndex(total, resetIndex) {
   const [activeIndex, setActiveIndex] = useState(resetIndex);
   useEffect(() => {

package/shared/dropdownField/useAsyncItems.d.ts

@@ -12,5 +12,9 @@ type Result<T> = {
     loadingMore: boolean;
     loadMore: () => void;
 };
+/**
+ * Drives async option loading for a Combobox field: debounces the query, respects
+ * `minChars`, paginates, and accumulates results with loading/load-more state.
+ */
 export declare function useAsyncItems<T>({ loadItems, query, isOpen, debounceMs, minChars, }: Args<T>): Result<T>;
 export {};

package/shared/dropdownField/useAsyncItems.js

@@ -1,6 +1,10 @@
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { DEFAULT_DEBOUNCE_MS } from './constants';
 import { useDebouncedValue } from './useDebouncedValue';
+/**
+ * Drives async option loading for a Combobox field: debounces the query, respects
+ * `minChars`, paginates, and accumulates results with loading/load-more state.
+ */
 export function useAsyncItems({
   loadItems,
   query,

package/shared/dropdownField/useDebouncedValue.d.ts

@@ -1 +1,2 @@
+/** Returns `value` debounced by `delay` ms (updates immediately when `delay <= 0`). */
 export declare function useDebouncedValue<V>(value: V, delay: number): V;

package/shared/dropdownField/useDebouncedValue.js

@@ -1,4 +1,5 @@
 import { useEffect, useState } from 'react';
+/** Returns `value` debounced by `delay` ms (updates immediately when `delay <= 0`). */
 export function useDebouncedValue(value, delay) {
   const [debounced, setDebounced] = useState(value);
   useEffect(() => {

package/shared/dropdownField/useDropdownItems.d.ts

@@ -17,5 +17,9 @@ type Result<T> = {
     loadingMore: boolean;
     loadMore: () => void;
 };
+/**
+ * Resolves the option list for a Combobox field from either static `items` or an
+ * async `loadItems` loader, applying the query filter and exposing loading/load-more state.
+ */
 export declare function useDropdownItems<T>({ items, loadItems, localItems, debounceMs, minChars, getLabel, filter, query, isOpen, }: Args<T>): Result<T>;
 export {};

package/shared/dropdownField/useDropdownItems.js

@@ -2,6 +2,10 @@ import { useMemo } from 'react';
 import { DEFAULT_DEBOUNCE_MS } from './constants';
 import { defaultLabelFilter } from './shared';
 import { useAsyncItems } from './useAsyncItems';
+/**
+ * Resolves the option list for a Combobox field from either static `items` or an
+ * async `loadItems` loader, applying the query filter and exposing loading/load-more state.
+ */
 export function useDropdownItems({
   items,
   loadItems,

package/shared/dropdownField/useDropdownPosition.d.ts

@@ -2,6 +2,10 @@ type Args = {
     isOpen?: boolean;
     onClickOutside?: () => void;
 };
+/**
+ * Positions the dropdown relative to the field via floating-ui (flip, offset,
+ * width/height sizing) and wires click-outside to `onClickOutside`.
+ */
 export declare function useDropdownPosition({ isOpen, onClickOutside }: Args): {
     setReference: (node: import("@floating-ui/react-dom").ReferenceType | null) => void;
     setFloating: (node: HTMLElement | null) => void;

package/shared/dropdownField/useDropdownPosition.js

@@ -1,6 +1,10 @@
 import { autoUpdate, flip, offset, size, useFloating } from '@floating-ui/react-dom';
 import { DROPDOWN_MAX_WIDTH } from './constants';
 import { useOnClickOutside } from '../../hooks';
+/**
+ * Positions the dropdown relative to the field via floating-ui (flip, offset,
+ * width/height sizing) and wires click-outside to `onClickOutside`.
+ */
 export function useDropdownPosition({
   isOpen,
   onClickOutside

package/shared/dropdownField/useFieldOpenEffects.d.ts

@@ -6,5 +6,9 @@ type Args = {
     autoFocus?: boolean;
     inputRef: RefObject<HTMLInputElement>;
 };
+/**
+ * Side effects tied to a Combobox field's open state: optional autofocus on mount
+ * and firing `onClose` when the field closes.
+ */
 export declare function useFieldOpenEffects({ isOpen, open, onClose, autoFocus, inputRef, }: Args): void;
 export {};

package/shared/dropdownField/useFieldOpenEffects.js

@@ -1,4 +1,8 @@
 import { useEffect, useRef } from 'react';
+/**
+ * Side effects tied to a Combobox field's open state: optional autofocus on mount
+ * and firing `onClose` when the field closes.
+ */
 export function useFieldOpenEffects({
   isOpen,
   open,

package/shared/dropdownField/useListNavigation.d.ts

@@ -14,5 +14,10 @@ type Args = {
     isQueryEmpty?: boolean;
     onBackspaceEmpty?: () => void;
 };
+/**
+ * Keyboard navigation for a Combobox list: arrow up/down to move the active row,
+ * Enter to select (or submit / pick the extra "create" row), Escape to close, and
+ * Backspace-on-empty handling.
+ */
 export declare function useListNavigation({ isOpen, open, itemCount, activeIndex, setActiveIndex, onSelectIndex, onEscape, onSubmit, onReachEnd, hasExtraRow, onSelectExtra, isQueryEmpty, onBackspaceEmpty, }: Args): (event: KeyboardEvent<HTMLInputElement>) => void;
 export {};

package/shared/dropdownField/useListNavigation.js

@@ -1,4 +1,9 @@
 import { useCallback } from 'react';
+/**
+ * Keyboard navigation for a Combobox list: arrow up/down to move the active row,
+ * Enter to select (or submit / pick the extra "create" row), Escape to close, and
+ * Backspace-on-empty handling.
+ */
 export function useListNavigation({
   isOpen,
   open,