uikit-react-public 0.14.21 → 0.21.8

package/lib/components/Select/Select.stories.tsx

@@ -1,37 +1,135 @@
 import type { Meta, StoryObj } from '@storybook/react';
 import { useArgs } from '@storybook/preview-api';
 import Select from './Select';
+import { css } from '@emotion/css';
+
+const select400pxWidthClass = css`
+  width: 400px;
+`;
+const storyWrapperStyle: React.CSSProperties = { minHeight: 150, width: 400 };
 
 const meta = {
-  title: 'Components/Ready to use/Select',
+  title: 'Components/Select',
   component: Select,
   argTypes: {
-    value: { control: { type: 'text' } },
+    selectionBehaviour: {
+      description:
+        'Keyboard selection behaviour for custom variant: `focus` commits on arrow keys, `commit` commits on Enter/click',
+      control: { type: 'radio' },
+      options: ['focus', 'commit'],
+      table: { type: { summary: "'focus' | 'commit'" } },
+    },
+    options: {
+      description: 'Array of option objects `{ label, value, optionProps? }`',
+      control: { type: 'object' },
+      table: { type: { summary: 'OptionData[]' } },
+    },
+    value: {
+      description: 'Selected value (string | number | null)',
+      control: { type: 'text' },
+      table: { type: { summary: 'string | number | null' } },
+    },
+    onValueChange: {
+      description:
+        'Change handler for the custom select variant (value, event)',
+      control: false,
+      table: {
+        type: {
+          summary:
+            '(value: string | number | null, ev: React.SyntheticEvent) => void',
+        },
+      },
+    },
     native: {
+      description: 'Render the native `<select>` variant when true',
       control: { type: 'boolean' },
+      table: { type: { summary: 'boolean' } },
+    },
+    nativeHtmlAttributes: {
+      description: 'Additional props to spread onto the native `<select>`',
+      control: false,
+      table: {
+        type: { summary: 'React.SelectHTMLAttributes<HTMLSelectElement>' },
+      },
     },
     disabled: {
+      description: 'Disable interaction',
       control: { type: 'boolean' },
+      table: { type: { summary: 'boolean' } },
     },
     placeholder: {
+      description: 'Helper text when no value is selected',
       control: { type: 'text' },
+      table: { type: { summary: 'string' } },
     },
-    testId: {
+    filterable: {
+      description:
+        'Show a filter input to narrow options in the custom variant',
+      control: { type: 'boolean' },
+      table: { type: { summary: 'boolean' } },
+    },
+    clearable: {
+      description:
+        'Show a clear action in the custom variant when a value is selected',
+      control: { type: 'boolean' },
+      table: { type: { summary: 'boolean' } },
+    },
+    filterInputProps: {
+      description:
+        'Additional props to spread onto the filter input (when filterable)',
+      control: { type: 'object' },
+      table: {
+        type: {
+          summary: 'React.InputHTMLAttributes<HTMLInputElement>',
+        },
+      },
+    },
+    id: {
+      description: 'Standard HTML id forwarded to the combobox/native select',
       control: { type: 'text' },
+      table: { type: { summary: 'string' } },
+    },
+    title: {
+      description:
+        'Standard title attribute forwarded to the combobox/native select',
+      control: { type: 'text' },
+      table: { type: { summary: 'string' } },
     },
     lineBreak: {
+      description: 'Wrap long option labels',
       control: { type: 'boolean' },
+      table: { type: { summary: 'boolean' } },
+    },
+    panelClassName: {
+      description: 'Custom className for the options panel',
+      control: { type: 'text' },
+      table: { type: { summary: 'string' } },
+    },
+    className: {
+      description: 'Custom className for the root element',
+      control: { type: 'text' },
+      table: { type: { summary: 'string' } },
+    },
+    testId: {
+      description: 'Test id applied to the root element',
+      control: { type: 'text' },
+      table: { type: { summary: 'string' } },
     },
   },
   args: {
+    selectionBehaviour: 'focus',
     value: undefined,
-    onChange: () => {},
     options: [
       { label: 'Option one', value: '1' },
       { label: 'Option two', value: '2' },
       { label: 'Option three', value: '3' },
     ],
   },
+  parameters: {
+    docs: {
+      story: { inline: true },
+    },
+  },
 } satisfies Meta<typeof Select>;
 
 export default meta;
@@ -40,16 +138,19 @@ type Story = StoryObj<typeof meta>;
 export const Default: Story = {
   render: () => {
     const [args, updateArgs] = useArgs();
-    const onValueChange = (value: string | number) => {
+    const onValueChange = (value: string | number | null) => {
       updateArgs({ value });
     };
     return (
-      <Select
-        {...args}
-        options={args.options}
-        value={args.value}
-        onValueChange={onValueChange}
-      />
+      <div style={storyWrapperStyle}>
+        <Select
+          {...args}
+          className={select400pxWidthClass}
+          options={args.options}
+          value={args.value}
+          onValueChange={onValueChange}
+        />
+      </div>
     );
   },
 };
@@ -60,16 +161,18 @@ export const Native: Story = {
   },
   render: () => {
     const [args, updateArgs] = useArgs();
-    const onValueChange = (value: string | number) => {
-      updateArgs({ value });
-    };
+    const onNativeChange = (event: React.ChangeEvent<HTMLSelectElement>) =>
+      updateArgs({ value: event.target.value });
     return (
-      <Select
-        {...args}
-        options={args.options}
-        value={args.value}
-        onValueChange={onValueChange}
-      />
+      <div style={storyWrapperStyle}>
+        <Select
+          {...args}
+          className={select400pxWidthClass}
+          options={args.options}
+          value={args.value}
+          nativeHtmlAttributes={{ onChange: onNativeChange }}
+        />
+      </div>
     );
   },
 };
@@ -80,17 +183,20 @@ export const Disabled: Story = {
   },
   render: () => {
     const [args, updateArgs] = useArgs();
-    const onValueChange = (value: string | number) => {
+    const onValueChange = (value: string | number | null) => {
       updateArgs({ value });
     };
 
     return (
-      <Select
-        {...args}
-        options={args.options}
-        value={args.value}
-        onValueChange={onValueChange}
-      />
+      <div style={storyWrapperStyle}>
+        <Select
+          {...args}
+          className={select400pxWidthClass}
+          options={args.options}
+          value={args.value}
+          onValueChange={onValueChange}
+        />
+      </div>
     );
   },
 };
@@ -99,17 +205,20 @@ export const WithPlaceholder: Story = {
   args: { placeholder: 'Please select an option' },
   render: () => {
     const [args, updateArgs] = useArgs();
-    const onValueChange = (value: string | number) => {
+    const onValueChange = (value: string | number | null) => {
       updateArgs({ value });
     };
 
     return (
-      <Select
-        {...args}
-        options={args.options}
-        value={args.value}
-        onValueChange={onValueChange}
-      />
+      <div style={storyWrapperStyle}>
+        <Select
+          {...args}
+          className={select400pxWidthClass}
+          options={args.options}
+          value={args.value}
+          onValueChange={onValueChange}
+        />
+      </div>
     );
   },
 };
@@ -125,17 +234,20 @@ export const SingleLongOption: Story = {
   },
   render: () => {
     const [args, updateArgs] = useArgs();
-    const onValueChange = (value: string | number) => {
+    const onValueChange = (value: string | number | null) => {
       updateArgs({ value });
     };
 
     return (
-      <Select
-        {...args}
-        options={args.options}
-        value={args.value}
-        onValueChange={onValueChange}
-      />
+      <div style={storyWrapperStyle}>
+        <Select
+          {...args}
+          className={select400pxWidthClass}
+          options={args.options}
+          value={args.value}
+          onValueChange={onValueChange}
+        />
+      </div>
     );
   },
 };
@@ -163,16 +275,85 @@ export const ManyOptions: Story = {
   },
   render: () => {
     const [args, updateArgs] = useArgs();
-    const onValueChange = (value: string | number) => {
+    const onValueChange = (value: string | number | null) => {
       updateArgs({ value });
     };
     return (
-      <Select
-        {...args}
-        options={args.options}
-        value={args.value}
-        onValueChange={onValueChange}
-      />
+      <div style={storyWrapperStyle}>
+        <Select
+          {...args}
+          className={select400pxWidthClass}
+          options={args.options}
+          value={args.value}
+          onValueChange={onValueChange}
+        />
+      </div>
+    );
+  },
+};
+
+export const filterable: Story = {
+  args: { filterable: true },
+  render: () => {
+    const [args, updateArgs] = useArgs();
+    const onValueChange = (value: string | number | null) =>
+      updateArgs({ value });
+    return (
+      <div style={storyWrapperStyle}>
+        <Select
+          {...args}
+          className={select400pxWidthClass}
+          options={args.options}
+          value={args.value}
+          onValueChange={onValueChange}
+          placeholder='Type to filter...'
+        />
+      </div>
+    );
+  },
+};
+
+export const Clearable: Story = {
+  args: {
+    clearable: true,
+    value: '2',
+    placeholder: 'Clear selection',
+  },
+  render: () => {
+    const [args, updateArgs] = useArgs();
+    const onValueChange = (value: string | number | null) =>
+      updateArgs({ value });
+    return (
+      <div style={storyWrapperStyle}>
+        <Select
+          {...args}
+          className={select400pxWidthClass}
+          options={args.options}
+          value={args.value}
+          onValueChange={onValueChange}
+        />
+      </div>
+    );
+  },
+};
+
+export const SelectionBehaviourCommit: Story = {
+  name: 'Selection behaviour: commit',
+  args: { selectionBehaviour: 'commit' },
+  render: () => {
+    const [args, updateArgs] = useArgs();
+    const onValueChange = (value: string | number | null) =>
+      updateArgs({ value });
+    return (
+      <div style={storyWrapperStyle}>
+        <Select
+          {...args}
+          className={select400pxWidthClass}
+          options={args.options}
+          value={args.value}
+          onValueChange={onValueChange}
+        />
+      </div>
     );
   },
 };

package/lib/components/Select/Select.tsx

@@ -1,25 +1,60 @@
 import { NativeSelect, CustomSelect } from './subcomponents';
-import { SelectProps } from './Select.types';
+import type { InternalSelectProps, SelectProps } from './Select.types';
 
-const Select = <T extends string | number = string>(props: SelectProps<T>) => {
-  if (props.native) {
-    const { onChange, value, ...rest } = props;
+type SelectComponent = <T extends string | number = string>(
+  props: SelectProps<T>
+) => React.JSX.Element;
+
+const Select = (<T extends string | number = string>(
+  props: InternalSelectProps<T>
+) => {
+  const {
+    native,
+    nativeHtmlAttributes,
+    filterable,
+    clearable,
+    onValueChange,
+    ref,
+    ...rest
+  } = props;
+
+  if (native) {
+    if (filterable) {
+      console.warn('filterable is not supported on native Select; ignoring.');
+    }
+    if (clearable) {
+      console.warn('clearable is not supported on native Select; ignoring.');
+    }
+    const { value, ...nativeRest } = rest;
+    const {
+      value: nativeAttrValue,
+      onChange,
+      ...nativeAttrs
+    } = nativeHtmlAttributes || {};
+    const nativeValue: string | number | undefined =
+      typeof value === 'string' || typeof value === 'number'
+        ? value
+        : undefined;
     return (
       <NativeSelect
+        value={nativeValue ?? (nativeAttrValue as string | number | undefined)}
         onChange={onChange}
-        value={value || ''}
-        {...rest}
-      />
-    );
-  } else {
-    const { onValueChange, ...rest } = props;
-    return (
-      <CustomSelect<T>
-        onValueChange={onValueChange}
-        {...rest}
+        ref={ref as React.Ref<HTMLSelectElement>}
+        {...nativeRest}
+        {...nativeAttrs}
       />
     );
   }
-};
+
+  return (
+    <CustomSelect<T>
+      onValueChange={onValueChange}
+      filterable={filterable}
+      clearable={clearable}
+      ref={ref as React.Ref<HTMLDivElement>}
+      {...rest}
+    />
+  );
+}) as SelectComponent;
 
 export default Select;

package/lib/components/Select/Select.types.ts

@@ -24,9 +24,29 @@ export type OptionData<T> = {
 };
 
 /**
- * Top level props that <Select> accepts when implemented
+ * Additional props forwarded to the filter input when `filterable` is true
  */
-interface BaseSelectProps<T = string> {
+export type FilterInputProps = Omit<
+  React.InputHTMLAttributes<HTMLInputElement>,
+  | 'value'
+  | 'onChange'
+  | 'disabled'
+  | 'ref'
+  | 'role'
+  | 'aria-autocomplete'
+  | 'aria-label'
+>;
+
+type SelectBaseProps<T = string | number> = Omit<
+  React.HTMLAttributes<HTMLElement>,
+  'onChange'
+> & {
+  /**
+   * Controls keyboard selection behaviour in the custom select variant.
+   * - `focus` (default): arrow keys move focus and commit value immediately.
+   * - `commit`: arrow keys only move focus; Enter or click commits value.
+   */
+  selectionBehaviour?: 'focus' | 'commit';
   /**
    * An array of option data, to be rendered either natively or custom
    */
@@ -51,62 +71,97 @@ interface BaseSelectProps<T = string> {
    * Native flag determines which implementation to use
    */
   native?: boolean;
-}
-
-// export type SelectProps = BaseSelectProps &
-//   // Discriminated union to determine which implementation to use
-//   (| ({ native: true; ref?: React.RefObject<HTMLSelectElement | null> } & Omit<
-//         React.SelectHTMLAttributes<HTMLSelectElement>,
-//         keyof BaseSelectProps
-//       >)
-//     | ({ native?: false; ref?: React.RefObject<HTMLDivElement | null> } & Omit<
-//         React.HTMLAttributes<HTMLDivElement>,
-//         keyof BaseSelectProps
-//       >)
-//   );
-
-// Props interface for the two variants are separated.
-// We expose SelectProps for developers to use, and handle discrepancies internally.
+  /**
+   * Adds a text input to filter options in the custom variant; ignored for native
+   */
+  filterable?: boolean;
+  /**
+   * Extra props to apply to the filter input when `filterable` is true
+   */
+  filterInputProps?: FilterInputProps;
+  /**
+   * Extra attributes forwarded to the native <select> when `native` is true
+   */
+  nativeHtmlAttributes?: React.SelectHTMLAttributes<HTMLSelectElement>;
+  /**
+   * Disable interaction
+   */
+  disabled?: boolean;
+  /**
+   * Allow long option labels to wrap instead of truncating
+   */
+  lineBreak?: boolean;
+  /**
+   * Custom className for the root element
+   */
+  className?: string;
+  /**
+   * Custom className for the options panel
+   */
+  panelClassName?: string;
+  /**
+   * Ref forwarded to the rendered element
+   * (div for custom, select for native)
+   */
+  ref?: React.Ref<HTMLDivElement | HTMLSelectElement | null>;
+};
 
-/**
- * Internal props for the custom implementation, with <div> as root element
- * onChange already exists on <div>. We override it.
- */
-export type CustomSelectProps<T> = Omit<
-  React.HTMLAttributes<HTMLDivElement>,
-  'onChange'
-> &
-  BaseSelectProps<T> & {
-    native?: false;
+export type NonClearableSelectProps<T = string | number> =
+  SelectBaseProps<T> & {
+    /**
+     * Current value (controlled)
+     */
     value?: T;
-    disabled?: boolean;
-    lineBreak?: boolean;
-    panelClassName?: string;
-    onValueChange?: (value: T, ev: React.UIEvent) => void;
-    ref?: React.RefObject<HTMLDivElement | null>;
+    /**
+     * Show a clear action in the custom variant when a value is selected
+     */
+    clearable?: false | undefined;
+    /**
+     * Change handler for the custom variant
+     */
+    onValueChange?: (value: T, ev: React.SyntheticEvent) => void;
   };
 
+export type ClearableSelectProps<T = string | number> = SelectBaseProps<T> & {
+  /**
+   * Current value (controlled)
+   */
+  value?: T | null;
+  /**
+   * Show a clear action in the custom variant when a value is selected
+   */
+  clearable: true;
+  /**
+   * Change handler for the custom variant
+   */
+  onValueChange?: (value: T | null, ev: React.SyntheticEvent) => void;
+};
+
 /**
- * Internal props for native implementation, with <select> as root element
- * Default props like value and onChange are passed to the <select> element automatically
+ * Public props for <Select>, used by both custom and native render paths.
  */
-export type NativeSelectProps = React.SelectHTMLAttributes<HTMLSelectElement> &
-  BaseSelectProps & {
-    native: true;
-    ref?: React.RefObject<HTMLSelectElement | null>;
-  };
+export type SelectProps<T = string | number> =
+  | NonClearableSelectProps<T>
+  | ClearableSelectProps<T>;
 
-export type SelectProps<T> = NativeSelectProps | CustomSelectProps<T>;
+export type InternalSelectProps<T = string | number> = SelectBaseProps<T> & {
+  value?: T | null;
+  clearable?: boolean;
+  onValueChange?: (value: T | null, ev: React.SyntheticEvent) => void;
+};
 
 /**
  * Each option as displayed in the Panel of <CustomSelect>
  * Roughly equivalent to a custom version of <option>
  */
-export interface CustomOptionProps<T>
-  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onSelect'> {
+export interface CustomOptionProps<T> extends Omit<
+  React.HTMLAttributes<HTMLDivElement>,
+  'onSelect'
+> {
   value: T;
+  optionIndex?: number;
   testId?: string;
   isSelected?: boolean;
-  onSelect: (event: React.MouseEvent, value: T) => void;
+  onSelect: (event: React.MouseEvent, value: T, optionIndex?: number) => void;
   lineBreak?: boolean;
 }