@adamosuiteservices/ui 1.5.6 → 1.6.7

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

@@ -1,35 +1,230 @@
+import { ComponentType, ReactNode } from 'react';
+/**
+ * Represents a single option in the combobox.
+ */
 type ComboboxOption = {
+    /** Unique value identifier for the option */
     value: string;
+    /** Display text for the option */
     label: string;
+    /** Whether the option is disabled and cannot be selected */
     disabled?: boolean;
 };
+/**
+ * Customizable text labels used throughout the combobox.
+ */
 type ComboboxLabels = {
+    /** Text shown when no option is selected */
     placeholder?: string;
+    /** Placeholder text for the search input */
     searchPlaceholder?: string;
+    /** Message displayed when no options match the search */
     noItemsFound?: string;
+    /** Function to generate text when multiple items are selected. Receives the count of selected items. */
     multipleSelected?: (count: number) => string;
 };
+/**
+ * CSS class names for customizing component styling.
+ */
 type ComboboxClassNames = {
+    /** Class name for the trigger button */
     trigger?: string;
+    /** Class name for the popover container */
     popover?: string;
+    /** Class name for the command component */
     command?: string;
+    /** Class name for the search input */
     input?: string;
+    /** Class name for the options list */
     list?: string;
+    /** Class name for the empty state message */
     empty?: string;
+    /** Class name for the option group */
     group?: string;
+    /** Class name for individual option items */
     item?: string;
+    /** Class name for checkbox elements */
     checkbox?: string;
+    /** Class name for check icon elements */
     check?: string;
 };
+/**
+ * Render prop functions for customizing component rendering.
+ * Each render prop receives relevant data and allows complete control over that part of the UI.
+ */
+type ComboboxRenderProps = {
+    /**
+     * Custom renderer for the entire trigger button.
+     * @param props.open - Whether the popover is open
+     * @param props.value - Current selected value(s)
+     * @param props.displayText - Formatted display text for selected value(s)
+     * @param props.placeholder - Placeholder text
+     * @param props.hasValue - Whether any value is selected
+     * @param props.icon - Optional icon component
+     * @param props.showIcon - Whether to show the icon
+     */
+    trigger?: (props: {
+        open: boolean;
+        value: string | string[];
+        displayText: string | null;
+        placeholder: string;
+        hasValue: boolean;
+        icon?: ComponentType<{
+            className?: string;
+        }>;
+    }) => ReactNode;
+    /**
+     * Custom renderer for the trigger dropdown icon.
+     * @param props.open - Whether the popover is open
+     */
+    triggerIcon?: (props: {
+        open: boolean;
+    }) => ReactNode;
+    /**
+     * Custom renderer for the placeholder text.
+     * @param props.text - The placeholder text
+     * @param props.hasValue - Whether any value is selected
+     */
+    placeholder?: (props: {
+        text: string;
+        hasValue: boolean;
+    }) => ReactNode;
+    /**
+     * Custom renderer for displaying selected value(s).
+     * @param props.text - Formatted display text
+     * @param props.value - Current selected value(s)
+     */
+    displayValue?: (props: {
+        text: string | null;
+        value: string | string[];
+    }) => ReactNode;
+    /**
+     * Custom renderer for an entire option item.
+     * @param props.option - The option data
+     * @param props.isSelected - Whether this option is currently selected
+     * @param props.selectedFeedback - Type of selection feedback ("checkbox" or "check")
+     */
+    option?: (props: {
+        option: ComboboxOption;
+        isSelected: boolean;
+        selectedFeedback: "checkbox" | "check";
+    }) => ReactNode;
+    /**
+     * Custom renderer for just the option label text.
+     * @param props.option - The option data
+     */
+    optionLabel?: (props: {
+        option: ComboboxOption;
+    }) => ReactNode;
+    /**
+     * Custom renderer for the selection feedback indicator (checkbox or check).
+     * @param props.option - The option data
+     * @param props.isSelected - Whether this option is currently selected
+     * @param props.type - Type of feedback indicator
+     */
+    selectedFeedback?: (props: {
+        option: ComboboxOption;
+        isSelected: boolean;
+        type: "checkbox" | "check";
+    }) => ReactNode;
+    /**
+     * Custom renderer for the empty state when no options match.
+     * @param props.text - The "no items found" message
+     */
+    empty?: (props: {
+        text: string;
+    }) => ReactNode;
+    /**
+     * Custom renderer for the search input field.
+     * @param props.placeholder - Placeholder text for the search input
+     */
+    searchInput?: (props: {
+        placeholder: string;
+    }) => ReactNode;
+};
+/**
+ * Props for the Combobox component.
+ */
 type ComboboxProps = Readonly<{
+    /** Enable search/filter functionality within the combobox */
     searchable?: boolean;
+    /** Allow multiple options to be selected simultaneously */
     multiple?: boolean;
+    /** Optional icon component to display in the trigger */
+    icon?: ComponentType<{
+        className?: string;
+    }>;
+    /** Controlled value for the combobox. Can be a single value or array of values for multiple selection. */
     value?: string | string[];
+    /** Callback fired when the selected value changes */
     onValueChange?: (value: string | string[]) => void;
+    /** Customizable text labels for various UI elements */
     labels?: ComboboxLabels;
+    /** Array of options to display in the combobox */
     options: ComboboxOption[];
+    /** CSS class names for styling various parts of the component */
     classNames?: ComboboxClassNames;
+    /** Type of selection feedback indicator to show ("checkbox" or "check") */
     selectedFeedback?: "checkbox" | "check";
+    /** Always show the placeholder text even when a value is selected. When enabled, both placeholder and value are displayed. */
+    alwaysShowPlaceholder?: boolean;
+    /** Position where the selected value is displayed when alwaysShowPlaceholder is true ("left" next to placeholder or "right" next to trigger icon) */
+    valuePosition?: "left" | "right";
+    /** Render prop functions for customizing component rendering */
+    renders?: ComboboxRenderProps;
 }>;
-declare function Combobox({ searchable, multiple, value: controlledValue, onValueChange, labels, options, classNames, selectedFeedback, }: ComboboxProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * A flexible combobox component with support for single/multiple selection, search, and extensive customization.
+ *
+ * @example
+ * ```tsx
+ * // Basic single select
+ * <Combobox
+ *   options={[
+ *     { value: "1", label: "Option 1" },
+ *     { value: "2", label: "Option 2" },
+ *   ]}
+ *   value={value}
+ *   onValueChange={setValue}
+ * />
+ *
+ * // Multiple select with search
+ * <Combobox
+ *   multiple
+ *   searchable
+ *   options={options}
+ *   value={selectedValues}
+ *   onValueChange={setSelectedValues}
+ *   labels={{
+ *     placeholder: "Select items...",
+ *     searchPlaceholder: "Search...",
+ *   }}
+ * />
+ *
+ * // With custom rendering
+ * <Combobox
+ *   options={options}
+ *   value={value}
+ *   onValueChange={setValue}
+ *   renders={{
+ *     optionLabel: ({ option }) => (
+ *       <div className="flex items-center gap-2">
+ *         <Avatar src={option.avatar} />
+ *         <span>{option.label}</span>
+ *       </div>
+ *     ),
+ *   }}
+ * />
+ *
+ * // Always show placeholder with value
+ * <Combobox
+ *   alwaysShowPlaceholder
+ *   options={options}
+ *   value={value}
+ *   onValueChange={setValue}
+ *   labels={{ placeholder: "Country" }}
+ * />
+ * ```
+ */
+declare function Combobox({ searchable, multiple, icon: Icon, value: controlledValue, onValueChange, labels, options, classNames, selectedFeedback, alwaysShowPlaceholder, valuePosition, renders, }: ComboboxProps): import("react/jsx-runtime").JSX.Element;
 export { Combobox };

package/dist/components/ui/combobox/combobox.stories.d.ts

@@ -25,3 +25,12 @@ export declare const ControlledMultiple: Story;
 export declare const CustomLabels: Story;
 export declare const CustomStyling: Story;
 export declare const InForm: Story;
+export declare const WithIcon: Story;
+export declare const AlwaysShowPlaceholder: Story;
+export declare const AlwaysShowPlaceholderMultiple: Story;
+export declare const CustomRendering: Story;
+export declare const CustomTrigger: Story;
+export declare const CustomEmptyState: Story;
+export declare const CustomSelectedFeedback: Story;
+export declare const WithIconAndPlaceholder: Story;
+export declare const ValuePositionLeft: Story;