❤
npm
Sign UpSign In

ai-kit-common
TypeScript icon, indicating that this package has built-in type declarations

1.4.3 • Public • Published

AI-KIT: Common

This is the frontend library for the AI-KIT module Common. Use it in conjunction with the django package django-ai-kit-common in order to get a functioning Common running in your app in no time.

Installation

You can easily install AI-KIT: Common via npmjs. Using npm, run

npm install ai-kit-common

Using yarn, run

yarn add ai-kit-common

Quickstart

ai-kit-common has a number of peer dependencies that you need to install yourself before you get started:

  • react@^16.8.0
  • @material-ui/core@^4.9.0
  • @material-ui/icons@^4.9.0

API Reference

DefaultTheme

This library provides the default Material Theme used by all AI-Kit Modules. You can use this theme for other projects as well or overwrite or extend it as you wish.

Usage

Wrap the Components that you want to be styled in a <ThemeProvider>

import React from 'react';
import { ThemeProvider } from '@material-ui/core'
import { DefaultTheme } from 'ai-kit-common';
import { MyComponent } from './components/MyComponent';
 
const App: React.FC = () => (
  <ThemeProvider theme={DefaultTheme}>
    <MyComponent />
  </ThemeProvider>
);
 

See the excellent Material-UI Docs on how to access the theme in a component.

Fonts

AI-Kit-Theme was designed with the Josefine Sans and Nunito Sans fonts in mind. These fonts will not be automatically loaded by Material-UI. The developer is responsible for loading all fonts used in their application. An example of this would be using Google's CDN, pasting the following line in your index.html's <head>.

<link href="https://fonts.googleapis.com/css?family=Josefin+Sans:300i,400,600|Nunito+Sans:400,400i,600&display=swap" rel="stylesheet">

If you do decide to extend or edit the provided Default Theme, make sure to include the right fonts in all the necessary weights and styles.

DefaultPrimaryColor

DefaultPrimaryColor is a Color Palette providing the different HUE-values of the primary color used in the DefaultTheme. You can access a color via this object, should you somehow need it's color code in you Component.

DefaultSecondaryColor

DefaultSecondary is a Color Palette providing the different HUE-values of the secondary color used in the DefaultTheme. You can access a color via this object, should you somehow need it's color code in you Component.

Menu

MobileProps

This interface describes the props passed to several components which need to render depending on whether the layout is in mobile or desktop mode. Its fields are

  • mobile?: boolean: whether or not the mobile version is rendered.
  • onClose?: () => void: a callback that closes the drawer in mobile mode.

Menu Description

In order to describe menus and submenus, you need to provide data structures according to the MenuContent interface. It contains the following fields:

  • label: string: the name of the menu, displayed to the user. It should concisely and accurately describe the collection of submenu items or the action performed when this item is clicked.
  • icon?: JSX.Element: the icon is shown to the left of the label and is completely optional
  • action: MenuContent[] | () => void | string: if the action is a list of further contents, the element is treated as a submenu. If it is a function, it is treated as a terminal item, and the function is called whenever the menu item is clicked. If it is a string, it is treated as a location path, and a react router NavLink is wrapped around it in order to apply a different style if the corresponding route is active. When the link is clicked, the application navigates to the specified location.

Besides the general MenuContent, there are more restrictive types which limit the number of submenu levels. MenuLeaf allows only functions or strings as actions, so there are no submenus. MenuMaxOneLevel allows for functions, strings, and lists of MenuLeafs, i.e. it allows for menus with a maximum level of one. MenuMaxTwoLevels allows for functions, strings and lists of MenuMaxOneLevels, so it has a maximum level of two.

These limits are checked by typescript at compile time, so you can get around this limitation by casting higher level menus via as operator, or using plain javascript in the first place, although it is not recommended.

Header Menu

This component renders a single menu bar at the top of your application. You can fill it with a logo, a classical popup-menu, toolbar items and user information. It is responsive, so on screens too small to contain all the content, the menu transforms to a drawer menu, which opens when the user clicks the menu icon.

Props

  • desktopClasses?: HeaderMenuDesktopClasses: css classes to style the desktop version of the header menu. For a list of possible keys, see below.
  • ToolbarClasses?: ToolbarProps['classes']: css classes to style the toolbar. Refer to the Toolbar API for a precise definition.
  • logo?: (props:MobileProps) => ReactElement: the logo to be displayed on the left in desktop mode and on the right in mobile mode.
  • user?: User|null: Information about the logged in user, which will be shown on the right in desktop mode and in the drawer in mobile mode. null means that no user is logged in and login/register buttons are shown if possible. The User interface contains
    • username: string: is shown in both desktop and mobile modes
    • email?: string: is shown in mobile mode only
    • avatar?: string: a url to the image shown as the user's avatar image. If it is not provided, a colored circle with the username's first letter in it will be used instead. Only provide one of user or userElement!
  • userElement?: null|(props:MobileProps) => ReactNode: A custom display of user info, in case the default display does not suit your needs. A value of null means that no user is logged in and login/register buttons are shown if possible. Only provide one of user or userElement!
  • userMenu?:MenuMaxOneLevel[]: definition of the user menu. In desktop mode it is a popup menu, in mobile mode, the entries are rendered below the user information in the drawer.
  • loggedOutActions?: LoggedOutActionProps: callbacks for login and register actions. LoggedOutActionProps contains the following fields:
    • loginAction: string|() => void: is visited or called when the login button is clicked. You could redirect to your login page or open a login modal for instance.
    • registerAction?: string|() => void: is visited or called when the register button is clicked. You could redirect to your register page or open a register modal for instance. If loggedOutActions is not provided, no login/register buttons are rendered. Likewise, if only the loginAction is provided, only the login button is rendered.
  • toolbarContent?: (props:MobileProps) => ReactNode: A list of toolbar items to be displayed in the menu bar, in both desktop and mobile mode. Toolbar items are displayed on the right, next to the user information in desktop mode and on the left, next to the menu icon, in mobile mode.
  • menuDefinition?:MenuMaxTwoLevels[]: a list of menu item definitions. In desktop mode, for each of the entries, a menu item is placed in the menu bar, which when clicked opens a popup beneath itself containing the submenu items. In mobile mode, all items are rendered as sections in the drawer.
  • drawerWidth?: number|string: width of the drawer that opens when clicking on the menu icon in mobile mode (default 330px)

Example

import React, { FC } from 'react';
 
export const HeaderMenuPage: FC<{username: string}> = ({username}) => {
  const menuProps = {
    user: username ? { username } : null,
    loggedOutActions: {
      loginAction: () => console.log('login action'),
    },
    menuDefinition: [
      { label: 'common 1', action: [
        { label: 'Submenu 1', action: [
          { label: 'Action 1', action: '/path/to/action/1' },
          { label: 'Action 2', action: () => console.log('Action 2') },
        ]},
        { label: 'Submenu 2', action: [
          { label: 'Action 3', action: () => console.log('Action 3') },
          { label: 'Action 4', action: () => console.log('Action 4') },
        ]},
        { label: 'Action 5', action: () => console.log('Action 5')},
      ]},
      { label: 'Action 6', action: () => console.log('Action 6')},
    ],
    toolbarContent: (
      <>
        <IconButton><NotificationsIcon /></IconButton>
        <IconButton><FavoriteIcon /></IconButton>
      </>
    ),
  };
 
  return (
    <div>
      <HeaderMenu {...menuProps} />
      {/* page content */}
    </div>
  );
};

Side Menu

The side menu is a special material-ui Drawer. It accepts a few additional props and renders a menu among other things. As developer, you are responsible for managing the open state of it, meaning it is not responsive on its own.

Props

  • All props inherited from Drawer
  • logo?: ReactNode: The logo is shown in the top part of the drawer, in an area which is 90px tall and hides overflow.
  • menuDefinition?:MenuMaxOneLevel[]: a list of menu item definitions. All items are rendered as sections in the drawer.
  • onClose?: () => void: although Drawer contains an onClose property, notice the signature change. This function will be called whenever the user clicks on the background, hits the escape key, or clicks on a menu item that has no submenu. However, no parameters are passed to the function.
  • drawerWidth?: number|string: The width of the drawer, which is evaluated like css. Default: 330px.
  • variant?: 'permanent'|'persistent'|'temporary': Same as in Drawer, however, the default here is 'permanent'.
  • open?: boolean: Same as in Drawer, however, the default here is true.
  • menuRef?: MutableRefObject<HTMLDivElement|null>: A reference, that will be pointed to the underlying <nav> tag.

Example

import React, { FC } from 'react';
 
export const SideMenuPage: FC = ({ children }) => {
  const menuProps = {
    logo: <CompanyLogo />,
    menuDefinition: [
      { label: 'Section 1', action: [
        { label: 'Navigation 1', action: '/path/to/location/1' },
        { label: 'Navigation 2', action: '/path/to/location/1' },
      ]},
    ],
    drawerWidth: 200,
  };
 
  return (
    <div style={{ display: 'flex' }}>
      <SideMenu {...menuProps} />
      <div>
        {children}
      </div>
    </div>
  );
};

Full Layout

The full layout combines a side menu and a header menu. In desktop mode on wide screens, it renders a permanent side menu and a header menu with separate menu items. The logo only appears in the side menu. In mobile mode on smaller screens, it renders a mobile mode header menu only, which brings with it its own drawer. For this mode, both menu descriptions are merged into one, so no menu items disappear between desktop and mobile mode.

Props

  • desktopClasses?: HeaderMenuDesktopClasses: css classes to style the desktop version of the header menu. For a list of possible keys, see below.
  • ToolbarClasses?: ToolbarProps['classes']: css classes to style the toolbar. Refer to the Toolbar API for a precise definition.
  • logo?: (props:MobileProps) => ReactElement: the logo to be displayed on the left in desktop mode and on the right in mobile mode.
  • user?: User|null: Information about the logged in user, which will be shown on the right in desktop mode and in the drawer in mobile mode. null means that no user is logged in and login/register buttons are shown if possible. The User interface contains
    • username: string: is shown in both desktop and mobile modes
    • email?: string: is shown in mobile mode only
    • avatar?: string: a url to the image shown as the user's avatar image. If it is not provided, a colored circle with the username's first letter in it will be used instead. Only provide one of user or userElement!
  • userElement?: null|(props:MobileProps) => ReactNode: A custom display of user info, in case the default display does not suit your needs. A value of null means that no user is logged in and login/register buttons are shown if possible. Only provide one of user or userElement!
  • userMenu?:MenuMaxOneLevel[]: definition of the user menu. In desktop mode it is a popup menu, in mobile mode, the entries are rendered below the user information in the drawer.
  • loggedOutActions?: LoggedOutActionProps: callbacks for login and register actions. LoggedOutActionProps contains the following fields:
    • loginAction: string|() => void: is visited or called when the login button is clicked. You could redirect to your login page or open a login modal for instance.
    • registerAction?: string|() => void: is visited or called when the register button is clicked. You could redirect to your register page or open a register modal for instance. If loggedOutActions is not provided, no login/register buttons are rendered. Likewise, if only the loginAction is provided, only the login button is rendered.
  • toolbarContent?: (props:MobileProps) => ReactNode: A list of toolbar items to be displayed in the menu bar, in both desktop and mobile mode. Toolbar items are displayed on the right, next to the user information in desktop mode and on the left, next to the menu icon, in mobile mode.
  • headerMenuDefinition?:MenuMaxTwoLevels[]: a list of menu item definitions. In desktop mode, for each of the entries, a menu item is placed in the menu bar, which when clicked opens a popup beneath itself containing the submenu items. In mobile mode, all items are rendered as sections in the drawer.
  • sideMenuDefinition?:MenuMaxOneLevel[]: a list of menu item definitions. These items are always displayed in the side menu bar.
  • drawerWidth?: number|string: width of the drawer that opens when clicking on the menu icon in mobile mode (default 330px)

Example

import React, { FC } from 'react';
 
export const FullLayoutPage: FC<{username: string}> = ({username}) => {
  const menuProps = {
    user: username ? { username } : null,
    loggedOutActions: {
      loginAction: () => console.log('login action'),
    },
    toolbarContent: (
      <>
        <IconButton><NotificationsIcon /></IconButton>
        <IconButton><FavoriteIcon /></IconButton>
      </>
    ),
    headerMenuDefinition: [
      { label: 'common 1', action: [
        { label: 'Action 1', action: () => console.log('Action 1') },
        { label: 'Action 2', action: () => console.log('Action 2') },
      ]},
    ],
    sideMenuDefinition: [
      { label: 'Section 1', action: [
        { label: 'Navigation 1', action: '/path/to/location/1' },
        { label: 'Navigation 2', action: '/path/to/location/2' },
      ]},
    ],
  };
 
  return (
    <FullLayout {...menuProps}>
      {/* page content */}
    </FullLayout>
  );
};

Readme

Keywords

Package Sidebar

Install

npm i ai-kit-common

Repository

gitlab.ambient-innovation.com/ai/ai.kit/common.git

Weekly Downloads

1

Version

1.4.3

License

MIT

Unpacked Size

95.1 kB

Total Files

51

Last publish

Collaborators

  • ambient-innovation
Try on RunKit
Report malware