@atlaskit/side-navigation 1.1.2

package/dist/types/components/Section/skeleton-heading-item.d.ts

@@ -0,0 +1,4 @@
+import { SkeletonHeadingItemProps } from '@atlaskit/menu';
+export type { SkeletonHeadingItemProps } from '@atlaskit/menu';
+declare const SkeletonHeadingItem: (props: SkeletonHeadingItemProps) => JSX.Element | null;
+export default SkeletonHeadingItem;

package/dist/types/components/SideNavigation/index.d.ts

@@ -0,0 +1,23 @@
+/// <reference types="react" />
+export interface SideNavigationProps {
+    /**
+     *  Describes the specific role of this navigation component for users viewing the page with a screen reader.
+     *  Differentiates from other navigation components on a page.
+     */
+    label: string;
+    /**
+     * Child navigation elements.
+     * You'll want to compose children from [navigation header](/packages/navigation/side-navigation/docs/navigation-header),
+     * [navigation content](/packages/navigation/side-navigation/docs/navigation-content) or [nestable navigation content](/packages/navigation/side-navigation/docs/nestable-navigation-content),
+     * and [navigation footer](/packages/navigation/side-navigation/docs/navigation-footer).
+     */
+    children: JSX.Element[] | JSX.Element;
+    /**
+     * A `testId` prop is provided for specified elements,
+     * which is a unique string that appears as a data attribute `data-testid` in the rendered code,
+     * serving as a hook for automated tests.
+     */
+    testId?: string;
+}
+declare const SideNavigation: import("react").ForwardRefExoticComponent<SideNavigationProps & import("react").RefAttributes<HTMLElement>>;
+export default SideNavigation;

package/dist/types/components/index.d.ts

@@ -0,0 +1,22 @@
+export { default as SideNavigation } from './SideNavigation';
+export type { SideNavigationProps } from './SideNavigation';
+export { Section, HeadingItem, SkeletonHeadingItem } from './Section';
+export type { HeadingItemProps, SectionProps, SkeletonHeadingItemProps, } from './Section';
+export { default as NestingItem } from './NestingItem';
+export type { NestingItemProps } from './NestingItem';
+export { default as NavigationContent } from './NavigationContent';
+export type { NavigationContentProps } from './NavigationContent';
+export { ButtonItem, GoBackItem, LinkItem, CustomItem, SkeletonItem, } from './Item';
+export type { CustomItemComponentProps, CustomItemProps, ButtonItemProps, GoBackItemProps, LinkItemProps, SkeletonItemProps, } from './Item';
+export { default as Footer } from './Footer';
+export type { FooterProps } from './Footer';
+export { default as Header } from './Header';
+export type { HeaderProps } from './Header';
+export { default as NavigationHeader } from './NavigationHeader';
+export type { NavigationHeaderProps } from './NavigationHeader';
+export { default as NavigationFooter } from './NavigationFooter';
+export type { NavigationFooterProps } from './NavigationFooter';
+export { default as LoadingItems } from './LoadingItems';
+export type { LoadingItemsProps } from './LoadingItems';
+export { default as NestableNavigationContent } from './NestableNavigationContent';
+export type { NestableNavigationContentProps } from './NestableNavigationContent';

package/dist/types/index.d.ts

@@ -0,0 +1,4 @@
+export { SideNavigation, Header, NavigationHeader, NavigationContent, Section, HeadingItem, SkeletonHeadingItem, NestableNavigationContent, NestingItem, ButtonItem, LinkItem, GoBackItem, CustomItem, SkeletonItem, Footer, NavigationFooter, LoadingItems, } from './components';
+export type { CustomItemComponentProps, CustomItemProps, LoadingItemsProps, ButtonItemProps, FooterProps, GoBackItemProps, HeaderProps, HeadingItemProps, LinkItemProps, NavigationContentProps, NavigationFooterProps, NavigationHeaderProps, NestableNavigationContentProps, NestingItemProps, SectionProps, SideNavigationProps, SkeletonHeadingItemProps, SkeletonItemProps, } from './components';
+export { useShouldNestedElementRender } from './components/NestableNavigationContent/context';
+export { VAR_SCROLL_INDICATOR_COLOR, VAR_SEPARATOR_COLOR, } from './common/constants';

package/docs/00-intro.tsx

@@ -0,0 +1,70 @@
+import React from 'react';
+
+import { code, Example, md } from '@atlaskit/docs';
+
+export default md`
+
+  ## Documentation
+
+  All the documentation can be found in the **sidebar nav links**  👈
+
+  - [Side navigation](side-navigation/docs/side-navigation)
+  - [Navigation header](side-navigation/docs/navigation-header)
+  - [Navigation content](side-navigation/docs/navigation-content)
+  - [Nestable navigation content](side-navigation/docs/nestable-navigation-content)
+  - [Navigation footer](side-navigation/docs/navigation-content)
+  - [Loading states](side-navigation/docs/loading-states)
+  - [Button item](side-navigation/docs/button-item)
+  - [Custom item](side-navigation/docs/custom-item)
+  - [Go back item](side-navigation/docs/go-back-item)
+  - [Link item](side-navigation/docs/link-item)
+  - [Nesting item](side-navigation/docs/nesting-item)
+  - [Heading item](side-navigation/docs/heading-item)
+  - [Section](side-navigation/docs/section)
+  - [Skeleton item](side-navigation/docs/skeleton-item)
+  - [Skeleton heading item](side-navigation/docs/skeleton-heading-item)
+
+  ## Usage
+
+  ${code`
+import {
+  SideNavigation,
+  Section,
+  NavigationHeader,
+  Header,
+  NestableNavigationContent,
+  ButtonItem,
+  NestingItem,
+  Footer,
+  NavigationFooter,
+} from '@atlaskit/side-navigation';
+
+<SideNavigation label="project">
+  <NavigationHeader>
+    <Header>NXTGen Industries</Header>
+  </NavigationHeader>
+  <NestableNavigationContent>
+    <Section>
+      <ButtonItem>Your work</ButtonItem>
+      <NestingItem title="Filters">
+        <Section>
+          <ButtonItem>Search issues</ButtonItem>
+        </Section>
+      </NestingItem>
+    </Section>
+  </NestableNavigationContent>
+  <NavigationFooter>
+    <Footer>You're in a next-gen project</Footer>
+  </NavigationFooter>
+</SideNavigation>
+  `}
+
+  ${(
+    <Example
+      title=""
+      Component={require('../examples/00-nested-side-navigation').default}
+      source={require('!!raw-loader!../examples/00-nested-side-navigation')}
+      packageName="@atlaskit/sidebar-navigation"
+    />
+  )}
+`;

package/docs/01-side-navigation.tsx

@@ -0,0 +1,33 @@
+import React from 'react';
+
+import { code, Example, md, Props } from '@atlaskit/docs';
+
+export default md`
+  This is the root component you should use every time you want a side navigation experience.
+  It will take up \`100%\` of its parents height & width -
+  so make sure you place it into an element that **has its height & width explicitly set**.
+  Comes with a minimum width of \`240px\`.
+
+  ${code`highlight=1,3,5
+import { SideNavigation } from '@atlaskit/side-navigation';
+
+<SideNavigation label="project">
+  ...
+</SideNavigation>
+  `}
+
+  ${(
+    <Example
+      title=""
+      Component={require('../examples/side-navigation.tsx').default}
+      source={require('!!raw-loader!../examples/side-navigation.tsx')}
+    />
+  )}
+
+  ${(
+    <Props
+      heading="Props"
+      props={require('!!extract-react-types-loader!../src/components/SideNavigation')}
+    />
+  )}
+`;

package/docs/02-navigation-header.tsx

@@ -0,0 +1,39 @@
+import React from 'react';
+
+import { code, Example, md, Props } from '@atlaskit/docs';
+
+export default md`
+  Header for the side navigation that is composed of navigation header and header components.
+  By default it will _not be interactive_ -
+  however you can pass in your own custom component to make it interactive.
+
+  ${code`
+import { NavigationHeader, Header } from '@atlaskit/side-navigation';
+
+<NavigationHeader>
+  <Header>My header</Header>
+</NavigationHeader>
+  `}
+
+  ${(
+    <Example
+      title=""
+      Component={require('../examples/navigation-header.tsx').default}
+      source={require('!!raw-loader!../examples/navigation-header.tsx')}
+    />
+  )}
+
+  ${(
+    <Props
+      heading="Navigation header props"
+      props={require('!!extract-react-types-loader!../src/components/NavigationHeader')}
+    />
+  )}
+
+  ${(
+    <Props
+      heading="Header props"
+      props={require('!!extract-react-types-loader!../src/components/Header')}
+    />
+  )}
+`;

package/docs/03-navigation-content.tsx

@@ -0,0 +1,40 @@
+import React from 'react';
+
+import { code, Example, md, Props } from '@atlaskit/docs';
+
+export default md`
+  Used as the container for navigation items.
+  This is useful for a single level navigation with no need for nested views.
+  If you have a need for that -
+  you'll want to check out the [nestable navigation content](/packages/navigation/side-navigation/docs/nestable-navigation-content) component!
+
+  ${code`highlight=1,7,11
+import { NavigationContent } from '@atlaskit/side-navigation';
+
+<NavigationHeader label="project">
+  <NavigationHeader>
+    <Header>Money machine</Header>
+  </NavigationHeader>
+  <NavigationContent>
+    <Section>
+      <ButtonItem>Print money</ButtonItem>
+    </Section>
+  </NavigationContent>
+</NavigationHeader>
+  `}
+
+  ${(
+    <Example
+      title=""
+      Component={require('../examples/navigation-content').default}
+      source={require('!!raw-loader!../examples/navigation-content')}
+    />
+  )}
+
+  ${(
+    <Props
+      heading="Props"
+      props={require('!!extract-react-types-loader!../src/components/NavigationContent')}
+    />
+  )}
+`;

package/docs/04-nestable-navigation-content.tsx

@@ -0,0 +1,95 @@
+import React from 'react';
+
+import { code, Example, md, Props } from '@atlaskit/docs';
+
+export default md`
+  Used as the container for navigation items with nested views.
+  If you have no need for nested views you'll want to check out the [navigation content](/packages/navigation/side-navigation/docs/navigation-content) component instead!
+
+  Nested views are enabled by composing [nesting item](/packages/navigation/side-navigation/docs/nesting-item) components inside this one.
+
+  ${code`highlight=1-4,10-11,15-16
+import {
+  NestableNavigationContent,
+  NestingItem
+} from '@atlaskit/side-navigation';
+
+<NavigationHeader label="project">
+  <NavigationHeader>
+    <Header>Money machine</Header>
+  </NavigationHeader>
+  <NestableNavigationContent>
+    <Section>
+      <NestingItem title="Print money">
+        <Section>
+          <ButtonItem>Money printed</ButtonItem>
+        </Section>
+      </NestingItem>
+    </Section>
+  </NestableNavigationContent>
+</NavigationHeader>
+  `}
+
+  ${(
+    <Example
+      title=""
+      Component={require('../examples/00-nested-side-navigation').default}
+      source={require('!!raw-loader!../examples/00-nested-side-navigation')}
+    />
+  )}
+
+  ${(
+    <Props
+      heading="Props"
+      props={require('!!extract-react-types-loader!../src/components/NestableNavigationContent')}
+    />
+  )}
+
+  ## Custom children
+
+  Sometimes you'll want to use components that aren't supplied by this library,
+  and that's great!
+  However you'll need to know that when you do if you don't opt into our "should I render" hook -
+  your element will be rendered on _every_ nested view,
+  which may or may not be what you want to happen.
+
+  When writing a leaf node component,
+  you'll want to conditionally return \`null\`:
+
+  ${code`
+import { useShouldNestedElementRender } from '@atlaskit/side-navigation';
+
+const CustomLeafNode = props => {
+  const { shouldRender } = useShouldNestedElementRender();
+  if (!shouldRender) {
+    return null;
+  }
+  return <div>hello world</div>;
+);
+  `}
+
+  When writing a wrapping component,
+  you'll want to conditionally return \`children\`:
+
+  ${code`
+import { useShouldNestedElementRender } from '@atlaskit/side-navigation';
+
+const CustomWrapper = props => {
+  const { shouldRender } = useShouldNestedElementRender();
+  if (!shouldRender) {
+    return props.children;
+  }
+  return <div>{props.children}</div>;
+);
+  `}
+
+  You can see an example of this below.
+
+  ${(
+    <Example
+      title=""
+      Component={require('../examples/custom-nested-children').default}
+      source={require('!!raw-loader!../examples/custom-nested-children')}
+    />
+  )}
+`;

package/docs/05-navigation-footer.tsx

@@ -0,0 +1,38 @@
+import React from 'react';
+
+import { code, Example, md, Props } from '@atlaskit/docs';
+
+export default md`
+  Footer for the side navigation that is composed of navigation footer and footer components.
+  Like the header if you pass an interactive element as the custom component to the footer it will appear interactive.
+
+  ${code`
+import { NavigationFooter, Footer } from '@atlaskit/side-navigation';
+
+<NavigationFooter>
+  <Footer>My footer</Footer>
+</NavigationFooter>
+  `}
+
+  ${(
+    <Example
+      title=""
+      Component={require('../examples/navigation-footer.tsx').default}
+      source={require('!!raw-loader!../examples/navigation-footer.tsx')}
+    />
+  )}
+
+  ${(
+    <Props
+      heading="Navigation footer props"
+      props={require('!!extract-react-types-loader!../src/components/NavigationFooter')}
+    />
+  )}
+
+  ${(
+    <Props
+      heading="Footer props"
+      props={require('!!extract-react-types-loader!../src/components/Footer')}
+    />
+  )}
+`;

package/docs/99-loading-states.tsx

@@ -0,0 +1,95 @@
+import React from 'react';
+
+import { code, Example, md, Props } from '@atlaskit/docs';
+
+export default md`
+  Occasionally you will need to asynchronously load some of your side nav.
+  There are a few things to take care of:
+
+  1. Only use skeletons when you're quite certain of what the loaded state will look like.
+  The majority of items that would appear in side navigation are probably fine to use with skeletons,
+  for example \`@atlaskit/tree\`
+  1. When transitioning from loading skeleton to loaded items try to ensure the jump does not look janky - use the equivalent skeleton item that is appropriate and be careful of things jumping around by a few pixels
+  We should be striving for UI that **feels solid**,
+  which means it doesn't jump around
+  1. Ensure loading does not take _too_ long - try to anticipate if a user will look at your menu via hover events and the like and pre-load the data as soon as you can
+  1. When content is loading in make sure it all loads in at once altogether - our minds aren't fast enough to distinguish each item loading individually for example,
+  and it would appear slower to the majority of users
+
+  For a more in-depth look at how to approach loading states have our _work in progress_ [Skeleton exploration](https://hello.atlassian.net/wiki/spaces/ADG/pages/598816601/Loading+experiences+-+3.4+-+Guideline+exploration+-+Skeleton#Exploration-(spec)) (only Atlassians will be able to access this link unfortuntely).
+
+  ${code`highlight=1,9-17,21
+import {
+  LoadingItems,
+  SectionHeading,
+  SkeletonItem
+} from '@atlaskit/side-navigation';
+
+<SideNavigation>
+  <NavigationContent>
+    <LoadingItems
+      isLoading={isLoading}
+      fallback={
+        <>
+          <SectionHeading>Project settings</SectionHeading>
+          <SkeletonItem />
+        </>
+      }
+    >
+      <Section title="Project settings">
+        <ButtonItem>Details</ButtonItem>
+      </Section>
+    </LoadingItems>
+  <NavigationContent>
+<SideNavigation>
+  `}
+
+  ${(
+    <Example
+      title=""
+      Component={require('../examples/07-loading-section.tsx').default}
+      source={require('!!raw-loader!../examples/07-loading-section.tsx')}
+    />
+  )}
+
+  ${(
+    <Props
+      heading="Props"
+      props={require('!!extract-react-types-loader!../src/components/LoadingItems')}
+    />
+  )}
+
+  ## React Suspense
+
+  If you're using [Suspense](https://reactjs.org/docs/code-splitting.html#reactlazy) you'll want to use it instead of using the loading items component.
+  Unfortunately you won't be able to cross-fade between states,
+  but you will simplify your code quite a bit.
+
+  ${code`highlight=1,6-15
+import { Suspense } from 'react';
+import { SectionHeading, SkeletonItem } from '@atlaskit/side-navigation';
+
+<SideNavigation>
+  <NavigationContent>
+    <Suspense
+      fallback={
+        <>
+          <SectionHeading>Project settings</SectionHeading>
+          <SkeletonItem />
+        </>
+      }
+    >
+      <LazyItems />
+    </Suspense>
+  <NavigationContent>
+<SideNavigation>
+  `}
+
+  ${(
+    <Example
+      title=""
+      Component={require('../examples/08-suspense-loading-section.tsx').default}
+      source={require('!!raw-loader!../examples/08-suspense-loading-section.tsx')}
+    />
+  )}
+`;