uikit-react-public 0.11.13

package/lib/components/common/Common.mdx

@@ -0,0 +1,82 @@
+import { Meta, Title, Subtitle, Canvas, Controls, ArgTypes } from '@storybook/blocks';
+import marginsStyle from './marginsStyle';
+import { CommonMargins } from './../Button/Button.stories';
+import { theme } from '../../theme';
+
+<Meta title="components/Common Props" />
+<Title>Common Props</Title>
+<Subtitle>Props shared across multiple components</Subtitle>
+
+## Contents 
+
+- [className](#classname)
+- [Margin props](#margin-props)
+
+## `className`
+
+We use <a href='https://emotion.sh/' target='_blank'>Emotion</a> for styling components in UIKit-React. Emotion is a <a href='https://en.wikipedia.org/wiki/CSS-in-JS' target='_blank'>CSS-in-JS</a> library: styles are written internally within the component `.tsx` file(s), and applied by React at runtime, rather than referenced in separate `.css` files.
+
+We expose a `className` prop on all components to allow you to override and extend default styles. This is useful for applying custom styles or overriding existing ones. 
+
+```tsx
+const additionalStyle = css`
+  background-color: yellow;
+`;
+
+// ...
+
+<Button className={additionalStyle}>Yellow Button</Button>
+```
+
+*Consideration:* Components in UIKit-React are styled according to the UCL Design System. A lot of thought has been put into the visual appearance and interactive behaviour of these components. Passing additional styles via `className` should be considered a fallback for edge cases. 
+
+## Margin props
+
+Many components in UIKit-React make use of common margin props. These set the <a href='https://developer.mozilla.org/en-US/docs/Web/CSS/margin' target='_blank'>`margin` CSS property</a> on the component, according to spacing values consistent with the UCL Design System.
+
+This is intended as a helpful internal API for developers to align and space components quickly while building out screens.  
+
+Using these props is optional — without them, you *could* still use a `className` prop to feed in additional styles to a given component.  
+
+Accepted prop values are: 
+{Object.entries(theme.margin).map(([key]) => (
+    <code>'{key.replace('m', '')}'</code>
+))}
+
+These prop values map to the equivalent pixel values: 
+{Object.entries(theme.margin).map(([key, value]) => (
+    <code>{key.replace('m', '')}px</code>
+))}
+
+The equivalent CSS propery for each prop is:
+
+- `m` = `margin`
+- `mv` = `margin-top` and `margin-bottom`
+- `mh` = `margin-left` and `margin-right`
+- `mt` = `margin-top`
+- `mb` = `margin-bottom`
+- `ml` = `margin-left`
+- `mr` = `margin-right`
+- `noMargins` = `margin: 0`
+
+`mh` is short for 'margin horizontal' and `mv` is short for 'margin vertical'.
+
+For example: 
+
+```tsx
+<Button m='2'>Button with 2px margin</Button>
+<Button mt='4'>Button with 4px margin-top</Button>
+<Button mh='8'>Button with 8px margin-left & margin-right</Button>
+```
+
+The available margin props are:
+
+<ArgTypes 
+  of={CommonMargins} 
+  include={['m', 'm', 'mv', 'mh', 'mt', 'mb', 'ml', 'mr', 'noMargins']} 
+/>
+
+[A live example of common margin props can be found in this `<Button>` story.](?path=/story/components-ready-to-use-button--common-margins)
+
+Implementation details can be found in <a href='https://github.com/ucl-isd/uikit-react/blob/main/lib/components/common/marginsStyle.ts' target='_blank'>uikit-react/components/common/MarginsStyle.tsx</a>
+

package/lib/components/common/marginsStyle.ts

@@ -0,0 +1,103 @@
+import { css, cx } from '@emotion/css';
+import { ThemeType } from '../../theme';
+
+type MarginType = ThemeType['margin'];
+
+type ExtractMarginValue<T> = T extends `m${infer N}` ? N : never;
+
+type MarginValueType = ExtractMarginValue<keyof MarginType>;
+
+export interface MarginProps {
+  /**
+   * Margin value for all sides
+   * @default undefined
+   */
+  m?: MarginValueType;
+
+  /**
+   * Margin value for vertical sides (top and bottom)
+   * @default undefined
+   */
+  mv?: MarginValueType;
+
+  /**
+   * Margin value for horizontal sides (left and right)
+   * @default undefined
+   */
+  mh?: MarginValueType;
+
+  /**
+   * Margin value for top side
+   * @default undefined
+   */
+  mt?: MarginValueType;
+
+  /**
+   * Margin value for bottom side
+   * @default undefined
+   */
+  mb?: MarginValueType;
+
+  /**
+   * Margin value for left side
+   * @default undefined
+   */
+  ml?: MarginValueType;
+
+  /**
+   * Margin value for right side
+   * @default undefined
+   */
+  mr?: MarginValueType;
+
+  /**
+   * If true, no margins will be applied
+   * @default false
+   */
+  noMargins?: boolean;
+}
+
+const marginsStyle = (marginProps: MarginProps, theme: ThemeType) => {
+  const { m, mv, mh, mt, mb, ml, mr, noMargins } = marginProps;
+
+  if (noMargins) {
+    return css`
+      margin: 0;
+    `;
+  } else {
+    return cx(
+      m &&
+        css`
+          margin: ${theme.margin[`m${m}`]};
+        `,
+      mv &&
+        css`
+          margin-top: ${theme.margin[`m${mv}`]};
+          margin-bottom: ${theme.margin[`m${mv}`]};
+        `,
+      mh &&
+        css`
+          margin-left: ${theme.margin[`m${mh}`]};
+          margin-right: ${theme.margin[`m${mh}`]};
+        `,
+      mt &&
+        css`
+          margin-top: ${theme.margin[`m${mt}`]};
+        `,
+      mb &&
+        css`
+          margin-bottom: ${theme.margin[`m${mb}`]};
+        `,
+      ml &&
+        css`
+          margin-left: ${theme.margin[`m${ml}`]};
+        `,
+      mr &&
+        css`
+          margin-right: ${theme.margin[`m${mr}`]};
+        `
+    );
+  }
+};
+
+export default marginsStyle;

package/lib/components/index.ts

@@ -0,0 +1,132 @@
+export { default as Icon } from './Icon';
+export type { IconProps } from './Icon';
+
+export { default as Input } from './Input';
+export type { InputProps } from './Input';
+
+export { default as Link } from './Link';
+export type { LinkProps } from './Link';
+
+export { default as Button } from './Button';
+export type { ButtonProps } from './Button';
+
+export { default as Label } from './Label';
+export type { LabelProps } from './Label';
+
+export { default as IconButton } from './IconButton';
+export type { IconButtonProps } from './IconButton';
+
+export { default as Blanket } from './Blanket';
+export type { BlanketProps } from './Blanket';
+
+export { default as Overlay } from './Overlay';
+export type { OverlayProps } from './Overlay';
+
+export { default as Snackbar } from './Snackbar';
+export type { SnackbarProps } from './Snackbar';
+
+export { default as Avatar } from './Avatar';
+export type { AvatarProps } from './Avatar';
+
+export { default as Spinner } from './Spinner';
+export type { SpinnerProps } from './Spinner';
+
+export { default as Textarea } from './Textarea';
+export type { TextareaProps } from './Textarea';
+
+export { default as Heading } from './Heading';
+export type { HeadingProps } from './Heading';
+
+export { default as Paragraph } from './Paragraph';
+export type { ParagraphProps } from './Paragraph';
+// TODO: Remove aliased export in future breaking release
+// <Paragraph> will be used in place of <Text> in the future
+export { default as Text } from './Paragraph';
+export type { TextProps } from './Paragraph';
+
+export { default as Modal } from './Modal';
+export type { ModalProps } from './Modal';
+
+export { UclLogo } from './UclLogo';
+export type { UclLogoProps } from './UclLogo';
+
+export { UclLogoNegativeSpace } from './UclLogo';
+export type { UclLogoNegativeSpaceProps } from './UclLogo';
+
+export { default as Tooltip } from './Tooltip';
+export type { TooltipProps } from './Tooltip';
+
+export { default as AppHeader, APP_HEADER_HEIGHT } from './AppHeader';
+export type { AppHeaderProps } from './AppHeader';
+
+export { default as Breadcrumbs } from './Breadcrumbs';
+export type { BreadcrumbsProps } from './Breadcrumbs';
+
+export { default as Checkbox, LabelledCheckbox } from './Checkbox';
+export type { CheckboxProps, LabelledCheckboxProps } from './Checkbox';
+
+export { default as Toggle } from './Toggle';
+export type { ToggleProps } from './Toggle';
+
+export { default as AppMenu } from './AppMenu';
+export type { AppMenuProps } from './AppMenu';
+
+export { default as Menu } from './Menu';
+export type { MenuProps } from './Menu';
+
+export { default as Select } from './Select';
+export type { SelectProps } from './Select';
+
+export { default as Footer } from './Footer';
+export type { FooterProps } from './Footer';
+
+export { default as Divider } from './Divider';
+export type { DividerProps } from './Divider';
+
+export { default as Header } from './Header';
+export type { HeaderProps } from './Header';
+
+export { default as HeaderDraft } from './HeaderDraft';
+export type { HeaderDraftProps } from './HeaderDraft';
+
+export { default as Table } from './Table';
+export type { TableProps } from './Table';
+
+export { default as Alert } from './Alert';
+export type { AlertProps } from './Alert';
+
+export { default as Tabs } from './Tabs';
+export type { TabsProps } from './Tabs';
+export type { TabProps } from './Tabs/Tab';
+
+// todo:
+// export { default as Accordion } from './Accordion';
+// export type { AccordionProps } from './Accordion';
+
+export { default as Field } from './Field';
+export type { FieldProps } from './Field';
+
+export { default as Pagination } from './Pagination';
+export type {
+  PaginationProps,
+  PaginationControlsProps,
+  PaginationInfoProps,
+} from './Pagination';
+
+export { default as Dialog, BaseDialog } from './Dialog';
+export type {
+  DialogProps,
+  DialogHeaderProps,
+  DialogFooterProps,
+  DialogBodyProps,
+  BaseDialogProps,
+} from './Dialog';
+
+export { FeedbackDialog } from './FeedbackDialog';
+export type { FeedbackDialogProps } from './FeedbackDialog';
+
+export { default as Radio, LabelledRadio } from './Radio';
+export type { RadioProps, LabelledRadioProps } from './Radio';
+
+export { default as Datepicker } from './Datepicker';
+export type { DatepickerProps } from './Datepicker';

package/lib/hooks/useMediaQuery.ts

@@ -0,0 +1,25 @@
+import { useState, useEffect } from 'react';
+
+const useMediaQuery = (query: string): boolean => {
+  const [isQueryMatch, setIsQueryMatch] = useState<boolean>(false);
+
+  useEffect(() => {
+    const mediaQueryList = window.matchMedia(query);
+
+    setIsQueryMatch(mediaQueryList.matches);
+
+    const handleChange = (event: MediaQueryListEvent) => {
+      setIsQueryMatch(event.matches);
+    };
+
+    mediaQueryList.addEventListener('change', handleChange);
+
+    return () => {
+      mediaQueryList.removeEventListener('change', handleChange);
+    };
+  }, [query]);
+
+  return isQueryMatch;
+};
+
+export default useMediaQuery;

package/lib/index.ts

@@ -0,0 +1,3 @@
+export { cx, css } from '@emotion/css';
+export * from './components';
+export * from './theme';

package/lib/theme/Colours.mdx

@@ -0,0 +1,44 @@
+import { Meta, Title, Subtitle, ColorPalette, ColorItem } from '@storybook/addon-docs/blocks';
+import theme from './defaultTheme';
+
+<Meta title="Theme/Colours" />
+<Title>Colours explorer</Title>
+<Subtitle>Colours approved for use in the UCL Design System</Subtitle> 
+
+More information on the use of colour in the UCL Design System <a href="https://www.figma.com/design/8Sm5PxWOWJYpYXAzhRzUzt/UCL-Design-System-UI-Kit?node-id=1-287" target="_blank">can be found on Figma</a>. 
+
+The colours populating this page are imported from the <a href="https://github.com/ucl-isd/uikit-react/blob/main/lib/theme/defaultTheme.ts#L5" target="_blank">theme file</a>. 
+
+Below are all colours per category, one category per line: 
+
+<ColorPalette>
+{
+  Object.entries(theme.color).map(([key, value]) => {
+    return (
+      <ColorItem key={key} title={key.charAt(0).toUpperCase() + key.slice(1)} colors={value} />
+    );
+  })
+}
+</ColorPalette>
+
+Below is a breakdown of each colour category. These are the same colours as above, but grouped by category, one colour per line: 
+
+{Object.entries(theme.color).map(([key, value]) => {
+  return (
+    <div key={key}>
+      <h2>{key.charAt(0).toUpperCase() + key.slice(1)}</h2>
+
+      <ColorPalette>
+
+      {Object.entries(value).map(([colorKey, colorValue]) => {
+        return (
+          <ColorItem key={colorKey} title={colorKey} colors={{ [colorKey]: colorValue }} />
+        );
+      })}
+
+      {console.log(key, value)}
+
+      </ColorPalette>
+    </div>
+  );
+})}

package/lib/theme/Icons.mdx

@@ -0,0 +1,30 @@
+import { createElement } from "react";
+import {
+  Meta,
+  Title,
+  Subtitle,
+  IconGallery,
+  IconItem,
+} from "@storybook/blocks";
+import { ThemeContextProvider } from "./useTheme";
+import { Icon } from "../components";
+
+<Meta title="Theme/Icons" />
+<Title>Icons explorer</Title>
+<Subtitle>All icons currently available in the theme</Subtitle>
+
+[Inspect the `<Icon>` component itself](?path=/docs/components-work-in-progress-icon--documentation)
+to see the implementation of these icons in React.
+
+Icons are taken from <a href='https://feathericons.com/' target='_blank'>Feather Icons</a>. 
+<br />
+
+<IconGallery>
+  <ThemeContextProvider>
+    {Icon.getIconNames().map((iconName) => (
+      <IconItem key={iconName} name={iconName}>
+        {createElement(Icon[iconName])}
+      </IconItem>
+    ))}
+  </ThemeContextProvider>
+</IconGallery>

package/lib/theme/Theme.mdx

@@ -0,0 +1,25 @@
+import { Meta, Title, Subtitle, Source } from '@storybook/addon-docs/blocks';
+import theme from './defaultTheme';
+
+{ console.log('theme:', theme) }
+
+<Meta title="Theme/Theme" />
+<Title>Theme explorer</Title>
+<Subtitle>All design tokens currently available in the theme</Subtitle>
+
+This theme explorer lists all the named properties of the theme object, found in the <a href="https://github.com/ucl-isd/uikit-react/blob/main/lib/theme/defaultTheme.ts" target="_blank">`defaultTheme.ts` file</a> .
+
+The theme object is a collection of <a href="https://atlassian.design/tokens/design-tokens/" target="_blank">design tokens</a> that are used to style the UIKit-React components.
+
+The theme object is also logged to the console when this page is loaded. 
+
+{
+  Object.entries(theme).map(([key, value]) => {
+  return (
+    <div key={key}>
+      <h2><code>{key}</code></h2>
+      <Source language="json" code={JSON.stringify(value, null, 2)} />
+    </div>
+  );
+})
+}

package/lib/theme/Typography.mdx

@@ -0,0 +1,79 @@
+import { Meta, Title, Subtitle, Typeset } from '@storybook/blocks';
+import theme from './defaultTheme';
+
+{ console.log(theme.font) } 
+
+<style>
+{/* Quick fix for broken table of contents */}
+{`
+.toc-wrapper {
+  display: none;
+}
+`}
+</style>
+
+<Meta title="Theme/Typography" />
+<Title>Typography explorer</Title>
+<Subtitle>All typographic design tokens currently available in the theme</Subtitle>
+
+More information on typography permitted in the UCL Design System <a href="https://www.figma.com/design/8Sm5PxWOWJYpYXAzhRzUzt/UCL-Design-System-UI-Kit?node-id=1-2" target="_blank">can be found in Figma</a>. 
+
+## Primary font family
+
+The primary font family is used for most text on the page. It is set to Helvetica, "Helvetica Neue", Arial, sans-serif.
+
+{
+  Object.entries(theme.font.weight).map(([key, value]) => {
+    return (
+      <div key={key}>
+        <h3>{key.charAt(0).toUpperCase() + key.slice(1)}</h3>
+        <Typeset
+          fontSizes={Object.values(theme.font.size).map((size) => size )}
+          fontWeight={value} 
+          sampleText="At University College London, the quick brown fox jumps over the lazy dog."
+          fontFamily={theme.font.family.primary}
+        />
+      </div>
+    );
+  })
+}
+
+## Secondary font family
+
+Secondary font family is set to Garamond, Baskerville, "Baskerville Old Face", "Hoefler Text", "Times New Roman", serif.
+
+{
+  Object.entries(theme.font.weight).map(([key, value]) => {
+    return (
+      <div key={key}>
+        <h3>{key.charAt(0).toUpperCase() + key.slice(1)}</h3>
+        <Typeset
+          fontSizes={Object.values(theme.font.size).map((size) => size )}
+          fontWeight={value} 
+          sampleText="At University College London, the quick brown fox jumps over the lazy dog."
+          fontFamily={theme.font.family.secondary}
+        />
+      </div>
+    );
+  })
+}
+
+## Fixed font family
+
+The fixed font family is used for code and other monospaced text. It is set to Courier, fixed.
+
+{
+  Object.entries(theme.font.weight).map(([key, value]) => {
+    return (
+      <div key={key}>
+        <h3>{key.charAt(0).toUpperCase() + key.slice(1)}</h3>
+        <Typeset
+          fontSizes={Object.values(theme.font.size).map((size) => size )}
+          fontWeight={value} 
+          sampleText="At University College London, the quick brown fox jumps over the lazy dog."
+          fontFamily={theme.font.family.fixed}
+        />
+      </div>
+    );
+  })
+}