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

Menu

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

SwipeableDrawer Menu.

Default menu items are (in this order):

• Logo button, navigating to /
• custom menu items (topChildren)
• MenuSections, auto-generated from collections prop
• custom menu items (bottomChildren)
• Logout button, calling onLogout

Menu.props

• 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

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

This dialog requests a single text field input. It behaves similar to the ConfirmDialog, but adds a single required text field to be filled before confirm.

InputDialog.props

See ConfirmDialog.props, plus:

• required entity: name of the required text input (shown in auto-generated title and the text field)
• title: the title of the dialog (default: '<entity> information needed')
• text: content of the dialog (default: 'Please provide below information to proceed')
• async validation(value): custom value validation

• (default: val => !!val.trim() → check for non-empty string)

• only return value true will be considered successful validation
• string return value will be displayed as snackbar
• thrown error message will be displayed as snackbar

Constants

DEFAULT_THEME

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

The default material theme used for the ToolFrameUI, if none is provided via the theme prop of ToolFrame

ITEM_ACTIONS

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

Actions given as the second parameter of the onItemChange callback. Either of:

• ITEM_ACTIONS.CREATE: given on item creation in the menu
• ITEM_ACTIONS.READ: just a placeholder, never used
• ITEM_ACTIONS.UPDATE: just a placeholder, never used
• ITEM_ACTIONS.DELETE: givon on item deletion in the menu