@tedi-design-system/react 17.0.0 → 17.1.0-rc.10

package/src/tedi/components/form/select/select.cjs.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const s=require("react/jsx-runtime"),ge=require("../../../../../external/classnames/index.cjs.js"),c=require("react"),Se=require("../../../../../external/react-select/dist/react-select.esm.cjs.js"),Me=require("../../../../../external/react-select/async/dist/react-select-async.esm.cjs.js"),be=require("../feedback-text/feedback-text.cjs.js"),Ie=require("../form-label/form-label.cjs.js"),qe=require("./components/select-clear-indicator.cjs.js"),Ce=require("./components/select-control.cjs.js"),Oe=require("./components/select-dropdown-indicator.cjs.js"),ve=require("./components/select-group.cjs.js"),Le=require("./components/select-group-heading.cjs.js"),Ve=require("./components/select-indicators-container.cjs.js"),ye=require("./components/select-input.cjs.js"),Re=require("./components/select-loading-indicator.cjs.js"),he=require("./components/select-menu.cjs.js"),xe=require("./components/select-menu-list.cjs.js"),je=require("./components/select-menu-portal.cjs.js"),we=require("./components/select-multi-value.cjs.js"),Ne=require("./components/select-multi-value-remove.cjs.js"),_e=require("./components/select-option.cjs.js"),Pe=require("./components/select-value-container.cjs.js"),n=require("./select.module.scss.cjs.js"),Te=require("../../../providers/label-provider/use-labels.cjs.js"),L=c.forwardRef((V,y)=>{const{options:R,defaultOptions:h,id:l,name:x,iconName:j="arrow_drop_down",label:w,required:f,value:N,defaultValue:_,tagsDirection:g="row",onChange:u,onInputChange:P,inputValue:T,loadOptions:G,isLoading:H,openMenuOnFocus:D=!1,openMenuOnClick:k=!0,tabSelectsValue:F=!1,disabled:S=!1,className:$,hideLabel:B=!1,helper:t,placeholder:E,invalid:z,valid:A,size:d,async:W=!1,renderOption:J,renderMessageListFooter:M,noOptionsMessage:K,loadingMessage:Q,multiple:p=!1,closeMenuOnSelect:U=!p,blurInputOnSelect:b=!1,autoFocus:X=!1,isClearable:Y=!0,isClearIndicatorVisible:Z=!1,isSearchable:I=!0,menuIsOpen:ee,onMenuClose:te,onMenuOpen:ne,onBlur:se,inputIsHidden:le,isTagRemovable:q=!1,optionGroupHeadingText:oe={modifiers:"small",color:"tertiary"},cacheOptions:ae=!0,showRadioButtons:re=!1,renderWithoutLabel:ie,tooltip:ce,classNames:C}=V,O=t?(t==null?void 0:t.id)??`${l}-helper`:void 0,a=c.useRef(null),{getLabel:v}=Te.useLabels();c.useImperativeHandle(y,()=>a.current);const ue=o=>{u==null||u(o),!b&&a.current&&setTimeout(()=>{var r,i;return(i=(r=a.current)==null?void 0:r.inputRef)==null?void 0:i.focus()},0)},de=c.useCallback(o=>s.jsx(xe.SelectMenuList,{...o,renderMessageListFooter:M}),[M]),pe=()=>{const o={ClearIndicator:e=>qe.SelectClearIndicator({isClearIndicatorVisible:Z,...e}),DropdownIndicator:()=>Oe.SelectDropDownIndicator({iconName:j}),IndicatorSeparator:()=>null,MenuPortal:je.SelectMenuPortal,Menu:he.SelectMenu,MenuList:de,Option:e=>_e.SelectOption({renderOption:J,multiple:p,showRadioButtons:re,...e}),Control:Ce.SelectControl,Input:ye.SelectInput,MultiValue:e=>we.SelectMultiValue({isTagRemovable:q,...e}),MultiValueRemove:Ne.SelectMultiValueRemove,Group:ve.SelectGroup,GroupHeading:e=>Le.SelectGroupHeading({optionGroupHeadingText:oe,...e}),IndicatorsContainer:Ve.SelectIndicatorsContainer,ValueContainer:Pe.SelectValueContainer,LoadingIndicator:Re.SelectLoadingIndicator},r=W?Me.default:Se.default,i=()=>v("select.no-options"),fe=()=>v("select.loading");return s.jsx(r,{id:l,"aria-describedby":O,autoFocus:X,ref:a,instanceId:l,className:"tedi-select__wrapper",name:x,options:R,defaultOptions:h,value:N,defaultValue:_,cacheOptions:ae,onChange:ue,onInputChange:P,onBlur:se,inputValue:T,inputId:`${l}-input`,loadOptions:G,isLoading:H,noOptionsMessage:K||i,loadingMessage:Q||fe,classNamePrefix:"select",components:o,isDisabled:S,isSearchable:I,menuIsOpen:ee,openMenuOnFocus:D,openMenuOnClick:k,tabSelectsValue:F,onMenuClose:te,onMenuOpen:ne,placeholder:E||"",isClearable:Y,backspaceRemovesValue:q,menuShouldScrollIntoView:!0,isMulti:p,hideSelectedOptions:!1,closeMenuOnSelect:U,blurInputOnSelect:b,menuPlacement:"auto",inputIsHidden:le,required:f,menuPortalTarget:document.body,menuPosition:"absolute",classNames:C?Object.fromEntries(Object.entries(C).map(([e,m])=>[e,typeof m=="string"?()=>m:m])):void 0,theme:e=>({...e,colors:{...e.colors,primary:"var(--tedi-blue-600)",danger:"var(--tedi-red-600)",dangerLight:"var(--tedi-red-200)"}}),styles:{input:e=>({...e,gridTemplateColumns:"0fr"})}})},me=ge.default(n.default["tedi-select"],$,{[n.default["tedi-select--invalid"]]:z||(t==null?void 0:t.type)==="error"},{[n.default["tedi-select--valid"]]:A||(t==null?void 0:t.type)==="valid"},{[n.default[`tedi-select--${d}`]]:d},{[n.default[`tedi-select--tags-${g}`]]:g},{[n.default["tedi-select--searchable"]]:I},{[n.default["tedi-select--disabled"]]:S});return s.jsxs("div",{"data-name":"select",className:me,children:[s.jsxs("div",{className:n.default["tedi-select__inner"],children:[s.jsx(Ie.FormLabel,{id:`${l}-input`,label:w,required:f,hideLabel:B,size:d,renderWithoutLabel:ie,tooltip:ce}),pe()]}),t&&s.jsx(be.FeedbackText,{...t,id:O})]})});L.displayName="Select";exports.Select=L;
+"use strict";Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:"Module"}});const v=require("react/jsx-runtime"),X=require("../../../../../external/classnames/index.cjs.js"),a=require("react"),We=require("../../../../../external/react-select/dist/react-select.esm.cjs.js"),Xe=require("../../../../../external/react-select/async/dist/react-select-async.esm.cjs.js"),Je=require("../feedback-text/feedback-text.cjs.js"),Qe=require("../form-label/form-label.cjs.js"),q=require("../input-group/input-group.cjs.js"),Ye=require("../input-group/input-group.module.scss.cjs.js"),r=require("./components/select-bulk-helpers.cjs.js"),Ze=require("./components/select-clear-indicator.cjs.js"),et=require("./components/select-control.cjs.js"),tt=require("./components/select-dropdown-indicator.cjs.js"),lt=require("./components/select-group.cjs.js"),nt=require("./components/select-group-heading.cjs.js"),ot=require("./components/select-indicators-container.cjs.js"),st=require("./components/select-input.cjs.js"),at=require("./components/select-loading-indicator.cjs.js"),rt=require("./components/select-menu.cjs.js"),it=require("./components/select-menu-list.cjs.js"),ut=require("./components/select-menu-portal.cjs.js"),ct=require("./components/select-multi-value.cjs.js"),dt=require("./components/select-multi-value-remove.cjs.js"),pt=require("./components/select-option.cjs.js"),ft=require("./components/select-single-value.cjs.js"),gt=require("./components/select-value-container.cjs.js"),f=require("./select.module.scss.cjs.js"),mt=require("../../../providers/label-provider/use-labels.cjs.js"),E=a.forwardRef((w,J)=>{var W;const{options:c,defaultOptions:Q,id:k,name:Y,iconName:Z="arrow_drop_down",label:ee,required:x,value:R,defaultValue:T,tagsDirection:C="stack",onChange:O,onInputChange:te,inputValue:le,loadOptions:ne,isLoading:oe,openMenuOnFocus:se=!1,openMenuOnClick:ae=!0,tabSelectsValue:re=!1,disabled:D=!1,className:ie,hideLabel:ue=!1,helper:i,placeholder:ce,invalid:de,valid:pe,size:V,async:fe=!1,renderOption:ge,renderMessageListFooter:G,noOptionsMessage:me,loadingMessage:Se,multiple:L=!1,showSelectAll:P=!1,selectableGroups:F=!1,dropdownType:be="menu",renderValue:Me,closeMenuOnSelect:ve=!L,blurInputOnSelect:N=!1,autoFocus:Le=!1,isClearable:ye=!0,isClearIndicatorVisible:Ie=!1,isSearchable:j=!0,menuIsOpen:he,onMenuClose:Ae,onMenuOpen:Ce,onBlur:Oe,inputIsHidden:Ve,isTagRemovable:_e=!1,backspaceRemovesValue:qe=!1,optionGroupHeadingText:Ee={modifiers:"small",color:"tertiary"},cacheOptions:we=!0,showRadioButtons:ke=!1,renderWithoutLabel:xe,tooltip:Re,classNames:H}=w,g=(W=q.useOptionalInputGroup)==null?void 0:W.call(q),Te=a.useId(),De=g==null?void 0:g.hasExternalLabel,_=w.id??(g==null?void 0:g.inputId)??Te,U=i?(i==null?void 0:i.id)??`${_}-helper`:void 0,I=a.useRef(null),{getLabel:h}=mt.useLabels();a.useImperativeHandle(J,()=>I.current);const S=!!P&&L,[Ge,Pe]=a.useState(T??null),B=R!==void 0,m=B?R:Ge,d=a.useMemo(()=>Array.isArray(m)?m:m?[m]:[],[m]),A=a.useMemo(()=>({value:r.SELECT_ALL_VALUE,label:h("select.select-all")}),[h]),b=!!F&&!!L,{groupFlattenedOptions:K,groupSentinelMap:y}=a.useMemo(()=>{const t=new Map;if(!b||!c||c.length===0)return{groupFlattenedOptions:null,groupSentinelMap:t};if(!c.some(e=>e&&Array.isArray(e.options)))return{groupFlattenedOptions:null,groupSentinelMap:t};const n=[],u=new Map;for(const e of c)if(e&&Array.isArray(e.options)){const l=e,o=`${r.GROUP_OPTION_PREFIX}${l.label??""}`,p=l.options.filter(M=>!M.isDisabled);u.set(o,{enabled:p}),n.push({value:o,label:l.label??""});for(const M of l.options)n.push({...M,customData:{...M.customData??{},__tediInGroup:!0}})}else n.push(e);return{groupFlattenedOptions:n,groupSentinelMap:u}},[c,b]),Fe=a.useMemo(()=>{let t=K??c;return S&&t&&t.length>0&&(t=[A,...t]),t},[c,K,S,A]),Ne=a.useMemo(()=>{const t=[];if(b&&y.size>0)for(const[s,n]of y)n.enabled.length>0&&r.areAllSelected(d,n.enabled)&&t.push({value:s,label:""});if(S){const s=r.getEnabledOptions(c??[]);s.length>0&&r.areAllSelected(d,s)&&t.push(A)}return t.length===0?m:[...d,...t]},[m,d,c,b,y,S,A]),je=(t,s)=>{let n=t;const u=s.option;if(b&&u&&y.has(u.value)){const e=y.get(u.value).enabled;if(s.action==="select-option"){const l=[...d];for(const o of e)l.some(p=>p.value===o.value)||l.push(o);n=l}else s.action==="deselect-option"&&(n=d.filter(l=>!e.some(o=>o.value===l.value)))}else if(S){const e=r.getEnabledOptions(c??[]),l=(u==null?void 0:u.value)===r.SELECT_ALL_VALUE;l&&s.action==="select-option"?n=[...d.filter(p=>p.value!==r.SELECT_ALL_VALUE&&!e.some(M=>M.value===p.value)),...e]:l&&s.action==="deselect-option"&&(n=d.filter(o=>o.value!==r.SELECT_ALL_VALUE&&!e.some(p=>p.value===o.value)))}Array.isArray(n)&&(n=n.filter(e=>e.value!==r.SELECT_ALL_VALUE&&!r.isGroupSentinel(e))),B||Pe(n),O==null||O(n),!N&&I.current&&setTimeout(()=>{var e,l;return(l=(e=I.current)==null?void 0:e.inputRef)==null?void 0:l.focus()},0)},He=a.useCallback((t,s)=>t.data.value===r.SELECT_ALL_VALUE||r.isGroupSentinel(t.data)||!s?!0:String(t.label).toLowerCase().includes(s.toLowerCase()),[]),[$,z]=a.useState(!1),Ue=t=>{(t.key==="ArrowUp"||t.key==="ArrowDown"||t.key==="Home"||t.key==="End"||t.key==="PageUp"||t.key==="PageDown"||t.key==="Tab")&&($||z(!0))},Be=a.useCallback(()=>{z(t=>t&&!1)},[]),Ke=a.useCallback(t=>v.jsx(it.SelectMenuList,{...t,renderMessageListFooter:G}),[G]),$e=()=>{const t={ClearIndicator:e=>Ze.SelectClearIndicator({isClearIndicatorVisible:Ie,...e}),DropdownIndicator:()=>tt.SelectDropDownIndicator({iconName:Z}),IndicatorSeparator:()=>null,MenuPortal:ut.SelectMenuPortal,Menu:rt.SelectMenu,MenuList:Ke,Option:e=>pt.SelectOption({renderOption:ge,multiple:L,showRadioButtons:ke,...e}),Control:et.SelectControl,Input:st.SelectInput,MultiValue:e=>ct.SelectMultiValue({isTagRemovable:_e,...e}),MultiValueRemove:dt.SelectMultiValueRemove,SingleValue:ft.SelectSingleValue,Group:lt.SelectGroup,GroupHeading:e=>nt.SelectGroupHeading({optionGroupHeadingText:Ee,...e}),IndicatorsContainer:ot.SelectIndicatorsContainer,ValueContainer:gt.SelectValueContainer,LoadingIndicator:at.SelectLoadingIndicator},s=fe?Xe.default:We.default,n=()=>h("select.no-options"),u=()=>h("select.loading");return v.jsx(s,{tagsDirection:C,showSelectAll:P,selectableGroups:F,dropdownType:be,renderValue:Me,keyboardMode:$,exitKeyboardMode:Be,onKeyDown:Ue,id:_,"aria-describedby":U,autoFocus:Le,ref:I,instanceId:k,className:"tedi-select__wrapper",name:Y,options:Fe,defaultOptions:Q,value:Ne,defaultValue:T,cacheOptions:we,onChange:je,filterOption:S||b?He:void 0,onInputChange:te,onBlur:Oe,inputValue:le,inputId:`${k}-input`,loadOptions:ne,isLoading:oe,noOptionsMessage:me||n,loadingMessage:Se||u,classNamePrefix:"select",components:t,isDisabled:D,isSearchable:j,menuIsOpen:he,openMenuOnFocus:se,openMenuOnClick:ae,tabSelectsValue:re,onMenuClose:Ae,onMenuOpen:Ce,placeholder:ce||"",isClearable:ye,backspaceRemovesValue:qe,menuShouldScrollIntoView:!0,isMulti:L,hideSelectedOptions:!1,closeMenuOnSelect:ve,blurInputOnSelect:N,menuPlacement:"auto",inputIsHidden:Ve,required:x,menuPortalTarget:document.body,menuPosition:"absolute",classNames:(()=>{const e={};if(H)for(const[l,o]of Object.entries(H))e[l]=typeof o=="string"?()=>o:o;if(g){const l=e.control;e.control=o=>X.default(l==null?void 0:l(o),Ye.default["tedi-input-group__input"])}return Object.keys(e).length>0?e:void 0})(),theme:e=>({...e,colors:{...e.colors,primary:"var(--tedi-blue-600)",danger:"var(--tedi-red-600)",dangerLight:"var(--tedi-red-200)"}}),styles:{input:e=>({...e,gridTemplateColumns:"0fr"})}})},ze=X.default(f.default["tedi-select"],ie,{[f.default["tedi-select--invalid"]]:de||(i==null?void 0:i.type)==="error"},{[f.default["tedi-select--valid"]]:pe||(i==null?void 0:i.type)==="valid"},{[f.default[`tedi-select--${V}`]]:V},{[f.default[`tedi-select--tags-${C}`]]:C},{[f.default["tedi-select--searchable"]]:j},{[f.default["tedi-select--disabled"]]:D});return v.jsxs("div",{"data-name":"select",className:ze,children:[v.jsxs("div",{className:f.default["tedi-select__inner"],children:[!De&&v.jsx(Qe.FormLabel,{id:`${_}-input`,label:ee,required:x,hideLabel:ue,size:V,renderWithoutLabel:xe,tooltip:Re}),$e()]}),i&&v.jsx(Je.FeedbackText,{...i,id:U})]})});E.displayName="Select";exports.Select=E;exports.default=E;

package/src/tedi/components/form/select/select.d.ts

@@ -8,55 +8,296 @@ declare module 'react-select/dist/declarations/src/Select' {
         inputIsHidden?: boolean;
     }
 }
-export interface SelectProps extends FormLabelProps {
-    id: string;
+export interface SelectProps extends Omit<FormLabelProps, 'id' | 'label'> {
+    /**
+     * Unique HTML id for the input. Also used as react-select's `instanceId` for SSR-stable internal IDs.
+     * When omitted, falls back to the surrounding `InputGroup`'s id or a generated `useId()`.
+     */
+    id?: string;
+    /** Visible label. May be omitted when the surrounding `InputGroup` provides its own label. */
+    label?: string;
+    /**
+     * The list of selectable options. Pass a flat `ISelectOption[]` for a simple
+     * list, or an array of `IGroupedOptions` (each with its own `options` array)
+     * for a grouped menu.
+     */
     options?: OptionsOrGroups<ISelectOption, IGroupedOptions<ISelectOption>>;
+    /**
+     * Used in async mode (`async: true`).
+     * - `true` — call `loadOptions` once on mount with an empty input string
+     *   and use the result as the initial option list.
+     * - An array — show these options before the user types anything.
+     * - Omit — start with no options until the user types.
+     */
     defaultOptions?: OptionsOrGroups<ISelectOption, IGroupedOptions<ISelectOption>> | boolean;
+    /** Text shown in the field when no value is selected. */
     placeholder?: string;
+    /** Extra class on the root wrapper. Use `classNames` for per-subcomponent overrides. */
     className?: string;
+    /**
+     * Icon shown on the right of the field as the dropdown indicator.
+     * - `"arrow_drop_down"` (default) — standard select chevron.
+     * - `"search"` — magnifier; useful for combobox-style search fields.
+     * @default 'arrow_drop_down'
+     */
     iconName?: 'arrow_drop_down' | 'search';
+    /**
+     * Fires whenever the selection changes. Receives the new value:
+     * a single `ISelectOption` (single-select), an array (multi-select),
+     * or `null` when cleared.
+     */
     onChange?: (value: TSelectValue) => void;
+    /**
+     * Fires whenever the user types in the search input. Receives the new input
+     * string and a `react-select` action descriptor (e.g. `'input-change'`,
+     * `'menu-close'`). Use this to drive controlled search.
+     */
     onInputChange?: (value: string, actionMeta: InputActionMeta) => void;
+    /** Controlled search input string. Pair with `onInputChange` to manage it from the parent. */
     inputValue?: string;
+    /**
+     * Async option loader. Called with the current search string; resolve the
+     * `callback` with the matching options. Only invoked when `async: true`.
+     */
     loadOptions?: (inputValue: string, callback: (options: OptionsOrGroups<ISelectOption, IGroupedOptions<ISelectOption>>) => void) => void;
+    /** When `true`, shows a loading spinner in the indicator area. Useful while async results are pending. */
     isLoading?: boolean;
+    /** Uncontrolled initial selection. Ignored when `value` is provided. */
     defaultValue?: TSelectValue;
+    /**
+     * Controlled selection. When set, the parent owns the value and must update
+     * it via `onChange`. Use `defaultValue` for uncontrolled usage.
+     */
     value?: TSelectValue;
+    /** Disables interaction and applies disabled styling. */
     disabled?: boolean;
+    /** Form field name; rendered onto the underlying hidden input for form submission. */
     name?: string;
+    /**
+     * Forces error styling. Also set automatically when `helper.type === 'error'`.
+     * @default false
+     */
     invalid?: boolean;
+    /**
+     * Forces valid (success) styling. Also set automatically when `helper.type === 'valid'`.
+     * @default false
+     */
     valid?: boolean;
+    /**
+     * Helper / feedback text rendered below the field. Set `type` to `'hint'`,
+     * `'error'`, or `'valid'` — the latter two also drive the field's invalid /
+     * valid visual state.
+     */
     helper?: FeedbackTextProps;
+    /**
+     * Visual size variant.
+     * - omit — default (40px tall).
+     * - `"small"` — compact (32px tall) for dense layouts.
+     */
     size?: 'small';
+    /**
+     * Switches the underlying component to `react-select`'s `AsyncSelect`. Pair
+     * with `loadOptions` (and optionally `defaultOptions`) to fetch options on
+     * the fly.
+     * @default false
+     */
     async?: boolean;
+    /**
+     * Custom renderer for the content of each option in the dropdown. Receives
+     * the full option props from `react-select`; return any React node. Use
+     * `renderValue` if you also want to customise how the selected value
+     * appears in the trigger.
+     */
     renderOption?: (props: OptionProps<ISelectOption, boolean>) => JSX.Element;
+    /**
+     * Message shown when the option list is empty (no matches for the search,
+     * or no options at all). Defaults to the localised `select.no-options`
+     * label from `LabelProvider`.
+     */
     noOptionsMessage?: (obj: {
         inputValue: string;
     }) => React.ReactNode;
+    /**
+     * Message shown while async options are loading. Defaults to the localised
+     * `select.loading` label from `LabelProvider`.
+     */
     loadingMessage?: (obj: {
         inputValue: string;
     }) => React.ReactNode;
+    /**
+     * Renders custom content underneath the option list, inside the dropdown
+     * (e.g. a "Show more" button or a "powered by" footer).
+     */
     renderMessageListFooter?: (props: MenuListProps<ISelectOption, boolean>) => JSX.Element;
+    /**
+     * Enables multi-select mode: the field renders selections as removable
+     * tags and `onChange` receives an array.
+     * @default false
+     */
     multiple?: boolean;
+    /**
+     * Layout for selected tags in multi-select mode.
+     * - `"stack"` (default) — tags wrap onto multiple rows.
+     * - `"row"` — tags stay on one row; overflow tags collapse into a `+N`
+     *   counter, just like the Angular `multiRow=false` mode.
+     * @default 'stack'
+     */
     tagsDirection?: 'stack' | 'row';
+    /**
+     * Layout for the dropdown menu.
+     * - `"menu"` (default): vertical list of options.
+     * - `"grid"`: swatch grid for color / icon pickers and similar compact
+     *   pickers. Grid sizing is customizable via the `--tedi-swatch-size`,
+     *   `--tedi-swatch-gap`, and `--tedi-swatch-columns` CSS variables on the
+     *   menu list element.
+     * @default 'menu'
+     */
+    dropdownType?: 'menu' | 'grid';
+    /**
+     * Custom renderer for the trigger value (single-select). Receives the
+     * currently selected option and may return any React node — useful for
+     * color swatches, icons, or any non-text representation in the field.
+     * Ignored in multi-select mode (use `renderOption` for tag rendering).
+     */
+    renderValue?: (option: ISelectOption) => React.ReactNode;
+    /**
+     * In multi-select mode, prepends a "Select all" toggle to the menu list.
+     * Toggles every enabled option (or, when filtering, every visible enabled
+     * option) on/off. Indeterminate when only some are selected. Ignored when
+     * `multiple` is false.
+     * @default false
+     */
+    showSelectAll?: boolean;
+    /**
+     * In multi-select mode with grouped options, makes each group heading a
+     * checkbox that toggles the whole group. Indeterminate when only some
+     * options in the group are selected. Ignored when `multiple` is false or
+     * `options` is not grouped.
+     * @default false
+     */
+    selectableGroups?: boolean;
+    /**
+     * Open the menu automatically when the input first receives focus.
+     * @default false
+     */
     openMenuOnFocus?: boolean;
+    /**
+     * Open the menu when the trigger area is clicked.
+     * @default true
+     */
     openMenuOnClick?: boolean;
+    /**
+     * Treat the Tab key as a confirm-and-move-on for the currently focused
+     * option (otherwise Tab simply moves focus out of the menu without
+     * selecting).
+     * @default false
+     */
     tabSelectsValue?: boolean;
+    /**
+     * Close the menu after each successful selection. Default depends on
+     * `multiple`: `true` for single-select, `false` for multi-select so the
+     * user can pick several options without re-opening.
+     */
     closeMenuOnSelect?: boolean;
+    /**
+     * Blur the search input after each selection. Useful if you want to
+     * collapse the cursor immediately on pick.
+     * @default false
+     */
     blurInputOnSelect?: boolean;
+    /**
+     * Focus the input on initial mount.
+     * @default false
+     */
     autoFocus?: boolean;
+    /**
+     * Whether the value can be cleared via the "×" indicator. The visible
+     * "×" button only appears if `isClearIndicatorVisible` is also `true`
+     * (that prop is now deprecated; see its docstring for migration plans).
+     * Backspace deletion is controlled separately by `backspaceRemovesValue`
+     * (default `false`).
+     * @default true
+     */
     isClearable?: boolean;
+    /**
+     * @deprecated This prop will be removed in a future major version.
+     *
+     * `isClearable` and `isClearIndicatorVisible` overlap: `isClearable` already
+     * controls whether the value can be cleared, and `isClearIndicatorVisible`
+     * only adds an extra gate on whether the visible "×" button renders. The
+     * default combination (`isClearable: true`, `isClearIndicatorVisible: false`)
+     * leaves consumers in a state where Backspace clears the value but no
+     * affordance is shown — a hidden interaction.
+     *
+     * In a future major version the prop will be removed and `isClearable`
+     * alone will control both behaviour and visibility (matching `react-select`
+     * and the Angular implementation). For new code, prefer `isClearable` and
+     * leave this prop unset.
+     */
     isClearIndicatorVisible?: boolean;
+    /**
+     * Allow filtering the option list by typing. Set to `false` for a pure
+     * dropdown with no search input (e.g. color/icon pickers).
+     * @default true
+     */
     isSearchable?: boolean;
+    /**
+     * In multi-select mode, render an "×" remove button on each selected tag
+     * so the user can deselect single options without re-opening the menu.
+     * @default false
+     */
     isTagRemovable?: boolean;
+    /**
+     * If `true`, pressing Backspace while the input is empty removes the
+     * last selected value (single-mode: clears it; multi-mode: pops the
+     * last tag). Disabled by default because react-select's upstream
+     * default (`true`) leads to accidental deletions, especially in
+     * multi-select with no visual cue for the affected tag.
+     * @default false
+     */
+    backspaceRemovesValue?: boolean;
+    /**
+     * Controlled menu open state. When set, the parent owns whether the menu
+     * is showing — pair with `onMenuOpen` / `onMenuClose`.
+     */
     menuIsOpen?: boolean;
+    /** Fires when the menu opens (uncontrolled or controlled). */
     onMenuOpen?: () => void;
+    /** Fires when the menu closes (uncontrolled or controlled). */
     onMenuClose?: () => void;
+    /** Fires when the input loses focus. */
     onBlur?: () => void;
+    /**
+     * Hide the underlying text input (its width collapses to 0). Useful when
+     * the field is a pure picker with no typing — the value display still
+     * shows, but the cursor caret area is removed.
+     */
     inputIsHidden?: boolean;
+    /**
+     * Typography overrides applied to group headings (when `options` is
+     * grouped). `text` on an individual `IGroupedOptions` entry takes
+     * precedence over this default.
+     * @default { modifiers: 'small', color: 'tertiary' }
+     */
     optionGroupHeadingText?: Pick<TextProps, 'modifiers' | 'color'>;
+    /**
+     * In async mode, cache the result of each `loadOptions` call by input
+     * string so the same query isn't re-fetched.
+     * @default false
+     */
     cacheOptions?: boolean;
+    /**
+     * In single-select mode, render each option with a leading radio button
+     * for a more explicit "pick one" UI. Has no effect in multi-select mode.
+     * @default false
+     */
     showRadioButtons?: boolean;
+    /**
+     * Per-subcomponent class overrides forwarded to react-select's `classNames`
+     * map. Each entry adds an extra class onto the corresponding internal
+     * subcomponent; use this for one-off styling without losing the default
+     * `tedi-select__*` BEM classes.
+     */
     classNames?: {
         clearIndicator?: string;
         container?: string;
@@ -82,15 +323,33 @@ export interface SelectProps extends FormLabelProps {
         valueContainer?: string;
     };
 }
+/**
+ * One option in the select list. `customData` is a typed escape hatch for
+ * carrying domain data alongside the display label — `renderOption` /
+ * `renderValue` can read it back via `props.data.customData`.
+ */
 export interface ISelectOption<CustomData = unknown> {
+    /** The string written into the form value when this option is picked. */
     value: string;
+    /** Display label. Strings are searchable; React nodes render as-is and aren't filtered by search. */
     label: string | React.ReactNode | React.ReactNode[];
+    /** When `true`, the option appears greyed out and can't be picked. */
     isDisabled?: boolean;
+    /** Arbitrary data attached to the option, accessible inside custom renderers. */
     customData?: CustomData;
 }
+/**
+ * A group of options in a grouped select. Extends react-select's `GroupBase`
+ * with a `text` field that overrides typography for this specific heading.
+ */
 export interface IGroupedOptions<CustomOption = unknown> extends GroupBase<CustomOption> {
+    /** Typography override for this group heading. Falls back to `optionGroupHeadingText`. */
     text?: Pick<TextProps, 'modifiers' | 'color'>;
 }
+/**
+ * Shape of the Select's value: a single option (single-select), an array
+ * (multi-select), or `null` when empty.
+ */
 export type TSelectValue<CustomData = unknown> = ISelectOption<CustomData> | ReadonlyArray<ISelectOption<CustomData>> | null;
 export declare const Select: React.ForwardRefExoticComponent<SelectProps & React.RefAttributes<SelectInstance<ISelectOption<unknown>, boolean, IGroupedOptions<ISelectOption<unknown>>>>>;
 export default Select;