@uob-web-and-digital/component-library 0.0.1 → 0.0.3

package/README.md

@@ -0,0 +1,64 @@
+# University of Birmingham Component Library
+This is the frontend component library for the University of Birmingham website built using Storybook 7 and SASS.
+
+## Contents
+* [Installation and setup](#installation-and-setup)
+* [Working locally on the project](#working-locally-on-the-project)
+* [Deploying changes to the public Storybook](#deploying-project-changes-to-the-public-storybook)
+* [Publishing changes to the NPMJS package library](#publishing-changes-to-the-npmjs-package-library)
+* [Creating Components](#creating-components)
+
+## Installation and setup
+
+### Node Compatibility
+**Node:** ^18.18.0
+
+### Setting up the project locally
+1. Clone the repo from Github: `git clone git@github.com:uob-itservices/component-library.git`
+2. Install NPM Node Modules by running `npm install` from the project root
+
+## Working locally on the project
+Run `npm run storybook` from the project root. This will run a new instance of [Storybook](https://storybook.js.org/) that can be accessed from `localhost:6006`.
+
+Changes made locally are automatically compiled and the browser instance of Storybook will automaticaly refresh, hot-loading changes very quickly where possible.
+
+## Deploying project changes to the public Storybook
+The visible Storybook for sharing changes is private and is accessed at [https://stunning-invention-1w42em5.pages.github.io/](https://stunning-invention-1w42em5.pages.github.io/) you will need to be a member of the uob-itservices GitHub organisation and have access to the repository.
+
+This is automatically deployed and built when changes are pushed to the `develop` branch of the GitHub repository.
+
+## Publishing changes to the NPMJS package library
+The repository will need publishing to the NPMJS package library [https://www.npmjs.com/package/@uob-web-and-digital/component-library](https://www.npmjs.com/package/@uob-web-and-digital/component-library) before it can be used in the UoB website.
+
+This is a private package so a read-only NPM access token will need be created in order to install the package.
+
+When the library in ready for a new release of the NPM package, you will need to increase the version number in the package.json and run a `npm install` to ensure the project gets updated with this version. After this you will need to create a pull request into the `develop`` branch and then another pull request from the `develop`` branch into `main`
+
+As this is a manual process, ensure that the `main` branch of the repository is always in sync with the currently published package.
+
+Releasing to the NPM registry are managed by GitHub Actions. You will need to create a new release and use the new release version as the tag. Once the release is published a GitHub Action will automatically run all the steps to publish the package on NPM.
+
+## Creating components
+Components should always be created within the `src/components` folder.
+
+### Naming component folders
+You can create a new folder within `src/components` that is based on the chosen name for your component. The format of this folder name, react component and story should always be PascalCase i.e. `MyNewComponent`. SASS files should always be camelCase i.e. `myNewComponent`
+
+### Component file structure
+Within the component folder you must create the following 3 files:
+
+```
+ComponentName
+ |_ {ComponentName}.tsx
+ |_ {ComponentName}.stories.ts
+ |_ {componentName}.scss
+```
+
+#### {ComponentName}.tsx
+This file is where the Component Structure is defined.
+
+#### {ComponentName}.stories.ts
+This file allows developers to pass in mockup content to the component that will render within Storybook. More information is available in the Storybook docs [Storybook JS - Defining Stories](https://storybook.js.org/docs/react/writing-stories/introduction#defining-stories)
+
+#### componentName.scss
+This is where component styling is defined using SASS/CSS.

package/dist/components/Button/Button.d.ts

@@ -0,0 +1,28 @@
+import { ReactElement } from 'react';
+import './button.scss';
+export interface ButtonProps {
+    /**
+     * Is this the principal call to action on the page?
+     */
+    primary?: boolean;
+    /**
+     * What background color to use
+     */
+    backgroundColor?: string;
+    /**
+     * How large should the button be?
+     */
+    size?: 'small' | 'medium' | 'large';
+    /**
+     * Button contents
+     */
+    label: string;
+    /**
+     * Optional click handler
+     */
+    onClick?: () => void;
+}
+/**
+ * Primary UI component for user interaction
+ */
+export declare const Button: ({ primary, size, backgroundColor, label, ...props }: ButtonProps) => ReactElement;

package/dist/components/Button/Button.stories.d.ts

@@ -0,0 +1,21 @@
+/// <reference types="react" />
+import type { StoryObj } from '@storybook/react';
+declare const meta: {
+    title: string;
+    component: ({ primary, size, backgroundColor, label, ...props }: import("./Button").ButtonProps) => import("react").ReactElement<any, string | import("react").JSXElementConstructor<any>>;
+    parameters: {
+        layout: string;
+    };
+    tags: string[];
+    argTypes: {
+        backgroundColor: {
+            control: string;
+        };
+    };
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+export declare const Primary: Story;
+export declare const Secondary: Story;
+export declare const Large: Story;
+export declare const Small: Story;

package/dist/components/CampusSelector/CampusSelector.d.ts

@@ -0,0 +1,15 @@
+import { ReactElement } from 'react';
+import { ThemeProps } from '../../themeProps';
+import './campusSelector.scss';
+interface CampusSelectorProps {
+    /**
+     * The theme to use
+     */
+    theme: ThemeProps;
+    active: 'uk' | 'dubai';
+    ukUrl: string;
+    dubaiUrl: string;
+    mobile: boolean;
+}
+export default function CampusSelector({ active, theme, ukUrl, dubaiUrl, mobile }: CampusSelectorProps): ReactElement;
+export {};

package/dist/components/CampusSelector/CampusSelector.stories.d.ts

@@ -0,0 +1,11 @@
+import type { StoryObj } from '@storybook/react';
+import CampusSelector from './CampusSelector';
+declare const meta: {
+    title: string;
+    component: typeof CampusSelector;
+    tags: string[];
+};
+export default meta;
+type Story = StoryObj<typeof CampusSelector>;
+export declare const Mobile: Story;
+export declare const Desktop: Story;

package/dist/components/CampusSelectorLink/CampusSelectorLink.d.ts

@@ -0,0 +1,17 @@
+import { ReactElement } from 'react';
+import { ThemeProps } from '../../themeProps';
+import './campusSelectorLink.scss';
+export interface CampusSelectorLinkProps {
+    /**
+     * The theme to use
+     */
+    theme: ThemeProps;
+    /**
+     * Whether to inverse the colours
+     */
+    label: string;
+    url: string;
+    externalLink?: boolean;
+    active?: boolean;
+}
+export default function CampusSelectorLink({ theme, label, url, externalLink, active }: CampusSelectorLinkProps): ReactElement;

package/dist/components/CampusSelectorLink/CampusSelectorLink.stories.d.ts

@@ -0,0 +1,11 @@
+import type { StoryObj } from '@storybook/react';
+import CampusSelectorLink from './CampusSelectorLink';
+declare const meta: {
+    title: string;
+    component: typeof CampusSelectorLink;
+    tags: string[];
+};
+export default meta;
+type Story = StoryObj<typeof CampusSelectorLink>;
+export declare const Default: Story;
+export declare const Active: Story;

package/dist/components/ExampleTheming/ExampleTheming.d.ts

@@ -0,0 +1,17 @@
+import { ReactElement } from 'react';
+import { ThemeProps } from '../../themeProps';
+import './exampleTheming.scss';
+export interface ExampleThemingProps {
+    /**
+     * The theme to use
+     */
+    theme: ThemeProps;
+    /**
+     * Whether to inverse the colours
+     */
+    inverse?: boolean;
+}
+/**
+ * Primary UI component for user interaction
+ */
+export declare const ExampleTheming: ({ theme, inverse }: ExampleThemingProps) => ReactElement;

package/dist/components/ExampleTheming/ExampleTheming.stories.d.ts

@@ -0,0 +1,12 @@
+/// <reference types="react" />
+import type { StoryObj } from '@storybook/react';
+import { ExampleTheming } from './ExampleTheming';
+declare const meta: {
+    title: string;
+    component: ({ theme, inverse }: import("./ExampleTheming").ExampleThemingProps) => import("react").ReactElement<any, string | import("react").JSXElementConstructor<any>>;
+    tags: string[];
+};
+export default meta;
+type Story = StoryObj<typeof ExampleTheming>;
+export declare const Dark: Story;
+export declare const Light: Story;

package/dist/components/Footer/Footer.d.ts

@@ -0,0 +1,15 @@
+import { ReactElement } from 'react';
+import { ThemeProps } from '../../themeProps';
+import './footer.scss';
+export interface FooterLinkProps {
+    label: string;
+    href: string;
+    externalLink: boolean;
+}
+export interface FooterProps {
+    theme: ThemeProps;
+    summaryLinks: FooterLinkProps[];
+    hygieneLinks: FooterLinkProps[];
+    locations: FooterLinkProps[];
+}
+export default function Footer({ theme, locations, summaryLinks, hygieneLinks }: FooterProps): ReactElement;

package/dist/components/Footer/Footer.stories.d.ts

@@ -0,0 +1,13 @@
+import type { StoryObj } from '@storybook/react';
+import Footer from './Footer';
+declare const meta: {
+    title: string;
+    component: typeof Footer;
+    tags: string[];
+    parameters: {
+        layout: string;
+    };
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+export declare const FooterExample: Story;

package/dist/components/Footer/defaultProps.d.ts

@@ -0,0 +1,5 @@
+import { FooterProps, FooterLinkProps } from './Footer';
+export declare const footerSummaryLinks: FooterLinkProps[];
+export declare const footerHygieneLinks: FooterLinkProps[];
+export declare const footerLocations: FooterLinkProps[];
+export declare const footerProps: FooterProps;

package/dist/components/Header/Header.d.ts

@@ -0,0 +1,23 @@
+import { ReactElement } from 'react';
+import { ThemeProps } from '../../themeProps';
+import { HeaderLink } from './types';
+import './header.scss';
+export interface HeaderProps {
+    /**
+     * The theme to use
+     */
+    theme: ThemeProps;
+    /**
+     * Large nav links on the main menu
+     */
+    primaryLinks: HeaderLink[];
+    /**
+     * Small nav links on the main menu
+     */
+    secondaryLinks: HeaderLink[];
+    homepageUrl: string;
+    dubaiUrl: string;
+    ukUrl: string;
+    activeCampus: 'uk' | 'dubai';
+}
+export declare const Header: ({ theme, primaryLinks, secondaryLinks, homepageUrl, dubaiUrl, ukUrl, activeCampus }: HeaderProps) => ReactElement;

package/dist/components/Header/Header.stories.d.ts

@@ -0,0 +1,11 @@
+/// <reference types="react" />
+import type { StoryObj } from '@storybook/react';
+import { Header } from './Header';
+declare const meta: {
+    title: string;
+    component: ({ theme, primaryLinks, secondaryLinks, homepageUrl, dubaiUrl, ukUrl, activeCampus }: import("./Header").HeaderProps) => import("react").ReactElement<any, string | import("react").JSXElementConstructor<any>>;
+    tags: string[];
+};
+export default meta;
+type Story = StoryObj<typeof Header>;
+export declare const Default: Story;

package/dist/components/Header/components/MainMenu.d.ts

@@ -0,0 +1,10 @@
+import { ReactElement } from 'react';
+import { HeaderLink } from '../types';
+import { ThemeProps } from '../../../themeProps';
+export interface MainMenuProps {
+    primaryLinks: HeaderLink[];
+    secondaryLinks: HeaderLink[];
+    onClickNavLink: (idx: number) => void;
+    theme: ThemeProps;
+}
+export declare const MainMenu: ({ primaryLinks, secondaryLinks, onClickNavLink, theme }: MainMenuProps) => ReactElement;

package/dist/components/Header/components/NestedMenu.d.ts

@@ -0,0 +1,11 @@
+import { ReactElement } from 'react';
+import { HeaderLink } from '../types';
+import { ThemeProps } from '../../../themeProps';
+export interface NestedMenuProps {
+    headingLink: HeaderLink;
+    onClickGoBack: () => void;
+    onClickNavLink: (idx: number) => void;
+    theme: ThemeProps;
+    backLinkLabel: string;
+}
+export declare const NestedMenu: ({ headingLink, onClickGoBack, onClickNavLink, theme, backLinkLabel }: NestedMenuProps) => ReactElement;

package/dist/components/Header/defaultProps.d.ts

@@ -0,0 +1,2 @@
+import { HeaderProps } from './Header';
+export declare const headerProps: HeaderProps;

package/dist/components/Header/types.d.ts

@@ -0,0 +1,7 @@
+export interface HeaderLink {
+    label: string;
+    url: string;
+    description?: string;
+    children?: HeaderLink[];
+}
+export type MenuLevel = 0 | 1 | 2;

package/dist/components/IconButton/IconButton.d.ts

@@ -0,0 +1,18 @@
+import React from 'react';
+import { IconType } from '../Icons/Icons';
+import { ThemeProps } from '../../themeProps';
+import './icon-button.scss';
+export interface IconButtonProps {
+    theme: ThemeProps;
+    inverse?: boolean;
+    url?: string;
+    title: string;
+    icon: IconType;
+    externalLink?: boolean;
+    onClick?: () => void;
+    ariaControls?: string;
+    autoFocus?: boolean;
+}
+type Ref = HTMLButtonElement | null;
+export declare const IconButton: React.ForwardRefExoticComponent<IconButtonProps & React.RefAttributes<Ref>>;
+export {};

package/dist/components/IconButton/IconButton.stories.d.ts

@@ -0,0 +1,23 @@
+/// <reference types="react" />
+import type { StoryObj } from '@storybook/react';
+declare const meta: {
+    title: string;
+    component: import("react").ForwardRefExoticComponent<import("./IconButton").IconButtonProps & import("react").RefAttributes<HTMLButtonElement | null>>;
+    tags: string[];
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+export declare const FacebookDark: Story;
+export declare const FacebookLight: Story;
+export declare const TwitterDark: Story;
+export declare const TwitterLight: Story;
+export declare const InstagramDark: Story;
+export declare const InstagramLight: Story;
+export declare const WeiboDark: Story;
+export declare const WeiboLight: Story;
+export declare const WechatDark: Story;
+export declare const WechatLight: Story;
+export declare const YoutubeDark: Story;
+export declare const YoutubeLight: Story;
+export declare const HamburgerDark: Story;
+export declare const HamburgerLight: Story;

package/dist/components/Icons/Icons.d.ts

@@ -0,0 +1,18 @@
+import { ReactElement } from 'react';
+import { ThemeProps } from '../../themeProps';
+import './icons.scss';
+export type IconType = 'twitter' | 'facebook' | 'wechat' | 'weibo' | 'youtube' | 'instagram' | 'linkedin' | 'chevron-down' | 'chevron-right' | 'arrow-right' | 'arrow-right-large' | 'location' | 'hamburger' | 'cross' | 'arrow-left';
+export type IconProps = {
+    /**
+     * The theme to use
+     */
+    theme: ThemeProps;
+    /**
+     * Whether to inverse the colours
+     */
+    inverse?: boolean;
+    icon: IconType;
+    name?: string;
+    ariaHidden?: boolean;
+};
+export default function Icon({ icon, ariaHidden, theme, inverse }: IconProps): ReactElement;

package/dist/components/Image/Image.d.ts

@@ -0,0 +1,13 @@
+import { ReactElement } from 'react';
+import './image.scss';
+export type ImageProps = {
+    src: {
+        small?: string;
+        medium?: string;
+        default: string;
+    };
+    altText?: string | null;
+    title?: string | null;
+    loadingAttr?: 'lazy' | 'eager' | undefined;
+};
+export default function Image({ src, altText, title, loadingAttr }: ImageProps): ReactElement;

package/dist/components/LinkStandard/LinkStandard.d.ts

@@ -0,0 +1,11 @@
+import { ReactElement } from 'react';
+import { ThemeProps } from '../../themeProps';
+import './link-standard.scss';
+export interface LinkStandardProps {
+    theme: ThemeProps;
+    inverse?: boolean;
+    url: string;
+    title: string;
+    externalLink: boolean;
+}
+export default function LinkStandard({ theme, inverse, url, title, externalLink }: LinkStandardProps): ReactElement;

package/dist/components/LinkStandard/LinkStandard.stories.d.ts

@@ -0,0 +1,11 @@
+import type { StoryObj } from '@storybook/react';
+import LinkStandard from './LinkStandard';
+declare const meta: {
+    title: string;
+    component: typeof LinkStandard;
+    tags: string[];
+};
+export default meta;
+type Story = StoryObj<typeof meta>;
+export declare const Dark: Story;
+export declare const Light: Story;

package/dist/components/LinkWithArrow/LinkWithArrow.d.ts

@@ -0,0 +1,17 @@
+import { ReactElement } from 'react';
+import { ThemeProps } from '../../themeProps';
+import './link-with-arrow.scss';
+export interface LinkWithArrowProps {
+    /**
+     * The theme to use
+     */
+    theme: ThemeProps;
+    /**
+     * Whether to inverse the colours
+     */
+    inverse?: boolean;
+    url: string;
+    title: string;
+    externalLink?: boolean;
+}
+export default function LinkWithArrow({ theme, inverse, url, title, externalLink }: LinkWithArrowProps): ReactElement;

package/dist/components/LinkWithArrow/LinkWithArrow.stories.d.ts

@@ -0,0 +1,12 @@
+import type { StoryObj } from '@storybook/react';
+import LinkWithArrow from './LinkWithArrow';
+declare const meta: {
+    title: string;
+    component: typeof LinkWithArrow;
+    tags: string[];
+};
+export default meta;
+type Story = StoryObj<typeof LinkWithArrow>;
+export declare const Dark: Story;
+export declare const Light: Story;
+export declare const Long: Story;

package/dist/components/MainWrapper/MainWrapper.d.ts

@@ -0,0 +1,5 @@
+import { PropsWithChildren, ReactElement } from 'react';
+interface MainWrapperProps {
+}
+export default function MainWrapper({ children }: PropsWithChildren<MainWrapperProps>): ReactElement;
+export {};

package/dist/components/NavLink/NavLink.d.ts

@@ -0,0 +1,14 @@
+import { ReactElement } from 'react';
+import { ThemeProps } from '../../themeProps';
+import './NavLink.scss';
+export interface NavLinkProps {
+    /**
+     * The theme to use
+     */
+    theme: ThemeProps;
+    label: string;
+    level: 'level-one' | 'level-two';
+    onClick: () => void;
+    autoFocus?: boolean;
+}
+export declare const NavLink: ({ theme, onClick, label, level, autoFocus }: NavLinkProps) => ReactElement;

package/dist/components/NavLink/NavLink.stories.d.ts

@@ -0,0 +1,18 @@
+import React from 'react';
+import type { StoryObj } from '@storybook/react';
+import { NavLink } from './NavLink';
+declare const meta: {
+    title: string;
+    component: ({ theme, onClick, label, level, autoFocus }: import("./NavLink").NavLinkProps) => React.ReactElement<any, string | React.JSXElementConstructor<any>>;
+    tags: string[];
+    parameters: {
+        backgrounds: {
+            default: string;
+        };
+    };
+};
+export default meta;
+type Story = StoryObj<typeof NavLink>;
+export declare const LevelOne: Story;
+export declare const LevelTwo: Story;
+export declare const Long: Story;

package/dist/components/PageLink/PageLink.d.ts

@@ -0,0 +1,17 @@
+import { ReactElement } from 'react';
+import { ThemeProps } from '../../themeProps';
+import './PageLink.scss';
+export interface PageLinkProps {
+    /**
+     * The theme to use
+     */
+    theme: ThemeProps;
+    url: string;
+    label: string;
+    /**
+     * The level in the navigation menu
+     */
+    level: 'level-one' | 'level-two';
+    autoFocus?: boolean;
+}
+export declare const PageLink: ({ theme, url, label, level, autoFocus }: PageLinkProps) => ReactElement;

package/dist/components/PageLink/PageLink.stories.d.ts

@@ -0,0 +1,18 @@
+import React from 'react';
+import type { StoryObj } from '@storybook/react';
+import { PageLink } from './PageLink';
+declare const meta: {
+    title: string;
+    component: ({ theme, url, label, level, autoFocus }: import("./PageLink").PageLinkProps) => React.ReactElement<any, string | React.JSXElementConstructor<any>>;
+    tags: string[];
+    parameters: {
+        backgrounds: {
+            default: string;
+        };
+    };
+};
+export default meta;
+type Story = StoryObj<typeof PageLink>;
+export declare const LevelOne: Story;
+export declare const LevelTwo: Story;
+export declare const Long: Story;

package/dist/components/ReverseLinkWithArrow/ReverseLinkWithArrow.d.ts

@@ -0,0 +1,19 @@
+import { ReactElement } from 'react';
+import { ThemeProps } from '../../themeProps';
+import './ReverseLinkWithArrow.scss';
+export interface ReverseLinkWithArrowProps {
+    /**
+     * The theme to use
+     */
+    theme: ThemeProps;
+    /**
+     * Whether to inverse the colours
+     */
+    inverse?: boolean;
+    label: string;
+    onClick: () => void;
+}
+/**
+ * Same as LinkWithArrow but arrow is on the left side
+ */
+export declare const ReverseLinkWithArrow: ({ theme, inverse, label, onClick }: ReverseLinkWithArrowProps) => ReactElement;

package/dist/components/ReverseLinkWithArrow/ReverseLinkWithArrow.stories.d.ts

@@ -0,0 +1,13 @@
+import React from 'react';
+import type { StoryObj } from '@storybook/react';
+import { ReverseLinkWithArrow } from './ReverseLinkWithArrow';
+declare const meta: {
+    title: string;
+    component: ({ theme, inverse, label, onClick }: import("./ReverseLinkWithArrow").ReverseLinkWithArrowProps) => React.ReactElement<any, string | React.JSXElementConstructor<any>>;
+    tags: string[];
+};
+export default meta;
+type Story = StoryObj<typeof ReverseLinkWithArrow>;
+export declare const Dark: Story;
+export declare const Light: Story;
+export declare const Long: Story;

package/dist/components/SignPost/SignPost.d.ts

@@ -0,0 +1,29 @@
+import { ReactElement } from 'react';
+import { ThemeProps } from '../../themeProps';
+import './SignPost.scss';
+export interface SignPostProps {
+    /**
+     * The theme to use
+     */
+    theme: ThemeProps;
+    /**
+     * Whether to inverse the colours
+     */
+    inverse?: boolean;
+    /**
+     * A SignPost can have 2 or 4 items
+     */
+    items: readonly [SignPostItem, SignPostItem];
+}
+type SignPostItem = {
+    title: string;
+    tag: string;
+    linkLabel: string;
+    linkUrl: string;
+    external?: boolean;
+};
+/**
+ * Text promo block with a link
+ */
+export default function SignPost({ theme, inverse, items }: SignPostProps): ReactElement;
+export {};

package/dist/components/SignPost/SignPost.stories.d.ts

@@ -0,0 +1,19 @@
+import { ReactElement } from 'react';
+import type { StoryObj } from '@storybook/react';
+import SignPost from './SignPost';
+declare const meta: {
+    title: string;
+    component: typeof SignPost;
+    tags: string[];
+    parameters: {
+        backgrounds: {
+            default: string;
+        };
+    };
+};
+export default meta;
+type Story = StoryObj<typeof SignPost>;
+export declare const Dark: Story;
+export declare const Light: Story;
+export declare const Stacked: () => ReactElement;
+export declare const Long: Story;

package/dist/components/SignPost/defaultProps.d.ts

@@ -0,0 +1,2 @@
+import { SignPostProps } from './SignPost';
+export declare const signPostProps: SignPostProps;

package/dist/components/SkipToContent/SkipToContent.d.ts

@@ -0,0 +1,8 @@
+import { ReactElement } from 'react';
+import './SkipToContent.scss';
+import { ThemeProps } from '../../themeProps';
+interface SkipToContentProps {
+    theme: ThemeProps;
+}
+export default function SkipToContent({ theme }: SkipToContentProps): ReactElement;
+export {};

package/dist/components/SkipToContent/SkipToContent.stories.d.ts

@@ -0,0 +1,15 @@
+import type { StoryObj } from '@storybook/react';
+import SkipToContent from './SkipToContent';
+declare const meta: {
+    title: string;
+    component: typeof SkipToContent;
+    tags: string[];
+    parameters: {
+        backgrounds: {
+            default: string;
+        };
+    };
+};
+export default meta;
+type Story = StoryObj<typeof SkipToContent>;
+export declare const Default: Story;