App header - Balance Design System

The AppHeader component serves as a consistent app header for all Reckon apps.

Usage

The app header expands to fill the container by using flexGrow:1. It is up to the consumer to provide an appropriate container.

appName*

Sets the name of the app in the banner.

Testing: testid is hard coded to app-header-app-name

appVersion*

Sets the version of the app in the user menu.

Testing: testid is hard coded to app-header-user-menu-dropdown-app-version

appIconUrl

Renders a small icon next to the app name.

It will render a loading skeleton while the icon is undefined, assumed to be in loading.

userMenu*

Renders a user menu all the way to the right of the header. It contains things like user details and a dropdown menu for user management such as Settings.

Testing: The userMenu is a Dropdown under the hood with a hardcoded testid app-header-user-menu-dropdown. Testids for each menu item can be provided as per normal drop down item testing. See dropdown testing for more details.

bookInfo*

All Reckon apps are powered by a book in the backend so it's important for the user to know which book they're working on. This app presents book info to the user.

Check the sample code below for more details.

Testing:
Book name testid app-header-book-name
App name testid app-header-app-name

utlitiActions

Provide a list of utility actions such as "Help" for the user to access quickly.

appSwitcher

If the user has access to multiple apps in the Reckon ecosystem, providing a list of apps and the loading state to this prop will allow the user to switch between them.

Renders an empty state when apps list array is empty.

Error should be handled by consumers using alert dialogs.

The app switcher can be closed programatically by using the closeAppSwitcher function.

Testing: Apps are rendered using List under the hood with a hard coded testid app-header-app-switcher Testids can be passed to individual apps using the testid prop.

pages

Provide a list of pages to render a horizontal navigation menu. The navigation items can be nested. You can provide as many pages as needed without worrying about horizontal real estate, the overflowing navigation items will collapse into a dropdown menu when it runs of of space.

Check the code sample below for more details.

Testing: Testids can be passed to individual pages and groups of pages using the testid prop.

selectedPage

If the pages prop has been provided, the selectedPage prop must be provided as well so the navigation menu can highlight the page the user is on.

globalActions

Allows the user to access the most common features of your app by putting them in the header.

Testing: globalActions is a render slot that expects a Dropdown majority of the time which has testability built in. See dropdown testing for more details.

Code

Below is the code sample with all the features of an AppHeader.

Testing: Testids have been used where possible.

Edit in Playroom

// This url should come from a GQL query when getting possible apps for a user
const MOCK_LOGO_URL =
  'https://images.dev.reckoncloud.com.au/images/ReckonReckonOneApplicationLogo.svg';
const pages: AppHeaderProps['pages'] = [
  {
    label: 'Pay runs',
    href: '#pay-runs',
    match: ['pay-runs'],
    testid: 'payruns',
  },
  {
    label: 'Employees',
    href: '#employees',
    match: ['employees'],
    testid: 'employees',
  },
  {
    label: 'Compliance',
    href: '#compliance',
    testid: 'compliance',
    options: [
      {
        label: 'Compliance 1',
        href: '#compliance-1',
        match: ['compliance-1'],
        testid: 'item-1',
      },
      {
        label: 'Compliance 2',
        href: '#compliance-2',
        match: ['compliance-2'],
        testid: 'item-2',
      },
      {
        label: 'Compliance 3',
        href: '#compliance-3',
        match: ['compliance-3'],
        testid: 'item-3',
      },
    ],
  },
  {
    label: 'Liabilities',
    href: '#liabilities',
    match: ['liabilities'],
    testid: 'liabilities',
  },
  {
    label: 'Payments',
    href: '#payments',
    testid: 'payments',
    options: [
      {
        label: 'Payments 1',
        href: '#payments-1',
        match: ['payments-1'],
        testid: 'item-1',
      },
      {
        label: 'Payments 2',
        href: '#payments-2',
        match: ['payments-2'],
        testid: 'item-2',
      },
      {
        label: 'Payments 3',
        href: '#payments-3',
        match: ['payments-3'],
        testid: 'item-3',
      },
    ],
  },
  {
    label: 'Accounting',
    href: '#accounting',
    testid: 'accounting',
    options: [
      {
        label: 'Accounting 1',
        href: '#accounting-1',
        match: ['accounting-1'],
        testid: 'item-1',
      },
      {
        label: 'Accounting 2',
        href: '#accounting-2',
        match: ['accounting-2'],
        testid: 'item-2',
      },
      {
        label: 'Accounting 3',
        href: '#accounting-3',
        match: ['accounting-3'],
        testid: 'item-3',
      },
    ],
  },
  {
    label: 'Reports',
    href: '#reports',
    match: ['reports'],
    testid: 'reports',
  },
  {
    label: 'Overflow 1',
    href: '#overflow-1',
    match: ['overflow-1'],
    testid: 'overflow-1',
  },
  {
    label: 'Overflow 2',
    href: '#overflow-2',
    match: ['overflow-2'],
    testid: 'overflow-2',
  },
  {
    label: 'Overflow 3',
    href: '#overflow-3',
    testid: 'overflow-3',
    options: [
      {
        label: 'Overflow 31',
        href: '#overflow-31',
        match: ['overflow-31'],
        testid: 'item-1',
      },
      {
        label: 'Overflow 32',
        href: '#overflow-32',
        match: ['overflow-32'],
        testid: 'item-2',
      },
      {
        label: 'Overflow 33',
        href: '#overflow-33',
        match: ['overflow-33'],
        testid: 'item-3',
      },
    ],
  },
];
/**
 * Your app should figure out the apps the user is allowed to use based on their subscriptions etc.
*/
const appSwitcherProps = (): AppHeaderProps['appSwitcher'] => {
  return {
    isLoading: false,
    onEmptyStatePrimaryActionClick: () => {
      closeAppSwitcher();
    },
    apps: [
      {
        appName: 'Invoices',
        iconUrl: MOCK_LOGO_URL,
        href: '#',
        testid: 'invoices',
      },
      {
        appName: 'Access',
        iconUrl: MOCK_LOGO_URL,
        href: '#',
        testid: 'access',
      },
    ],
  };
};
return (
  <React.Fragment>
    <AppHeader
      appName="Payroll"
      appVersion="0.1.234"
      appIconUrl={MOCK_LOGO_URL}
      /** List of routes */
      pages={pages}
      /** Current pathFragment of the url. This is used to determine the selected navigation item.  */
      selectedPage="compliance-3"
      /** List of apps the user has access to. */
      appSwitcher={{...appSwitcherProps()}}
      /** Currently selected book. */
      bookInfo={{
        bookName: 'Book Name',
        onClick: () => alert('Book info clicked'),
      }}
      /** User menu for things like settings and sign out. */
      userMenu={{
        userFullName: 'Jason Smith',
        userEmail: 'jason.smith@gmail.com',
        items: (
          <React.Fragment>
            <Dropdown.Item
              startElement={<UserIcon size="small" color="muted" />}
              href="#"
              target="_blank"
              data={{ testid: 'manage-profile' }}
            >
              Manage Profile
            </Dropdown.Item>
            <Dropdown.Item
              startElement={<GridIcon size="small" color="muted" />}
              href="#"
              target="_blank"
              data={{ testid: 'go-to-platform' }}
            >
              Got to Platform
            </Dropdown.Item>
            <Dropdown.Divider />
            <Dropdown.Item
              startElement={<StarIcon size="small" color="muted" />}
              href="#"
              target="_blank"
              data={{ testid: 'upgrade' }}
            >
              Upgrade
            </Dropdown.Item>
            <Dropdown.Divider />
            <Dropdown.Item
              startElement={<StarIcon size="small" color="muted" />}
              onSelect={() => 'Sign out'}
              data={{ testid: 'sign-out' }}
            >
              Sign out
            </Dropdown.Item>
          </React.Fragment>
        ),
      }}
      /**
       * Custom actions in the header displayed next to the navigation for actions like "Add thing".
       * Use components from the buttons package.
      * */
      globalActions={
          <Dropdown align="start" data={{ testid: 'global-actions-dropdown' }}>
            <Dropdown.Trigger>
              <Dropdown.Trigger>
                {({ isOpen, triggerProps }: CustomTriggerProps) => {
                  return (
                    <Button
                      aria-label="Add new"
                      label="Add new"
                      size="small"
                      iconAfter={isOpen ? ChevronUpIcon : ChevronDownIcon}
                      {...triggerProps}
                    />
                  );
                }}
              </Dropdown.Trigger>
            </Dropdown.Trigger>
            <Dropdown.Item
              startElement={<DollarSignIcon size="small" />}
              onSelect={() => alert('Add pay run')}
              data={{ testid: 'pay-run' }}
            >
              Pay run
            </Dropdown.Item>
            <Dropdown.Item
              startElement={<UserIcon size="small" />}
              onSelect={() => alert('Add employee')}
              data={{ testid: 'employee' }}
            >
              Employee
            </Dropdown.Item>
          </Dropdown>
        }
      /** Icons next to the user menu for quick actions such as search and help. */
      utilityActions={[
        {
          key: 'SearchIcon',
          Icon: SearchIcon,
          onClick: () => alert('Search'),
          testid: 'search-icon',
        },
        {
          key: 'HelpCircleIcon',
          Icon: HelpCircleIcon,
          onClick: () => alert('Help'),
          testid: 'help-icon',
        },
        {
          key: 'SettingsIcon',
          Icon: SettingsIcon,
          onClick: () => alert('Settings'),
          testid: 'settings-icon',
        },
      ]}
    />
  </React.Fragment>
);