@jetbrains/ring-ui 6.0.1-beta.0 → 6.0.1

package/components/popup/popup.js

@@ -287,9 +287,9 @@ Popup.propTypes = {
     children: PropTypes.node.isRequired,
     dontCloseOnAnchorClick: PropTypes.bool,
     shortcuts: PropTypes.bool,
-    keepMounted: PropTypes.bool,
+    keepMounted: PropTypes.bool, // pass this prop to preserve the popup's DOM state while hidden
     'data-test': PropTypes.string,
-    client: PropTypes.bool,
+    client: PropTypes.bool, // true means that it's never used in SSR
     directions: PropTypes.arrayOf(PropTypes.string),
     autoPositioning: PropTypes.bool,
     autoCorrectTopOverflow: PropTypes.bool,
@@ -298,7 +298,7 @@ Popup.propTypes = {
     maxHeight: PropTypes.oneOfType([PropTypes.string, PropTypes.number]),
     minWidth: PropTypes.number,
     sidePadding: PropTypes.number,
-    attached: PropTypes.bool,
+    attached: PropTypes.bool, // Popup adjacent to an input, without upper border and shadow
     onMouseDown: PropTypes.func,
     onMouseUp: PropTypes.func,
     onMouseOver: PropTypes.func,

package/components/popup/position.js

@@ -99,7 +99,10 @@ export function maxHeightForDirection(direction, anchorNode, containerNode) {
     const container = containerNode || document.documentElement;
     const domRect = anchorNode.getBoundingClientRect();
     const containerRect = container.getBoundingClientRect();
-    const topMaxHeight = Math.max(domRect.top - containerRect.top, 0);
+    const containerTop = domRect.top < 0
+        ? containerRect.top
+        : Math.max(containerRect.top, 0);
+    const topMaxHeight = Math.max(domRect.top - containerTop, 0);
     const containerHeight = Math.max(containerRect.height, 
     // XXX
     // If container is the document element

package/components/popup-menu/popup-menu.d.ts

@@ -12,7 +12,17 @@ export default class PopupMenu<T = unknown> extends Popup<PopupMenuProps<T>> {
     static isItemType: <T_1>(listItemType: import("../list/consts").Type, item: ListDataItem<T_1>) => boolean;
     static ListProps: {
         Type: typeof import("../list/consts").Type;
-        Dimension: typeof import("../list/consts").Dimension;
+        Dimension: {
+            ITEM_PADDING: number;
+            ITEM_HEIGHT: number;
+            COMPACT_ITEM_HEIGHT: number;
+            SEPARATOR_HEIGHT: number;
+            SEPARATOR_FIRST_HEIGHT: number;
+            SEPARATOR_TEXT_HEIGHT: number;
+            TITLE_HEIGHT: number;
+            INNER_PADDING: number;
+            MARGIN: number;
+        };
     };
     static defaultProps: {
         renderOptimization: boolean;
@@ -56,5 +66,15 @@ export default class PopupMenu<T = unknown> extends Popup<PopupMenuProps<T>> {
 export type PopupMenuAttrs<T = unknown> = JSX.LibraryManagedAttributes<typeof PopupMenu, PopupMenuProps<T>>;
 export declare const ListProps: {
     Type: typeof import("../list/consts").Type;
-    Dimension: typeof import("../list/consts").Dimension;
+    Dimension: {
+        ITEM_PADDING: number;
+        ITEM_HEIGHT: number;
+        COMPACT_ITEM_HEIGHT: number;
+        SEPARATOR_HEIGHT: number;
+        SEPARATOR_FIRST_HEIGHT: number;
+        SEPARATOR_TEXT_HEIGHT: number;
+        TITLE_HEIGHT: number;
+        INNER_PADDING: number;
+        MARGIN: number;
+    };
 };

package/components/progress-bar/progress-bar.css

@@ -1,7 +1,6 @@
 @import "../global/variables.css";
 
 @value dark from "../global/variables_dark.css";
-@value unit from "../global/global.css";
 
 :root {
   --ring-progress-bar-background-color: rgba(0, 0, 0, 0.2);
@@ -20,8 +19,8 @@
 
   overflow: hidden;
 
-  height: calc(unit / 2);
-  margin-bottom: calc(unit / 2);
+  height: calc(var(--ring-unit) / 2);
+  margin-bottom: calc(var(--ring-unit) / 2);
 
   border-radius: 2px;
   background-color: var(--ring-progress-bar-background-color);
@@ -49,7 +48,7 @@
   border-radius: 2px;
   background-color: var(--ring-main-color);
 
-  line-height: calc(unit / 2);
+  line-height: calc(var(--ring-unit) / 2);
 
   &::after {
     position: absolute;
@@ -63,6 +62,12 @@
 
     background-image: linear-gradient(to right, rgba(0, 0, 0, 0), var(--ring-progress-bar-line-background-color), rgba(0, 0, 0, 0));
     background-repeat: no-repeat;
+
+    .staticLineColor &  {
+      animation: none;
+
+      background-image: var(--ring-progress-bar-line-background-color);
+    }
   }
 }
 

package/components/progress-bar/progress-bar.d.ts

@@ -5,6 +5,7 @@ export interface ProgressBarProps extends HTMLAttributes<HTMLElement> {
     value: number;
     label: string;
     global?: boolean | null | undefined;
+    staticColor?: boolean;
 }
 /**
  * @name Progress Bar
@@ -43,6 +44,11 @@ export default class ProgressBar extends PureComponent<ProgressBarProps> {
          * @type {number}
          */
         value: PropTypes.Requireable<number>;
+        /**
+         * Disables Disabled progress bar color animation and sets it to static color.
+         * @type {boolean}
+         */
+        staticColor: PropTypes.Requireable<boolean>;
     };
     static defaultProps: {
         max: number;

package/components/progress-bar/progress-bar.js

@@ -42,7 +42,12 @@ export default class ProgressBar extends PureComponent {
          * A floating point number that specifies current task completion rate.
          * @type {number}
          */
-        value: PropTypes.number
+        value: PropTypes.number,
+        /**
+         * Disables Disabled progress bar color animation and sets it to static color.
+         * @type {boolean}
+         */
+        staticColor: PropTypes.bool
     };
     static defaultProps = {
         max: 1.0,
@@ -58,10 +63,11 @@ export default class ProgressBar extends PureComponent {
         this.progressbar = el;
     };
     render() {
-        const { className, global, max, value, label, ...otherProps } = this.props;
+        const { className, global, max, value, label, staticColor, ...otherProps } = this.props;
         const width = value ? `${ProgressBar.toPercent(value, max)}%` : undefined;
         const classes = classNames(styles.progressBar, className, {
-            [styles.globalMode]: global
+            [styles.globalMode]: global,
+            [styles.staticLineColor]: staticColor
         });
         return (<div {...otherProps} className={classes} ref={this.progressbarWrapperRef}>
         <div className={styles.line} ref={this.progressbarRef} role="progressbar" aria-label={label} aria-valuenow={value} aria-valuemin={0} aria-valuemax={max} style={{ width }}/>

package/components/query-assist/query-assist.css

@@ -1,13 +1,12 @@
 @import "../global/variables.css";
 @import "../button/button.css";
 
-@value unit from "../global/global.css";
 @value overInputZIndex: 2;
-@value inputGap: calc(unit * 3);
+@value inputGap: calc(var(--ring-unit) * 3);
 
 .queryAssist {
-  --ring-input-icon-offset: calc(unit * 2.5);
-  --ring-input-padding-inline: unit;
+  --ring-input-icon-offset: calc(var(--ring-unit) * 2.5);
+  --ring-input-padding-inline: var(--ring-unit);
   --ring-input-padding-block: 1px;
 
   position: relative;

package/components/query-assist/query-assist.d.ts

@@ -17,6 +17,7 @@ export interface FocusChange {
 }
 export interface QueryAssistChange {
     query: string;
+    prevCaret?: number | null;
     caret: number;
     focus?: boolean;
     selection?: Position | number | null;
@@ -296,36 +297,10 @@ export default class QueryAssist extends Component<QueryAssistProps> {
     clearRef: (node: ComponentRef<typeof Button> | null) => void;
     shortcutsScope: string;
     shortcutsMap: ShortcutsMap;
+    listShortcutsMap: ShortcutsMap;
     renderActions(): React.ReactNode[];
     render(): React.JSX.Element;
 }
 export type QueryAssistAttrs = JSX.LibraryManagedAttributes<typeof QueryAssist, QueryAssistProps>;
-export declare const RerenderableQueryAssist: {
-    new (props: QueryAssistProps): {
-        _propsCache: QueryAssistProps & React.RefAttributes<unknown>;
-        rerender(props?: Partial<QueryAssistProps>, callback?: (() => void) | undefined): void;
-        node?: HTMLElement | null | undefined;
-        context: unknown;
-        setState<K extends never>(state: {} | ((prevState: Readonly<{}>, props: Readonly<QueryAssistProps>) => {} | Pick<{}, K> | null) | Pick<{}, K> | null, callback?: (() => void) | undefined): void;
-        forceUpdate(callback?: (() => void) | undefined): void;
-        render(): React.ReactNode;
-        readonly props: Readonly<QueryAssistProps>;
-        state: Readonly<{}>;
-        refs: {
-            [key: string]: React.ReactInstance;
-        };
-        componentDidMount?(): void;
-        shouldComponentUpdate?(nextProps: Readonly<QueryAssistProps>, nextState: Readonly<{}>, nextContext: any): boolean;
-        componentWillUnmount?(): void;
-        componentDidCatch?(error: Error, errorInfo: React.ErrorInfo): void;
-        getSnapshotBeforeUpdate?(prevProps: Readonly<QueryAssistProps>, prevState: Readonly<{}>): any;
-        componentDidUpdate?(prevProps: Readonly<QueryAssistProps>, prevState: Readonly<{}>, snapshot?: any): void;
-        componentWillMount?(): void;
-        UNSAFE_componentWillMount?(): void;
-        componentWillReceiveProps?(nextProps: Readonly<QueryAssistProps>, nextContext: any): void;
-        UNSAFE_componentWillReceiveProps?(nextProps: Readonly<QueryAssistProps>, nextContext: any): void;
-        componentWillUpdate?(nextProps: Readonly<QueryAssistProps>, nextState: Readonly<{}>, nextContext: any): void;
-        UNSAFE_componentWillUpdate?(nextProps: Readonly<QueryAssistProps>, nextState: Readonly<{}>, nextContext: any): void;
-    };
-};
+export declare const RerenderableQueryAssist: React.ForwardRefExoticComponent<QueryAssistProps & React.RefAttributes<QueryAssist>>;
 export {};

package/components/query-assist/query-assist.js

@@ -239,11 +239,12 @@ export default class QueryAssist extends Component {
         this.setupRequestHandler(delay);
         const shouldSetCaret = typeof caret === 'number' && caret !== prevProps.caret;
         if (shouldSetCaret) {
+            this.immediateState.prevCaret = prevProps.caret;
             this.immediateState.caret = caret;
         }
         if (typeof query === 'string' && queryChanged && query !== this.immediateState.query) {
             this.immediateState.query = query;
-            if (prevProps.autoOpen && query?.length > 0) {
+            if (query && (this.props.autoOpen === 'force' || prevProps.autoOpen && query.length > 0)) {
                 this.requestData?.();
             }
             else if (query) {
@@ -447,13 +448,14 @@ export default class QueryAssist extends Component {
             : currentCaret?.position ?? 0;
         const popupHidden = (!this.state.showPopup) && e.type === 'click';
         if (!this.props.disabled && (caret !== this.immediateState.caret || popupHidden)) {
+            this.immediateState.prevCaret = this.immediateState.caret;
             this.immediateState.caret = caret;
             this.scrollInput();
             if (this.immediateState.query.length > 0) {
                 this.requestData?.();
             }
         }
-        if (this.immediateState.query.length < 1) {
+        if (this.props.autoOpen !== 'force' && this.immediateState.query.length < 1) {
             this.setState({ showPopup: false });
         }
     };
@@ -472,7 +474,7 @@ export default class QueryAssist extends Component {
                 placeholderEnabled: !query,
                 query,
                 suggestions,
-                showPopup: !!suggestions.length && !afterCompletion
+                showPopup: !!suggestions.length && (this.props.autoOpen === 'force' || !afterCompletion)
             };
             this.immediateState.suggestionsQuery = query;
             // Do not update deep equal styleRanges to simplify shouldComponentUpdate check
@@ -506,6 +508,7 @@ export default class QueryAssist extends Component {
         const prefix = suggestion.prefix || '';
         const suffix = suggestion.suffix || '';
         const state = {
+            prevCaret: currentCaret,
             caret: suggestion.caret ?? 0,
             selection: suggestion.caret ?? 0,
             query: query.substr(0, suggestion.completionStart) + prefix + suggestion.option + suffix
@@ -768,6 +771,10 @@ export default class QueryAssist extends Component {
         home: noop,
         end: noop
     };
+    listShortcutsMap = {
+        home: noop,
+        end: noop
+    };
     renderActions() {
         const actions = [...(this.props.actions || [])];
         const renderClear = this.props.clear && !!this.state.query;
@@ -793,7 +800,7 @@ export default class QueryAssist extends Component {
         const inputClasses = classNames(this.props.inputClassName, {
             [`${styles.input} ring-js-shortcuts`]: true,
             [styles.inputGap]: actions.length || this.isRenderingGlassOrLoader() && !glass,
-            [styles.inputGap2]: actions.length === 2,
+            [styles.inputGap2]: actions.length === 2, // TODO: replace with flex-box layout
             [styles.inputRevertOrder]: !glass || huge
         });
         const placeholderStyles = classNames({
@@ -827,7 +834,7 @@ export default class QueryAssist extends Component {
                     ? (<div data-test="ring-query-assist-actions" className={styles.actions}>{actions}</div>)
                     : null}
 
-              <PopupMenu hidden={!this.state.showPopup} onCloseAttempt={this.closePopup} ref={this.popupRef} anchorElement={this.node} keepMounted attached className={this.props.popupClassName} directions={[PopupMenu.PopupProps.Directions.BOTTOM_RIGHT]} data={useCustomItemRender ? this.state.suggestions : this.renderSuggestions()} data-test="ring-query-assist-popup" hint={this.props.hint} hintOnSelection={this.props.hintOnSelection} left={this.getPopupOffset(this.state.suggestions)} maxHeight={PopupMenu.PopupProps.MaxHeight.SCREEN} onMouseDown={this.trackPopupMouseState} onMouseUp={this.trackPopupMouseState} onSelect={item => this.handleComplete(item)}/>
+              <PopupMenu hidden={!this.state.showPopup} onCloseAttempt={this.closePopup} ref={this.popupRef} anchorElement={this.node} keepMounted attached className={this.props.popupClassName} directions={[PopupMenu.PopupProps.Directions.BOTTOM_RIGHT]} data={useCustomItemRender ? this.state.suggestions : this.renderSuggestions()} data-test="ring-query-assist-popup" hint={this.props.hint} shortcutsMap={this.listShortcutsMap} hintOnSelection={this.props.hintOnSelection} left={this.getPopupOffset(this.state.suggestions)} maxHeight={PopupMenu.PopupProps.MaxHeight.SCREEN} onMouseDown={this.trackPopupMouseState} onMouseUp={this.trackPopupMouseState} onSelect={item => this.handleComplete(item)}/>
 
               {glass && huge && (<div className={styles.rightSearchButton} data-test="query-assist-search-button">
                   <Icon glyph={searchIcon} className={styles.rightSearchIcon} title={translations?.searchTitle ?? translate('searchTitle')} onClick={this.handleApply} ref={this.glassRef} data-test="query-assist-search-icon"/>

package/components/radio/radio.css

@@ -1,8 +1,5 @@
 @import "../global/variables.css";
 
-@value unit from "../global/global.css";
-@value radio-size: calc(2 * unit);
-
 .radio {
   position: relative;
 
@@ -30,15 +27,15 @@
   flex-shrink: 0;
 
   box-sizing: border-box;
-  width: radio-size;
-  height: radio-size;
+  width: calc(2 * var(--ring-unit));
+  height: calc(2 * var(--ring-unit));
 
   user-select: none;
   transition: border-color var(--ring-ease), box-shadow var(--ring-ease);
   pointer-events: none;
 
   border: 1px solid var(--ring-borders-color);
-  border-radius: unit;
+  border-radius: var(--ring-unit);
   background-color: var(--ring-content-background-color);
 
   &::after {
@@ -46,8 +43,8 @@
     top: 3px;
     left: 3px;
 
-    width: unit;
-    height: unit;
+    width: var(--ring-unit);
+    height: var(--ring-unit);
 
     content: "";
 
@@ -57,7 +54,7 @@
 
     opacity: 0;
 
-    border-radius: calc(unit / 2);
+    border-radius: calc(var(--ring-unit) / 2);
     background-color: var(--ring-main-color);
   }
 }
@@ -119,7 +116,7 @@
 }
 
 .label {
-  margin-left: unit;
+  margin-left: var(--ring-unit);
 
   line-height: var(--ring-line-height);
 }

package/components/select/select-popup.css

@@ -1,11 +1,9 @@
 @import "../global/variables.css";
 
-@value unit from "../global/global.css";
-
 .filterWithTags {
   overflow: hidden;
 
-  margin: calc(unit * 2) unit 0;
+  margin: calc(var(--ring-unit) * 2) var(--ring-unit) 0;
   padding: 3px;
 
   text-align: left;
@@ -42,45 +40,59 @@
   width: 0;
 }
 
+.popup {
+  overscroll-behavior: contain;
+}
+
 .filterWrapper {
   position: relative;
 
   display: flex;
 
   margin: 0;
-  padding-right: unit;
-  padding-left: calc(unit * 5.5);
+  padding-right: var(--ring-unit);
+  padding-left: calc(var(--ring-unit) * 5.5);
 
   border-bottom: 1px solid var(--ring-borders-color);
 
   [dir="rtl"] & {
-    padding-right: calc(unit * 5.5);
-    padding-left: unit;
+    padding-right: calc(var(--ring-unit) * 5.5);
+    padding-left: var(--ring-unit);
   }
 }
 
 .filterIcon {
   position: absolute;
   top: 7px;
-  left: calc(unit * 2);
+  left: calc(var(--ring-unit) * 2);
 
   color: var(--ring-icon-color);
 
   [dir="rtl"] & {
-    right: calc(unit * 2);
+    right: calc(var(--ring-unit) * 2);
     left: auto;
   }
 }
 
 .bottomLine {
   text-align: center;
+
+  &.bottomLineOverItem {
+    position: relative;
+
+    z-index: var(--ring-fixed-z-index);
+
+    margin-top: -36px;
+
+    background-color: var(--ring-content-background-color);
+  }
 }
 
 .message {
   display: inline-block;
 
-  margin: unit 0;
-  padding: 0 calc(2 * unit);
+  margin: var(--ring-unit) 0;
+  padding: 0 calc(2 * var(--ring-unit));
 }
 
 .selectAll {

package/components/select/select.css

@@ -1,6 +1,5 @@
 @import "../global/variables.css";
 
-@value unit from "../global/global.css";
 @value button-shadow from "../button/button.css";
 
 .select {
@@ -29,12 +28,12 @@
   }
 
   .toolbar & {
-    height: calc(4 * unit);
-    margin: unit 0;
+    height: calc(4 * var(--ring-unit));
+    margin: var(--ring-unit) 0;
   }
 
   &.buttonSpaced {
-    padding: 0 calc(2 * unit);
+    padding: 0 calc(2 * var(--ring-unit));
   }
 }
 
@@ -63,8 +62,8 @@
 
   display: inline-block;
 
-  width: calc(2 * unit);
-  height: calc(2 * unit);
+  width: calc(2 * var(--ring-unit));
+  height: calc(2 * var(--ring-unit));
   margin: 0 4px;
 
   background-repeat: no-repeat;
@@ -80,15 +79,15 @@
 }
 
 .sizeS {
-  width: calc(unit * 12);
+  width: calc(var(--ring-unit) * 12);
 }
 
 .sizeM {
-  width: calc(unit * 30);
+  width: calc(var(--ring-unit) * 30);
 }
 
 .sizeL {
-  width: calc(unit * 50);
+  width: calc(var(--ring-unit) * 50);
 }
 
 .sizeFULL {
@@ -113,7 +112,7 @@
 
   box-sizing: border-box;
   width: 100%;
-  height: calc(unit * 4 + 1px);
+  height: calc(var(--ring-unit) * 4 + 1px);
   padding: 0 0 3px;
 
   cursor: pointer;
@@ -157,10 +156,10 @@
   display: block;
 
   width: 100%;
-  padding-left: unit;
+  padding-left: var(--ring-unit);
 
   text-align: left;
-  vertical-align: calc(0 - unit);
+  vertical-align: calc(var(--ring-unit) * -1);
 }
 
 .buttonValue:focus-visible {
@@ -216,8 +215,8 @@
 }
 
 .popup {
-  min-width: calc(unit * 30);
-  max-width: calc(unit * 40);
+  min-width: calc(var(--ring-unit) * 30);
+  max-width: calc(var(--ring-unit) * 40);
 }
 
 .chevron.chevron {

package/components/select/select.d.ts

@@ -214,6 +214,7 @@ export default class Select<T = unknown> extends Component<SelectProps<T>, Selec
     nodeRef: (el: HTMLElement | null) => void;
     _popup: SelectPopup<SelectItemData<T>> | null;
     onEmptyPopupEnter: () => void;
+    focus: () => void;
     private _onEnter;
     private _onEsc;
     _inputShortcutHandler: () => void;
@@ -271,32 +272,5 @@ export default class Select<T = unknown> extends Component<SelectProps<T>, Selec
 export type SingleSelectAttrs<T = unknown> = JSX.LibraryManagedAttributes<typeof Select, SingleSelectProps<T>>;
 export type MultipleSelectAttrs<T = unknown> = JSX.LibraryManagedAttributes<typeof Select, MultipleSelectProps<T>>;
 export type SelectAttrs<T = unknown> = JSX.LibraryManagedAttributes<typeof Select, SelectProps<T>>;
-export declare const RerenderableSelect: {
-    new (props: SelectProps<unknown>): {
-        _propsCache: SelectProps<unknown> & React.RefAttributes<unknown>;
-        rerender(props?: Partial<SelectProps<unknown>>, callback?: (() => void) | undefined): void;
-        node?: HTMLElement | null | undefined;
-        context: unknown;
-        setState<K extends keyof SelectState<unknown>>(state: SelectState<unknown> | ((prevState: Readonly<SelectState<unknown>>, props: Readonly<SelectProps<unknown>>) => SelectState<unknown> | Pick<SelectState<unknown>, K> | null) | Pick<SelectState<unknown>, K> | null, callback?: (() => void) | undefined): void;
-        forceUpdate(callback?: (() => void) | undefined): void;
-        render(): React.ReactNode;
-        readonly props: Readonly<SelectProps<unknown>>;
-        state: Readonly<SelectState<unknown>>;
-        refs: {
-            [key: string]: React.ReactInstance;
-        };
-        componentDidMount?(): void;
-        shouldComponentUpdate?(nextProps: Readonly<SelectProps<unknown>>, nextState: Readonly<SelectState<unknown>>, nextContext: any): boolean;
-        componentWillUnmount?(): void;
-        componentDidCatch?(error: Error, errorInfo: React.ErrorInfo): void;
-        getSnapshotBeforeUpdate?(prevProps: Readonly<SelectProps<unknown>>, prevState: Readonly<SelectState<unknown>>): any;
-        componentDidUpdate?(prevProps: Readonly<SelectProps<unknown>>, prevState: Readonly<SelectState<unknown>>, snapshot?: any): void;
-        componentWillMount?(): void;
-        UNSAFE_componentWillMount?(): void;
-        componentWillReceiveProps?(nextProps: Readonly<SelectProps<unknown>>, nextContext: any): void;
-        UNSAFE_componentWillReceiveProps?(nextProps: Readonly<SelectProps<unknown>>, nextContext: any): void;
-        componentWillUpdate?(nextProps: Readonly<SelectProps<unknown>>, nextState: Readonly<SelectState<unknown>>, nextContext: any): void;
-        UNSAFE_componentWillUpdate?(nextProps: Readonly<SelectProps<unknown>>, nextState: Readonly<SelectState<unknown>>, nextContext: any): void;
-    };
-};
+export declare const RerenderableSelect: React.ForwardRefExoticComponent<SelectProps<unknown> & React.RefAttributes<Select<unknown>>>;
 export {};

package/components/select/select.js

@@ -181,46 +181,46 @@ function isSameSelected(prevSelected, selected) {
 export default class Select extends Component {
     static defaultProps = {
         data: [],
-        filter: false,
+        filter: false, // enable filter (not in INPUT modes)
         filterIcon: null,
         filterRef: noop,
-        multiple: false,
-        clear: false,
-        loading: false,
-        disabled: false,
+        multiple: false, // multiple can be an object - see demo for more information
+        clear: false, // enable clear button that clears the "selected" state
+        loading: false, // show a loading indicator while data is loading
+        disabled: false, // disable select
         type: Type.BUTTON,
         size: Size.M,
-        targetElement: null,
-        hideSelected: false,
-        allowAny: false,
-        hideArrow: false,
+        targetElement: null, // element to bind the popup to (select BUTTON or INPUT by default)
+        hideSelected: false, // INPUT mode: clears the input after an option is selected (useful when the selection is displayed in some custom way elsewhere)
+        allowAny: false, // INPUT mode: allows any value to be entered
+        hideArrow: false, // hide dropdown arrow icon
         showPopup: false,
-        maxHeight: 600,
+        maxHeight: 600, // height of the options list, including the filter and the 'Add' button
         directions: [
             Popup.PopupProps.Directions.BOTTOM_RIGHT,
             Popup.PopupProps.Directions.BOTTOM_LEFT,
             Popup.PopupProps.Directions.TOP_LEFT,
             Popup.PopupProps.Directions.TOP_RIGHT
         ],
-        selected: null,
-        label: null,
-        selectedLabel: null,
-        inputPlaceholder: '',
-        hint: null,
+        selected: null, // current selection (item / array of items)
+        label: null, // BUTTON or INPUT label (nothing selected)
+        selectedLabel: null, // BUTTON or INPUT label (something selected)
+        inputPlaceholder: '', // Placeholder for input modes
+        hint: null, // hint text to display under the list
         shortcutsEnabled: false,
         onBeforeOpen: noop,
         onLoadMore: noop,
         onOpen: noop,
         onClose: noop,
-        onFilter: noop,
+        onFilter: noop, // search string as first argument
         onFocus: noop,
         onBlur: noop,
         onKeyDown: noop,
-        onSelect: noop,
-        onDeselect: noop,
-        onOutsideClick: noop,
-        onChange: noop,
-        onAdd: noop,
+        onSelect: noop, // single + multi
+        onDeselect: noop, // multi
+        onOutsideClick: noop, // multi
+        onChange: noop, // multi
+        onAdd: noop, // search string as first argument
         onDone: noop,
         onReset: noop,
         tags: null,
@@ -337,6 +337,11 @@ export default class Select extends Component {
             this.addHandler();
         }
     };
+    focus = () => {
+        const focusableSelectExists = this.node?.querySelector('[data-test~=ring-select__focus]');
+        const restoreFocusNode = this.props.targetElement || focusableSelectExists;
+        restoreFocusNode?.focus();
+    };
     _onEnter = () => {
         if (this.state.addButton && this.state.shownData.length === 0) {
             this.addHandler();
@@ -459,12 +464,7 @@ export default class Select extends Component {
                 filterValue: this.props.allowAny ? prevState.filterValue : ''
             }));
             if (tryFocusAnchor) {
-                const focusableSelectExists = this.node &&
-                    this.node.querySelector('[data-test~=ring-select__focus]');
-                const restoreFocusNode = this.props.targetElement || focusableSelectExists;
-                if (restoreFocusNode) {
-                    restoreFocusNode.focus();
-                }
+                this.focus();
             }
         }
     }
@@ -866,7 +866,7 @@ export default class Select extends Component {
                                 onClick: this._clickHandler,
                                 disabled: this.props.disabled,
                                 children: this._getPlaceholder(),
-                                'data-test': 'ring-select_focus'
+                                'data-test': 'ring-select__focus'
                             },
                             popup: this._renderPopup()
                         })}