@commercetools/nimbus 2.0.1 → 2.2.0

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

@@ -0,0 +1,339 @@
+import { Node } from 'react-stately';
+/**
+ * Default text-based filter for combobox items
+ * Filters individual items by their text content
+ * Does NOT handle sections - use createSectionAwareFilter for that
+ *
+ * @param nodes - Collection nodes to filter
+ * @param inputValue - Current filter text from input
+ * @returns Filtered collection nodes containing only items that match the input
+ *
+ * @example
+ * ```tsx
+ * <ComboBox.Root
+ *   items={items}
+ *   filter={filterByText}
+ *   placeholder="Search..."
+ * />
+ * ```
+ *
+ * **Behavior:**
+ * - Case-insensitive substring matching
+ * - Returns all nodes when input is empty or whitespace
+ * - Filters based on Node.textValue property
+ * - Does not preserve sections (use section-aware filter for that)
+ *
+ * **Note:** This filter works on individual items only. For filtering with
+ * sections preserved, use `createSectionAwareFilter` to wrap your custom
+ * filter logic.
+ */
+export declare function filterByText<T extends object>(nodes: Iterable<Node<T>>, inputValue: string): Iterable<Node<T>>;
+/**
+ * Starts-with filter for combobox items
+ * Matches items where textValue begins with the input
+ *
+ * @param nodes - Collection nodes to filter
+ * @param inputValue - Current filter text from input
+ * @returns Filtered collection nodes containing only items that start with the input
+ *
+ * @example
+ * ```tsx
+ * <ComboBox.Root
+ *   items={items}
+ *   filter={filterByStartsWith}
+ *   placeholder="Type to filter..."
+ * />
+ * ```
+ *
+ * **Behavior:**
+ * - Case-insensitive prefix matching
+ * - More restrictive than substring matching
+ * - Useful for autocomplete-style filtering
+ * - Returns all nodes when input is empty
+ *
+ * **Use Cases:**
+ * - Country/state selection where users type the beginning
+ * - Name lookups where first letters matter
+ * - Command palettes with prefix shortcuts
+ */
+export declare function filterByStartsWith<T extends object>(nodes: Iterable<Node<T>>, inputValue: string): Iterable<Node<T>>;
+/**
+ * Case-sensitive filter for combobox items
+ * Matches items with exact case matching
+ *
+ * @param nodes - Collection nodes to filter
+ * @param inputValue - Current filter text from input
+ * @returns Filtered collection nodes containing only items that match with exact case
+ *
+ * @example
+ * ```tsx
+ * <ComboBox.Root
+ *   items={programmingLanguages}
+ *   filter={filterByCaseSensitive}
+ *   placeholder="Case-sensitive search..."
+ * />
+ * ```
+ *
+ * **Behavior:**
+ * - Exact case matching (case-sensitive substring)
+ * - More precise than case-insensitive filtering
+ * - Returns all nodes when input is empty
+ *
+ * **Use Cases:**
+ * - Code/variable name search
+ * - File path filtering
+ * - Technical identifiers that are case-sensitive
+ */
+export declare function filterByCaseSensitive<T extends object>(nodes: Iterable<Node<T>>, inputValue: string): Iterable<Node<T>>;
+/**
+ * Word boundary filter for combobox items
+ * Matches items where input appears at word boundaries
+ *
+ * @param nodes - Collection nodes to filter
+ * @param inputValue - Current filter text from input
+ * @returns Filtered collection nodes where input matches at word boundaries
+ *
+ * @example
+ * ```tsx
+ * <ComboBox.Root
+ *   items={items}
+ *   filter={filterByWordBoundary}
+ *   placeholder="Search by word..."
+ * />
+ * ```
+ *
+ * **Behavior:**
+ * - Matches whole words or word beginnings
+ * - Case-insensitive
+ * - Input "eagle" matches "Bald Eagle" but not "beagle"
+ * - Returns all nodes when input is empty
+ *
+ * **Use Cases:**
+ * - Product search where partial words don't make sense
+ * - Name search with multiple words
+ * - Tag/category filtering
+ */
+export declare function filterByWordBoundary<T extends object>(nodes: Iterable<Node<T>>, inputValue: string): Iterable<Node<T>>;
+/**
+ * Fuzzy matching filter for combobox items
+ * Matches items where all input characters appear in order (but not necessarily consecutive)
+ *
+ * @param nodes - Collection nodes to filter
+ * @param inputValue - Current filter text from input
+ * @returns Filtered collection nodes that match the fuzzy pattern
+ *
+ * @example
+ * ```tsx
+ * <ComboBox.Root
+ *   items={items}
+ *   filter={filterByFuzzy}
+ *   placeholder="Fuzzy search..."
+ * />
+ * ```
+ *
+ * **Behavior:**
+ * - Case-insensitive fuzzy matching
+ * - Input "ble" matches "Bald Eagle"
+ * - All characters must appear in order, but can have gaps
+ * - More forgiving than substring matching
+ * - Returns all nodes when input is empty
+ *
+ * **Use Cases:**
+ * - Quick command/action selection
+ * - File/folder navigation
+ * - Large lists where users know approximate spelling
+ * - Abbreviated lookups (e.g., "nj" for "New Jersey")
+ */
+export declare function filterByFuzzy<T extends object>(nodes: Iterable<Node<T>>, inputValue: string): Iterable<Node<T>>;
+/**
+ * Creates a filter that searches across multiple object properties
+ * Useful when items have structured data with multiple searchable fields
+ *
+ * @param propertyPaths - Array of property paths to search (e.g., ['name', 'description', 'tags'])
+ * @returns A filter function that searches across specified properties
+ *
+ * @example
+ * ```tsx
+ * type Product = {
+ *   name: string;
+ *   category: string;
+ *   description: string;
+ * };
+ *
+ * const productFilter = createMultiPropertyFilter<Product>(['name', 'category', 'description']);
+ *
+ * <ComboBox.Root
+ *   items={products}
+ *   filter={productFilter}
+ *   placeholder="Search products..."
+ * >
+ *   {(item) => <ComboBox.Option textValue={item.name}>{item.name}</ComboBox.Option>}
+ * </ComboBox.Root>
+ * ```
+ *
+ * **Behavior:**
+ * - Searches all specified properties
+ * - Case-insensitive substring matching
+ * - Matches if ANY property contains the input
+ * - Returns all nodes when input is empty
+ *
+ * **Use Cases:**
+ * - Product catalogs with multiple searchable fields
+ * - User directories (search by name, email, department)
+ * - Document search (title, author, tags, content)
+ * - Complex data structures with nested properties
+ *
+ * **Note:** Uses node.value to access the original item data.
+ * If you need to search nested properties, use dot notation: 'address.city'
+ */
+export declare function createMultiPropertyFilter<T extends object>(propertyPaths: string[]): (nodes: Iterable<Node<T>>, inputValue: string) => Iterable<Node<T>>;
+/**
+ * Creates a filter with custom scoring/ranking logic
+ * Returns items sorted by relevance score (highest first)
+ *
+ * @param scoreFn - Function that returns a relevance score for each item (higher = more relevant)
+ * @returns A filter function that sorts results by score
+ *
+ * @example
+ * ```tsx
+ * // Prefer items that start with input, but also include substring matches
+ * const rankedFilter = createRankedFilter<SimpleOption>((node, inputValue) => {
+ *   const text = node.textValue.toLowerCase();
+ *   const input = inputValue.toLowerCase();
+ *
+ *   if (text.startsWith(input)) return 100; // Highest score for prefix match
+ *   if (text.includes(input)) return 50;    // Lower score for substring match
+ *   return 0;                               // No match
+ * });
+ *
+ * <ComboBox.Root
+ *   items={items}
+ *   filter={rankedFilter}
+ *   placeholder="Search..."
+ * />
+ * ```
+ *
+ * **Behavior:**
+ * - Applies custom scoring logic to each item
+ * - Filters out items with score <= 0
+ * - Sorts remaining items by score (descending)
+ * - Returns all nodes when input is empty
+ *
+ * **Use Cases:**
+ * - Search with relevance ranking
+ * - Prioritizing certain match types (prefix vs substring)
+ * - Boosting items based on metadata (popularity, recency, etc.)
+ * - Implementing search algorithms like TF-IDF
+ *
+ * **Score Guidelines:**
+ * - Return 0 or negative for non-matches (will be filtered out)
+ * - Higher scores = better matches
+ * - Consider using score ranges (e.g., 0-100) for consistent behavior
+ */
+export declare function createRankedFilter<T extends object>(scoreFn: (node: Node<T>, inputValue: string) => number): (nodes: Iterable<Node<T>>, inputValue: string) => Iterable<Node<T>>;
+/**
+ * Creates a filter that matches any of multiple input terms (OR logic)
+ * Splits input by spaces and matches if any term matches
+ *
+ * @param baseFilter - The underlying filter to use for each term (defaults to filterByText)
+ * @returns A filter function that matches any term
+ *
+ * @example
+ * ```tsx
+ * const multiTermFilter = createMultiTermFilter();
+ *
+ * <ComboBox.Root
+ *   items={items}
+ *   filter={multiTermFilter}
+ *   placeholder="Search (space-separated terms)..."
+ * />
+ * // Input "eagle bison" matches both "Bald Eagle" and "Bison"
+ * ```
+ *
+ * **Behavior:**
+ * - Splits input by whitespace
+ * - Matches if ANY term matches (OR logic)
+ * - Each term is filtered using the base filter
+ * - Returns all nodes when input is empty
+ *
+ * **Use Cases:**
+ * - Search with multiple keywords
+ * - Tag-based filtering (e.g., "react typescript")
+ * - Alternative spellings or synonyms
+ * - Flexible search where users enter multiple criteria
+ *
+ * **Note:** To require ALL terms to match (AND logic), consider chaining filters
+ * or implementing a custom filter function.
+ */
+export declare function createMultiTermFilter<T extends object>(baseFilter?: (nodes: Iterable<Node<T>>, inputValue: string) => Iterable<Node<T>>): (nodes: Iterable<Node<T>>, inputValue: string) => Iterable<Node<T>>;
+/**
+ * Creates a section-aware filter that preserves section structure
+ * Wraps a custom filter function to work with sections, hiding empty sections
+ *
+ * @param itemFilter - Filter function to apply to individual items
+ * @returns A filter function that preserves sections and hides empty ones
+ *
+ * @example
+ * ```tsx
+ * // Using with built-in filters
+ * const sectionAwareStartsWith = createSectionAwareFilter(
+ *   (nodes, input) => filterByStartsWith(nodes, input)
+ * );
+ *
+ * <ComboBox.Root
+ *   items={sectionsWithItems}
+ *   filter={sectionAwareStartsWith}
+ * >
+ *   {(section) => (
+ *     <ComboBox.Section title={section.name}>
+ *       {section.items.map((item) => (
+ *         <ComboBox.Option key={item.id} textValue={item.name}>
+ *           {item.name}
+ *         </ComboBox.Option>
+ *       ))}
+ *     </ComboBox.Section>
+ *   )}
+ * </ComboBox.Root>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Using with custom filter logic
+ * const customSectionFilter = createSectionAwareFilter(
+ *   (nodes, input) => {
+ *     const lowerInput = input.toLowerCase();
+ *     const filtered: Node<T>[] = [];
+ *     for (const node of nodes) {
+ *       // Custom filtering logic
+ *       if (node.textValue.toLowerCase().startsWith(lowerInput)) {
+ *         filtered.push(node);
+ *       }
+ *     }
+ *     return filtered;
+ *   }
+ * );
+ * ```
+ *
+ * **Behavior:**
+ * - Applies the item filter to items within each section
+ * - Preserves section nodes in the output
+ * - Automatically hides sections that have no matching items
+ * - Returns all nodes when input is empty
+ *
+ * **Use Cases:**
+ * - Categorized combobox options (Animals → Mammals, Birds, etc.)
+ * - Grouped data where sections provide context
+ * - Multi-level hierarchies that need filtering
+ * - Search where maintaining visual grouping is important
+ *
+ * **Important Notes:**
+ * - The item filter receives ONLY item nodes (not section nodes)
+ * - Section nodes are detected by checking node.type === "section"
+ * - Empty sections are automatically excluded from results
+ * - Section order is preserved from the original collection
+ *
+ * **Performance:**
+ * - Filters items separately for each section
+ * - More efficient than flat filtering for large datasets with many sections
+ */
+export declare function createSectionAwareFilter<T extends object>(itemFilter: (nodes: Iterable<Node<T>>, inputValue: string) => Iterable<Node<T>>): (nodes: Iterable<Node<T>>, inputValue: string) => Iterable<Node<T>>;

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

@@ -0,0 +1,10 @@
+import { Key } from 'react-stately';
+/**
+ * Normalize selectedKeys to Set format
+ */
+export declare const normalizeSelectedKeys: (keys: Key | Key[] | undefined | null) => Set<Key>;
+/**
+ * Denormalize selectedKeys from Set to array
+ * Always returns an array regardless of selection mode for simpler API
+ */
+export declare const denormalizeSelectedKeys: (keys: Set<Key>) => Key[];

package/dist/components/combobox/utils/test-data.d.ts

@@ -0,0 +1,6 @@
+/** most basic option */
+export type SimpleOption = {
+    name: string;
+    id: number;
+};
+export declare const simpleOptions: SimpleOption[];

package/dist/components/combobox/utils/test-utils.d.ts

@@ -0,0 +1,30 @@
+import { ComboBoxRootProps } from '../combobox.types';
+export declare function ComposedComboBox<T extends object>(props: ComboBoxRootProps<T>): import("react/jsx-runtime").JSX.Element;
+/** Initial Pokemomn API return type */
+export type Pokemon = {
+    name: string;
+    url: string;
+};
+/** Pokemon API Details return type */
+export type PokemonDetails = {
+    id: number;
+    name: string;
+    sprites: {
+        front_default: string;
+    };
+    types: Array<{
+        type: {
+            name: string;
+        };
+    }>;
+    height: number;
+    weight: number;
+    base_experience: number;
+};
+/**
+ * Reusable Pokemon option component that displays detailed information.
+ * Fetches full Pokemon details on mount and displays sprite, name, types, and stats.
+ */
+export declare const PokemonOption: ({ pokemon }: {
+    pokemon: Pokemon;
+}) => import("react/jsx-runtime").JSX.Element;

package/dist/components/combobox.cjs

@@ -1,2 +1,2 @@
-"use strict";const o=require("../chunks/combobox-Bntl4sYo.cjs.js");exports.ComboBox=o.ComboBox;exports._ComboBoxOption=o.ComboBoxOption;exports._ComboBoxOptionGroup=o.ComboBoxOptionGroup;exports._ComboBoxRoot=o.ComboBoxRoot;
+"use strict";const o=require("../chunks/combobox-B7ck7gxL.cjs.js");exports.ComboBox=o.ComboBox;
 //# sourceMappingURL=combobox.cjs.map

package/dist/components/combobox.es.js

@@ -1,8 +1,5 @@
-import { C as b, c as m, b as x, a as C } from "../chunks/combobox-DYREbkL7.es.js";
+import { C as r } from "../chunks/combobox-vjauyzlS.es.js";
 export {
-  b as ComboBox,
-  m as _ComboBoxOption,
-  x as _ComboBoxOptionGroup,
-  C as _ComboBoxRoot
+  r as ComboBox
 };
 //# sourceMappingURL=combobox.es.js.map

package/dist/components/components.cjs

@@ -1,2 +1,2 @@
-"use strict";const o=require("../chunks/dialog.title-CynBe3KN.cjs.js");exports.DialogBody=o.DialogBody;exports.DialogCloseTrigger=o.DialogCloseTrigger;exports.DialogContent=o.DialogContent;exports.DialogFooter=o.DialogFooter;exports.DialogHeader=o.DialogHeader;exports.DialogRoot=o.DialogRoot;exports.DialogTitle=o.DialogTitle;exports.DialogTrigger=o.DialogTrigger;
+"use strict";const o=require("../chunks/accordion.content-Cqet9SQ-.cjs.js");exports.AccordionContent=o.AccordionContent;exports.AccordionHeader=o.AccordionHeader;exports.AccordionHeaderRightContent=o.AccordionHeaderRightContent;exports.AccordionItem=o.AccordionItem;exports.AccordionRoot=o.AccordionRoot;
 //# sourceMappingURL=components.cjs.map

package/dist/components/components.es.js

@@ -1,12 +1,9 @@
-import { d as g, g as i, b as e, e as l, c as s, D, f as r, a as t } from "../chunks/dialog.title-CfBfNT9q.es.js";
+import { c as n, b as r, d as a, a as d, A as e } from "../chunks/accordion.content-GGayEeqD.es.js";
 export {
-  g as DialogBody,
-  i as DialogCloseTrigger,
-  e as DialogContent,
-  l as DialogFooter,
-  s as DialogHeader,
-  D as DialogRoot,
-  r as DialogTitle,
-  t as DialogTrigger
+  n as AccordionContent,
+  r as AccordionHeader,
+  a as AccordionHeaderRightContent,
+  d as AccordionItem,
+  e as AccordionRoot
 };
 //# sourceMappingURL=components.es.js.map

package/dist/components/data-table/components/data-table.body.d.ts

@@ -1,4 +1,9 @@
 import { DataTableBodyProps, DataTableRowItem } from '../data-table.types';
+/**
+ * DataTable.Body - The table body section that renders all data rows with selection and expansion capabilities
+ *
+ * @supportsStyleProps
+ */
 export declare const DataTableBody: {
     <T extends DataTableRowItem = DataTableRowItem>({ ref, ...props }: DataTableBodyProps<T>): import("react/jsx-runtime").JSX.Element;
     displayName: string;

package/dist/components/data-table/components/data-table.cell.d.ts

@@ -1,2 +1,10 @@
 import { DataTableCellProps } from '../data-table.types';
-export declare const DataTableCell: ({ ref, children, isDisabled, ...props }: DataTableCellProps) => import("react/jsx-runtime").JSX.Element;
+/**
+ * DataTable.Cell - Individual cell component that displays data values with proper accessibility attributes
+ *
+ * @supportsStyleProps
+ */
+export declare const DataTableCell: {
+    ({ ref, children, isDisabled, ...props }: DataTableCellProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/dist/components/data-table/components/data-table.column.d.ts

@@ -1,2 +1,7 @@
 import { DataTableColumnComponent } from '../data-table.types';
+/**
+ * DataTable.Column - Individual column header component that handles sorting interactions
+ *
+ * @supportsStyleProps
+ */
 export declare const DataTableColumn: DataTableColumnComponent;

package/dist/components/data-table/components/data-table.context.d.ts

@@ -1,3 +1,5 @@
-import { DataTableContextValue } from '../data-table.types';
+import { DataTableContextValue, CustomSettingsContextValue } from '../data-table.types';
 export declare const DataTableContext: import('react').Context<DataTableContextValue<Record<string, unknown>> | null>;
+export declare const CustomSettingsContext: import('react').Context<CustomSettingsContextValue | null>;
 export declare const useDataTableContext: <T extends object = Record<string, unknown>>() => DataTableContextValue<T>;
+export declare const useCustomSettingsContext: () => CustomSettingsContextValue;

package/dist/components/data-table/components/data-table.footer.d.ts

@@ -5,6 +5,11 @@ export type DataTableFooterProps = {
      */
     ref?: React.Ref<HTMLDivElement>;
 };
+/**
+ * DataTable.Footer - Optional footer section for displaying summary information, pagination, or actions
+ *
+ * @supportsStyleProps
+ */
 export declare const DataTableFooter: {
     ({ ref: forwardedRef, children, ...props }: DataTableFooterProps): import("react/jsx-runtime").JSX.Element;
     displayName: string;

package/dist/components/data-table/components/data-table.header.d.ts

@@ -1,4 +1,9 @@
 import { DataTableHeaderProps, DataTableColumnItem } from '../data-table.types';
+/**
+ * DataTable.Header - The table header section that renders column headers with sorting capabilities
+ *
+ * @supportsStyleProps
+ */
 export declare const DataTableHeader: {
     <T extends DataTableColumnItem = DataTableColumnItem>({ ref, ...props }: DataTableHeaderProps<T>): import("react/jsx-runtime").JSX.Element;
     displayName: string;

package/dist/components/data-table/components/data-table.layout-settings-panel.d.ts

@@ -0,0 +1,4 @@
+import { DataTableProps } from '../data-table.types';
+export declare const LayoutSettingsPanel: ({ onSettingsChange, }: {
+    onSettingsChange?: DataTableProps["onSettingsChange"];
+}) => import("react/jsx-runtime").JSX.Element;

package/dist/components/data-table/components/data-table.manager.d.ts

@@ -0,0 +1,9 @@
+/**
+ * DataTable.Manager - Manager component for the data table
+ *
+ * @supportsStyleProps
+ */
+export declare const DataTableManager: {
+    (): import("react/jsx-runtime").JSX.Element | null;
+    displayName: string;
+};

package/dist/components/data-table/components/data-table.root.d.ts

@@ -1,4 +1,9 @@
 import { DataTableProps } from '../data-table.types';
+/**
+ * DataTable.Root - The root container that provides context and state management for the entire data table
+ *
+ * @supportsStyleProps
+ */
 export declare const DataTableRoot: {
     <T extends object = Record<string, unknown>>(props: DataTableProps<T>): import("react/jsx-runtime").JSX.Element;
     displayName: string;

package/dist/components/data-table/components/data-table.table.d.ts

@@ -1,4 +1,9 @@
 import { DataTableTableSlotProps } from '../data-table.types';
+/**
+ * DataTable.Table - The main table element that wraps the header and body components
+ *
+ * @supportsStyleProps
+ */
 export declare const DataTableTable: {
     ({ ref: forwardedRef, children, ...props }: DataTableTableSlotProps): import("react/jsx-runtime").JSX.Element;
     displayName: string;

package/dist/components/data-table/components/data-table.visible-columns-panel.d.ts

@@ -0,0 +1,7 @@
+import { ColumnManagerListItem } from '../data-table.types';
+export declare const VisibleColumnsPanel: ({ hiddenItems, visibleItems, handleVisibleColumnsUpdate, handleResetColumns, }: {
+    hiddenItems: ColumnManagerListItem[];
+    visibleItems: ColumnManagerListItem[];
+    handleVisibleColumnsUpdate: (updatedItems: ColumnManagerListItem[]) => void;
+    handleResetColumns: () => void;
+}) => import("react/jsx-runtime").JSX.Element | null;

package/dist/components/data-table/components/index.d.ts

@@ -0,0 +1,10 @@
+export { DataTableRoot } from './data-table.root';
+export { DataTableTable } from './data-table.table';
+export { DataTableHeader } from './data-table.header';
+export { DataTableColumn } from './data-table.column';
+export { DataTableBody } from './data-table.body';
+export { DataTableRow } from './data-table.row';
+export { DataTableCell } from './data-table.cell';
+export { DataTableFooter } from './data-table.footer';
+export { DataTableManager } from './data-table.manager';
+export { DataTableContext, useDataTableContext, useCustomSettingsContext, } from './data-table.context';

package/dist/components/data-table/constants.d.ts

@@ -0,0 +1,4 @@
+export declare const UPDATE_ACTIONS: {
+    readonly TOGGLE_TEXT_VISIBILITY: "toggleTextVisibility";
+    readonly TOGGLE_ROW_DENSITY: "toggleRowDensity";
+};