@commercetools/nimbus 2.0.1 → 2.2.0

package/dist/components/combobox/components/combobox.hidden-input.d.ts

@@ -0,0 +1,17 @@
+import { ComboBoxHiddenInputProps } from '../combobox.types';
+/**
+ * # ComboBoxHiddenInput (Internal Component)
+ *
+ * Hidden input element for form submission.
+ * Follows React Aria's pattern for ComboBox form integration.
+ *
+ * By default, submits the selected item's key.
+ * When formValue="text" or allowsCustomOptions=true, submits the text value instead.
+ *
+ * @see https://react-spectrum.adobe.com/react-aria/ComboBox.html#html-forms
+ * @internal
+ */
+export declare const ComboBoxHiddenInput: {
+    <T extends object>(props: ComboBoxHiddenInputProps<T>): import("react/jsx-runtime").JSX.Element | null;
+    displayName: string;
+};

package/dist/components/combobox/components/combobox.input.d.ts

@@ -0,0 +1,20 @@
+import { ComboBoxInputProps } from '../combobox.types';
+/**
+ * # ComboBox.Input (Internal Component)
+ *
+ * Internal text input field for filtering and typing in the combobox.
+ * Automatically rendered by ComboBox.Trigger - not exposed to consumers.
+ *
+ * Consumes React Aria's InputContext which provides all necessary ARIA attributes
+ * (role, aria-autocomplete, aria-controls, aria-expanded, etc.).
+ *
+ * Input width dynamically adjusts to match the text content or placeholder length,
+ * collapsing to 1px when empty to avoid creating blank lines in multi-select mode.
+ *
+ * @internal
+ * @supportsStyleProps
+ */
+export declare const ComboBoxInput: {
+    (props: ComboBoxInputProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/dist/components/combobox/components/combobox.leading-element.d.ts

@@ -1,10 +1,12 @@
 /**
- * This component is needed as proxy around the leading element slot.
- * It measures the width of whatever the user hands over via `leadingElement`
- * and provides this width as css variable on the root element.
+ * # ComboBox.LeadingElement (Internal Component)
  *
- * the css variable is then used in the recipe to update the left-padding of the
- * input.
+ * Internal wrapper component that positions the leading element (icon, avatar, etc.)
+ * within the combobox trigger using CSS Grid's named template area.
+ * Automatically rendered by ComboBox.Trigger when leadingElement prop is provided.
+ *
+ * @internal
+ * @supportsStyleProps
  */
 export declare const ComboBoxLeadingElement: ({ children, }: {
     children: React.ReactNode;

package/dist/components/combobox/components/combobox.listbox.d.ts

@@ -0,0 +1,27 @@
+import { ComboBoxListBoxProps } from '../combobox.types';
+/**
+ * # ComboBox.ListBox
+ *
+ * Container for the dropdown options list that displays filtered results.
+ * Use the render prop pattern - do NOT manually map over items as this is less performant.
+ * The item is automatically provided from the items passed to ComboBox.Root.
+ *
+ * Automatically injects `id` and `textValue` props to Option components from item metadata.
+ *
+ * @example
+ * ```tsx
+ * <ComboBox.ListBox>
+ *   {(item) => (
+ *     <ComboBox.Option>
+ *       {item.name}
+ *     </ComboBox.Option>
+ *   )}
+ * </ComboBox.ListBox>
+ * ```
+ *
+ * @supportsStyleProps
+ */
+export declare function ComboBoxListBox<T extends object>({ children, ref, ...restProps }: ComboBoxListBoxProps<T>): import("react/jsx-runtime").JSX.Element;
+export declare namespace ComboBoxListBox {
+    var displayName: string;
+}

package/dist/components/combobox/components/combobox.option.d.ts

@@ -1,5 +1,34 @@
 import { ComboBoxOptionProps } from '../combobox.types';
-export declare const ComboBoxOption: {
-    <T extends object>({ children, ref, ...props }: ComboBoxOptionProps<T>): import("react/jsx-runtime").JSX.Element;
-    displayName: string;
-};
+/**
+ * # ComboBox.Option
+ *
+ * Individual option within the combobox listbox.
+ * Wraps React Aria's ListBoxItem for automatic ARIA management.
+ * Displays a checkmark indicator for selected items in multi-select mode.
+ * Supports render prop pattern for custom rendering.
+ *
+ * @example
+ * ```tsx
+ * <ComboBox.Root>
+ *   <ComboBox.Option id="1">Option 1</ComboBox.Option>
+ *   <ComboBox.Option id="2">Option 2</ComboBox.Option>
+ * </ComboBox.Root>
+ * ```
+ *
+ * @example Render prop pattern
+ * ```tsx
+ * <ComboBox.Option id="1">
+ *   {({ isSelected, isDisabled }) => (
+ *     <div>
+ *       Option 1 {isSelected && "(Selected)"}
+ *     </div>
+ *   )}
+ * </ComboBox.Option>
+ * ```
+ *
+ * @supportsStyleProps
+ */
+export declare function ComboBoxOption<T extends object>({ children, ref, ...props }: ComboBoxOptionProps<T>): import("react/jsx-runtime").JSX.Element;
+export declare namespace ComboBoxOption {
+    var displayName: string;
+}

package/dist/components/combobox/components/combobox.popover.d.ts

@@ -0,0 +1,27 @@
+import { ComboBoxPopoverProps } from '../combobox.types';
+/**
+ * # ComboBox.Popover
+ *
+ * Popover wrapper for the options dropdown list.
+ * Uses Nimbus Popover component which reads from PopoverContext provided by the custom context provider.
+ *
+ * The PopoverContext provides:
+ * - open state
+ * - positioning configuration (fixed strategy, bottom-start placement, --nimbus-combobox-trigger-width CSS var)
+ * - positionReference (trigger ref for proper positioning)
+ *
+ * @example
+ * ```tsx
+ * <ComboBox.Popover>
+ *   <ComboBox.ListBox>
+ *     {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
+ *   </ComboBox.ListBox>
+ * </ComboBox.Popover>
+ * ```
+ *
+ * @supportsStyleProps
+ */
+export declare const ComboBoxPopover: {
+    ({ children, ref, ...restProps }: ComboBoxPopoverProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/dist/components/combobox/components/combobox.root-context.d.ts

@@ -0,0 +1,13 @@
+import { ComboBoxRootContextValue } from '../combobox.types';
+/**
+ * Context for ComboBox state and configuration.
+ * Uses 'object' as the generic type since different ComboBox instances
+ * can have different item types, and TypeScript can't track this through context.
+ */
+export declare const ComboBoxRootContext: import('react').Context<ComboBoxRootContextValue<object> | null>;
+/**
+ * Hook to access ComboBox context with proper typing.
+ * The generic type T represents the item type used in the ComboBox.
+ * At runtime, the context contains the correct type from ComboBox.Root.
+ */
+export declare const useComboBoxRootContext: <T extends object = object>() => ComboBoxRootContextValue<T>;

package/dist/components/combobox/components/combobox.root.d.ts

@@ -1,12 +1,32 @@
 import { ComboBoxRootProps } from '../combobox.types';
 /**
- * # ComboBox
+ * # ComboBox.Root
  *
- * A combo box combines a text input with a dropdown list, allowing users to filter a list of options to items matching a query.
+ * Root component for ComboBox that provides state management and context for all child components.
+ * Handles selection state, input filtering, menu open/close, and custom option creation.
  *
- * @see {@link https://nimbus-documentation.vercel.app/components/inputs/combobox}
+ * @example
+ * ```tsx
+ * <ComboBox.Root
+ *   items={items}
+ *   getKey={(item) => item.id}
+ *   getTextValue={(item) => item.name}
+ *   onSelectionChange={(keys) => console.log(keys)}
+ * >
+ *   <ComboBox.Trigger>
+ *     <ComboBox.Input />
+ *   </ComboBox.Trigger>
+ *   <ComboBox.Popover>
+ *     <ComboBox.ListBox>
+ *       {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
+ *     </ComboBox.ListBox>
+ *   </ComboBox.Popover>
+ * </ComboBox.Root>
+ * ```
+ *
+ * @supportsStyleProps
  */
-export declare const ComboBoxRoot: {
-    <T extends object>({ children, ref, ...props }: ComboBoxRootProps<T>): import("react/jsx-runtime").JSX.Element;
-    displayName: string;
-};
+export declare function ComboBoxRoot<T extends object>(props: ComboBoxRootProps<T>): import("react/jsx-runtime").JSX.Element;
+export declare namespace ComboBoxRoot {
+    var displayName: string;
+}

package/dist/components/combobox/components/combobox.section.d.ts

@@ -0,0 +1,32 @@
+import { RefAttributes } from 'react';
+import { ComboBoxSectionProps } from '../combobox.types';
+/**
+ * # ComboBox.Section
+ *
+ * Section grouping for options with optional label header.
+ * Wraps React Aria's ListBoxSection component.
+ * Supports both static children and collection rendering with items.
+ *
+ * @example Static children
+ * ```tsx
+ * <ComboBox.ListBox>
+ *   <ComboBox.Section label="Fruits">
+ *     <ComboBox.Option id="apple">Apple</ComboBox.Option>
+ *     <ComboBox.Option id="banana">Banana</ComboBox.Option>
+ *   </ComboBox.Section>
+ * </ComboBox.ListBox>
+ * ```
+ *
+ * @example Collection rendering
+ * ```tsx
+ * <ComboBox.Section label="Fruits" items={fruits}>
+ *   {(item) => <ComboBox.Option id={item.id}>{item.name}</ComboBox.Option>}
+ * </ComboBox.Section>
+ * ```
+ *
+ * @supportsStyleProps
+ */
+export declare function ComboBoxSection<T extends object>({ children, label, items, ref, ...props }: ComboBoxSectionProps<T> & RefAttributes<HTMLDivElement>): import("react/jsx-runtime").JSX.Element;
+export declare namespace ComboBoxSection {
+    var displayName: string;
+}

package/dist/components/combobox/components/combobox.tag-group.d.ts

@@ -0,0 +1,26 @@
+import { ComboBoxTagGroupProps } from '../combobox.types';
+/**
+ * # ComboBox.TagGroup (Internal Component)
+ *
+ * Internal component that displays selected items as tags in multi-select mode.
+ * Automatically rendered by ComboBox.Trigger - not exposed to consumers.
+ *
+ * Consumes React-Aria's TagGroupContext, which is populated by the
+ * TagGroupContextProvider in ComboBox.Root with:
+ * - items: selected items array from collection
+ * - onRemove: handler to remove tags
+ * - size: tag size matching ComboBox size
+ * - aria-label: accessible label for the tag group
+ * - id: generated in ComboBox.Root
+ * - selectionMode: "none" (tags are not selectable)
+ * - disabledKeys: disabled tag keys
+ *
+ * Renders null in single-select mode to avoid unnecessary DOM elements.
+ *
+ * @internal
+ * @supportsStyleProps
+ */
+export declare const ComboBoxTagGroup: {
+    (props: ComboBoxTagGroupProps): import("react/jsx-runtime").JSX.Element | null;
+    displayName: string;
+};

package/dist/components/combobox/components/combobox.trigger.d.ts

@@ -0,0 +1,26 @@
+import { ComboBoxTriggerProps } from '../combobox.types';
+/**
+ * # ComboBox.Trigger
+ *
+ * The trigger element that contains the input field and controls for the combobox.
+ * Automatically renders the tag group (for multi-select), input field, toggle button, and clear button.
+ * Handles click interactions to focus the input when clicking anywhere on the trigger area.
+ *
+ * @example
+ * ```tsx
+ * <ComboBox.Root>
+ *   <ComboBox.Trigger />
+ *   <ComboBox.Popover>
+ *     <ComboBox.ListBox>
+ *       <ComboBox.Item value="option1">Option 1</ComboBox.Item>
+ *     </ComboBox.ListBox>
+ *   </ComboBox.Popover>
+ * </ComboBox.Root>
+ * ```
+ *
+ * @supportsStyleProps
+ */
+export declare const ComboBoxTrigger: {
+    ({ children, ...restProps }: ComboBoxTriggerProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/dist/components/combobox/components/index.d.ts

@@ -0,0 +1,6 @@
+export { ComboBoxRoot } from './combobox.root';
+export { ComboBoxTrigger } from './combobox.trigger';
+export { ComboBoxPopover } from './combobox.popover';
+export { ComboBoxListBox } from './combobox.listbox';
+export { ComboBoxOption } from './combobox.option';
+export { ComboBoxSection } from './combobox.section';

package/dist/components/combobox/index.d.ts

@@ -1,2 +1,2 @@
-export * from './combobox';
+export { ComboBox } from './combobox';
 export * from './combobox.types';

package/dist/components/combobox/intl/de.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Pre-compiled de messages for ComboBox
+ * Generated by @internationalized/string-compiler
+ * DO NOT EDIT MANUALLY
+ */
+declare const _default: {
+    clearSelection: string;
+    toggleOptions: string;
+    selectedValues: string;
+    options: string;
+};
+export default _default;

package/dist/components/combobox/intl/en.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Pre-compiled en messages for ComboBox
+ * Generated by @internationalized/string-compiler
+ * DO NOT EDIT MANUALLY
+ */
+declare const _default: {
+    clearSelection: string;
+    toggleOptions: string;
+    selectedValues: string;
+    options: string;
+};
+export default _default;

package/dist/components/combobox/intl/es.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Pre-compiled es messages for ComboBox
+ * Generated by @internationalized/string-compiler
+ * DO NOT EDIT MANUALLY
+ */
+declare const _default: {
+    clearSelection: string;
+    toggleOptions: string;
+    selectedValues: string;
+    options: string;
+};
+export default _default;

package/dist/components/combobox/intl/fr-FR.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Pre-compiled fr-FR messages for ComboBox
+ * Generated by @internationalized/string-compiler
+ * DO NOT EDIT MANUALLY
+ */
+declare const _default: {
+    clearSelection: string;
+    toggleOptions: string;
+    selectedValues: string;
+    options: string;
+};
+export default _default;

package/dist/components/combobox/intl/pt-BR.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Pre-compiled pt-BR messages for ComboBox
+ * Generated by @internationalized/string-compiler
+ * DO NOT EDIT MANUALLY
+ */
+declare const _default: {
+    clearSelection: string;
+    toggleOptions: string;
+    selectedValues: string;
+    options: string;
+};
+export default _default;

package/dist/components/combobox/utils/collection.d.ts

@@ -0,0 +1,13 @@
+import { Key } from 'react-stately';
+/**
+ * Default key extractor - uses string/number id or object with id property
+ */
+export declare function defaultGetKey<T extends object>(item: T | string | number): Key;
+/**
+ * Default text value extractor - uses string item or object with name property
+ */
+export declare function defaultGetTextValue<T extends object>(item: T | string): string;
+/**
+ * Default getNewOptionData - creates an object with id and name
+ */
+export declare function defaultGetNewOptionData<T extends object>(inputValue: string): T;