feat: complete new Nav and Docs (#101)

## Description

<!-- Write and explain of the changes introduced by this PR for the reviewers to fully understand -->

## Screenshot

<!-- Provide a screenshot or gif of the change to demonstrate it -->

## Test Plan

<!-- Explain what you tested and why -->

<!--
  Have any questions? Check out the contributing doc for more
-->

.eslintrc.json

@@ -32,6 +32,9 @@
     "react/no-render-return-value": 0,
     /* JSX rules */
     "react/jsx-key": "error",
+    /* Since we are using React 17+ we no longer need these */
+    "react/jsx-uses-react": "off",
+    "react/react-in-jsx-scope": "off",
     /* eslint basic rules */
     "padding-line-between-statements": [
       "error",
@@ -57,27 +60,33 @@
     //    "no-unused-expressions": "warn",
     "no-unused-vars": "off",
     "no-debugger": "warn",
-    "no-console": "warn",
-
+    "no-console": "warn"
+  },
+  "overrides": [
     /* Typescript rules */
-    "@typescript-eslint/no-unused-expressions": "warn",
-    "@typescript-eslint/no-unused-vars": [
-      "warn",
-      {
-        "args": "all",
-        "argsIgnorePattern": "^__",
-        "varsIgnorePattern": "^__|React"
+    {
+      "files": ["**/*.ts?(x)"],
+      "rules": {
+        "@typescript-eslint/no-unused-expressions": "warn",
+        "@typescript-eslint/no-unused-vars": [
+          "warn",
+          {
+            "args": "all",
+            "argsIgnorePattern": "^__",
+            "varsIgnorePattern": "^__|React"
+          }
+        ],
+        "@typescript-eslint/ban-ts-ignore": 0,
+        "@typescript-eslint/no-empty-function": 0,
+        "@typescript-eslint/camelcase": 0,
+        "@typescript-eslint/prefer-interface": 0,
+        "@typescript-eslint/no-inferrable-types": 0,
+        "@typescript-eslint/explicit-member-accessibility": 0,
+        "@typescript-eslint/explicit-function-return-type": 0,
+        "@typescript-eslint/ban-ts-comment": "warn"
       }
-    ],
-    "@typescript-eslint/ban-ts-ignore": 0,
-    "@typescript-eslint/no-empty-function": 0,
-    "@typescript-eslint/camelcase": 0,
-    "@typescript-eslint/prefer-interface": 0,
-    "@typescript-eslint/no-inferrable-types": 0,
-    "@typescript-eslint/explicit-member-accessibility": 0,
-    "@typescript-eslint/explicit-function-return-type": 0,
-    "@typescript-eslint/ban-ts-comment": "warn"
-  },
+    }
+  ],
   "settings": {
     "react": {
       "pragma": "React",

.github/workflows/pr.yml

@@ -6,6 +6,7 @@ on:
       - 'master'
       - 'next'
       - 'v3.x'
+      - '**'
 
 jobs:
   deploy-review-app:

documentation/.eslintrc.json

@@ -0,0 +1,6 @@
+{
+  "extends": ["../.eslintrc.json"],
+  "rules": {
+    "@typescript-eslint/no-var-requires": "off"
+  }
+}

documentation/docs/api/Components/LinkWithStatePassthrough.mdx

@@ -0,0 +1,40 @@
+---
+id: "LinkWithStatePassthrough"
+title: "LinkWithStatePassthrough"
+sidebar_label: "LinkWithStatePassthrough"
+sidebar_position: 3
+---
+
+```ts
+import { LinkWithStatePassthrough } from '@orfium/toolbox';
+```
+
+## Description
+
+A utility component that wraps over React Router's [`Link`](https://v5.reactrouter.com/web/api/Link) component,
+but takes care to pass the _current_ history state over to the next link location.
+
+**Example usage**
+
+```tsx
+// `to` value can be a full or partial location object
+// (do note that explicitly passing a `state` object here will be ignored)
+function EmptyPage() {
+  return (
+    <LinkWithStatePassthrough to={{ pathname: '/login' }} />
+  );
+}
+```
+
+```tsx
+// `to` value can also just be a string
+function EmptyPage() {
+  return (
+    <LinkWithStatePassthrough to={'/login'} />
+  );
+}
+```
+
+## Props
+
+Ƭ `LinkProps`

documentation/docs/api/Components/NavLinkWithStatePassthrough.mdx

@@ -0,0 +1,40 @@
+---
+id: "NavLinkWithStatePassthrough"
+title: "NavLinkWithStatePassthrough"
+sidebar_label: "NavLinkWithStatePassthrough"
+sidebar_position: 3
+---
+
+```ts
+import { NavLinkWithStatePassthrough } from '@orfium/toolbox';
+```
+
+## Description
+
+A utility component that wraps over React Router's [`NavLink`](https://v5.reactrouter.com/web/api/NavLink) component,
+but takes care to pass the _current_ history state over to the next link location.
+
+**Example usage**
+
+```tsx
+// `to` value can be a full or partial location object
+// (do note that explicitly passing a `state` object here will be ignored)
+function EmptyPage() {
+  return (
+    <NavLinkWithStatePassthrough to={{ pathname: '/login' }} />
+  );
+}
+```
+
+```tsx
+// `to` value can also just be a string
+function EmptyPage() {
+  return (
+    <NavLinkWithStatePassthrough to={'/login'} />
+  );
+}
+```
+
+## Props
+
+Ƭ `NavLinkProps`

documentation/docs/api/Components/Navigation.mdx

@@ -0,0 +1,67 @@
+---
+id: 'Navigation'
+title: 'Navigation'
+sidebar_label: 'Navigation'
+sidebar_position: 1
+---
+
+import Type from '../_type-definitions/NavigationProps.md';
+
+```ts
+import { Navigation } from '@orfium/toolbox';
+```
+
+## Description
+
+A UI component that handles user navigation both within the current product and among Orfium products. It is comprised of
+two main parts, the **global navigation bar** and the **local navigation drawer**.
+
+### Global navigation bar
+
+Top-to-bottom, it consists of :
+
+- An **hamburger button** that when clicked will toggle the **local navigation drawer**. **(Small screens only)**
+- A **list of icon links** corresponding to all the Orfium products that are available to the user. The currently used product
+  icon is highlighted.
+- An **extra button** (![admin button](/img/admin_button.png)) that when clicked will navigate to `/admin` (configurable by `adminNavigationURLSegment`) and toggle
+  the contents of the [**main navigation section**](#local-navigation-drawer) between the admin-only (`adminNavigation`) and the regular navigation (`regularNavigation`) menu. **(Admin users only)**
+
+### Local navigation drawer
+
+Top-to-bottom, it consists of three main sections:
+
+- the **organisation switcher**, which allows the user to switch between the organisations available to their account. **(Controlled by** `hideOrgSwitcher`**)**
+- the **main navigation section**, which lists links internal to the currently used application. Admin-only navigation will
+  show up here.
+- the **extra information section**, which can contain various external links to educational or support material. **(Optional)**
+
+You can read more [here](/docs/tutorials/Installation%20and%20Usage/UI/Navigation%20Component).
+
+:::info
+Exiting the admin-only navigation by clicking the extra admin button (![admin button](/img/admin_button.png)) will take you back to exactly where you were before
+entering the admin-only navigation, restoring any previously applied URL params, _as long as you navigated using only
+the local navigation drawer links_.
+
+The above works because when you enter the admin navigation the previous URL path is pushed to the history state and the
+navigation links within `Navigation` pass that history state around to one another. The admin button uses the stored
+URL path as its `href` value.
+:::
+
+:::caution
+If your admin views have navigation of their own (by means of redirects or links), using regular
+[`Link`](https://v5.reactrouter.com/web/api/Link)s, [`NavLink`](https://v5.reactrouter.com/web/api/NavLink)s or
+[`Redirect`](https://v5.reactrouter.com/web/api/Redirect)s without passing around the history state will "break" the
+above functionality. Use the utility components [`RedirectWithStatePassthrough`](./RedirectWithStatePassthrough),
+[`LinkWithStatePassthrough`](./LinkWithStatePassthrough) and [`NavLinkWithStatePassthrough`](./NavLinkWithStatePassthrough) instead, if you want to maintain the return
+URL path.
+:::
+
+## Props
+
+Ƭ [`NavigationProps`](../types/NavigationProps)
+
+<Type />
+
+:::tip
+Memoising the values of `regularNavigation`, `adminNavigation` and `extras` will optimise performance.
+:::

documentation/docs/api/Components/RedirectWithStatePassthrough.mdx

@@ -0,0 +1,40 @@
+---
+id: "RedirectWithStatePassthrough"
+title: "RedirectWithStatePassthrough"
+sidebar_label: "RedirectWithStatePassthrough"
+sidebar_position: 3
+---
+
+```ts
+import { RedirectWithStatePassthrough } from '@orfium/toolbox';
+```
+
+## Description
+
+A utility component that wraps over React Router's [`Redirect`](https://v5.reactrouter.com/web/api/Redirect) component,
+but takes care to pass the _current_ history state over to the next redirect location.
+
+**Example usage**
+
+```tsx
+// `to` value can be a full or partial location object
+// (do note that explicitly passing a `state` object here will be ignored)
+function EmptyPage() {
+  return (
+    <RedirectWithStatePassthrough to={{ pathname: '/login' }} />
+  );
+}
+```
+
+```tsx
+// `to` value can also just be a string
+function EmptyPage() {
+  return (
+    <RedirectWithStatePassthrough to={'/login'} />
+  );
+}
+```
+
+## Props
+
+Ƭ `RedirectProps`

documentation/docs/api/Components/Toolbox.mdx

@@ -0,0 +1,24 @@
+---
+id: 'Toolbox'
+title: 'Toolbox'
+sidebar_label: 'Toolbox'
+sidebar_position: 0
+---
+
+import Type from '../_type-definitions/ToolboxProps.md';
+
+```ts
+import { Toolbox } from '@orfium/toolbox';
+```
+
+## Description
+
+A provider component that manages user authentication. You will need to wrap your app with it in order to use Orfium's
+SSO mechanism and to be able to use the [`useAuthentication`](../hooks/useAuthentication),
+[`useOrganizations`](../hooks/useOrganizations), [`useOrfiumProducts`](../hooks/useOrfiumProducts) and [`useTopBarUtilitySection`](../hooks/useTopBarUtilitySection) hooks.
+
+## Props
+
+Ƭ [`ToolboxProps`](../types/ToolboxProps)
+
+<Type />

documentation/docs/api/Components/TopBar.mdx

@@ -0,0 +1,27 @@
+---
+id: 'TopBar'
+title: 'TopBar'
+sidebar_label: 'TopBar'
+sidebar_position: 2
+---
+
+import Type from '../_type-definitions/TopBarProps.md';
+
+```ts
+import { TopBar } from '@orfium/toolbox';
+```
+
+## Description
+
+A UI component that holds other UI elements such as the user menu on the right and an optional utility section on the
+left. Read more [here](/docs/tutorials/Installation%20and%20Usage/UI/Top%20Bar%20Component).
+
+The component will display whatever you pass down as a value to the `utilitySection` prop, unless some other component
+is making use of the [`useTopBarUtilitySection`](../hooks/useTopBarUtilitySection) hook at the same time. In that case
+the value passed to the hook will take precedence over the value of the `utilitySection` prop.
+
+## Props
+
+Ƭ [`TopBarProps`](../types/TopBarProps)
+
+<Type />

documentation/docs/api/Components/_category_.json

@@ -0,0 +1,3 @@
+{
+  "position": 1
+}

documentation/docs/api/Hooks/_category_.json

@@ -0,0 +1,3 @@
+{
+  "position": 2
+}

documentation/docs/api/Hooks/useAuthentication.mdx

@@ -0,0 +1,30 @@
+---
+id: 'useAuthentication'
+title: 'useAuthentication'
+sidebar_label: 'useAuthentication'
+sidebar_position: 0
+---
+
+import Type from '../_type-definitions/AuthenticationContextValue.md';
+
+```ts
+import { useAuthentication } from '@orfium/toolbox';
+```
+
+:::info
+Only descendants of [`Toolbox`](../components/Toolbox) can use this hook.
+:::
+
+## Description
+
+A hook that returns an assortment of authentication related methods and data.
+
+## Parameters
+
+None
+
+## Return value
+
+Ƭ [`AuthenticationContextValue`](../types/AuthenticationContextValue)
+
+<Type />