uikit-react-public 0.11.13

package/lib/components/Button/Button.stories.tsx

@@ -0,0 +1,420 @@
+import type { Meta, StoryObj } from '@storybook/react';
+import { useArgs } from '@storybook/preview-api';
+import Button from './Button';
+import Icon from '../Icon';
+import { theme } from '../../theme';
+
+// Common margin props documentation currently lives here.
+const marginKeys = Object.keys(theme.margin) as Array<
+  keyof typeof theme.margin
+>;
+const marginKeysAsString = marginKeys
+  .map((key) => `'${key.replace('m', '')}'`)
+  .join(', ');
+const commonMarginPropsInfo = {
+  table: {
+    type: {
+      summary: 'string',
+      detail: marginKeysAsString,
+    },
+    defaultValue: { summary: 'undefined' },
+    // Disabled for most <Button> stories by default
+    disable: true,
+  },
+};
+
+const meta = {
+  title: 'Components/Ready to use/Button',
+  component: Button,
+  parameters: {
+    layout: 'centered',
+  },
+  argTypes: {
+    variant: {
+      options: ['primary', 'secondary', 'tertiary'],
+      control: { type: 'select' },
+      type: 'string',
+    },
+    size: {
+      options: ['small', 'default', 'large'],
+      control: { type: 'select' },
+      type: 'string',
+    },
+    as: {
+      options: ['button', 'a'],
+      control: { type: 'select' },
+      type: 'string',
+      table: {
+        type: {
+          summary: 'string | React.ElementType',
+          detail: "'button' | 'a' | React.ComponentType",
+        },
+      },
+    },
+    destructive: {
+      control: { type: 'boolean' },
+      type: 'boolean',
+    },
+    disabled: {
+      control: { type: 'boolean' },
+      type: 'boolean',
+    },
+    iconPosition: {
+      control: { type: 'select' },
+      options: ['left', 'right'],
+      type: 'string',
+      table: {
+        type: { summary: 'string', detail: "'left' | 'right'" },
+      },
+    },
+    children: {
+      control: { type: 'text' },
+      type: 'string',
+    },
+    tooltip: {
+      control: { type: 'text' },
+      table: { type: { summary: 'string' } },
+    },
+    loading: {
+      control: { type: 'boolean' },
+      type: 'boolean',
+    },
+    fullWidth: {
+      control: { type: 'boolean' },
+      type: 'boolean',
+    },
+    href: {
+      control: { type: 'text' },
+      type: 'string',
+    },
+    target: {
+      control: { type: 'text' },
+      type: 'string',
+    },
+    testId: {
+      control: { type: 'text' },
+      type: 'string',
+    },
+    className: {
+      control: { type: 'text' },
+      type: 'string',
+    },
+    // Common margin props specified here for 'Common Props' documentation
+    m: commonMarginPropsInfo,
+    mv: commonMarginPropsInfo,
+    mh: commonMarginPropsInfo,
+    mt: commonMarginPropsInfo,
+    mb: commonMarginPropsInfo,
+    ml: commonMarginPropsInfo,
+    mr: commonMarginPropsInfo,
+    noMargins: {
+      control: { type: 'boolean' },
+      type: 'boolean',
+      default: false,
+      table: {
+        type: { summary: 'boolean' },
+        defaultValue: { summary: 'false' },
+        disable: true,
+      },
+    },
+  },
+  args: {
+    children: 'Button',
+  },
+  tags: ['autodocs'],
+} satisfies Meta<typeof Button>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {
+  args: {
+    children: 'Default button',
+  },
+};
+
+export const Primary: Story = {
+  args: {
+    variant: 'primary',
+    children: 'Primary button',
+  },
+};
+
+export const Secondary: Story = {
+  args: {
+    variant: 'secondary',
+    children: 'Secondary button',
+  },
+};
+
+export const Tertiary: Story = {
+  args: {
+    variant: 'tertiary',
+    children: 'Tertiary button',
+  },
+};
+
+export const Destructive: Story = {
+  name: 'Destructive primary',
+  args: {
+    destructive: true,
+    children: 'Destructive button',
+  },
+};
+
+export const DestructiveSecondary: Story = {
+  name: 'Destructive secondary',
+  args: {
+    variant: 'secondary',
+    destructive: true,
+    children: 'Destructive secondary button',
+  },
+};
+
+export const Small: Story = {
+  name: 'Small primary',
+  args: {
+    size: 'small',
+    children: 'Small button',
+  },
+};
+
+export const Large: Story = {
+  name: 'Large primary',
+  args: {
+    size: 'large',
+    children: 'Large button',
+  },
+};
+
+export const SmallSecondary: Story = {
+  name: 'Small secondary',
+  args: {
+    size: 'small',
+    variant: 'secondary',
+    children: 'Small secondary button',
+  },
+};
+
+export const LargeSecondary: Story = {
+  name: 'Large secondary',
+  args: {
+    size: 'large',
+    variant: 'secondary',
+    children: 'Large secondary button',
+  },
+};
+
+export const Disabled: Story = {
+  name: 'Primary disabled',
+  args: {
+    disabled: true,
+    children: 'Disabled button',
+  },
+};
+
+export const DisabledSecondary: Story = {
+  name: 'Secondary disabled',
+  args: {
+    variant: 'secondary',
+    disabled: true,
+    children: 'Disabled secondary button',
+  },
+};
+
+export const DisabledTertiary: Story = {
+  name: 'Tertiary disabled',
+  args: {
+    variant: 'tertiary',
+    disabled: true,
+    children: 'Disabled tertiary button',
+  },
+};
+
+export const WithIcon: Story & {
+  argTypes: {
+    iconName: {
+      control: { type: 'select' };
+      options: string[];
+    };
+  };
+} = {
+  name: 'With an icon',
+  argTypes: {
+    iconName: {
+      control: { type: 'select' },
+      options: ['none', ...Icon.getIconNames()],
+    },
+  },
+  args: {
+    iconName: Icon.getIconNames()[0],
+    children: 'Button',
+    iconPosition: 'left',
+  },
+  render: () => {
+    const [args] = useArgs();
+
+    const IconComponent =
+      args.IconName !== 'none'
+        ? (Icon[args.iconName as keyof typeof Icon] as React.FC)
+        : null;
+
+    return (
+      <Button
+        {...args}
+        icon={IconComponent ? <IconComponent /> : undefined}
+      />
+    ) as React.ReactElement;
+  },
+};
+
+export const IconOnly: Story & {
+  argTypes: {
+    iconName: {
+      control: { type: 'select' };
+      options: string[];
+    };
+  };
+} = {
+  name: 'Icon only',
+  argTypes: {
+    iconName: {
+      control: { type: 'select' },
+      options: ['none', ...Icon.getIconNames()],
+    },
+  },
+  args: {
+    iconName: Icon.getIconNames()[0],
+    tooltip: 'Tooltip',
+    children: '',
+  },
+  render: () => {
+    const [args] = useArgs();
+
+    const IconComponent =
+      args.IconName !== 'none'
+        ? (Icon[args.iconName as keyof typeof Icon] as React.FC)
+        : null;
+
+    return (
+      <Button
+        {...args}
+        icon={IconComponent ? <IconComponent /> : undefined}
+      />
+    );
+  },
+};
+
+export const Loading: Story = {
+  name: 'Loading',
+  args: {
+    loading: true,
+    children: 'Loading button',
+  },
+};
+
+export const Link: Story = {
+  name: 'As a link',
+  args: {
+    as: 'a',
+    href: 'https://www.ucl.ac.uk/',
+    target: '_blank',
+    children: "Got to UCL's website",
+    disabled: false,
+  },
+};
+
+export const FullWidth: Story = {
+  name: 'Full width',
+  args: {
+    fullWidth: true,
+    children: 'Full width button',
+  },
+  parameters: {
+    layout: 'fullscreen',
+  },
+};
+
+export const CommonMargins: Story = {
+  name: 'With common margins',
+  parameters: { layout: 'fullscreen' },
+  argTypes: {
+    m: {
+      control: { type: 'select' },
+      options: [
+        '0',
+        ...Object.keys(theme.margin).map((key) => key.replace('m', '')),
+      ],
+      table: {
+        disable: false,
+      },
+    },
+    mv: {
+      control: { type: 'select' },
+      options: [
+        '0',
+        ...Object.keys(theme.margin).map((key) => key.replace('m', '')),
+      ],
+      table: {
+        disable: false,
+      },
+    },
+    mh: {
+      control: { type: 'select' },
+      options: [
+        '0',
+        ...Object.keys(theme.margin).map((key) => key.replace('m', '')),
+      ],
+      table: {
+        disable: false,
+      },
+    },
+    mt: {
+      control: { type: 'select' },
+      options: [
+        '0',
+        ...Object.keys(theme.margin).map((key) => key.replace('m', '')),
+      ],
+      table: {
+        disable: false,
+      },
+    },
+    mb: {
+      control: { type: 'select' },
+      options: [
+        '0',
+        ...Object.keys(theme.margin).map((key) => key.replace('m', '')),
+      ],
+      table: {
+        disable: false,
+      },
+    },
+    ml: {
+      control: { type: 'select' },
+      options: [
+        '0',
+        ...Object.keys(theme.margin).map((key) => key.replace('m', '')),
+      ],
+      table: {
+        disable: false,
+      },
+    },
+    mr: {
+      control: { type: 'select' },
+      options: [
+        '0',
+        ...Object.keys(theme.margin).map((key) => key.replace('m', '')),
+      ],
+      table: {
+        disable: false,
+      },
+    },
+    noMargins: {
+      control: { type: 'boolean' },
+      type: 'boolean',
+      table: {
+        disable: false,
+      },
+    },
+  },
+};

package/lib/components/Button/Button.tsx

@@ -0,0 +1,146 @@
+import { useState, useRef, 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 = ({
+  as,
+  variant = 'primary',
+  destructive = false,
+  size = 'default',
+  disabled = false,
+  icon,
+  iconPosition = 'left',
+  tooltip,
+  loading = false,
+  fullWidth = false,
+  testId = NAME,
+  ref,
+  children,
+  className,
+  ...props
+}: ButtonProps) => {
+  if (variant === 'tertiary' && destructive) {
+    console.warn("Button variant 'tertiary' cannot also be 'destructive'.");
+  }
+
+  const internalRef = useRef(null);
+  const effectiveRef = ref || internalRef;
+  const [isHovered, setIsHovered] = useState(false);
+  const [theme] = useTheme();
+
+  const baseStyle = css`
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    gap: ${theme.padding.p8};
+    position: relative;
+    box-sizing: border-box;
+    font-family: ${theme.font.family.primary};
+    font-size: ${theme.font.size.f16};
+    outline: none;
+    text-decoration: none;
+    user-select: none;
+
+    &:focus-visible {
+      box-shadow: ${theme.boxShadow.focus};
+    }
+  `;
+
+  const iconOnlyStyle = css`
+    width: 48px;
+    padding: 0;
+    justify-content: center;
+  `;
+
+  const sizeSmallStyle = css`
+    height: 40px;
+    padding: 0 ${theme.padding.p16};
+  `;
+
+  const sizeDefaultStyle = css`
+    height: 48px;
+    padding: 0 ${theme.padding.p24};
+  `;
+
+  const sizeLargeStyle = css`
+    height: 56px;
+    padding: 0 ${theme.padding.p24};
+    font-size: ${theme.font.size.f18};
+  `;
+
+  const fullWidthStyle = css`
+    width: 100%;
+  `;
+
+  const variantStyle = {
+    primary: buttonPrimaryStyle(theme, destructive, disabled, loading),
+    secondary: buttonSecondaryStyle(theme, destructive, disabled, loading),
+    tertiary: buttonTertiaryStyle(theme, disabled, loading),
+  }[variant];
+
+  const style = cx(
+    NAME,
+    baseStyle,
+    marginsStyle(props, theme),
+    size === 'small' && sizeSmallStyle,
+    size === 'default' && sizeDefaultStyle,
+    size === 'large' && sizeLargeStyle,
+    fullWidth && fullWidthStyle,
+    variantStyle,
+    !children && iconOnlyStyle,
+    className
+  );
+
+  const Component = as || 'button';
+
+  return (
+    <>
+      <Component
+        ref={effectiveRef}
+        disabled={loading || disabled}
+        onMouseEnter={() => setIsHovered(true)}
+        onMouseLeave={() => setIsHovered(false)}
+        className={style}
+        data-testid={testId}
+        aria-disabled={disabled}
+        {...props}
+        href={
+          Component === 'a' && disabled
+            ? undefined
+            : (props as { href?: string }).href
+        }
+      >
+        {loading ? (
+          <Spinner />
+        ) : (
+          <>
+            {icon && iconPosition === 'left' && icon}
+            {children}
+            {icon && iconPosition === 'right' && icon}
+          </>
+        )}
+      </Component>
+      {tooltip && isHovered && (
+        <Overlay
+          reference={effectiveRef}
+          placement='top'
+          shift={false}
+          flip={false}
+          offset={10}
+        >
+          <Tooltip>{tooltip}</Tooltip>
+        </Overlay>
+      )}
+    </>
+  );
+};
+
+export default memo(Button);

package/lib/components/Button/Button.types.ts

@@ -0,0 +1,46 @@
+import {
+  ReactElement,
+  ButtonHTMLAttributes,
+  AnchorHTMLAttributes,
+  ComponentPropsWithRef,
+  ElementType,
+  RefObject,
+} from 'react';
+import { MarginProps } from '../common/marginsStyle';
+
+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;
+  ref?: RefObject<HTMLElement | null>;
+}
+
+export type ButtonAsButtonProps = ButtonBaseProps &
+  ButtonHTMLAttributes<HTMLButtonElement> & {
+    as?: 'button';
+  };
+
+export type ButtonAsAnchorProps = ButtonBaseProps &
+  AnchorHTMLAttributes<HTMLAnchorElement> & {
+    as: 'a';
+  };
+
+export type ButtonAsCustomProps<C extends ElementType> = ButtonBaseProps & {
+  as: C;
+} & Omit<ComponentPropsWithRef<C>, keyof ButtonBaseProps | 'as'>;
+
+export type ButtonProps = (
+  | ButtonAsButtonProps
+  | ButtonAsAnchorProps
+  | ButtonAsCustomProps<ElementType>
+) &
+  MarginProps;
+
+export type Ref = Element;