uikit-react-public 0.11.13 → 0.11.15

package/lib/Welcome.mdx

@@ -1,10 +1,10 @@
-import { Meta } from '@storybook/blocks';
-import UclLogo from './components/UclLogo';
+import { Meta } from "@storybook/blocks";
+import { UclLogo } from "./components/";
 
 <Meta title="Welcome" />
 
 <style>
-{` 
+  {` 
 .logo-container {
   display: flex;
   align-items: flex-end;
@@ -18,13 +18,13 @@ import UclLogo from './components/UclLogo';
 `}
 </style>
 
-<div className='logo-container'>
-  <UclLogo className='ucl-logo' />
+<div className="logo-container">
+  <UclLogo className="ucl-logo" />
 </div>
 
-# UIKit-React 
+# UIKit-React
 
-This component library of React components implements the UCL Design System. 
+This component library of React components implements the UCL Design System.
 
 - [GitHub repo](https://github.com/ucl-isd/uikit-react)
 - [Design System Figma](https://www.figma.com/design/8Sm5PxWOWJYpYXAzhRzUzt/UCL-Design-System-UI-Kit)

package/lib/components/Button/Button.tsx

@@ -1,16 +1,43 @@
-import { useState, useRef, memo } from 'react';
+import {
+  useState,
+  useRef,
+  ReactElement,
+  ElementType,
+  ComponentPropsWithRef,
+  memo,
+} from 'react';
 import { css, cx } from '@emotion/css';
 import useTheme from '../../theme/useTheme';
 import buttonPrimaryStyle from './buttonPrimaryStyle';
 import buttonSecondaryStyle from './buttonSecondaryStyle';
 import buttonTertiaryStyle from './buttonTertiaryStyle';
-import { ButtonProps } from './Button.types';
 import { Spinner, Overlay, Tooltip } from '../';
 import marginsStyle from '../common/marginsStyle';
 
 export const NAME = 'ucl-uikit-button';
 
-const Button = ({
+type PolymorphicRef<C extends ElementType> = ComponentPropsWithRef<C>['ref'];
+
+export interface ButtonBaseProps {
+  variant?: 'primary' | 'secondary' | 'tertiary';
+  destructive?: boolean;
+  size?: 'large' | 'default' | 'small';
+  disabled?: boolean;
+  icon?: ReactElement;
+  iconPosition?: 'left' | 'right';
+  tooltip?: string;
+  loading?: boolean;
+  fullWidth?: boolean;
+  testId?: string;
+}
+
+export type ButtonProps<C extends ElementType = 'button'> = {
+  as?: C;
+  ref?: PolymorphicRef<C>;
+} & ButtonBaseProps &
+  Omit<ComponentPropsWithRef<C>, keyof ButtonBaseProps | 'as'>;
+
+const Button = <C extends ElementType = 'button'>({
   as,
   variant = 'primary',
   destructive = false,
@@ -26,7 +53,9 @@ const Button = ({
   children,
   className,
   ...props
-}: ButtonProps) => {
+}: ButtonProps<C>) => {
+  const Component = as || 'button';
+
   if (variant === 'tertiary' && destructive) {
     console.warn("Button variant 'tertiary' cannot also be 'destructive'.");
   }
@@ -99,8 +128,6 @@ const Button = ({
     className
   );
 
-  const Component = as || 'button';
-
   return (
     <>
       <Component
@@ -143,4 +170,6 @@ const Button = ({
   );
 };
 
-export default memo(Button);
+const MemoizedButton = memo(Button) as typeof Button;
+
+export default MemoizedButton;

package/lib/components/Button/buttonPrimaryStyle.ts

@@ -1,12 +1,12 @@
 import { css, cx } from '@emotion/css';
 import { ThemeType } from '../../theme';
-import { ButtonProps } from './Button.types';
+import { ButtonBaseProps } from './Button';
 
 const buttonPrimaryStyle = (
   theme: ThemeType,
-  destructive: ButtonProps['destructive'],
-  disabled: ButtonProps['disabled'],
-  loading: ButtonProps['loading']
+  destructive: ButtonBaseProps['destructive'],
+  disabled: ButtonBaseProps['disabled'],
+  loading: ButtonBaseProps['loading']
 ) => {
   const {
     color: { system, interaction },

package/lib/components/Button/buttonSecondaryStyle.ts

@@ -1,12 +1,12 @@
 import { css, cx } from '@emotion/css';
 import { ThemeType } from '../../theme';
-import { ButtonProps } from './Button.types';
+import { ButtonBaseProps } from './Button';
 
 const buttonSecondaryStyle = (
   theme: ThemeType,
-  destructive: ButtonProps['destructive'],
-  disabled: ButtonProps['disabled'],
-  loading: ButtonProps['loading']
+  destructive: ButtonBaseProps['destructive'],
+  disabled: ButtonBaseProps['disabled'],
+  loading: ButtonBaseProps['loading']
 ) => {
   const {
     color: { system, interaction },

package/lib/components/Button/buttonTertiaryStyle.ts

@@ -1,11 +1,11 @@
 import { css, cx } from '@emotion/css';
 import { ThemeType } from '../../theme';
-import { ButtonProps } from './Button.types';
+import { ButtonBaseProps } from './Button';
 
 const buttonTertiaryStyle = (
   theme: ThemeType,
-  disabled: ButtonProps['disabled'],
-  loading: ButtonProps['loading']
+  disabled: ButtonBaseProps['disabled'],
+  loading: ButtonBaseProps['loading']
 ) => {
   const {
     color: { interaction },

package/lib/components/Button/index.ts

@@ -1,2 +1,2 @@
 export { default } from './Button';
-export type { ButtonProps } from './Button.types';
+export type { ButtonProps, ButtonBaseProps } from './Button';

package/lib/components/Icon/svgs/AvatarSvg.tsx

@@ -13,8 +13,8 @@ const AvatarSvg = ({ ...props }) => {
     >
       {title && <title>{title}</title>}
       <path
-        fill-rule='evenodd'
-        clip-rule='evenodd'
+        fillRule='evenodd'
+        clipRule='evenodd'
         d='M4 20.9995C4.49232 17.0534 7.8586 14 11.938 14C16.0175 14 19.5077 17.0539 20 21C18 23 15 24 12 24C9 24 6 23 4 20.9995Z'
       />
       <circle

package/lib/components/Icon/svgs/ChevronDownSvg.tsx

@@ -22,11 +22,8 @@ const ChevronDownSvg = ({ ...props }) => {
 
 export default memo(ChevronDownSvg);
 
-// Used by Select
+// Used by <Select>
 const DATA_URI =
   'data:image/svg+xml,%3Csvg%20xmlns%3D%22http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg%22%20viewBox%3D%220%200%2024%2024%22%20fill%3D%22none%22%20stroke%3D%22{{COLOUR}}%22%20stroke-width%3D%222%22%20stroke-linecap%3D%22round%22%20stroke-linejoin%3D%22round%22%20width%3D%2224%22%20height%3D%2224%22%20class%3D%22ucl-icon%20css-4bxmzw%22%3E%3Cpolyline%20points%3D%226%209%2012%2015%2018%209%22%3E%3C%2Fpolyline%3E%3C%2Fsvg%3E';
 export const dataUri = (colour: string) =>
-  DATA_URI.replace(
-    '{{COLOUR}}',
-    encodeURIComponent(colour)
-  );
+  DATA_URI.replace('{{COLOUR}}', encodeURIComponent(colour));

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

@@ -1,27 +1,206 @@
 import type { Meta, StoryObj } from '@storybook/react';
-
+import { useArgs } from '@storybook/preview-api';
 import Select from './Select';
+import { Icon } from '../';
+import { SelectEvent } from './Select.types';
 
 const meta = {
-  title: 'Components/Work in progress/Select',
+  title: 'Components/Ready to use/Select',
   component: Select,
+  argTypes: {
+    value: { control: { type: 'text' } },
+    native: {
+      control: { type: 'boolean' },
+    },
+    disabled: {
+      control: { type: 'boolean' },
+    },
+    placeholder: {
+      control: { type: 'text' },
+    },
+    testId: {
+      control: { type: 'text' },
+    },
+    width: {
+      control: { type: 'range', min: 80, max: 624, step: 1 },
+    },
+  },
+  args: {
+    value: undefined,
+    onChange: () => {},
+    options: [
+      { text: 'Option one', value: '1' },
+      { text: 'Option two', value: '2' },
+      { text: 'Option three', value: '3' },
+    ],
+  },
 } satisfies Meta<typeof Select>;
 
 export default meta;
-
 type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {
-  render: () => (
-    <Select>
-      <option value='1'>Option 1</option>
-      <option value='2'>Option 2</option>
-      <option value='3'>Option 3</option>
-    </Select>
-  ),
+  render: () => {
+    const [args, updateArgs] = useArgs();
+    const onChange = (_event: SelectEvent, value: string) => {
+      updateArgs({ value });
+    };
+    return (
+      <Select
+        {...args}
+        options={args.options}
+        value={args.value}
+        onChange={onChange}
+      />
+    );
+  },
+};
+
+export const Native: Story = {
+  args: {
+    native: true,
+  },
+  render: () => {
+    const [args, updateArgs] = useArgs();
+    const onChange = (_event: SelectEvent, value: string) => {
+      updateArgs({ value });
+    };
+    return (
+      <Select
+        {...args}
+        options={args.options}
+        value={args.value}
+        onChange={onChange}
+      />
+    );
+  },
+};
+
+export const OptionsWithIcons: Story = {
+  name: 'Options with icons',
+  args: {
+    options: [
+      { text: 'Option 1', value: '1', icon: <Icon.Printer /> },
+      { text: 'Option 2', value: '2', icon: <Icon.User /> },
+      { text: 'Option 3', value: '3', icon: <Icon.Info /> },
+    ],
+  },
+  render: () => {
+    const [args, updateArgs] = useArgs();
+    const onChange = (_event: SelectEvent, value: string) => {
+      updateArgs({ value });
+    };
+
+    return (
+      <Select
+        {...args}
+        options={args.options}
+        value={args.value}
+        onChange={onChange}
+      />
+    );
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    disabled: true,
+  },
+  render: () => {
+    const [args, updateArgs] = useArgs();
+    const onChange = (_event: SelectEvent, value: string) => {
+      updateArgs({ value });
+    };
+
+    return (
+      <Select
+        {...args}
+        options={args.options}
+        value={args.value}
+        onChange={onChange}
+      />
+    );
+  },
+};
+
+export const WithPlaceholder: Story = {
+  args: { placeholder: 'Please select an option' },
+  render: () => {
+    const [args, updateArgs] = useArgs();
+    const onChange = (_event: SelectEvent, value: string) => {
+      updateArgs({ value });
+    };
+
+    return (
+      <Select
+        {...args}
+        options={args.options}
+        value={args.value}
+        onChange={onChange}
+      />
+    );
+  },
+};
+
+export const SingleLongOption: Story = {
+  name: 'Long option',
+  args: {
+    options: [
+      { text: 'Option 1', value: '1' },
+      { text: 'Option 2', value: '2' },
+      { text: 'Option 3 long long long long ', value: '3' },
+    ],
+  },
+  render: () => {
+    const [args, updateArgs] = useArgs();
+    const onChange = (_event: SelectEvent, value: string) => {
+      updateArgs({ value });
+    };
+
+    return (
+      <Select
+        {...args}
+        options={args.options}
+        value={args.value}
+        onChange={onChange}
+      />
+    );
+  },
 };
 
-export const NoOptions: Story = {
-  name: 'No options',
-  render: () => <Select />,
+export const ManyOptions: Story = {
+  name: 'Many options',
+  args: {
+    options: [
+      { text: 'Option one', value: '1' },
+      { text: 'Option two', value: '2' },
+      { text: 'Option three', value: '3' },
+      { text: 'Option four', value: '4' },
+      { text: 'Option five', value: '5' },
+      { text: 'Option six', value: '6' },
+      { text: 'Option seven', value: '7' },
+      { text: 'Option eight', value: '8' },
+      { text: 'Option nine', value: '9' },
+      { text: 'Option ten', value: '10' },
+      { text: 'Option eleven', value: '11' },
+      { text: 'Option twelve', value: '12' },
+      { text: 'Option thirteen', value: '13' },
+      { text: 'Option fourteen', value: '14' },
+      { text: 'Option fifteen', value: '15' },
+    ],
+  },
+  render: () => {
+    const [args, updateArgs] = useArgs();
+    const onChange = (_event: SelectEvent, value: string) => {
+      updateArgs({ value });
+    };
+    return (
+      <Select
+        {...args}
+        options={args.options}
+        value={args.value}
+        onChange={onChange}
+      />
+    );
+  },
 };

package/lib/components/Select/Select.tsx

@@ -1,82 +1,39 @@
-import {
-  memo,
-  SelectHTMLAttributes,
-  forwardRef,
-} from 'react';
-import { css, cx } from '@emotion/css';
-import { useTheme } from '../..';
-import { dataUri as chevronDownSvgDataUri } from '../Icon/svgs/ChevronDownSvg';
-
-export const NAME = 'ucl-uikit-select';
-
-export interface SelectProps
-  extends SelectHTMLAttributes<HTMLSelectElement> {
-  testId?: string;
-}
-
-export type Ref = HTMLSelectElement;
-
-const Select = forwardRef<Ref, SelectProps>(
-  ({ testId = NAME, className, ...props }, ref) => {
-    const [theme] = useTheme();
-
-    const baseStyle = css`
-      height: ${theme.padding.p48};
-      line-height: ${theme.padding.p48};
-      font-family: ${theme.font.family.primary};
-      padding: 0 ${theme.padding.p40} 0 ${theme.padding.p16};
-      background-color: ${theme.color.neutral.white};
-      border: ${theme.border.b1} solid
-        ${theme.color.neutral.grey40};
-      appearance: none;
-      -webkit-appearance: none;
-      -moz-appearance: none;
-      outline: none;
-      cursor: pointer;
-
-      background-image: url(${chevronDownSvgDataUri(
-        theme.color.interaction.blue70
-      )});
-      background-size: 24px 24px;
-      background-position: right 8px center;
-      background-repeat: no-repeat;
-    `;
-
-    const hoverStyle = css`
-      &:hover {
-        border-color: ${theme.color.neutral.grey60};
-        background-color: ${theme.color.neutral.grey5};
-      }
-    `;
-
-    const focusStyle = css`
-      &:focus {
-        box-shadow: ${theme.boxShadow.focus};
-      }
-    `;
-
-    const disabledStyle = css`
-      cursor: not-allowed;
-    `;
-
-    const style = cx(
-      NAME,
-      baseStyle,
-      !props.disabled && hoverStyle,
-      !props.disabled && focusStyle,
-      props.disabled && disabledStyle,
-      className
+import { NativeSelect, CustomSelect } from './subcomponents';
+import { SelectProps } from './Select.types';
+
+const Select = (props: SelectProps) => {
+  if (props.native) {
+    // We can throw away `native` prop before passing to internal components
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { onChange, value, native, ...rest } = props;
+    const handleNativeChange = (
+      event: React.ChangeEvent<HTMLSelectElement>
+    ) => {
+      if (onChange) onChange(event, event.target.value);
+    };
+    return (
+      <NativeSelect
+        onChange={handleNativeChange}
+        value={value || ''}
+        {...rest}
+      />
     );
-
+  } else {
+    // eslint-disable-next-line @typescript-eslint/no-unused-vars
+    const { onChange, native, ...rest } = props;
+    const handleCustomChange = (
+      event: React.MouseEvent | React.KeyboardEvent,
+      value: string
+    ) => {
+      if (onChange) onChange(event, value);
+    };
     return (
-      <select
-        ref={ref}
-        className={style}
-        data-testid={testId}
-        {...props}
+      <CustomSelect
+        onChange={handleCustomChange}
+        {...rest}
       />
     );
   }
-);
+};
 
-export default memo(Select);
+export default Select;

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

@@ -0,0 +1,146 @@
+/**
+ * Represents an 'option' in the <Select>
+ * Maps to a native <option> element in <NativeSelect>
+ * or a <CustomOption> in <CustomSelect>
+ */
+export type OptionData = {
+  /**
+   * Display text shown to the user
+   */
+  text: string;
+  /**
+   * Data-friendly value that is returned when the option is selected
+   * We assume this will be submitted to a server or used in some other way
+   */
+  value: string;
+  /**
+   * Optional icon to be displayed to the left of the option text.
+   * Only used by <CustomOption>
+   * Takes in an actual <Icon> component
+   */
+  icon?: React.ReactNode;
+};
+
+/**
+ * Utility type we expose to developers
+ * We expect this to be used in typing event handlers
+ * This only applies to the top-level <Select> component
+ */
+export type SelectEvent =
+  | React.ChangeEvent<HTMLSelectElement>
+  | React.MouseEvent
+  | React.KeyboardEvent;
+
+/**
+ * Top level props that <Select> accepts when implemented
+ */
+interface BaseSelectProps {
+  /**
+   * An array of option data, to be rendered either natively or custom
+   */
+  options: OptionData[];
+  /**
+   * The currently selected value
+   * This determines which option is shown when the select is closed
+   */
+  value: string | undefined | null;
+  /**
+   * Generic onChange that splits into native and custom versions
+   * The original event is exposed, and the value always returns the value of the selected option
+   */
+  onChange: (event: SelectEvent, value: string) => void;
+  /**
+   * Prevents use, including focus events
+   */
+  disabled?: boolean | undefined;
+  /**
+   * Placeholder text shown when no option is selected
+   * Displayed in visible field of custom implementation
+   * or as a disabled option in the native implementation
+   */
+  placeholder?: string;
+  /**
+   * Specify a specific width if the default (325px) is not suitable
+   */
+  width?: number;
+  /**
+   * Test ID for testing purposes
+   * This is passed to the root element of the component
+   * as `data-testid`
+   */
+  testId?: string;
+  /**
+   * Optional className for styling
+   * This is passed to the root element of the component
+   * for additional CSS styling via Emotion.
+   */
+  className?: string;
+  /**
+   * Native flag determines which implementation to use
+   */
+  native?: boolean;
+  // `ref` prop added in the discriminated union below
+}
+
+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.
+
+/**
+ * Internal props for the custom implementation, with <div> as root element
+ * onChange already exists on <div>. We override it.
+ */
+export interface CustomSelectProps
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'> {
+  options: OptionData[];
+  value: string | undefined | null;
+  onChange: (
+    // Stripping out the native <select> event signature
+    event: React.MouseEvent | React.KeyboardEvent,
+    // Value returned by <CustomOption>: we validate there
+    value: string
+  ) => void;
+  disabled?: boolean;
+  placeholder?: string;
+  width?: number;
+  testId?: string;
+  className?: string;
+  ref?: React.RefObject<HTMLDivElement | null>;
+}
+
+/**
+ * Internal props for native implementation, with <select> as root element
+ * Default props like value and onChange are passed to the <select> element automatically
+ */
+export interface NativeSelectProps
+  extends React.SelectHTMLAttributes<HTMLSelectElement> {
+  options: OptionData[];
+  placeholder?: string;
+  width?: number;
+  testId?: string;
+  className?: string;
+  ref?: React.RefObject<HTMLSelectElement | null>;
+}
+
+/**
+ * Each option as displayed in the Panel of <CustomSelect>
+ * Roughly equivalent to a custom version of <option>
+ */
+export interface CustomOptionProps
+  extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onSelect'> {
+  value: string;
+  testId?: string;
+  isSelected?: boolean;
+  onSelect: (event: React.MouseEvent, value: string) => void;
+}