asma-ui-core 3.3.11 → 3.4.0

package/dist/src/components/inputs/dynamic-select/StyledDynamicSelect.d.ts

@@ -1,2 +1,155 @@
 import type { StyledDynamicSelectComponent } from './types';
+/**
+ * A smart, adaptive select input that automatically chooses the best UI representation
+ * based on the number of options provided.
+ *
+ * **Rendering strategy:**
+ * - `1–5 options` → renders as an interactive chip group (`DynamicInteractiveChipGroup`).
+ *   Chips behave as radio buttons (single) or checkboxes (multiple).
+ *   Long labels automatically switch to a vertical stacked layout.
+ *   When `!required` and a value is selected, a "Clear selection" button is shown.
+ * - `0 or 6+ options` → renders as a searchable autocomplete (`DynamicSelectAutocomplete`).
+ *   Typing is disabled when there are ≤10 options (caret hidden, keyboard blocked).
+ *
+ * **Option types:**
+ * Options can be primitives (`string | number | boolean`) or objects. When using objects,
+ * the component reads `option.value` and `option.label` by default. Override with
+ * `valueKey` and `labelKey` to use different keys. Individual options can be disabled
+ * by setting `option.disabled = true`.
+ *
+ * @template TOption – The option type. Must extend `DynamicSelectOption`.
+ *
+ * ---
+ *
+ * @example
+ * // 1. Single select – primitive strings (chip group for ≤5, autocomplete for 6+)
+ * const [value, setValue] = useState<string | null>(null)
+ *
+ * <StyledDynamicSelect
+ *   dataTest="status-select"
+ *   options={['Active', 'Inactive', 'Pending']}
+ *   value={value}
+ *   onChange={setValue}
+ * />
+ *
+ * ---
+ *
+ * @example
+ * // 2. Single select – object options with default value/label keys
+ * type Status = { value: string; label: string; disabled?: boolean }
+ * const statuses: Status[] = [
+ *   { value: 'active',   label: 'Active' },
+ *   { value: 'inactive', label: 'Inactive', disabled: true },
+ * ]
+ * const [status, setStatus] = useState<Status | null>(null)
+ *
+ * <StyledDynamicSelect
+ *   dataTest="status-select"
+ *   options={statuses}
+ *   value={status}
+ *   onChange={setStatus}
+ *   title="Status"
+ *   required
+ *   error={!status}
+ *   helperText="Status is required"
+ * />
+ *
+ * ---
+ *
+ * @example
+ * // 3. Multiple select – object options with custom keys
+ * type User = { id: string; fullName: string; disabled?: boolean }
+ * const users: User[] = [
+ *   { id: '1', fullName: 'Alice Smith' },
+ *   { id: '2', fullName: 'Bob Jones', disabled: true },
+ * ]
+ * const [selected, setSelected] = useState<User[] | null>([])
+ *
+ * <StyledDynamicSelect
+ *   dataTest="assignee-select"
+ *   options={users}
+ *   value={selected}
+ *   onChange={setSelected}
+ *   multiple
+ *   valueKey="id"
+ *   labelKey="fullName"
+ *   title="Assignees"
+ *   placeholder="Search users…"
+ *   maxTags={3}
+ * />
+ *
+ * ---
+ *
+ * @example
+ * // 4. Read-only display – only selected options are shown
+ * <StyledDynamicSelect
+ *   dataTest="status-readonly"
+ *   options={statuses}
+ *   value={selectedStatus}
+ *   onChange={() => {}}
+ *   readOnly
+ * />
+ *
+ * ---
+ *
+ * @example
+ * // 5. Custom label renderer (e.g. with avatar or description)
+ * <StyledDynamicSelect
+ *   dataTest="user-select"
+ *   options={users}
+ *   value={selected}
+ *   onChange={setSelected}
+ *   multiple
+ *   valueKey="id"
+ *   labelKey="fullName"
+ *   renderLabel={(user) => (
+ *     <span className="flex items-center gap-2">
+ *       <Avatar src={user.avatarUrl} size={20} />
+ *       {user.fullName}
+ *     </span>
+ *   )}
+ * />
+ *
+ * ---
+ *
+ * @example
+ * // 6. Per-option tooltip
+ * <StyledDynamicSelect
+ *   dataTest="plan-select"
+ *   options={plans}
+ *   value={selectedPlan}
+ *   onChange={setSelectedPlan}
+ *   getOptionTooltip={(plan) =>
+ *     plan.disabled ? 'Upgrade your subscription to unlock this plan' : null
+ *   }
+ * />
+ *
+ * ---
+ *
+ * @example
+ * // 7. Loading state (skeletons in chip group, disabled in autocomplete)
+ * <StyledDynamicSelect
+ *   dataTest="category-select"
+ *   options={categories}
+ *   value={value}
+ *   onChange={setValue}
+ *   loading={isFetching}
+ * />
+ *
+ * ---
+ *
+ * @example
+ * // 8. Forwarded ref – focus the input programmatically
+ * const ref = useRef<HTMLInputElement>(null)
+ *
+ * <StyledDynamicSelect
+ *   ref={ref}
+ *   dataTest="search-select"
+ *   options={options}
+ *   value={value}
+ *   onChange={setValue}
+ * />
+ *
+ * <button onClick={() => ref.current?.focus()}>Focus</button>
+ */
 export declare const StyledDynamicSelect: StyledDynamicSelectComponent;

package/dist/src/components/inputs/dynamic-select/types.d.ts

@@ -18,25 +18,75 @@ type MultipleDynamicSelectProps<TOption extends DynamicSelectOption> = {
     onChange: (value: TOption[] | null) => void;
 };
 type DynamicSelectCommonProps<TOption extends DynamicSelectOption> = {
+    /** Unique identifier used as the root `data-test` attribute for QA selectors. */
     dataTest: string;
+    /** The full list of selectable options. Determines which UI is rendered: 1–5 → chip group, 0 or 6+ → autocomplete. */
     options: TOption[];
+    /** When `true`, the component is non-interactive and only shows selected value(s) as plain chip(s). */
     readOnly?: boolean;
+    /** Prevents the built-in clear button from appearing even when a value is set. Applies to autocomplete only. */
     disableClearable?: boolean;
+    /** Optional label rendered above the input/chip group. */
     title?: string;
+    /** Controls the visual size of chips and buttons. Defaults to `'medium'`. */
     size?: 'small' | 'medium';
+    /** Placeholder text shown in the autocomplete input when no value is selected. */
     placeholder?: string;
+    /** Disables all interactions. */
     disabled?: boolean;
+    /** Text shown in the autocomplete dropdown when no options match the search query. */
     noOptionsText?: string;
+    /** When `true`, shows the error style and renders an error icon next to the helper text. */
     error?: boolean;
+    /**
+     * When `true`, hides the "Clear selection" button in the chip group.
+     * Use this when the field must always have a value.
+     */
+    required?: boolean;
+    /** Supplementary text rendered below the input. Shown as-is, or falls back to `'Required'` when `error=true` and no text is provided. */
     helperText?: React.ReactNode;
+    /**
+     * Key of `TOption` used as the option's identity for comparison and as the chip/tag key.
+     * Defaults to `'value'`. Only applicable when `TOption` is an object.
+     */
     valueKey?: TOption extends object ? keyof TOption : never;
+    /**
+     * Key of `TOption` used as the displayed label string.
+     * Defaults to `'label'`. Only applicable when `TOption` is an object.
+     */
     labelKey?: TOption extends object ? keyof TOption : never;
+    /**
+     * Custom label renderer. When provided, its return value is used instead of the
+     * plain string resolved from `labelKey`. Useful for rich content (icons, avatars, etc.).
+     */
     renderLabel?: (option: TOption) => React.ReactNode;
+    /**
+     * Returns a tooltip node shown when hovering a specific option.
+     * Return `null` to show no tooltip for that option.
+     */
     getOptionTooltip?: (option: TOption) => React.ReactNode;
+    /** Node prepended inside the autocomplete text input (e.g. a search icon). */
     startAdornment?: React.ReactNode;
+    /** Escape hatch to pass any MUI `Autocomplete` prop directly. Applied on top of internal defaults in the autocomplete variant. */
     autocompleteProps?: Partial<AutocompleteProps<TOption, boolean | undefined, boolean | undefined, boolean | undefined>>;
+    /**
+     * When `true`, renders loading skeletons (chip group) or disables the input (autocomplete)
+     * while data is being fetched.
+     */
     loading?: boolean;
+    /**
+     * Limits how many selected-value chips are visible in the autocomplete's input area.
+     * Remaining selections are summarised as `+N`. Has no effect on the chip group variant.
+     */
     maxTags?: number;
+    /**
+     * Controls locale-sensitive labels and messages used by the component.
+     * Use `'no'` for Norwegian and `'en'` for English.
+     *
+     * Intended for consumer-facing text such as clear actions, helper copy,
+     * or empty-state messaging when localized behavior is supported.
+     */
+    locale?: 'no' | 'en';
 };
 export type StyledDynamicSelectProps<TOption extends DynamicSelectOption> = DynamicSelectCommonProps<TOption> & (SingleDynamicSelectProps<TOption> | MultipleDynamicSelectProps<TOption>);
 export type StyledDynamicSelectComponent = <TOption extends DynamicSelectOption>(props: StyledDynamicSelectProps<TOption> & React.RefAttributes<HTMLInputElement>) => React.ReactElement | null;