@stack-spot/citric-react 0.42.0 → 0.43.0

package/dist/citric.css

@@ -1895,7 +1895,8 @@ nav[data-citric="menu"].rounded-items, [data-citric="menu"].rounded-items nav {
 [data-citric="select"] select,
 [data-citric="rich-select"],
 [data-citric="multi-select"],
-[data-citric="textarea"] {
+[data-citric="textarea"],
+[data-citric="autocomplete"] {
   height: 2.5rem;
   padding: var(--spacing-3);
   outline: none;
@@ -2796,6 +2797,243 @@ a[data-citric="badge"] {
 }
 
 
+[data-citric="autocomplete"] {
+  --default-padding: 4px 8px;
+  --default-max-height: 300px;
+  --animation-duration: 0.3s;
+  position: relative;
+  height: auto;
+  display: flex;
+  flex-direction: row;
+  align-items: center;
+  box-sizing: border-box;
+  
+  &:after {
+    content: '';
+    position: absolute;
+    pointer-events: none;
+    top: 0;
+    left: 0;
+    right: 0;
+    bottom: 0;
+    border: 1px solid var(--border-color, var(--light-600));
+    border-radius: var(--radius-xs);
+    transition: border var(--animation-duration);
+  }
+
+  &.focused,
+  &:has(:focus) {
+    &:after {
+      border: 2px solid var(--border-color, var(--scheme-500, var(--primary-500)));
+    }
+
+    .dropdown-panel:after {
+      border: 2px solid var(--border-color, var(--scheme-500, var(--primary-500)));
+      border-top: none;
+    }
+  }
+
+  &:has(:disabled),
+  &.disabled {
+    background-color: var(--light-500);
+    border-color: var(--light-600);
+    color: var(--light-700);
+    cursor: not-allowed;
+
+    [data-citric="progress-circular"] {
+      border-color: var(--light-400);
+    }
+  }
+
+  header {
+    display: flex;
+    gap: 6px;
+    align-items: center;
+    margin: 0px !important;
+    min-width: 80px;
+    justify-content: space-between;
+    flex: 1;
+    flex-wrap: wrap;
+    outline: none;
+
+    .input-container {
+      display: flex;
+      flex: 1;
+      flex-wrap: wrap;
+      flex-direction: row;
+
+      input {
+        all: unset;
+        width: 0px;
+        min-width: 30px;
+        flex-grow: 1;
+      }
+    }
+
+    .end-adornment {
+      display: flex;
+      align-items: center;
+      gap: 8px;
+    }
+  }
+
+  .loader {
+    display: none;
+  }
+
+  /* Dropdown panel */
+  .dropdown-panel {
+    max-height: 0;
+    overflow: hidden;
+    transition: max-height var(--animation-duration) ease-in;
+    position: absolute;
+    top: calc(100% - 3px);
+    z-index: 9999;
+    left: 0;
+    right: 0;
+    background-color: var(--light-300);
+    display: flex;
+    flex-direction: column;
+    gap: 8px;
+    border-bottom-left-radius: var(--radius-xs);
+    border-bottom-right-radius: var(--radius-xs);
+
+    .message {
+      padding: var(--padding, var(--default-padding));
+      text-align: center;
+      color: var(--light-700);
+      font-style: italic;
+    }
+
+    >.options {
+      margin: 0;
+      padding: 0;
+      list-style: none;
+      display: flex;
+      flex-direction: column;
+      flex: 1;
+      overflow: hidden;
+
+      >.option {
+        padding: var(--padding, var(--default-padding));
+        display: flex;
+        transition: background-color 0.3s;
+        cursor: pointer;
+        align-items: center;
+        gap: 8px;
+
+        &:not(:last-child) {
+          border-bottom: 1px solid var(--light-600);
+        }
+
+        &:hover {
+          background-color: var(--scheme-500, var(--light-500));
+        }
+
+        &.highlighted {
+          background-color: var(--scheme-500, var(--light-500));
+        }
+
+        &.selected {
+          background-color: var(--scheme-400, var(--light-400));
+
+          &:hover {
+            background-color: var(--scheme-500, var(--light-500));
+          }
+        }
+
+        &.create-option {
+          color: var(--light-contrastText);
+          font-weight: 500;
+          border-bottom: 2px solid var(--light-600);
+
+          &:hover {
+            background-color: var(--scheme-300, var(--primary-300));
+          }
+        }
+      }
+    }
+
+    &:after {
+      content: '';
+      position: absolute;
+      top: 0;
+      bottom: 0;
+      left: 0;
+      right: 0;
+      pointer-events: none;
+      border: 1px solid var(--border-color, var(--light-600));
+      border-top: none;
+      transition: border var(--animation-duration);
+    }
+
+    &::-webkit-scrollbar,
+    ::-webkit-scrollbar {
+      width: 0.5rem;
+    }
+  }
+
+  &[aria-busy="true"],
+  &[aria-busy=""] {
+    cursor: progress !important;
+
+    .loader {
+      display: block;
+    }
+  }
+
+  &:not(.open) {
+    .dropdown-panel {
+      opacity: 0;
+      animation: var(--animation-duration) autocomplete-delayed-opacity;
+    }
+  }
+
+  &.open {
+    header:after {
+      transform: rotate(180deg);
+    }
+
+    .dropdown-panel {
+      max-height: var(--max-height, var(--default-max-height));
+      opacity: 1;
+
+      .options {
+        overflow: auto;
+        animation: var(--animation-duration) autocomplete-delayed-overflow;
+      }
+    }
+  }
+}
+
+@keyframes autocomplete-delayed-overflow {
+  0% {
+    overflow: hidden;
+  }
+
+  99% {
+    overflow: hidden;
+  }
+
+  100% {
+    overflow: auto;
+  }
+}
+
+@keyframes autocomplete-delayed-opacity {
+  0% {
+    opacity: 1;
+  }
+
+  99% {
+    opacity: 1;
+  }
+
+  100% {
+    opacity: 0;
+  }
+}
+
 [data-citric="alert"] {
   padding: var(--spacing-4);
   font: var(--font-body2);

package/dist/components/Autocomplete.d.ts

@@ -0,0 +1,370 @@
+import { ColorPaletteName, ColorSchemeName } from '@stack-spot/portal-theme';
+export interface CustomSelectedTagsConfig {
+    /**
+     * Color scheme for the tags (badges).
+     */
+    colorScheme?: ColorSchemeName;
+    /**
+     * Color palette for the tags (badges).
+     */
+    colorPalette?: ColorPaletteName;
+    /**
+     * Appearance of the tags (badges).
+     * @default 'circle'
+     */
+    appearance?: 'square' | 'circle';
+    /**
+     * Maximum number of tags to show before displaying "+N more".
+     */
+    maxItems?: number;
+}
+export interface BaseAutocompleteProps<T, Multiple extends boolean = false> {
+    /**
+     * The list of options available for selection.
+     */
+    options: T[];
+    /**
+     * The current value(s) selected.
+     * - Single selection: T | undefined
+     * - Multiple selection: T[]
+     */
+    value: Multiple extends true ? T[] : (T | undefined);
+    /**
+     * Callback fired when the value changes (user selects/removes an option).
+     * This is the main callback for getting the final selected value(s).
+     *
+     * @example
+     * ```tsx
+     * // Single selection
+     * <Autocomplete
+     *   value={user}
+     *   onChange={(selectedUser) => {
+     *     console.log('Selected:', selectedUser)
+     *     setUser(selectedUser)
+     *   }}
+     * />
+     *
+     * // Multiple selection
+     * <Autocomplete
+     *   multiple
+     *   value={selectedUsers}
+     *   onChange={(users) => {
+     *     console.log('Selected users:', users)
+     *     setSelectedUsers(users)
+     *   }}
+     * />
+     * ```
+     */
+    onChange: Multiple extends true ? (value: T[]) => void : (value: T | undefined) => void;
+    /**
+     * If true, enables multiple selection mode.
+     * @default false
+     */
+    multiple?: Multiple;
+    /**
+     * If true, allows the user to enter values that are not in the options list.
+     * @default false
+     */
+    freeSolo?: boolean;
+    /**
+     * If true, allows creating new options when no match is found.
+     * Shows an "Add [value]" option at the top of the list.
+     * @default false
+     */
+    creatable?: boolean;
+    /**
+     * Callback fired when a new option is created.
+     * Required when creatable is true and you want manual control.
+     */
+    onCreate?: (inputValue: string) => void;
+    /**
+     * Function to create a new option object from the input value.
+     * Used when creatable is true and onCreate is NOT defined.
+     * Allows automatic option creation on Enter key.
+     *
+     * Note: This prop has no effect when onCreate is defined, as onCreate takes precedence.
+     *
+     * @param inputValue - The text typed by the user
+     * @returns A new option object
+     *
+     * @example
+     * ```tsx
+     * // Auto-create tags on Enter
+     * <Autocomplete
+     *   multiple
+     *   creatable
+     *   freeSolo
+     *   getOptionFromInput={(text) => ({
+     *     id: Date.now(),
+     *     name: text,
+     *     isCustom: true
+     *   })}
+     * />
+     * ```
+     */
+    getOptionFromInput?: (inputValue: string) => T;
+    /**
+     * The input value (controlled mode).
+     * Use this when you need full control over the input text.
+     * Usually used with onInputChange for controlled components.
+     *
+     * @example
+     * ```tsx
+     * const [inputValue, setInputValue] = useState('')
+     *
+     * <Autocomplete
+     *   inputValue={inputValue}
+     *   onInputChange={setInputValue}
+     *   options={options}
+     * />
+     * ```
+     */
+    inputValue?: string;
+    /**
+     * Callback fired when the input text changes (user types).
+     * Use this to control the input value or perform side effects like API calls.
+     * Different from onChange which fires when an option is selected.
+     *
+     * @param value - The current text in the input field
+     *
+     * @example
+     * ```tsx
+     * // Debounced API search
+     * <Autocomplete
+     *   onInputChange={(text) => {
+     *     console.log('User typed:', text)
+     *     debouncedSearch(text)
+     *   }}
+     * />
+     *
+     * // Controlled input
+     * <Autocomplete
+     *   inputValue={inputValue}
+     *   onInputChange={(text) => setInputValue(text.toUpperCase())}
+     * />
+     * ```
+     */
+    onInputChange?: (value: string) => void;
+    /**
+     * A function to render the item label.
+     * @default "the item's toString() result."
+     */
+    renderLabel?: (option: T) => string;
+    /**
+     * A function to generate a unique key for each option.
+     */
+    renderKey?: (option: T) => string | number | undefined;
+    /**
+     * A function to render an option in the dropdown.
+     */
+    renderOption?: (option: T) => React.ReactNode;
+    /**
+     * Custom function to render the selected values display area in multiple mode.
+     * When defined, gives you full control over how selected values are displayed.
+     * The customSelectedTags prop has no effect when this is defined.
+     *
+     * @param values - Array of selected options
+     * @param onRemove - Function to call when user wants to remove an option
+     * @returns React element to display selected values
+     *
+     * @example
+     * ```tsx
+     * <Autocomplete
+     *   multiple
+     *   renderSelected={(values, onRemove) => (
+     *     <div style={{ display: 'flex', gap: '4px', flexWrap: 'wrap' }}>
+     *       {values.map(user => (
+     *         <div key={user.id} style={{ background: '#e3f2fd', padding: '4px 8px', borderRadius: '12px' }}>
+     *           <Avatar src={user.avatar} size="xs" />
+     *           {user.name}
+     *           <button onClick={() => onRemove(user)}>×</button>
+     *         </div>
+     *       ))}
+     *     </div>
+     *   )}
+     * />
+     * ```
+     */
+    renderSelected?: (values: T[], onRemove: (option: T) => void) => React.ReactElement;
+    /**
+     * Configuration for the default selected tags appearance in multiple mode.
+     * Has no effect when renderSelected is defined.
+     *
+     * @example
+     * ```tsx
+     * <Autocomplete
+     *   multiple
+     *   customSelectedTags={{
+     *     colorScheme: 'primary',
+     *     appearance: 'square',
+     *     maxItems: 3
+     *   }}
+     * />
+     * ```
+     */
+    customSelectedTags?: CustomSelectedTagsConfig;
+    /**
+     * Custom filter function for options.
+     * When not set, the filter will use the text returned by renderLabel (case-insensitive includes).
+     *
+     * @param options - The full list of options
+     * @param inputValue - The current input text
+     * @returns Filtered array of options
+     *
+     * @example
+     * ```tsx
+     * // Search by name OR email
+     * <Autocomplete
+     *   filterOptions={(options, input) =>
+     *     options.filter(user =>
+     *       user.name.toLowerCase().includes(input.toLowerCase()) ||
+     *       user.email.toLowerCase().includes(input.toLowerCase())
+     *     )
+     *   }
+     * />
+     * ```
+     */
+    filterOptions?: (options: T[], inputValue: string) => T[];
+    /**
+     * If true, shows a loading indicator.
+     * @default false
+     */
+    loading?: boolean;
+    /**
+     * If true, the component is disabled.
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Placeholder text for the input.
+     */
+    placeholder?: string;
+    /**
+     * Maximum height for the dropdown panel in pixels.
+     */
+    maxHeight?: number;
+    /**
+     * If true, automatically highlights the first option.
+     * @default false
+     */
+    autoHighlight?: boolean;
+    /**
+     * If true, clears the input value when an option is selected.
+     * Only applies when multiple is true.
+     * When false, the input keeps the text after selection, useful for adding multiple similar items quickly.
+     *
+     * Note: Adding multiple tags with similar prefixes when clearOnSelect={false}, you can select "React",
+     * then easily select "React Native"
+     * without retyping "React" from scratch
+     * @default true (for multiple mode)
+     *
+     * @example
+     * ```tsx
+     * // Clear input after each selection (default)
+     * <Autocomplete multiple clearOnSelect />
+     *
+     * // Keep input text after selection
+     * const [tags, setTags] = useState<Tag[]>([])
+     *
+     * <Autocomplete
+     *   multiple
+     *   clearOnSelect={false}
+     *   value={tags}
+     *   onChange={setTags}
+     *   options={availableTags}
+     *   renderLabel={tag => tag.name}
+     * />
+     * ```
+     */
+    clearOnSelect?: boolean;
+    /**
+     * If true, the popup will open on input focus.
+     * @default true
+     */
+    openOnFocus?: boolean;
+    /**
+     * Text to display when no options are available.
+     */
+    noOptionsText?: string;
+    /**
+     * Text to display when loading.
+     */
+    loadingText?: string;
+    /**
+     * Callback fired when the user scrolls to the end of the options list.
+     * Useful for implementing infinite scroll/pagination.
+     *
+     * @example
+     * ```tsx
+     * <Autocomplete
+     *   options={options}
+     *   onScrollEnd={() => fetchMoreOptions()}
+     *   loading={isFetchingMore}
+     * />
+     * ```
+     */
+    onScrollEnd?: () => void;
+    /**
+     * Margin in pixels before the end of the list to trigger onScrollEnd.
+     * @default 200
+     */
+    scrollEndMargin?: number;
+    /**
+     * Color scheme for the autocomplete component.
+     * Applies the theme's color scheme to the component root.
+     */
+    colorScheme?: ColorSchemeName;
+    /**
+     * The id attribute for the input element.
+     * Useful for associating with a label element.
+     */
+    id?: string;
+}
+export type AutocompleteProps<T, Multiple extends boolean = false> = Omit<React.JSX.IntrinsicElements['div'], 'ref' | 'onChange'> & BaseAutocompleteProps<T, Multiple>;
+/**
+ * A combination of a text input and a dropdown that suggests options as the user types.
+ * Supports both single and multiple selection modes, similar to Material-UI Autocomplete.
+ *
+ * @example
+ * Basic usage (single selection):
+ * ```tsx
+ * const [value, setValue] = useState<Option | null>(null)
+ *
+ * <Autocomplete
+ *   options={options}
+ *   value={value}
+ *   onChange={setValue}
+ *   renderLabel={o => o.name}
+ *   renderKey={o => o.id}
+ * />
+ * ```
+ *
+ * @example
+ * Multiple selection with tags:
+ * ```tsx
+ * const [value, setValue] = useState<Option[]>([])
+ *
+ * <Autocomplete
+ *   multiple
+ *   options={options}
+ *   value={value}
+ *   onChange={setValue}
+ *   renderLabel={o => o.name}
+ *   renderKey={o => o.id}
+ * />
+ * ```
+ *
+ * @example
+ * Free solo (allow custom values):
+ * ```tsx
+ * <Autocomplete
+ *   freeSolo
+ *   options={options}
+ *   value={value}
+ *   onChange={setValue}
+ *   renderLabel={o => o.name}
+ * />
+ * ```
+ */
+export declare const Autocomplete: <T, Multiple extends boolean = false>(props: AutocompleteProps<T, Multiple>) => React.ReactElement;
+//# sourceMappingURL=Autocomplete.d.ts.map

package/dist/components/Autocomplete.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Autocomplete.d.ts","sourceRoot":"","sources":["../../src/components/Autocomplete.tsx"],"names":[],"mappings":"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"}