@admixltd/admix-component-library v0.5.17

ACL 🔷 Admix Components Library

yarn add @admixltd/admix-component-library

Subpackages list

this packages not included to @admixltd/admix-component-library directly and should use specific import

'@admixltd/admix-component-library/Api'
'@admixltd/admix-component-library/AuthWrapper'
'@admixltd/admix-component-library/AutoComplete'
'@admixltd/admix-component-library/ChipArray'
'@admixltd/admix-component-library/Deprecated'
'@admixltd/admix-component-library/FormAtomGenerator'
'@admixltd/admix-component-library/NumericInput'
'@admixltd/admix-component-library/RecoilNexus'
'@admixltd/admix-component-library/Snackbar'
'@admixltd/admix-component-library/Table'

Usage in your project:

1. Install component-specific dependencies

Deprecated

If you want to use legacy packages from deprecated section, based on antd, you should install next packages:

They are in the deprecated section because they use direct or indirect dependence on antd, for example AdmixButton in AppDiscoveryItem.tsx

yarn add recharts antd

import { AdmixButton, AdmixBarChart, AdmixBarChartProps } from '@admixltd/admix-component-library/Deprecated'

Autocomplete , Select

To use Autocomplete or Select component please install:

yarn add react-window
 

import { AutoComplete, Select } from '@admixltd/admix-component-library/AutoComplete'

Table

To use Table component please install:

yarn add @mui/x-data-grid react-window 
 

import { Table } from '@admixltd/admix-component-library/Table'

NumericInput

To use NumericInput component please install:

yarn add react-number-format
 

import { NumericInput } from '@admixltd/admix-component-library/NumericInput'

AuthWrapper

To use AuthWrapper component please install:

yarn add react-cookie notistack
 

import { AuthWrapper } from '@admixltd/admix-component-library/AuthWrapper'

ChipArray

To use ChipArray component please install:

yarn add react-transition-group
 

import { ChipArray } from '@admixltd/admix-component-library/ChipArray'

FormAtomGenerator

To use FormAtomGenerator component please install:

More usage details

yarn add recoil
 

import { FormAtomGenerator } from '@admixltd/admix-component-library/FormAtomGenerator'

RecoilNexus

To use RecoilNexus component please install:

More usage details

yarn add recoil
 

import { RecoilNexus } from '@admixltd/admix-component-library/RecoilNexus'

Snackbar

If you want use Snackbar component please install:

More usage details

yarn add notistack

import { Snackbar } from '@admixltd/admix-component-library/Snackbar'

2. Add Inter font

To use this library, please add Inter font to your project

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">

Or use local Inter font copy (Preferred for ssr)

Use: https://amio.github.io/embedded-google-fonts/ to store font in one file with base64

<!-- Your html file-->
<!--suppress CommaExpressionJS -->
<script>
    const fontFile = '/inter.css'
    const fontFamily = `Inter`
    /**
     * Save font into localstorage for fast refresh
     */
    ;(function() {
      function addFont() {
        const e = document.createElement('style');
        document.head.appendChild(e);
        e.textContent = localStorage.preloaded_font;
      }
      const fontExists = !!localStorage.preloaded_font && localStorage.preloaded_font.includes(fontFamily);
      if (fontExists){
        addFont();
        return;
      } 
      fetch(fontFile).then(t=>t.text()).then(t=>{
        localStorage.setItem('preloaded_font', t);
        addFont();
      });
    })()
</script>

3. Use theme

1. Merge AdmixLibraryTheme with your @emotion theme

//styles/theme.ts

import { AdmixLibraryTheme } from '@admixltd/admix-component-library'

/**
 * Your styles
 */
const projectTheme = {
  purple: `#DDA0DD`,
}

/**
 * Override theme styles
 */
AdmixLibraryTheme.colors.primary = '#000'
AdmixLibraryTheme.colors.secondary = projectTheme.purple

/**
 * Extend style-components with theme type
 */
export type ITheme = typeof AdmixLibraryTheme & typeof projectTheme
const theme = { ...AdmixLibraryTheme, ...projectTheme } as ITheme
export type PropsWithTheme<T = unknown> = T & {
  theme: ITheme
}
export default theme

2. Redeclare Theme

https://emotion.sh/docs/typescript#define-a-theme

//emotion.d.ts
import "@emotion/react";
import { ITheme } from "@styles/theme";


declare module "@emotion/react" {
  /**
   * Should be interface not a type
   */
  export interface Theme extends ITheme {
  }
}

3.Wrap your app with AdmixThemeProvider and ThemeProvider from @emotion

//App.jsx

import { AdmixThemeProvider } from '@admixltd/admix-component-library';
import theme from 'styles/theme';

<AdmixThemeProvider theme={theme}>
  <App />
</AdmixThemeProvider>

/**
 * Or same without AdmixThemeProvider
 */

import { ThemeProvider as EmotionThemeProvider } from '@emotion/react'
import { createTheme, ThemeProvider as MuiThemeProvider } from '@mui/material'
import theme from 'styles/theme';

const muiTheme = createTheme({});

<MuiThemeProvider theme={muiTheme}>
  <EmotionThemeProvider theme={theme}>
    <App />
  </EmotionThemeProvider>
</MuiThemeProvider>

1. Merge AdmixLibraryTheme with your styled-components theme

//styles/theme.ts

import { AdmixLibraryTheme } from '@admixltd/admix-component-library'

/**
 * Your styles
 */
const projectTheme = {
  purple: `#DDA0DD`,
}

/**
 * Override theme styles
 */
AdmixLibraryTheme.colors.primary = '#000'
AdmixLibraryTheme.colors.secondary = projectTheme.purple

/**
 * Extend style-components with theme type
 */

export type ITheme = typeof AdmixLibraryTheme & typeof projectTheme
const theme = { ...AdmixLibraryTheme, ...projectTheme } as ITheme
export default theme

2. Redeclare DefaultTheme

https://styled-components.com/docs/api#create-a-declarations-file

//styled.d.ts
import 'styled-components'
import { ITheme } from '@styles/theme'


declare module 'styled-components' {
  /**
   * Should be interface not a type
   */
  export interface DefaultTheme extends ITheme {}
}

3.Wrap your app with AdmixThemeProvider and ThemeProvider from styled-components

//App.jsx

import { AdmixThemeProvider } from '@admixltd/admix-component-library';
import { ThemeProvider } from 'styled-components';
import theme from 'styles/theme';

<AdmixThemeProvider>
  <ThemeProvider theme={theme}>
    <App />
  </ThemeProvider>
</AdmixThemeProvider>

/**
 * Or same without AdmixThemeProvider
 */

import { ThemeProvider as EmotionThemeProvider } from '@emotion/react'
import { createTheme, ThemeProvider as MuiThemeProvider } from '@mui/material'
import { ThemeProvider } from 'styled-components';
import theme from 'styles/theme';

const muiTheme = createTheme({});


<MuiThemeProvider theme={muiTheme}>
  <EmotionThemeProvider theme={theme}>
    <ThemeProvider theme={theme}>
      <App />
    </ThemeProvider>
  </EmotionThemeProvider>
</MuiThemeProvider>

4. Enjoy using it, you are wonderful! 🎂

Development

If you haven't used yarn before, please make sure that you install dependencies in an empty node_modules folder

Install yarn and rimraf

npm install --global yarn 
yarn global add rimraf

Remove node_modules recursively

rimraf node_modules

1. Install dependencies

yarn

2. Run storybook

yarn start

Build project

yarn clean && yarn build

Link projects to work locally

1. Start building in watch mode

   
yarn build-watch
   

2. Link dependencies and admix-component-library in your project package.json file

{
  "@admixltd/admix-component-library": "link:../admix-component-library/build",
  "react": "link:../admix-component-library/node_modules/react",
  "react-dom": "link:../admix-component-library/node_modules/react-dom",
  "@emotion/react": "link:../admix-component-library/node_modules/@emotion/react",
  "@emotion/styled": "link:../admix-component-library/node_modules/@emotion/styled",
  "@mui/material": "link:../admix-component-library/node_modules/@mui/material",
  "notistack": "link:../admix-component-library/node_modules/notistack",
  "recoil": "link:../admix-component-library/node_modules/recoil"
}

3. Use theming

Snackbar usage

1. Install notistack package

yarn add notistack

2. Wrap your app with SnackbarProvider

3. Add SnackbarUtilsConfigurator next to your app

import { SnackbarProvider } from 'notistack';
import { SnackbarUtilsConfigurator } from '@admixltd/admix-component-library/Snackbar';

<SnackbarProvider
  maxSnack={10}
  anchorOrigin={{
    vertical: 'bottom', horizontal: 'right',
  }}
>
  <YourApp />
  <SnackbarUtilsConfigurator />
</SnackbarProvider>

4. Use Snackbar anywhere

import { Snackbar } from '@admixltd/admix-component-library/Snackbar'

Snackbar.toast('Hello world!')
Snackbar.success(<>Hello <strong>world</strong>!</>)

FormAtomGenerator usage

import { useRecoilState } from 'recoil'
import { FormAtomGenerator } from "@admixltd/admix-component-library/FormAtomGenerator";

const initialValue: FormDataProps = {
  name: 'Jake',
  surname: 'Smith'
}

interface FormDataProps {
  name: string
  surname: string
}

const {
	AtomUpdater: SomeFormAtomUpdater,
	DataUpdater: SomeFormDataUpdater,
	DataMerger: SomeFormDataMerger,
} = FormAtomGenerator<FormDataProps>(
	'SomeFormKey',
	initialValue
)



const SomeComponent = () => {
  /**
   * Control value for specific field
   */
  const [value1, setValue1] = useRecoilState(SomeFormAtomUpdater('name'))
  const [value2, setValue2] = useRecoilState(SomeFormAtomUpdater('surname'))


  /**
   * Control array of fields ( useful for errors )
   */
  const [value3, setValue3] = useRecoilState(SomeFormAtomUpdater(['name', 'surname']))
  /**
   * value3 - returns first non undefinened value from list of fields 
   * value3 = values1['name'] ?? values1['surname'] ?? values1[...]
   * setValue3('SomeText') - updates current field form value3
   * if value3 = values1['name'] - updates 'name'
   */
  
  
  /**
   * Controll all values
   * setValues1 first call  {x: text}
   * setValues1 second call {y: text}
   * ===>
   * {y: text}
   */
  const [values1, setValues1] = useRecoilState(SomeFormDataUpdater)


  /**
   * Controll all values with merge
   * Merge values by parts like:
   * setValues2 first call  {x: text}
   * setValues2 second call {y: text}
   * ===>
   * {x: text, y: text}
   */
  const [values2, setValues2] = useRecoilState(SomeFormDataMerger)

  
  return <></>
}

RecoilNexus usage

1. Add RecoilNexus in your RecoilRoot

import React from "react";
import { RecoilRoot } from "recoil";
import { RecoilNexus } from "@admixltd/admix-component-library/RecoilNexus";

export default function App() {
  return (
    <RecoilRoot>
      <RecoilNexus />

      {/* ... */}
    </RecoilRoot>
  );
}

export default App;

2. Use the following methods to get/set values passing your atom as a parameter.

| Method | Returns | |:-------------------|:----------------------------------------------------------------------------| | getRecoil | getter function | | getRecoilPromise | getter function, returns a promise. To be used with asynchronous selectors. | | setRecoil | setter function, pass value to be set as second parameter | | resetRecoil | pass atom as parameter to reset to default value |

// Loading example
import { loadingState } from "../atoms/loadingState";
import { getRecoil, setRecoil } from "@admixltd/admix-component-library/RecoilNexus";

export default function toggleLoading() {
  const loading = getRecoil(loadingState);
  setRecoil(loadingState, !loading);
}

//Loader
import React from "react";
import { useRecoilValue } from "recoil";

export default function Loader() {
  loading = useRecoilValue(loadingState);
  return loading ? <h3>Loading...</h3> : null;
}

//Atom
import { atom } from "recoil";

export const loadingState = atom({
  key: "LOADING",
  default: false,
});

Helpers description

Hooks description

Utils description

Chromatic manual deploying

npx chromatic --project-token=YOUR_TOKEN