@lightspeed/cirrus-sidebar v1.0.2

Sidebar

The composable and reusable <Sidebar> component. Since these components are very flexible, it's recommended to build your own abstraction specific to your product on top of this.

ℹ️ Note: The implementation of the breakpoints (when to hide) and animation is up to the consumer of this package as of now.

Installation

First, make sure you have been through the install steps steps required to add Flame in your application. Although it's not required to have Flame installed to use Logo, you will need to install its peer dependencies.

If using Yarn:

yarn add @lightspeed/cirrus-sidebar

Or using npm:

npm i -S @lightspeed/cirrus-sidebar

Styles

Because the <Sidebar> is completely unknown in what environment it's being rendered and at what breakpoints the sidebar should hide, we open up a couple of animation styles for you to use.

These styles are exposed at @lightspeed/cirrus-sidebar/styles. These constants are exposed at @lightspeed/cirrus-sidebar/styles/constants.

Example

import styled from '@emotion/styled';
import { slideInDurationMs, slideInBezier } from '@lightspeed/cirrus-sidebar/styles';
import { PAGE_HEADER_HEIGHT, SIDEBAR_WIDTH } from '@lightspeed/cirrus-sidebar/styles/constants';
import { Sidebar } from '@lightspeed/cirrus-sidebar';

const SidebarWrapper = styled.div`
  position: absolute;
  left: -${SIDEBAR_WIDTH}px;
  top: 0;
  bottom: 0;
  transition: left ${slideInDurationMs} ${slideInBezier};

  ${props => props.active && 'left: 0;'}
  @media (min-device-width: 480px) {
    left: 0;
  }
`;

const App = () => (
  <SidebarWrapper>
    <Sidebar>Sidebar content here</Sidebar>
  </SidebarWrapper>
);

export default App;

Full featured Sidebar

Example

import React from 'react';
import { Text } from '@lightspeed/cirrus-text';
import Icon from '@lightspeed/cirrus-icon';
import {
  Sidebar,
  SidebarHeader,
  SidebarAppSwitcher,
  SidebarShopButton,
  SidebarDropdownButton,
  SidebarAccountDropdown,
  SidebarMenu,
  SidebarMenuItem,
  SidebarItem,
  SidebarNotificationBadge,
  SidebarNav,
  SidebarFooter,
  SidebarFooterItem,
} from '@lightspeed/cirrus-sidebar';

const items = [
  { icon: <Icon name="home" />, children: 'Home', href: '/', active: true },
  { icon: <Icon name="statistics" />, children: 'Statistics', href: 'statistics' },
  {
    icon: <Icon name="orders" />,
    children: 'Orders',
    href: 'orders',
    hasSublevel: true,
    notifications: <SidebarNotificationBadge>2</SidebarNotificationBadge>,
  },
  { icon: <Icon name="products" />, children: 'Products', href: 'products', hasSublevel: true },
  { icon: <Icon name="customers" />, children: 'Customers', href: 'customers', hasSublevel: true },
  { icon: <Icon name="design" />, children: 'Design', href: 'themes', hasSublevel: true },
  { icon: <Icon name="content" />, children: 'Content', href: 'pages', hasSublevel: true },
  {
    icon: <Icon name="discount-rules" />,
    children: 'Marketing',
    href: 'discount_codes',
    hasSublevel: true,
  },
  {
    icon: <Icon name="blogs" />,
    children: 'Blogs',
    href: 'blogs',
    onClick: e => {
      e.preventDefault();
      console.log('You can also just hook into the item through onClick!');
    },
    hasSublevel: true,
  },
  {
    icon: <Icon name="apps" />,
    children: 'Apps',
    href: 'store/apps/dashboard',
    disabled: true,
    hasSublevel: true,
  },
  { icon: <Icon name="tools" />, children: 'Tools', href: 'imports', hasSublevel: true },
  { icon: <Icon name="settings" />, children: 'Settings', href: 'settings', disabled: true },
];

class MyComponent extends React.Component {
  constructor(props) {
    super(props);

    this.state = {
      isUserMenuOpen: false,
    };

    this.openUserMenu = this.openUserMenu.bind(this);
    this.closeUserMenu = this.closeUserMenu.bind(this);
  }

  openUserMenu() {
    this.setState(() => ({
      isUserMenuOpen: true,
    }));
  }

  closeUserMenu() {
    this.setState(() => ({
      isUserMenuOpen: true,
    }));
  }

  render() {
    const { isUserMenuOpen } = this.state;

    return (
      <div>
        <Sidebar>
          <SidebarHeader>
            <SidebarAppSwitcher
              currentProduct="ecom"
              canSwitchTo={[{ name: 'retail', href: '/retail' }]}
            />

            <SidebarShopButton>
              <Text color="snow">SEOshop</Text>
              <Text color="snow">http://shop1.webshopapp.dev/</Text>
            </SidebarShopButton>

            <SidebarAccountDropdown
              isOpen={isUserMenuOpen}
              onOpen={this.openUserMenu}
              onClose={this.closeUserMenu}
              target={({ targetProps, targetEvents }) => (
                <SidebarDropdownButton {...targetProps} {...targetEvents} active={isUserMenuOpen}>
                  Awesome Merchant
                </SidebarDropdownButton>
              )}
            >
              <SidebarMenu>
                <SidebarMenuItem href="#">Tasks</SidebarMenuItem>
                <SidebarMenuItem href="#">My Account</SidebarMenuItem>
                <SidebarMenuItem href="#" danger>
                  Logout
                </SidebarMenuItem>
              </SidebarMenu>
            </SidebarAccountDropdown>
          </SidebarHeader>

          <SidebarNav>
            <ul>
              {items.map(item => (
                <SidebarItem key={item.title} {...item} />
              ))}
            </ul>
          </SidebarNav>

          <SidebarFooter>
            <SidebarFooterItem
              icon={<Icon name="help" />}
              href="#"
              target="_blank"
              rel="noopener noreferrer"
            >
              Help
            </SidebarFooterItem>

            <SidebarFooterItem icon={<Icon name="search" />} href="#">
              Search
            </SidebarFooterItem>
          </SidebarFooter>
        </Sidebar>
      </div>
    );
  }
}

export default MyComponent;

Sidebar

The wrapper of the sidebar (controls the width and color).

Props

Example

import React from 'react';
import { Sidebar } from '@lightspeed/cirrus-sidebar';

const App = () => <Sidebar>My content here</Sidebar>;

export default App;

SidebarHeader

The top part of the sidebar (contains the appswitcher, shopbutton and account menu). This element divides the top part of the sidebar from the main navigation and the footer.

Props

Example

import React from 'react';
import { Sidebar, SidebarHeader } from '@lightspeed/cirrus-sidebar';

const App = () => (
  <Sidebar>
    <SidebarHeader>Your header stuff here</SidebarHeader>

    <nav>Other stuff here</nav>
  </Sidebar>
);

export default App;

SidebarAppSwitcher

This component is responsible for showing the correct current app and what apps the user can switch to.

Props

AppsConfig

The apps config is an object with the key being the app identifier and the value being the app logo. This allows you to then use these as the currentProduct and within the switchable apps array.

Note: This does not override existing apps (e.g. retail and ecom will still remain available)

Example

const appsConfig = {
  customApp: <svg />,
  anotherApp: <svg />,
};

<SidebarAppSwitcher
  appsConfig={appsConfig}
  currentProduct="customApp"
  canSwitchTo={[{ name: 'retail', href: '/retail' }, { name: 'anotherApp', href: '/another-app' }]}
/>;

Example

User is not able to switch between products

import React from 'react';
import { Sidebar, SidebarHeader, SidebarAppSwitcher } from '@lightspeed/cirrus-sidebar';

const App = () => (
  <Sidebar>
    <SidebarHeader>
      <SidebarAppSwitcher currentProduct="ecom" />
    </SidebarHeader>
  </Sidebar>
);

export default App;

User can switch to retail

import React from 'react';
import { Sidebar, SidebarHeader, SidebarAppSwitcher } from '@lightspeed/cirrus-sidebar';

const App = () => (
  <Sidebar>
    <SidebarHeader>
      <SidebarAppSwitcher
        currentProduct="ecom"
        canSwitchTo={[{ name: 'retail', href: '/retail' }]}
      />
    </SidebarHeader>
  </Sidebar>
);

export default App;

User can switch to retail through onClick

import React from 'react';
import { Sidebar, SidebarHeader, SidebarAppSwitcher } from '@lightspeed/cirrus-sidebar';

const App = () => (
  <Sidebar>
    <SidebarHeader>
      <SidebarAppSwitcher
        currentProduct="ecom"
        canSwitchTo={[
          {
            name: 'retail',
            onClick: e => {
              e.preventDefault();
              router.goTo('/retail');
            },
          },
        ]}
      />
    </SidebarHeader>
  </Sidebar>
);

export default App;

With custom config

import React from 'react';
import { Sidebar, SidebarHeader, SidebarAppSwitcher } from '@lightspeed/cirrus-sidebar';

const App = () => (
  <Sidebar>
    <SidebarHeader>
      <SidebarAppSwitcher
        appsConfig={{ customProduct: '🔥' }}
        currentProduct="ecom"
        canSwitchTo={[
          { name: 'retail', href: '/retail' },
          { name: 'customProduct', href: '/custom-product' },
        ]}
      />
    </SidebarHeader>
  </Sidebar>
);

export default App;

Add link to logo

import React from 'react';
import { Sidebar, SidebarHeader, SidebarAppSwitcher } from '@lightspeed/cirrus-sidebar';

const App = () => (
  <Sidebar>
    <SidebarHeader>
      <SidebarAppSwitcher logoProps={{ href: '/' }} currentProduct="ecom" />
    </SidebarHeader>
  </Sidebar>
);

export default App;

Add data attribute to trigger button

import React from 'react';
import { Sidebar, SidebarHeader, SidebarAppSwitcher } from '@lightspeed/cirrus-sidebar';

const App = () => (
  <Sidebar>
    <SidebarHeader>
      <SidebarAppSwitcher
        triggerProps={{ 'data-test': 'sidebar-product-trigger' }}
        currentProduct="ecom"
      />
    </SidebarHeader>
  </Sidebar>
);

export default App;

SidebarShopButton

The button that is all around the current shop and register.

Props

Example

import React from 'react';
import { Text } from '@lightspeed/cirrus-text';
import { SidebarShopButton } from '@lightspeed/cirrus-sidebar';

const App = () => (
  <Sidebar>
    <SidebarHeader>
      <SidebarShopButton onClick={() => router.goTo('/switch')}>
        <Text color="snow">SEOshop</Text>
        <Text color="snow">http://shop1.webshopapp.dev/</Text>
      </SidebarShopButton>
    </SidebarHeader>
  </Sidebar>
);

export default App;

SidebarDropdownButton

The dropdown button that is used for opening menus (contains an icon that indicates that a menu will open). See <SidebarAccountDropdown> for an example.

Props

SidebarMenu

See <SidebarAccountDropdown> for an example.

Props

SidebarMenuItem

The menu item for the <SidebarMenu>. See <SidebarAccountDropdown> for an example.

Props

Example

SidebarAccountDropdown

The Sidebar popover menu. Renders a cirrus-popover with some customized positional styles.

Props

Example

import React from 'react';
import { Text } from '@lightspeed/cirrus-text';
import {
  Sidebar,
  SidebarHeader,
  SidebarAccountDropdown,
  SidebarDropdownButton,
  SidebarMenu,
  SidebarMenuItem,
} from '@lightspeed/cirrus-sidebar';

class MyComponent extends React.Component {
  constructor(props) {
    super(props);

    this.state = {
      isUserMenuOpen: false,
    };

    this.openUserMenu = this.openUserMenu.bind(this);
    this.closeUserMenu = this.closeUserMenu.bind(this);
  }

  openUserMenu() {
    this.setState(() => ({
      isUserMenuOpen: true,
    }));
  }

  closeUserMenu() {
    this.setState(() => ({
      isUserMenuOpen: true,
    }));
  }

  render() {
    const { isUserMenuOpen } = this.state;

    return (
      <Sidebar>
        <SidebarHeader>
          <SidebarAccountDropdown
            isOpen={isUserMenuOpen}
            onOpen={this.openUserMenu}
            onClose={this.closeUserMenu}
            target={({ targetProps, targetEvents }) => (
              <SidebarDropdownButton {...targetProps} {...targetEvents} active={isUserMenuOpen}>
                Awesome Merchant
              </SidebarDropdownButton>
            )}
          >
            <SidebarMenu>
              <SidebarMenuItem href="#">Tasks</SidebarMenuItem>
              <SidebarMenuItem href="#">My Account</SidebarMenuItem>
              <SidebarMenuItem href="#" danger>
                Logout
              </SidebarMenuItem>
            </SidebarMenu>
          </SidebarAccountDropdown>
        </SidebarHeader>
      </Sidebar>
    );
  }
}

export default MyComponent;

SidebarNav

The <nav> element styled for the Sidebar.

Note: Automatically removes the list-style from a direct child <ul> tag.

Props

Example

import React from 'react';
import { Text } from '@lightspeed/cirrus-text';
import { Sidebar, SidebarHeader, SidebarNav } from '@lightspeed/cirrus-sidebar';

const App = () => (
  <Sidebar>
    <SidebarHeader>The header here</SidebarHeader>

    <SidebarNav>
      <ul>
        <li>Your nav items here</li>
      </ul>
    </SidebarNav>
  </Sidebar>
);

export default App;

SidebarItem

The sidebar navigation link (<a>).

Props

Example

Using href

import React from 'react';
import Icon from '@lightspeed/cirrus-icon';
import { Text } from '@lightspeed/cirrus-text';
import { Sidebar, SidebarHeader, SidebarNav, SidebarItem } from '@lightspeed/cirrus-sidebar';

const App = () => (
  <Sidebar>
    <SidebarHeader>The header here</SidebarHeader>

    <SidebarNav>
      <ul>
        <li>
          <SidebarItem icon={<Icon name="home" />} href="/">
            Home
          </SidebarItem>
        </li>
      </ul>
    </SidebarNav>
  </Sidebar>
);

export default App;

Using onClick

When passing onClick, you should still pass a href as well, to indicate that the element is interactable.

import React from 'react';
import Icon from '@lightspeed/cirrus-icon';
import { Text } from '@lightspeed/cirrus-text';
import { Sidebar, SidebarHeader, SidebarNav, SidebarItem } from '@lightspeed/cirrus-sidebar';

const App = () => (
  <Sidebar>
    <SidebarHeader>The header here</SidebarHeader>

    <SidebarNav>
      <ul>
        <li>
          <SidebarItem
            icon={<Icon name="home" />}
            href="/"
            onClick={e => {
              e.preventDefault();
              router.goTo('/');
            }}
          >
            Home
          </SidebarItem>
        </li>
      </ul>
    </SidebarNav>
  </Sidebar>
);

export default App;

SidebarNotificationBadge

The notification badge that can be used within the <SidebarItem />'s notifications prop.

Props

Example

import React from 'react';
import Icon from '@lightspeed/cirrus-icon';
import { Text } from '@lightspeed/cirrus-text';
import {
  Sidebar,
  SidebarHeader,
  SidebarNav,
  SidebarItem,
  SidebarNotificationBadge,
} from '@lightspeed/cirrus-sidebar';

const App = () => (
  <Sidebar>
    <SidebarHeader>The header here</SidebarHeader>

    <SidebarNav>
      <ul>
        <li>
          <SidebarItem
            icon={<Icon name="home" />}
            href="/"
            notifications={<SidebarNotificationBadge>2</SidebarNotificationBadge>}
          >
            Home
          </SidebarItem>
        </li>
      </ul>
    </SidebarNav>
  </Sidebar>
);

export default App;

SidebarFooter

The <footer> styled for the Sidebar

Props

Example

import React from 'react';
import Icon from '@lightspeed/cirrus-icon';
import { Text } from '@lightspeed/cirrus-text';
import { Sidebar, SidebarHeader, SidebarNav, SidebarFooter } from '@lightspeed/cirrus-sidebar';

const App = () => (
  <Sidebar>
    <SidebarHeader>The header here</SidebarHeader>
    <SidebarNav>Nav here</SidebarNav>
    <SidebarFooter>The Footer goes here</SidebarFooter>
  </Sidebar>
);

export default App;

SidebarFooterItem

The items that go inside the footer (renders a <a>).

Props

Example

import React from 'react';
import Icon from '@lightspeed/cirrus-icon';
import { Text } from '@lightspeed/cirrus-text';
import {
  Sidebar,
  SidebarHeader,
  SidebarNav,
  SidebarFooter,
  SidebarFooterItem,
} from '@lightspeed/cirrus-sidebar';

const App = () => (
  <Sidebar>
    <SidebarHeader>The header here</SidebarHeader>
    <SidebarNav>Nav here</SidebarNav>
    <SidebarFooter>
      <SidebarFooterItem icon={<Icon name="help" />} href="/help">
        Help
      </SidebarFooterItem>
    </SidebarFooter>
  </Sidebar>
);

export default App;