feat: update exports, fix a bug with authentication and switchorg and…

… update docs (#109)

## 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
-->

documentation/docs/api/Hooks/useAuthentication.mdx

@@ -5,7 +5,7 @@ sidebar_label: 'useAuthentication'
 sidebar_position: 0
 ---
 
-import Type from '../_type-definitions/AuthenticationContextValue.md';
+import Type from '../_type-definitions/UseAuthenticationReturnValue.md';
 
 ```ts
 import { useAuthentication } from '@orfium/toolbox';
@@ -25,6 +25,6 @@ None
 
 ## Return value
 
-Ƭ [`AuthenticationContextValue`](../types/AuthenticationContextValue)
+Ƭ [`useAuthenticationReturnValue`](../Types/useAuthenticationReturnValue)
 
 <Type />

documentation/docs/api/Hooks/useOrfiumProducts.mdx

@@ -5,7 +5,7 @@ sidebar_label: 'useOrfiumProducts'
 sidebar_position: 2
 ---
 
-import Type from '../_type-definitions/OrfiumProductsContextValue.md';
+import Type from '../_type-definitions/UseOrfiumProductsReturnValue.md';
 
 ```ts
 import { useOrfiumProducts } from '@orfium/toolbox';
@@ -25,6 +25,6 @@ None
 
 ## Return value
 
-Ƭ [`OrfiumProductsContextValue`](../types/OrfiumProductsContextValue)
+Ƭ [`useOrfiumProductsReturnValue`](../Types/useOrfiumProductsReturnValue)
 
 <Type />

documentation/docs/api/Hooks/useOrganizations.mdx

@@ -5,7 +5,7 @@ sidebar_label: 'useOrganizations'
 sidebar_position: 1
 ---
 
-import Type from '../_type-definitions/OrganizationsContextValue.md';
+import Type from '../_type-definitions/UseOrganizationsReturnValue.md';
 
 ```ts
 import { useOrganizations } from '@orfium/toolbox';
@@ -25,6 +25,6 @@ None
 
 ## Return value
 
-Ƭ [`OrganizationsContextValue`](../types/OrganizationsContextValue)
+Ƭ [`useOrganizationsReturnValue`](../Types/useOrganizationsReturnValue)
 
 <Type />

documentation/docs/api/Hooks/useTopBarUtilitySection.mdx

@@ -5,8 +5,6 @@ sidebar_label: 'useTopBarUtilitySection'
 sidebar_position: 3
 ---
 
-import Type from '../_type-definitions/TopBarUtilitySectionContextValue.md';
-
 ```ts
 import { useTopBarUtilitySection } from '@orfium/toolbox';
 ```
@@ -48,7 +46,6 @@ function Page() {
 // The utility section will end up with 'this will be shown' as its content
 
 import { useTopBarUtilitySection } from '@orfium/toolbox';
-import { useMemo } from 'react';
 
 function AnotherPage() {
   useTopBarUtilitySection('this will not be shown');

documentation/docs/api/Types/UseAuthenticationReturnValue.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_position: 1
+---
+import Type from '../_type-definitions/UseAuthenticationReturnValue.md';
+
+
+```ts
+import { type AuthenticationContextValue } from '@orfium/toolbox';
+```
+
+### Definition
+
+<Type />

documentation/docs/api/Types/UseOrfiumProductsReturnValue.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_position: 1
+---
+import Type from '../_type-definitions/UseOrfiumProductsReturnValue.md';
+
+
+```ts
+import { type OrfiumProductsContextValue } from '@orfium/toolbox';
+```
+
+### Definition
+
+<Type />

documentation/docs/api/Types/UseOrganizationsReturnValue.mdx

@@ -0,0 +1,13 @@
+---
+sidebar_position: 1
+---
+import Type from '../_type-definitions/UseOrganizationsReturnValue.md';
+
+
+```ts
+import { type OrganizationsContextValue } from '@orfium/toolbox';
+```
+
+### Definition
+
+<Type />

documentation/docs/api/_type-definitions/UseOrfiumProductsReturnValue.md

@@ -0,0 +1 @@
+[`Product`](../Types/Product)`[] | null`

documentation/docs/tutorials/01-Installation and Usage/Authentication/Usage.mdx

@@ -2,7 +2,7 @@
 sidebar_position: 1
 ---
 
-import Type from '../../../api/_type-definitions/AuthenticationContextValue.md'
+import Type from '../../../api/_type-definitions/UseAuthenticationReturnValue.md'
 
 It's fairly easy to setup the Orfium One SSO using the [`Toolbox`](../../../api/Components/Toolbox.mdx). We will cover this in 5 simple steps.
 

documentation/docs/tutorials/01-Installation and Usage/index.md

@@ -5,16 +5,66 @@ sidebar_position: 1
 
 # Installing the package
 
-To install the package  run
+To install the package run
 
 ```bash
 $ yarn add @orfium/toolbox
 ```
 
-Now you can use any of the available modules like so:
+Now you can use any of the available exports like so:
 
 ```js
 import { ... } from '@orfium/toolbox';
 ```
 
+You will _need_ to use the [`Toolbox`](../../api/Components/Toolbox.mdx) provider component in order to use most of
+the functionality provided by this package.
+
+## Example Usage of `Toolbox`
+
+The [`Toolbox`](../../api/Components/Toolbox.mdx) component makes use of hooks provided by [`ThemeProvider`](https://designlab.orfium.com/?path=/docs/design-system-themeprovider--setting-up-a-button-example) and [`Router`](https://v5.reactrouter.com/web/api/Router),
+so make sure it is a descendant of both.
+
+```tsx title="App.tsx"
+import { ThemeProvider } from '@orfium/ictinus';
+import { Toolbox } from '@orfium/toolbox';
+import { BrowserRouter as Router } from 'react-router-dom';
+
+function App() {
+  return (
+    <ThemeProvider>
+      <Router>
+        <Toolbox>{/*...*/}</Toolbox>
+      </Router>
+    </ThemeProvider>
+  );
+}
+```
+
+:::danger
+Due to some [changes](https://react.dev/blog/2022/03/08/react-18-upgrade-guide#updates-to-strict-mode) in the way `StrictMode`
+works in React 18, if you are using React 18+ make sure that `<StrictMode>` is a descendant of `<Toolbox>` and not the other way around.
+(this is required until a future update on our end)
+
+```tsx title="App.tsx"
+import { ThemeProvider } from '@orfium/ictinus';
+import { Toolbox } from '@orfium/toolbox';
+import { StrictMode } from 'react';
+import { BrowserRouter as Router } from 'react-router-dom';
+
+function App() {
+  return (
+    <ThemeProvider>
+      <Router>
+        <Toolbox>
+          <StrictMode>{/*...*/}</StrictMode>
+        </Toolbox>
+      </Router>
+    </ThemeProvider>
+  );
+}
+```
+
+:::
+
 For available exports please refer to the [API documentation](/docs/api/)

documentation/src/css/custom.css

@@ -26,16 +26,21 @@
 
 /* For readability concerns, you should choose a lighter palette in dark mode. */
 [data-theme='dark'] {
-  --ifm-color-primary: #1de9b6;
-  --ifm-color-primary-dark: #1ad1a3;
-  --ifm-color-primary-darker: #17ba91;
-  --ifm-color-primary-darkest: #118b6d;
-  --ifm-color-primary-light: #33ebbd;
-  --ifm-color-primary-lighter: #4aedc4;
-  --ifm-color-primary-lightest: #60efcb;
+  --ifm-color-primary: #739cf9;
+  --ifm-color-primary-dark: #5c8cf8;
+  --ifm-color-primary-darker: #457bf7;
+  --ifm-color-primary-darkest: #2e6bf6;
+  --ifm-color-primary-light: #8badfa;
+  --ifm-color-primary-lighter: #a2bdfb;
+  --ifm-color-primary-lightest: #b9cdfc;
   --docusaurus-highlighted-code-line-bg: rgba(0, 0, 0, 0.3);
   /* custom overrides */
   --ifm-menu-color: var(--ifm-color-emphasis-700);
+  --ifm-navbar-link-color: #fff;
+  --ifm-navbar-link-hover-color: var(--ifm-color-primary-dark);
+  --ifm-background-surface-color: #151447;
+  --ifm-menu-color-active: var(--ifm-color-primary-darker);
+  --ifm-hover-overlay: #edefff;
 }
 
 [data-theme='light'] button[class*='toggleButton_'] path {

src/contexts/index.ts

@@ -1,8 +1,2 @@
-export {
-  type AuthenticationContextValue,
-  type DecodedTokenResponse,
-  type User,
-} from './authentication';
-export { type OrfiumProductsContextValue, type Product } from './orfium-products';
-export { type OrganizationsContextValue } from './organizations';
-export { type TopBarUtilitySectionContextValue } from './top-bar-utility-section';
+export { type DecodedTokenResponse, type User } from './authentication';
+export { type Product } from './orfium-products';

src/contexts/orfium-products.ts

@@ -1,12 +1,10 @@
 import { createContext } from 'react';
 
-type ClientMetadata = {
-  product_code: string;
-};
-
 export type Product = {
   client_id: string;
-  client_metadata: ClientMetadata;
+  client_metadata: {
+    product_code: string;
+  };
   grant_types: string | null;
   icon_url: string;
   login_url: string;

src/contexts/organizations.ts

@@ -1,16 +1,19 @@
 import { createContext } from 'react';
-import { Organization } from '../store/organizations';
+import { type SwitchOrganization, type _SwitchOrganization } from '../providers/Organizations';
+import { type Organization } from '../store/organizations';
 
 export type OrganizationsContextValue = {
   organizations: Organization[];
   selectedOrganization: Organization | null;
-  switchOrganization: (organisation: Organization['org_id']) => void;
+  switchOrganization: SwitchOrganization;
+  _switchOrganization: _SwitchOrganization;
 };
 
 export const defaultOrganizationsContextValues: OrganizationsContextValue = {
   organizations: [],
   selectedOrganization: null,
   switchOrganization: (__x) => {},
+  _switchOrganization: (__x) => {},
 };
 
 export const OrganizationsContext = createContext<OrganizationsContextValue>(

src/hooks/README.md

@@ -0,0 +1,51 @@
+## Hook utilities usage examples
+
+### useSafeContext
+
+_Description:</br> Accepts two parameters a **react context instance**, and a ** string** that specifies the name of the context.<br />It will throw an exception if someone tries to use hook outside of provider._
+
+```typescript jsx
+import { useSafeContext } from '@orfium/toolbox';
+
+const CustomContext = React.createContext(null);
+
+export const useCustomContext = () => useSafeContext(CustomContext, 'CustomContext');
+```
+
+_Error log_
+
+```
+Error: useCustomContext must be used within a CustomContextProvider
+```
+
+### useSafeDispatch
+
+_Description:</br> Accepts a **dispatch method** generated from a `useReducer` hook.<br />It will return an optimized and guarded dispatch callback which will be invoked only when the component is mounted._
+
+```typescript jsx
+import { useSafeDispatch } from '@orfium/toolbox';
+
+type State = Record<string, string> | null;
+type Action = { type: string; payload: boolean };
+
+const init = (shouldInit: boolean) => ({ type: 'INIT', payload: shouldInit });
+
+const reducer = (state: State, action: Dispatch<Action>) => {
+  if (action.type === 'INIT') {
+    return { ...state, init: action.payload };
+  }
+
+  return state;
+};
+
+export const Component = () => {
+  const [state, dispatch] = useReducer<typeof reducer>(reducer, null);
+  const safeDispatch = useSafeDispatch<Action>(dispatch);
+
+  const onClick = () => {
+    safeDispatch(init(true));
+  };
+
+  return <button onClick={onClick}>init state</button>;
+};
+```