@atlaskit/side-navigation 1.2.14 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@atlaskit/side-navigation",
-  "version": "1.2.14",
+  "version": "1.3.0",
   "description": "A highly composable side navigation component that supports nested views.",
   "publishConfig": {
     "registry": "https://registry.npmjs.org/"
@@ -12,6 +12,13 @@
   "module": "dist/esm/index.js",
   "module:es2019": "dist/es2019/index.js",
   "types": "dist/types/index.d.ts",
+  "typesVersions": {
+    ">=4.0 <4.5": {
+      "*": [
+        "dist/types-ts4.0/*"
+      ]
+    }
+  },
   "sideEffects": false,
   "atlaskit:src": "src/index.tsx",
   "atlassian": {
@@ -25,13 +32,13 @@
   },
   "dependencies": {
     "@atlaskit/ds-lib": "^2.1.0",
-    "@atlaskit/icon": "^21.10.0",
+    "@atlaskit/icon": "^21.11.0",
     "@atlaskit/menu": "^1.3.0",
     "@atlaskit/motion": "^1.2.0",
-    "@atlaskit/theme": "^12.1.0",
+    "@atlaskit/theme": "^12.2.0",
     "@atlaskit/tokens": "^0.10.0",
     "@babel/runtime": "^7.0.0",
-    "@emotion/core": "^10.0.9"
+    "@emotion/react": "^11.7.1"
   },
   "peerDependencies": {
     "react": "^16.8.0"
@@ -40,14 +47,14 @@
     "@atlaskit/atlassian-navigation": "^2.2.0",
     "@atlaskit/button": "^16.3.0",
     "@atlaskit/docs": "*",
-    "@atlaskit/logo": "^13.8.0",
-    "@atlaskit/onboarding": "^10.5.0",
-    "@atlaskit/section-message": "^6.0.0",
-    "@atlaskit/select": "^15.6.0",
+    "@atlaskit/logo": "^13.10.0",
+    "@atlaskit/onboarding": "^10.6.0",
+    "@atlaskit/section-message": "^6.3.0",
+    "@atlaskit/select": "^15.7.0",
     "@atlaskit/visual-regression": "*",
     "@atlaskit/webdriver-runner": "*",
     "@atlassian/atlassian-frontend-prettier-config-1.0.1": "npm:@atlassian/atlassian-frontend-prettier-config@1.0.1",
-    "@testing-library/react": "^8.0.1",
+    "@testing-library/react": "^12.1.5",
     "@types/jest-axe": "^3.5.0",
     "ast-types": "^0.13.3",
     "jest-axe": "^4.0.0",
@@ -55,7 +62,7 @@
     "jscodeshift": "^0.13.0",
     "raf-stub": "^2.0.1",
     "react-beautiful-dnd": "^12.1.1",
-    "typescript": "4.3.5"
+    "typescript": "4.5.5"
   },
   "techstack": {
     "@atlassian/frontend": {

package/report.api.md

@@ -1,6 +1,8 @@
-## API Report File for "@atlaskit/side-navigation"
+## API Report File for "@atlaskit/side-navigation".
 
-> Do not edit this file. It is a report generated by [API Extractor](https://api-extractor.com/).
+> Do not edit this file. This report is auto-generated by [API Extractor](https://api-extractor.com/).
+
+[Learn more about API reports](https://hello.atlassian.net/wiki/spaces/UR/pages/1825484529/Package+API+Reports)
 
 ```ts
 /// <reference types="react" />
@@ -12,6 +14,7 @@ import { CustomItemProps } from '@atlaskit/menu';
 import { ForwardRefExoticComponent } from 'react';
 import { HeadingItemProps } from '@atlaskit/menu';
 import { HTMLAttributes } from 'react';
+import { jsx } from '@emotion/react';
 import { LinkItemProps } from '@atlaskit/menu';
 import { Overrides } from '@atlaskit/menu';
 import { default as React_2 } from 'react';
@@ -20,6 +23,15 @@ import { RefAttributes } from 'react';
 import { SkeletonHeadingItemProps } from '@atlaskit/menu';
 import { SkeletonItemProps } from '@atlaskit/menu';
 
+/**
+ * __Button item__
+ *
+ * A button item renders an item wrapped in a button tag, used primarily when an
+ * action does something other than changing routes.
+ *
+ * - [Examples](https://atlassian.design/components/side-navigation/examples#button-item)
+ * - [Code](https://atlassian.design/components/side-navigation/code)
+ */
 export declare const ButtonItem: React_2.ForwardRefExoticComponent<
   ButtonItemProps & React_2.RefAttributes<HTMLElement>
 >;
@@ -31,13 +43,13 @@ export { ButtonItemProps as GoBackItemProps };
  * Used to support any custom items needed by products alongside the Header and Footer patterns.
  * Specific implementation of headers and footers are provided in the examples folder.
  */
-export declare const CustomItem: CustomItemType;
+export declare const CustomItem: CustomItemPropsHack;
 
 export { CustomItemComponentProps };
 
 export { CustomItemProps };
 
-declare interface CustomItemType {
+declare interface CustomItemPropsHack {
   <TComponentProps extends {}>(
     props: CustomItemProps<TComponentProps> & {
       ref?: any;
@@ -45,12 +57,33 @@ declare interface CustomItemType {
   ): JSX.Element | null;
 }
 
+/**
+ * __Header__
+ *
+ * - [Examples](https://atlassian.design/components/side-navigation/examples#header-and-footer)
+ * - [Code](https://atlassian.design/components/side-navigation/code)
+ */
 export declare const Footer: (props: HeaderProps) => JSX.Element;
 
+/**
+ * __Go back item__
+ *
+ * A go back item is used to provide a customized "go back" button in nested
+ * navigations.
+ *
+ * - [Examples](https://atlassian.design/components/side-navigation/examples#go-back-item)
+ * - [Code](https://atlassian.design/components/side-navigation/code)
+ */
 export declare const GoBackItem: React_2.ForwardRefExoticComponent<
   ButtonItemProps & React_2.RefAttributes<HTMLElement>
 >;
 
+/**
+ * __Header__
+ *
+ * - [Examples](https://atlassian.design/components/side-navigation/examples#header-and-footer)
+ * - [Code](https://atlassian.design/components/side-navigation/code)
+ */
 export declare const Header: React_2.ForwardRefExoticComponent<
   HeaderProps & React_2.RefAttributes<HTMLElement>
 >;
@@ -87,29 +120,51 @@ declare interface HeaderProps {
    */
   testId?: string;
   /**
-     * Custom component to render as an item.
-     * This can be both a functional component or a class component.
-     * **Will return `null` if no component is defined.**
-
-     * **NOTE:** Make sure the reference for this component does not change between renders else undefined behavior may happen.
-     */
+   * Custom component to render as an item.
+   * This can be both a functional component or a class component.
+   * __Will return `null` if no component is defined.__
+   *
+   * __NOTE:__ Make sure the reference for this component does not change between renders else undefined behavior may happen.
+   */
   component?: React_2.ComponentType<CustomItemComponentProps>;
 }
 export { HeaderProps as FooterProps };
 export { HeaderProps };
 
+/**
+ * __Heading item__
+ *
+ * Available for advanced use cases, for most situations providing a title to Section should be enough.
+ *
+ */
 export declare const HeadingItem: (
   props: HeadingItemProps,
 ) => JSX.Element | null;
 
 export { HeadingItemProps };
 
+/**
+ * __Link item__
+ *
+ * Renders an item wrapped in an anchor tag, useful when you have an item that
+ * should change routes using native browser navigation. For SPA transitions use
+ * a [custom item](https://atlassian.design/components/side-navigation/examples#custom-item)
+ * with the respective router logic.
+ *
+ * - [Examples](https://atlassian.design/components/side-navigation/examples#link-item)
+ * - [Code](https://atlassian.design/components/side-navigation/code)
+ */
 export declare const LinkItem: React_2.ForwardRefExoticComponent<
   LinkItemProps & React_2.RefAttributes<HTMLElement>
 >;
 
 export { LinkItemProps };
 
+/**
+ * __Loading items__
+ *
+ * Loading items conditionally render based on the useShouldNestedElementRender() hook.
+ */
 export declare const LoadingItems: ({
   children,
   isLoading,
@@ -134,17 +189,25 @@ export declare interface LoadingItemsProps {
    */
   isLoading?: boolean;
   /**
-     * 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.
-
-     * Will set these elements when defined:
-     * - The entering container - `{testId}--entering`
-     * - The exiting container - `{testId}--exiting`
-     */
+   * 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.
+   *
+   * Will set these elements when defined:
+   * - The entering container - `{testId}--entering`
+   * - The exiting container - `{testId}--exiting`
+   */
   testId?: string;
 }
 
+/**
+ * __Navigation content__
+ *
+ * A navigation content is used as the container for navigation items.
+ *
+ * - [Examples](https://atlassian.design/components/side-navigation/examples#content)
+ * - [Code](https://atlassian.design/components/side-navigation/code)
+ */
 export declare const NavigationContent: ForwardRefExoticComponent<
   NavigationContentProps &
     HTMLAttributes<HTMLElement> &
@@ -165,25 +228,49 @@ export declare interface NavigationContentProps {
   testId?: string;
 }
 
+/**
+ * __Navigation footer__
+ *
+ * Allows for customisation of the footer.
+ *
+ * - [Examples](https://atlassian.design/components/side-navigation/examples#header-and-footer)
+ * - [Code](https://atlassian.design/components/side-navigation/code)
+ */
 export declare const NavigationFooter: ({
   children,
-}: NavigationFooterProps) => JSX.Element;
+}: NavigationFooterProps) => jsx.JSX.Element;
 
 export declare interface NavigationFooterProps {
   children: ReactNode;
 }
 
+/**
+ * __Navigation header__
+ *
+ * Allows for customisation of the header.
+ *
+ * - [Examples](https://atlassian.design/components/side-navigation/examples#header-and-footer)
+ * - [Code](https://atlassian.design/components/side-navigation/code)
+ */
 export declare const NavigationHeader: (
   props: NavigationHeaderProps,
-) => JSX.Element;
+) => jsx.JSX.Element;
 
 export declare interface NavigationHeaderProps {
   children: JSX.Element | JSX.Element[];
 }
 
+/**
+ * __Nestable navigation content__
+ *
+ * The container for navigation items with nested views
+ *
+ * - [Examples](https://atlassian.design/components/side-navigation/examples#nested-navigation)
+ * - [Code](https://atlassian.design/components/side-navigation/code)
+ */
 export declare const NestableNavigationContent: (
   props: NestableNavigationContentProps,
-) => JSX.Element;
+) => jsx.JSX.Element;
 
 export declare interface NestableNavigationContentProps {
   /**
@@ -193,14 +280,14 @@ export declare interface NestableNavigationContentProps {
    */
   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.
-
-     * Will set these elements when defined:
-     * - This wrapper - `{testId}`
-     * - The back item (displayed when inside a nested view) - `{testId}--go-back-item`
-     */
+   * 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.
+   *
+   * Will set these elements when defined:
+   * - This wrapper - `{testId}`
+   * - The back item (displayed when inside a nested view) - `{testId}--go-back-item`
+   */
   testId?: string;
   /**
    * Array of the initial stack you want to show.
@@ -223,10 +310,10 @@ export declare interface NestableNavigationContentProps {
    */
   onChange?: (stack: string[]) => void;
   /**
-     Custom overrides for the composed components.
-
-     @deprecated Please avoid using this prop as we intend to remove the prop completely in a future release. See DSP-2682 for more information.
-     */
+   * Custom overrides for the composed components.
+   *
+   *   @deprecated Please avoid using this prop as we intend to remove the prop completely in a future release. See DSP-2682 for more information.
+   */
   overrides?: {
     /**
      * Use this to override the default back button displayed when navigation is nested.
@@ -288,16 +375,16 @@ export declare interface NestingItemProps<
    */
   component?: React_2.ComponentType<TCustomComponentProps>;
   /**
-     * 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.
-
-     * Will set these elements when defined:
-     * - The container - `{testId}--container`
-     * - The nesting item - `{testId}--item`
-     * - The go back item - `{testId}--go-back-item` (only used if you pass in a override).
-     * - The nesting item default right arrow icon - `{testId}--item--right-arrow`
-     */
+   * 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.
+   *
+   * Will set these elements when defined:
+   * - The container - `{testId}--container`
+   * - The nesting item - `{testId}--item`
+   * - The go back item - `{testId}--go-back-item` (only used if you pass in a override).
+   * - The nesting item default right arrow icon - `{testId}--item--right-arrow`
+   */
   testId?: string;
   /**
    * A function that can be used to override the styles of the component.
@@ -337,6 +424,15 @@ export declare interface NestingItemProps<
   overrides?: NestingItemOverrides;
 }
 
+/**
+ * __Section__
+ *
+ * Used to separate items into sections. Using the title prop makes a section
+ * implicitly group the items for screen readers with no additional work required.
+ *
+ * - [Examples](https://atlassian.design/components/side-navigation/examples#section)
+ * - [Code](https://atlassian.design/components/side-navigation/code)
+ */
 export declare const Section: React_2.ForwardRefExoticComponent<
   SectionProps & React_2.RefAttributes<HTMLElement>
 >;
@@ -364,6 +460,15 @@ export declare interface SectionProps {
   testId?: string;
 }
 
+/**
+ * __Side navigation__
+ *
+ * A highly composable side navigation component that supports nested views.
+ *
+ * - [Examples](https://atlassian.design/components/side-navigation/examples)
+ * - [Code](https://atlassian.design/components/side-navigation/code)
+ * - [Usage](https://atlassian.design/components/side-navigation/usage)
+ */
 export declare const SideNavigation: ForwardRefExoticComponent<
   SideNavigationProps & RefAttributes<HTMLElement>
 >;
@@ -389,12 +494,27 @@ export declare interface SideNavigationProps {
   testId?: string;
 }
 
+/**
+ * __Skeleton heading item__
+ *
+ * A skeleton heading item for use in managing loading states.
+ *
+ * - [Examples](https://atlassian.design/components/side-navigation/examples#loading)
+ */
 export declare const SkeletonHeadingItem: (
   props: SkeletonHeadingItemProps,
 ) => JSX.Element | null;
 
 export { SkeletonHeadingItemProps };
 
+/**
+ * __Skeleton item__
+ *
+ * A skeleton item can be used to reduce the perceived laoding time.
+ *
+ * - [Examples](https://atlassian.design/components/side-navigation/examples#loading)
+ * - [Code](https://atlassian.design/components/side-navigation/code)
+ */
 export declare const SkeletonItem: (
   props: SkeletonItemProps,
 ) => JSX.Element | null;