@g.ui/tool-frame NPM

TODO

core concepts

content: Route wrapped Content
routing (see react-router-dom) + export all that stuff from react-roueter-dom that is not used/burned internally
collections props (inkl items) STRG+F Pass an array of MenuSections.props
onItemChange(entity, action, item) erläutern, erwartet, dass via collection back to ToolFrame
notifcations hooks (see notistack but erweitert)

@g.ui/tool-frame-ui /// also in imports

React Framework for Web-Tooling.

Utilizing react-router-dom, @mui/material and notistack.

Simple use for Framing Application Logic Components with fully customizable:

Login
Navbar with Breadcrumbs and QuickAccess
Menu with home button, auto-generated MenuSections from collections, custom items and logout button
Wrapper for your application logic Contents
Routing
Notification-Snackbar

Hooks

TODO: useBreakpoint, useColor, useNotify, useSnackbar

Components

ToolFrame

import ToolFrame from '@g.ui/tool-frame'; or import { ToolFrame } from '@g.ui/tool-frame';

This is the main component to use the ToolFrameUI. This provides all the functionality for rendering the pretty tool frame around your application logic components, which you may provide as Content Routes.

ToolFrame.props

initializing: control whether a LoadingScreen is displayed above the tool (default: false)
loading: control whether loading indicator is shown in the default Navbar (default: false)
auth: controll whether your content routes should be exposed to the user (default: false)
- true: all content routes are accessible by the user
- false: content routes are unmounted, a redirect to the login is mounted, the login is displayed
application: the application name, displayed in login, and navbar (default: '')
theme: material theme to be used (default: constant DEFAULT_THEME)
collections: controls auto-generated MenuSections in the menu and NavbarBreadcrumbs and QuickAccess in the navbar. Pass an array of MenuSections.props objects. (default: [])
logo: logo component type passed to Login, MenuHomeButton and ContentNotFound (default: Logo), use false to disable logos, true equals default
menu: menu component type (default: Menu), use false for disabling menu, true equals default
navbar: navbar component type (default: Navbar), use false for disabling navbar, true equals default
quickAccess: component type of quick acccess (default: 'iconsOnly')
- true: auto-generated QuickAccess from collections
- 'iconsOnly': auto-generated QuickAccess from collections with option iconsOnly
- falsy: no QuickAccess shown
- given custom QuickAccess compatible component
login: login component type (default: Login), use false for no login, true equals default
- NOTE: false implies, that auth is circumenveted and content routes are always mounted
loadingScreen: loading screen component type (default: LoadingScreen), use false to disable loading screen, true equals default
contentNotFound: component type of 404 page (default: ContentNotFound), use false to disable content not found page, true equals default
menuProps: props to be passed to the menu component (default: { <logo>, <collection>, <onItemChange>, <onLogout> })
navbarProps: props to be passed to the navbar component (default: { <application>, <collections>, <quickAccess>, <loading>, <onLogout> })
async onItemChange(entity, action, item): callback for collection item change (add/delete item in menu section) (default: noop)
async onLogin( username, password }): callback called on login form submit, check your credentials here! (default: noop → credentials always valid)
async onLogout(): callback called on click to the logout button (default: noop → logout always successful)
children: your application logic to be framed Content Routes (default: [])

Login Components

Login

import { Login } from '@g.ui/tool-frame';

Fullscreen Grid with Logo and login fields.

Login.props

checking: control whether the login screen displays the loading spinner (default: false)
logo: logo component type to be used (default: Logo), use false for no logo
color: color of the background (only behind login fields) (default: 'secondary')
loadingSpinner: spinner component type to be used (default: LoadingSpinner), use false for no spinner
application: application name to be displayed in the headerText (default: '')
headerText: welcome text (default: 'Welcome!' or 'Welcome to <application>')
usernameLabel: label for the username field (default: 'User Name/E-Mail')
usernameAutocomplete: autocomplete prop for the username field (default: 'username email')
passwordLabel: label for the password field (default: 'Password')
loginButtonText: text of the login button (default: 'Login')
async onSubmit({ username, password }): *callback called on submit, check your credentials here! (default: async noop)
further props are proxied to the underlying Grid component

Logo

import { Logo } from '@g.ui/tool-frame';

Avatar with a tool-frame typical CMY colored background containing a Material Icon] or SvgIcon.

Logo.props

icon: icon component type to be used (default: AppsOutage)
size: size of the logo (default: 40)
color: color of the icon (default: #f8f8f8ee = slightly transparent near-white)
sx: sx passed to the underlying Avatar (default: {})
further props are proxied to the underlying Avatar component

Navbar Components

Navbar

import { Navbar } from '@g.ui/tool-frame';

AppBar Navigation.

Default Navbar items are (in this order):

Breadcrumbs to the current path
QuickAccess to <collection>/new, plus Logout button calling onLogout

Navbar.props

collections: controls auto-generated breadcrumbs and quick access if displayed. Pass an array of MenuSections.props objects. (default: [])
breadcrumbs: control which breadcrumbs are displayed (default: true)
- true: auto-generate breadcrumbs from collections, if quickAccess is true or a custom component
- falsy: no breadcrumbs (only menu button)
- array of obejcts (name*, icon?, link?) to be shown as breadcrumbs
- given custom component
application: name of the application, displayed in the first breadcrumb/menu button (default: '')
quickAccess: control what QuickAccess should be shown (default: 'iconsOnly')
- true: auto-generated QuickAccess from collections
- 'iconsOnly': auto-generated QuickAccess from collections with option iconsOnly
- falsy: no QuickAccess shown
- given custom QuickAccess compatible component
loading: control whether to show LoadingSpinner on the right (default: false)
position: position passed to the underlying AppBar (default: 'sticky')
color: color passed to the underlying AppBar (default: 'clear' → none)
sx: sx passed to the underlying AppBar (default: {} or { background: <white>, color: <primary> } if color === 'clear')
onMenuOpen(): callback called on click on the first breadcrum (= menu button) (default: noop)
onLogout(): callback called on click to the logout button (default: noop)
further props are proxied to the underlying AppBar component

NavbarBreadcrumbs

import { NavbarBreadcrumbs } from '@g.ui/tool-frame';

Breadcrumbs for use in Navbar.

Default Breadcrumbs falls back to generating them from location with help (icon) from collections.

NavbarBreadcrumbs.props

application: application name to display in the first breadcrumb (= menu button) (default: '')
collections: deliver entity names and icon component types for breadcrumbs auto-generation. pass an array of MenuSections.props objects. (default: [])
breadcrumbs: if you want to provide your own breadcrumbs, provide them here (default: [])
- falsy: no breadcrumbs, only auto-generated if fallbackToLocation
- array of obejcts (name*, icon?, link?) to be shown as breadcrumbs
- given custom component
fallbackToLocation: whether to auto-generate breadcrumbs from window location with help of collections (default: true)
- NOTE: this only auto-generates breadcrumbs if breadcrumbs is falsy or an empty array
truncation: how many charactes each breadcrumb should not exceed (default: 40)
displayThreshold: hide certain elements on displays smaller than this threshold (default: 'md')
- hides the application name when smaller than threshold
- hides the icon of all breadcrumbs when display is smaller than threshold, but the menu icon and the icon of the last crumb are always shown
- valid values are (xs → never hide, sm, md, lg, xl)
onMenuOpen(): callback called when the firs (=menu) breadcrumb is clicked (default: noop)
further props are proxied to the underlying Breadcrumbs component

NavbarBreadcrumbsItem

import { NavbarBreadcrumbsItem } from '@g.ui/tool-frame';

ListItemButton for use in NavbarBreadcrumbs.

Displays an icon, a name and navigates to a given link path.

NavbarBreadcrumbsItem.props

name: name to display (default: '')
icon: icon component type for displaying the icon. (default: Fragment → none)
link: link to be navigated to on click. (default: false → none), use false for no navigate
truncation: how many charactes each breadcrumb should not exceed (default: 40)
iconDisplayThreshold: hide icon element on displays smaller than this threshold (default: 'sm')
- valid values are (xs → never hide, sm, md, lg, xl)
further props are proxied to the underlying Breadcrumbs component
- NOTE if you overwrite the onClick() prop, no navigation will be performed, even if a link is provided

QuickAccess

import { QuickAccess } from '@g.ui/tool-frame';

Array of ListItemButtons for quick access, eg. in Navbar.

Each item consists of (from left):

IconButton using the collection `iconSingular
item.entity as Text

If no link is given in the item it will navigate to /<entity>/new.

QuickAccess.props

items: controls the items display (default: []), must be compatible with collections array (eg. passed by Navbar) but can have an extra link, so it can have this properties:
- entity: name to be displayed if not iconsOnly
- icon or iconSingular: icon to be display
- link: link to overwrite default link (default: '/<entity>/new')
iconsOnly: control whether text should be hidden (default: true)

Menu Components

logo: component type of the logo displayed on top of the menu items (default: Logo)
opened: control whether dialog is opened (default: false)
width: drawer width (default: 300)
homeButton: component type used for home button (default: MenuHomeButton), use false for disabled home button without logo
collections: controls auto-generated MenuSections listed in the menu. Pass an array of MenuSections.props objects. (default: [])
mutexEditing: whether just one MenuSection should be in editing mode concurrently (default: true)
mutexExpand: whether just on MenuSection should be expanded concurrently (default: true)
topChildren: custom menu items displayed before the auto-generated MenuSections (default: [])
bottomChildren: custom menu items displayed after the auto-generated MenuSections (default: [])
logoutButton: component type used for logout button (default: MenuLogoutButton), use false for no home button
logoutButtonPosition: list position of the logout button (default: 4)
- 0: before home button
- 1: after home button
- 2: after topChildren
- 3: after auto-generated MenuSections
- 4: after bottomChildren
async onItemChange(entity, action, item): callback for menu item change (add/delete item in section) (default: noop)
onOpen(): callback called whenever menu is opened (default: noop)
onClose(): callback called on escape, backdrop click and item click (default: noop)
onLogout(): callback called on clicking logout button (default: noop)
further props are proxied to the underlying SwipeableDrawer component

MenuHomeButton

import { MenuHomeButton } from '@g.ui/tool-frame';

ListItemButton for use as Menu.homeButton.

MenuHomeButton.props

logo: logo copmonent type to be used as only child of the ListItemButton (default: false → no logo)
disabled: whether button click should be disabled and logo hidden (default: false)
sx: sx passed to the underlying innermost ListItemButton (default: {})
further props are proxied to the underlying ListItemButton component

MenuLogoutButton

import { MenuLogoutButton } from '@g.ui/tool-frame';

ListItemButton for use as Menu.logoutButton.

MenuLogoutButton.props

text: text of the item (default: 'Logout')
onClick(): callback called on click (default: noop)
further props are proxied to the underlying ListItemButton component

MenuSection

import { MenuSection } from '@g.ui/tool-frame';

Section for the Menu consisting of:

Header with collections icon and entity name, plus (from the right)
- collapse button, if collapsable
- edit penicil, if editable
- add button, if editing and amendable
Items displaying the items name, plus
- delete button if in edit mode

All edit mode buttons (edit pencil, delete bin, add plus) are of the themes warning color if section is in edit mode.

MenuSection.props

required entity: name of the collections entity
items: array of items (default: []), rendered as MenuSectionItem, see MenuSectionItem.props.item for details
icon: material icon type for the header (default: Fragment → blank icon)
editable: control if an edit pencil is displayed to toggle editing mode (default: false)
amendable: control if an add plus is displayed in edit mode to a add an item to the colleciton (default: true)
editing: control whether section is currently in edit mode (default: false)
expandable: control whether section can be collapsed and expanded (default: false)
expanded: control whether section is currently expanded (default: false)
async onItemChange(entity, action, item): callback for item change (add/delete item) (default: noop)
onEditing(entity): callback for edit mode change (default: noop)
onCollapse(entity): callback when section collapses (default: noop)
onExpand(entity): callback when section expands (default: noop)

MenuSectionItem

import { MenuSectionItem } from '@g.ui/tool-frame';

ListItemButton for use as a MenuSection child. Contains (from left):

ChevronRight if selected
item.name as text
Delete button if editing

The item is highlighted as selected if selected.

MenuSectionItem.props

required entity: name of the collections entity
required item: item to be displayed, id (number) and name (string) property required (fallback: { id: -1, name: 'n/a' })
selected: control whether the item is highlighted as selected (default: true/false if window location ends with '/<entity>/<item.id>')
deletable: control whether delete bin is displayed (default: false)
onClick(): callback called on item click (default: noop)
onDelete(): callback called when delete bin is clicked and confirmed (default: noop)
further props are proxied to the underlying ListItemButton component

Content Components

Content

import { Content } from '@g.ui/tool-frame';

Wrapper for the content you want to be shown on a specific Content Route. It wraps the content with Box, Container, Paper and another Box in this nesting order.

NOTE: We highly recommend you put a component of type Content to the element prop of each Route you wan to be handled. This way you can control the contents to fill the ToolFrame or be displayed as a Paper on whatever position within the navbar and menu framing.

Content.props

initializing: control whether a LoadingScreen is shown above the content (default: false)
maxWidth: maxWidth of the Container (default: false → full size)
elevation: elevation ot the Paper (default: 4 or 0 if full size)
position: where the Container should be positioned, valid values are 'center', 'top', 'bottom', 'left', 'right', 'topleft', 'topright', 'bottomleft', 'bottomright' (default: 'center')
align: horizontal align of the items within the innermost Box, valid values are 'left', 'center', 'right' (default: '')
- NOTE: the Box surrounding your content will have flex-direction: column, if you set this
sx: sx passed to the underlying innermost Box (default: {})
children: your app logic content component(s) (default: [])
further props are proxied to the underlying innermost Box component

ContentNotFound

import { ContentNotFound } from '@g.ui/tool-frame';

Content filled with 404 page contents.

ContentNotFound.props

title: title of the page (default: 'Page not found!')
logo: logo component type to be used (default: Logo), use false for no logo
backButtonText: text of the button (default: 'Back to home'), use false for no button
further props are proxied to the underlying Content component

Further Components

LoadingScreen

import { LoadingScreen } from '@g.ui/tool-frame';

Backdrop with backdrop-filter and LoadingSpinner (if spinner).

NOTE: backdrop-filter is known to not be working in Firefox as of early 2022. So the background will be untouched (not grayscaled, brightened or blurred), but the backdrop will overlay a fullscreen transparent layer anyway

LoadingScreen.props

opened: control whether loading screen is currently displayed (default: false)
spinner: spinner component type to be displayed (default: LoadingSpinner), use false for no spinner
grayscale: backdrop-filter grayscale value (default: .9)
brightness: backdrop-filter brightness value (default: 1.5)
blur: backdrop-filter blur value in pixels (default: 10)
sx: sx passed to the underlying Backdrop (default: { zIndex: 'drawer', backdropFilter: 'grayscale(<grayscale>), brightness(<brightness>), blur(<blur>px)' })
further props are proxied to the underlying Backdrop component

LoadingSpinner

import { LoadingSpinner } from '@g.ui/tool-frame';

<img> loading spinner with the typical tool-frame prisma.gif.

LoadingSpinner.props

size: size of the spinner, valid values are: (default) → 40, 'small' → 30, 'large' → 60 or a custom number
rotate: control whether the spinner <img> has an css rotate animation (default: true)
- NOTE: this is additional to the rotating triangles in the gif itself
further props are proxied to the underlying <img> component

ConfirmDialog

import { ConfirmDialog } from '@g.ui/tool-frame';

This dialog consists of a simple title and text plus a cancel butten and a confirm button. Whenever you want users to confirm an action before execution, use this dialog.

ConfirmDialog.props

opened: controls whether dialog is opened (default: false)
title: the title of the dialog (default: 'Are you sure?')
text: content of the dialog (default: 'Do you really want to perform this action?')
cancelButtonText: text of the cancel button (default: 'Cancel')
confirmButtonText: text of the confirm button (default: 'OK')
color: theme color used for header and buttons (default: 'warning')
confirmOnEnter: whether an 'Enter' keyup event will be considered as confirm (default: false)
onClose(): callback called on escape, backdrop click, cancel and confirm (default: noop)
onConfirm(): callback called on confirm (default: noop)
onKeyUp(event): onKeyUp callback proxied to the underlying Dialog (default: noop)
further props are proxied to the underlying Dialog component

InputDialog