Introduction.mdx

import packageJson from "../../package.json" import { Meta } from "@storybook/blocks";

# Scientific React UI - v{packageJson.version}

    ## Introduction

    SciReactUI is a collection of useful scientific focused components which utilizing Material UI
    to make your React based websites look great.

    Check out the list of components on the left. To use them, follow the instructions below.
</div>

## Usage

    ### First, Install the Package.

    In your React App, add the latest SciReactUI version:

    ```shell
    pnpm add @diamondlightsource/sci-react-ui
    ```

    ### Next, Add a ThemeProvider

    Select a theme, either `GenericTheme` or `DiamondTheme` (Or you can create your own, see below), and add
    it to the App via the ThemeProvider:

    ```tsx filename="main.tsx"
    import {
        ThemeProvider,
        GenericTheme
    } from "@diamondlightsource/sci-react-ui";

    root.render(
      <ThemeProvider theme={GenericTheme}>
        <App />
      </ThemeProvider>
    )
    ```

    ### Finally, Add the Components

    Then create something, for instance, you may want a Navigation Bar at the top of your website:

    ```tsx filename="App.tsx"
    import {Container, Typography} from "@mui/material";
    import {
      Navbar,
      NavLink,
      NavLinks
    } from "@diamondlightsource/sci-react-ui";

    function App() {
      return <>
        <Navbar>
          <NavLinks key="links">
            <NavLink href="#" key="first">A link</NavLink>
          </NavLinks>
        </Navbar>
        <Container>
          <Typography variant="h2">Scientific UI Collection</Typography>
          <Typography>A collection of science based React components.</Typography>
        </Container>
    </>
    }
    export default App;
    ```

    Typically, a complete app page would combine many components, for example:

    ```tsx filename="App.tsx"

    function App() {
        return <>
            <Navbar
                logo="theme"
                leftSlot={
                    <NavLinks>
                        <NavLink href="#link">Link</NavLink>
                    </NavLinks>
                }
                rightSlot={<>
                    <User
                        onLogin={}
                        onLogout={}
                    />
                    <ColourSchemeButton />
                </>}
            />

            <Container>
                <Typography>Main Content here.</Typography>
            </Container>

            <Footer logo="theme">
                <FooterLinks>
                    <FooterLink href="#link">Link</FooterLink>
                </FooterLinks>
                <p>From SciReactUI</p>
            </Footer>

        </>
    }
    ```
</div>

## Create new Theme

    The 'GenericTheme.ts' shows you a simple example of creating a new theme.
    Use `mergeThemeOptions` to create a new one from an existing one.

    To inherit from the DiamondTheme by overriding the light palette, use something like this:

    ```tsx
    import { createTheme, Theme } from "@mui/material/styles";
    import { DiamondThemeOptions, mergeThemeOptions } from '@diamondlightsource/sci-react-ui'

    const MyThemeOptions = mergeThemeOptions({
        colorSchemes: {
            light: {
                palette: {
                    primary: {
                        main: "#f00",
                        light: "#f55",
                        dark: "#a00",
                        contrastText: "#fff",
                    },
                },
            },
        }
    }, DiamondThemeOptions);

    const MyTheme: Theme = createTheme(MyThemeOptions);
    export { MyTheme };
    ```

    The theme options are documented in MUI. For the examples used in DiamondTheme
    see [DiamondTheme.tsx](https://github.com/DiamondLightSource/sci-react-ui/blob/main/src/themes/DiamondTheme.ts)
    on GitHub.

</div>