feat: rename utility section to utility slot and update docs (#117)

## 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/Components/Toolbox.mdx

@@ -15,7 +15,7 @@ import { Toolbox } from '@orfium/toolbox';
 
 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.
+[`useOrganizations`](../hooks/useOrganizations), [`useOrfiumProducts`](../hooks/useOrfiumProducts) and [`useTopBarUtilitySlot`](../hooks/useTopBarUtilitySlot) hooks.
 
 ## Props
 

documentation/docs/api/Components/TopBar.mdx

@@ -21,9 +21,9 @@ Must be a descendant of [`Toolbox`](./Toolbox), [`ThemeProvider`](https://design
 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.
+The component will display whatever you pass down as a value to the `utilitySlot` prop, unless some other component
+is making use of the [`useTopBarUtilitySlot`](../hooks/useTopBarUtilitySlot) hook at the same time. In that case
+the value passed to the hook will take precedence over the value of the `utilitySlot` prop.
 
 ## Props
 

documentation/docs/api/Hooks/useTopBarUtilitySection.mdx → documentation/docs/api/Hooks/useTopBarUtilitySlot.mdx

@@ -1,12 +1,12 @@
 ---
-id: 'useTopBarUtilitySection'
-title: 'useTopBarUtilitySection'
-sidebar_label: 'useTopBarUtilitySection'
+id: 'useTopBarUtilitySlot'
+title: 'useTopBarUtilitySlot'
+sidebar_label: 'useTopBarUtilitySlot'
 sidebar_position: 3
 ---
 
 ```ts
-import { useTopBarUtilitySection } from '@orfium/toolbox';
+import { useTopBarUtilitySlot } from '@orfium/toolbox';
 ```
 
 :::info
@@ -29,32 +29,32 @@ due to the `useEffect` execution order.
 **Example usage**
 
 ```tsx
-import { useTopBarUtilitySection } from '@orfium/toolbox';
+import { useTopBarUtilitySlot } from '@orfium/toolbox';
 import { useMemo } from 'react';
 
 function Page() {
-  const utilitySectionElement = useMemo(() => {
+  const utilitySlotElement = useMemo(() => {
     return <h2>Hello</h2>;
   }, []);
 
-  useTopBarUtilitySection(utilitySectionElement);
+  useTopBarUtilitySlot(utilitySlotElement);
   return <div>Page contents</div>;
 }
 ```
 
 ```tsx
 // The utility section will end up with 'this will be shown' as its content
 
-import { useTopBarUtilitySection } from '@orfium/toolbox';
+import { useTopBarUtilitySlot } from '@orfium/toolbox';
 
 function AnotherPage() {
-  useTopBarUtilitySection('this will not be shown');
+  useTopBarUtilitySlot('this will not be shown');
 
   return <h1>INNER PAGE</h1>;
 }
 
 function Page() {
-  useTopBarUtilitySection('this will be shown');
+  useTopBarUtilitySlot('this will be shown');
 
   return (
     <div>
@@ -67,10 +67,10 @@ function Page() {
 
 ## Parameters
 
-- `topBarUtilitySectionElement: ReactNode` - The React Element you want to set as the content of the utility section
+- `topBarUtilitySlotElement: ReactNode` - The React Element you want to set as the content of the utility section
 
 :::danger
-Make **sure** you memoise the value of `topBarUtilitySectionElement` otherwise you **will** cause an infinite render loop.
+Make **sure** you memoise the value of `topBarUtilitySlotElement` otherwise you **will** cause an infinite render loop.
 Take care to avoid trashing the memoised value unless necessary.
 :::
 

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

@@ -1,4 +1,4 @@
 | Name               | Type                                                                                               |
 | :----------------- | :------------------------------------------------------------------------------------------------- |
-| ` utilitySection?` | `ReactNode`                                                                                        |
+| ` utilitySlot?` | `ReactNode`                                                                                        |
 | `menuItems?`       | <pre>\{ <br/> text: string; <br/> url: string; <br/> iconName?: AcceptedIconNames; <br/>\}[]</pre> |

documentation/docs/tutorials/01-Installation and Usage/UI/top-bar-component.md

@@ -14,6 +14,8 @@ logged-in user, and it's also home to the user menu, which includes a list of av
 The component provides a utility slot that sits on the left side, where the user can opt to display things such as
 breadcrumbs, or whatever is necessary based on product requirements.
 
+![TopBar layout](/img/top-bar.png)
+
 ## Usage
 
 In order to use the `TopBar` component you only have to import it from `@orfium/toolbox` and add it to the file where you build your product's overall layout.
@@ -32,8 +34,8 @@ function Page() {
       // highlight-next-line
       <header>
         <TopBar
-        menuItems={[{ text: 'Settings', url: 'one.orfium.com/settings', iconName: 'settings' }]}
-        utilitySection={<div>hello there</div>}
+          menuItems={[{ text: 'Settings', url: 'one.orfium.com/settings', iconName: 'settings' }]}
+          utilitySlot={<div>hello there</div>}
         />
       </header>
       // rest of the page

src/contexts/top-bar-utility-slot.ts

@@ -0,0 +1,14 @@
+import { createContext, Dispatch, ReactNode, SetStateAction } from 'react';
+
+export type TopBarUtilitySlotContextValue = {
+  topBarUtilitySlot: ReactNode;
+  setTopBarUtilitySlot: Dispatch<SetStateAction<ReactNode>>;
+};
+
+export const defaultTopBarUtilitySlotContextValue: TopBarUtilitySlotContextValue = {
+  topBarUtilitySlot: null,
+  setTopBarUtilitySlot: () => {},
+};
+export const TopBarUtilitySlotContext = createContext<TopBarUtilitySlotContextValue>(
+  defaultTopBarUtilitySlotContextValue
+);

src/hooks/index.ts

@@ -4,7 +4,4 @@ export { useOrfiumProducts, type UseOrfiumProductsReturnValue } from './useOrfiu
 export { useOrganizations, type UseOrganizationsReturnValue } from './useOrganizations';
 export { useSafeContext } from './useSafeContext';
 export { useSafeDispatch } from './useSafeDispatch';
-export {
-  useTopBarUtilitySection,
-  type UseTopBarUtilitySectionReturnValue,
-} from './useTopBarUtilitySection';
+export { useTopBarUtilitySlot } from './useTopBarUtilitySlot';

src/hooks/useTopBarUtilitySlot.ts

@@ -0,0 +1,17 @@
+import { ReactNode, useContext, useEffect } from 'react';
+import { TopBarUtilitySlotContext } from '../contexts/top-bar-utility-slot';
+
+export const _useTopBarUtilitySlot = () => useContext(TopBarUtilitySlotContext);
+export const useTopBarUtilitySlot = (topBarUtilitySlotElement: ReactNode) => {
+  const { setTopBarUtilitySlot } = useContext(TopBarUtilitySlotContext);
+
+  useEffect(() => {
+    setTopBarUtilitySlot(topBarUtilitySlotElement);
+
+    return function () {
+      setTopBarUtilitySlot(null);
+    };
+  }, [setTopBarUtilitySlot, topBarUtilitySlotElement]);
+};
+
+export type UseTopBarUtilitySlotReturnValue = undefined;

src/providers/Toolbox/Toolbox.tsx

@@ -10,7 +10,7 @@ import ErrorFallback from '../../ui/ErrorFallback/ErrorFallback';
 import { Authentication } from '../Authentication';
 import { OrfiumProducts } from '../OrfiumProducts';
 import { Organizations } from '../Organizations';
-import { TopBarUtilitySection } from '../TopBarUtilitySection';
+import { TopBarUtilitySlot } from '../TopBarUtilitySlot';
 import { Box, LoadingContent, Wrapper } from './Toolbox.style';
 
 export type ToolboxProps = { children: ReactNode };
@@ -31,9 +31,9 @@ export function Toolbox({ children }: ToolboxProps) {
       <Organizations>
         <Authentication>
           <OrfiumProducts>
-            <TopBarUtilitySection>
+            <TopBarUtilitySlot>
               <AuthenticationWrapper>{children}</AuthenticationWrapper>
-            </TopBarUtilitySection>
+            </TopBarUtilitySlot>
           </OrfiumProducts>
         </Authentication>
       </Organizations>

src/providers/TopBarUtilitySlot.tsx

@@ -0,0 +1,18 @@
+import { ReactNode, useState } from 'react';
+import { TopBarUtilitySlotContext } from '../contexts/top-bar-utility-slot';
+
+export function TopBarUtilitySlot(props: { children: ReactNode }) {
+  const { children } = props;
+  const [topBarUtilitySlot, setTopBarUtilitySlot] = useState<ReactNode>(null);
+
+  return (
+    <TopBarUtilitySlotContext.Provider
+      value={{
+        topBarUtilitySlot: topBarUtilitySlot,
+        setTopBarUtilitySlot: setTopBarUtilitySlot,
+      }}
+    >
+      {children}
+    </TopBarUtilitySlotContext.Provider>
+  );
+}

src/ui/TopBar/TopBar.styles.ts

@@ -27,7 +27,7 @@ export const UserSection = styled.div`
   ${topAppBarSectionStyles};
   flex-shrink: 0;
 `;
-export const UserDefinedSection = styled.div`
+export const UserDefinedSlot = styled.div`
   ${topAppBarSectionStyles};
   flex-grow: 1;
   justify-content: flex-start;

src/ui/TopBar/TopBar.tsx

@@ -2,16 +2,16 @@ import { Global } from '@emotion/react';
 import { useBreakpoints, useTheme } from '@orfium/ictinus';
 import { ReactNode } from 'react';
 import Logo from '../../assets/orfium_logo.svg';
-import { _useTopBarUtilitySection } from '../../hooks/useTopBarUtilitySection';
+import { _useTopBarUtilitySlot } from '../../hooks/useTopBarUtilitySlot';
 import UserMenu, { UserMenuProps } from './components/UserMenu';
-import { backGround, TopAppBarWrapper, UserDefinedSection, UserSection } from './TopBar.styles';
+import { backGround, TopAppBarWrapper, UserDefinedSlot, UserSection } from './TopBar.styles';
 
 export type TopBarProps = {
-  utilitySection?: ReactNode;
+  utilitySlot?: ReactNode;
 } & Partial<UserMenuProps>;
 
-export function TopBar({ utilitySection, menuItems = [] }: TopBarProps) {
-  const { topBarUtilitySection } = _useTopBarUtilitySection();
+export function TopBar({ utilitySlot, menuItems = [] }: TopBarProps) {
+  const { topBarUtilitySlot } = _useTopBarUtilitySlot();
   const theme = useTheme();
   const breakpoints = useBreakpoints();
   const isDesktop = breakpoints.des1366;
@@ -20,7 +20,7 @@ export function TopBar({ utilitySection, menuItems = [] }: TopBarProps) {
     <TopAppBarWrapper role="banner" aria-label="Top Application Banner">
       <Global styles={{ body: backGround(theme) }} />
       {isDesktop ? null : <img alt={'Orfium logo'} src={Logo} height={28} width={28} />}
-      <UserDefinedSection>{topBarUtilitySection || utilitySection}</UserDefinedSection>
+      <UserDefinedSlot>{topBarUtilitySlot || utilitySlot}</UserDefinedSlot>
       <UserSection>
         <UserMenu menuItems={menuItems} />
       </UserSection>