@stack-spot/portal-layout 0.0.65 → 1.0.0

package/dist/utils.d.ts

@@ -1,80 +1,17 @@
-export declare function valueOfLayoutVar(varname: string): string;
-/**
- * Important for accessibility.
- *
- * Makes it so we focus the next focusable element in the DOM hierarchy, disregarding the element passed as parameter and its children.
- *
- * If there's no next focusable element, the first focusable of the page will be focused. If the page doesn't contain any focusable
- * element, nothing happens.
- *
- * @param current the reference element to focus the next. If not provided, will be the currently active element.
- */
-export declare function focusNextIgnoringChildren(current?: HTMLElement | null): void;
-type TagPriority = 'a' | 'button' | 'input' | 'textarea' | 'select' | 'other';
-type TagPriorityElement = TagPriority | TagPriority[];
-interface FocusOptions {
-    /**
-     * Instead of focusing the first element overall, focus the first according to this list of priorities.
-     */
-    priority?: TagPriorityElement[];
-    /**
-     * Ignores any element that matches this query selector.
-     */
-    ignore?: string;
-}
-/**
- * Checks if an element can receive focus.
- *
- * Elements can receive focus only if:
- * - they exist;
- * - they're visible;
- * - they're not disabled;
- * - they are a focusable tag name or have a positive tab index;
- * - they don't have a negative tab index.
- * @param element the element to check.
- * @returns true if the element is focusable, false otherwise.
- */
-export declare function isFocusable(element?: Element | null): boolean;
-/**
- * Focus the element passed as parameter if it can receive focus. Otherwise, decides on another element to focus based on the HTML tree
- * and accessibility attributes.
- *
- * Decision making:
- * - If the element is focusable, focus it.
- * - If the element is not focusable, check if it has an id and if another element controls it (aria-controls).
- * - If the element is controlled by another, try to focus the controller, based in this same algorithm.
- * - Otherwise, try to focus its parent.
- *
- * If no focusable element is found. Nothing happens.
- * @param element the element to focus.
- */
-export declare function focusAccessibleElement(element?: Element | null): void;
 /**
- * Focus the first focusable child of the element provided. If the element has no focusable child, nothing happens.
- *
- * A priority list can be passed in the second parameter, as an option. If it's provided, it will focus the first element according to the
- * list.
+ * Gets the value for a css variable of the layout.
  *
- * An ignore query selector can also be passed in the options parameter. If the first focusable element matches the query selector, the
- * next element is focused instead.
+ * Supposing the actual name of the variable is name-of-variable, the value passed to the first parameter (varname) may be: name-of-variable
+ * or --name-of-variable or var(--name-of-variable). All these formats work.
  *
- * @example
- * Suppose the children of element are: h1, button, p, input, select.
- * 1. We don't pass a priority list. The focused element will be the button.
- * 2. Our priority list is ['button']. The focused element will be the button.
- * 3. Our priority list is ['input', 'button']. The focused element will be the input.
- * 4. Our priority list is ['select', 'input']. The focused element will be the select.
- * 5. Our priority list is [['select', 'input'], 'button']. The focused element will be the input.
- *
- * @param element the element to search a child to focus.
- * @param options optional.
+ * @param varname the name of css variable.
+ * @returns the value of `varname`.
  */
-export declare function focusFirstChild(element: HTMLElement | Document | null | undefined, { priority, ignore }?: FocusOptions): void;
+export declare function valueOfLayoutVar(varname: string): string;
 /**
  * Accessibility: makes the screen reader announce some text out loud.
  *
  * @param text the message for the screen reader to read.
  */
 export declare function announce(text: string): void;
-export {};
 //# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAGA,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAIxD;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,OAAO,CAAC,EAAE,WAAW,GAAG,IAAI,QAWrE;AAED,KAAK,WAAW,GAAG,GAAG,GAAG,QAAQ,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAA;AAC7E,KAAK,kBAAkB,GAAG,WAAW,GAAG,WAAW,EAAE,CAAA;AAErD,UAAU,YAAY;IACpB;;OAEG;IACH,QAAQ,CAAC,EAAE,kBAAkB,EAAE,CAAC;IAChC;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAWD;;;;;;;;;;;GAWG;AACH,wBAAgB,WAAW,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,WAYnD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,QAO9D;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,WAAW,GAAG,QAAQ,GAAG,IAAI,GAAG,SAAS,EAAE,EAAE,QAAa,EAAE,MAAM,EAAE,GAAE,YAAiB,QA0B/H;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,QAKpC"}
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAIxD;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,QAKpC"}

package/dist/utils.js

@@ -1,141 +1,20 @@
 import { valueOf } from '@stack-spot/portal-theme';
 import { getLayoutElements } from './elements.js';
+/**
+ * Gets the value for a css variable of the layout.
+ *
+ * Supposing the actual name of the variable is name-of-variable, the value passed to the first parameter (varname) may be: name-of-variable
+ * or --name-of-variable or var(--name-of-variable). All these formats work.
+ *
+ * @param varname the name of css variable.
+ * @returns the value of `varname`.
+ */
 export function valueOfLayoutVar(varname) {
     const layout = document.getElementById('layout');
     if (!layout)
         return '';
     return valueOf(varname, layout);
 }
-/**
- * Important for accessibility.
- *
- * Makes it so we focus the next focusable element in the DOM hierarchy, disregarding the element passed as parameter and its children.
- *
- * If there's no next focusable element, the first focusable of the page will be focused. If the page doesn't contain any focusable
- * element, nothing happens.
- *
- * @param current the reference element to focus the next. If not provided, will be the currently active element.
- */
-export function focusNextIgnoringChildren(current) {
-    current = current ?? document.activeElement;
-    while (current && !current.nextElementSibling) {
-        current = current?.parentElement;
-    }
-    current = current?.nextElementSibling;
-    while (current && current.tabIndex < 0) {
-        current = (current.children.length ? current.firstChild : current.nextElementSibling);
-    }
-    if (current)
-        current?.focus?.();
-    else
-        focusFirstChild(document);
-}
-const selectors = {
-    a: 'a[href]:not(:disabled)',
-    button: 'button:not(:disabled)',
-    input: 'input:not(:disabled):not([type="hidden"])',
-    select: 'textarea:not(:disabled)',
-    textarea: 'select:not(:disabled)',
-    other: '[tabindex]:not([tabindex="-1"])',
-};
-/**
- * Checks if an element can receive focus.
- *
- * Elements can receive focus only if:
- * - they exist;
- * - they're visible;
- * - they're not disabled;
- * - they are a focusable tag name or have a positive tab index;
- * - they don't have a negative tab index.
- * @param element the element to check.
- * @returns true if the element is focusable, false otherwise.
- */
-export function isFocusable(element) {
-    if (!element)
-        return false;
-    // is disabled: return false
-    if (element.ariaDisabled || element.getAttribute('disabled') !== null)
-        return false;
-    // is invisible: return false
-    if (!element.checkVisibility({ checkOpacity: true, checkVisibilityCSS: true }))
-        return false;
-    // has tab index: return false if negative, true otherwise
-    const tabIndexStr = element.getAttribute('tabindex');
-    const tabIndex = tabIndexStr ? parseInt(tabIndexStr) : undefined;
-    if (tabIndex !== undefined)
-        return tabIndex >= 0;
-    // check the tag name
-    return ['a', 'button', 'input', 'iframe', 'select', 'textarea'].includes(element.tagName.toLowerCase() ?? '');
-}
-/**
- * Focus the element passed as parameter if it can receive focus. Otherwise, decides on another element to focus based on the HTML tree
- * and accessibility attributes.
- *
- * Decision making:
- * - If the element is focusable, focus it.
- * - If the element is not focusable, check if it has an id and if another element controls it (aria-controls).
- * - If the element is controlled by another, try to focus the controller, based in this same algorithm.
- * - Otherwise, try to focus its parent.
- *
- * If no focusable element is found. Nothing happens.
- * @param element the element to focus.
- */
-export function focusAccessibleElement(element) {
-    let elementToFocus = element;
-    while (elementToFocus && !isFocusable(elementToFocus)) {
-        const controlledBy = elementToFocus.id ? document.querySelector(`[aria-controls=${elementToFocus.id}]`) : undefined;
-        elementToFocus = (controlledBy ?? elementToFocus.parentElement);
-    }
-    elementToFocus?.focus?.();
-}
-/**
- * Focus the first focusable child of the element provided. If the element has no focusable child, nothing happens.
- *
- * A priority list can be passed in the second parameter, as an option. If it's provided, it will focus the first element according to the
- * list.
- *
- * An ignore query selector can also be passed in the options parameter. If the first focusable element matches the query selector, the
- * next element is focused instead.
- *
- * @example
- * Suppose the children of element are: h1, button, p, input, select.
- * 1. We don't pass a priority list. The focused element will be the button.
- * 2. Our priority list is ['button']. The focused element will be the button.
- * 3. Our priority list is ['input', 'button']. The focused element will be the input.
- * 4. Our priority list is ['select', 'input']. The focused element will be the select.
- * 5. Our priority list is [['select', 'input'], 'button']. The focused element will be the input.
- *
- * @param element the element to search a child to focus.
- * @param options optional.
- */
-export function focusFirstChild(element, { priority = [], ignore } = {}) {
-    let focusable;
-    let missing = ['a', 'button', 'input', 'other', 'select', 'textarea'];
-    for (const p of priority) {
-        const tags = Array.isArray(p) ? p : [p];
-        const querySelectors = tags.map(t => {
-            missing = missing.filter(tag => tag != t);
-            return selectors[t];
-        });
-        focusable = element?.querySelectorAll(querySelectors.join(', '));
-        if (focusable)
-            break;
-    }
-    if (!focusable) {
-        element?.querySelectorAll(missing.map(t => selectors[t]).join(', '));
-    }
-    let elementToFocus;
-    for (const f of focusable ?? []) {
-        if (!ignore || !f.matches(ignore)) {
-            const styles = window.getComputedStyle(f);
-            if (styles.display != 'none' && styles.visibility != 'hidden') {
-                elementToFocus = f;
-                break;
-            }
-        }
-    }
-    elementToFocus?.focus?.();
-}
 /**
  * Accessibility: makes the screen reader announce some text out loud.
  *

package/dist/utils.js.map

@@ -1 +1 @@
-{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,0BAA0B,CAAA;AAClD,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAA;AAE9C;;;;;;;;GAQG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAe;IAC9C,MAAM,MAAM,GAAG,QAAQ,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAA;IAChD,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAA;IACtB,OAAO,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;AACjC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAY;IACnC,MAAM,EAAE,sBAAsB,EAAE,GAAG,iBAAiB,EAAE,CAAA;IACtD,IAAI,CAAC,sBAAsB;QAAE,OAAM;IACnC,sBAAsB,CAAC,WAAW,GAAG,IAAI,CAAA;IACzC,UAAU,CAAC,GAAG,EAAE,CAAC,sBAAsB,CAAC,WAAW,GAAG,EAAE,EAAE,IAAI,CAAC,CAAA;AACjE,CAAC"}

package/package.json

@@ -1,29 +1,26 @@
 {
   "name": "@stack-spot/portal-layout",
-  "version": "0.0.65",
+  "version": "1.0.0",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
-  "scripts": {
-    "build": "tsc && tsc-esm-fix --target='dist' && cpy src/layout.css dist --flat",
-    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0"
-  },
   "peerDependencies": {
-    "@citric/core": ">=6.0.0",
-    "@citric/icons": ">=5.7.1",
-    "@citric/ui": ">=5.7.2",
-    "@stack-spot/portal-theme": ">=0.0.11",
-    "@stack-spot/portal-translate": ">=0.0.6",
-    "@stack-spot/portal-components": ">=0.0.17",
-    "react": ">=18.2.0",
-    "react-dom": ">=18.2.0",
-    "styled-components": ">=6.1.1"
+    "@citric/core": "^6.0.0",
+    "@citric/icons": "^5.7.1",
+    "@citric/ui": "^5.7.2 || ^6.0.0",
+    "@stack-spot/portal-theme": "^1.0.0",
+    "@stack-spot/portal-translate": "^1.0.0",
+    "@stack-spot/portal-components": "^1.0.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "styled-components": "^6.1.10"
   },
   "devDependencies": {
     "@types/react": "^18.2.37",
     "@types/react-dom": "^18.2.15",
     "@typescript-eslint/eslint-plugin": "^6.10.0",
     "@typescript-eslint/parser": "^6.10.0",
+    "agadoo": "^3.0.0",
     "cpy-cli": "^5.0.0",
     "eslint": "^8.53.0",
     "eslint-plugin-filenames": "^1.3.2",
@@ -37,6 +34,10 @@
     "typescript": "^5.2.2"
   },
   "dependencies": {
-    "react-toastify": "^9.1.3"
+    "react-toastify": "^10.0.5"
+  },
+  "scripts": {
+    "build": "tsc && tsc-esm-fix --target='dist' && cpy src/layout.css dist --flat",
+    "lint": "eslint . --ext ts,tsx --report-unused-disable-directives --max-warnings 0"
   }
 }

package/readme.md

@@ -0,0 +1,146 @@
+# Layout
+Implements the general layout for a Stackspot web application.
+
+## Components
+- Header: a top bar with a logo and a user menu.
+- Menu (sections): a left vertical bar with every section in the application.
+- Menu (content, or contextual): a left vertical bar on the right of the menu sections that shows the menu for the current section or page.
+- Page: the actual page content.
+- Modal: a floating panel to show modal content.
+- Right panel: a floating panel that shows like a modal, but is fixed to the right side of the window.
+- Bottom dialog: a floating fixed panel fixed to the bottom of the window.
+- Toaster: a floating set of cards at the top right corner used to show notifications.
+
+The overlay components (modal, right panel, bottom dialog and toaster) are controlled imperatively through the overlay object. Example:
+`overlay.showModal(options)`.
+
+The header, menus and page are rendered by the component `<Layout>` according to its props. If you need a custom header or menu, you can use
+`<RawLayout>` which accepts React elements instead of configuration objects.
+
+You can also render the menu and header separately by importing the components `<MenuContent>`, `<MenuSections>` or `<Header>`.
+
+## The Layout component
+To render the layout, use the component `<Layout>`, check the example below:
+
+```tsx
+const menu = {
+  options: [
+    {
+      label: 'Section 1',
+      icon: <MyIcon />,
+      href: '/section-1',
+      active: true,
+    },
+    {
+      label: 'Section 2',
+      icon: <MyIcon2 />,
+      href: '/section-2',
+    }
+  ]
+}
+
+const header = {
+  userName: 'Test',
+  email: 'test@stackspot.com',
+  center: <SearchField />,
+  options: [
+    {
+      label: 'Logout',
+      icon: <Logout />,
+      onClick: () => logout(),
+    }
+  ]
+}
+
+const MyApp = () => {
+  return <Layout menu={menu} header={header}>Hello World!</Layout>
+}
+```
+
+The Header and Menu in a layout are highly customizable. Check the code documentation for more details!
+
+## Modal and right panel pitfalls
+Both these elements of the layout were designed to be used as imperative/procedural calls, i.e. instead of rendering a modal based on a
+React State, we just call `overlay.showModal(content)` or `await confirm({ message: '...' })`. This makes using a modal much easier, but
+prevents us from using React Portals.
+
+Without the use of React Portals, the modal content becomes isolated from the context it was called, meaning, updating a state of the
+component who called it, won't update the content of the modal.
+
+Programming a modal isolated from whatever called it is a good thing! It makes the code more maintainable and less coupled. But we need to
+keep this behavior in mind. See the example below:
+
+```tsx
+const Counter = () => {
+  const [current, setCurrent] = useState(0)
+  function showCounterModal() {
+    overlay.showModal({
+      title: 'Counter',
+      children: (
+        <div>
+          <p>The value is {counter}.</p>
+          <button onClick={setCurrent(v => v + 1)}>Increment</button>
+        </div>
+      ),
+    })
+  }
+  return <button onClick={showCounterModal}>Show counter modal</button>
+}
+```
+
+This won't work because the state was declared outside the modal. We may click as muck as we want to increment the value, the text will keep
+saying the first value it showed. The value will only be updated once we close the modal and open it up again.
+
+The correct way of doing this would be, instead of declaring the state outside the modal, declaring it inside, see the example below:
+
+```tsx
+const CounterModal = () => {
+  const [current, setCurrent] = useState(0)
+
+  return (
+    <div>
+      <p>The value is {counter}.</p>
+      <button onClick={setCurrent(v => v + 1)}>Increment</button>
+    </div>
+  )
+}
+
+const Counter = () => {
+  function showCounterModal() {
+    overlay.showModal({
+      title: 'Counter',
+      children: <CounterModal />,
+    })
+  }
+  return <button onClick={showCounterModal}>Show counter modal</button>
+}
+```
+
+This is going to work as expected, because the modal controls its own state!
+
+If you really need to use an external state, consider:
+
+1. Using a React Context declared before `<Layout>`.
+2. Calling `overlay.showModal()` again to force its UI to update with the new state value.
+
+### Attention: opening and closing modals are side-effects!
+The operations to open or close a modal or right panel are side effects, and, because of this, they should not be called during the
+rendering phase of a component!
+
+You should open/close a modal/rightPanel on events (e.g. `onClick`) or React effects (e.g. `useEffect`).
+
+## Layout elements
+You can easily refer to layout elements by using their ids: `elementIds` or by calling the function `getLayoutElements()`.
+
+## Error handling
+Every part of the layout is wrapped under a React Error Boundary. If an error occurs in a part of the layout that is large enough
+(e.g. Page), an error feedback is rendered. Otherwise, the content stays empty. The error is always logged to the console.
+
+In development mode, a button shows up in the error feedback, the button allows the error message to be seen without opening the console.
+For the error boundaries that don't show an error feedback, in development mode, a small error icon is rendered.
+
+To better format errors in an error boundary, please pass `errorDescriptor` to the component `<Layout>`, this is a function that transforms
+an Error into something readable to present to the user.
+
+To intercept every error when it's catch by an Error Boundary, use the property `onError` of the component `<Layout>`. This is useful for
+sending error reports to the backend.

package/src/Layout.tsx

@@ -1,4 +1,4 @@
-import { TourProps, TourProvider, defaultTourConfig, isNewTourStep } from '@stack-spot/portal-components'
+import { TourProps, TourProvider, defaultTourConfig, isNewTourStep } from '@stack-spot/portal-components/Tour'
 import { CSSToCitricAdapter, WithStyle, listToClass } from '@stack-spot/portal-theme'
 import '@stack-spot/portal-theme/dist/theme.css'
 import { ReactElement, ReactNode, useEffect } from 'react'
@@ -13,33 +13,81 @@ import { MenuSections } from './components/menu/MenuSections'
 import { MenuProps } from './components/menu/types'
 import { usePortalSwitcherStep } from './components/tour/PortalSwitcherStep'
 import { elementIds, getLayoutElements } from './elements'
-import { LayoutContext, LayoutProvider } from './layout-context'
 import './layout.css'
 
-interface Props extends WithStyle, LayoutContext {
+interface Props extends WithStyle {
+  /**
+   * The config for the menu.
+   */
   menu: MenuProps,
+  /**
+   * The config for the header.
+   */
   header: HeaderProps,
+  /**
+   * The React node to go in the page content.
+   */
   children: ReactNode,
+  /**
+   * A React node to place right after the page.
+   */
   extra?: ReactNode,
+  /**
+   * A function to convert errors into a readable format so they're properly rendered and logged.
+   */
   errorDescriptor?: DescriptionFn,
+  /**
+   * A function to run whenever an error is catch by an error boundary.
+   */
   onError?: ErrorHandler,
+  /**
+   * The options for the React Tour's tutorial.
+   */
   tourProps?: TourProps,
 }
 
-interface RawProps extends WithStyle, LayoutContext {
+interface RawProps extends WithStyle {
+  /**
+   * The React element to go in the menu sections.
+   */
   menuSections?: ReactElement,
+  /**
+   * The React element to go in the menu content.
+   */
   menuContent?: ReactElement,
+  /**
+   * The React element to go in the header.
+   */
   header?: ReactElement,
+  /**
+   * The React node to go in the page content.
+   */
   children?: ReactNode,
+  /**
+   * A React node to place right after the page.
+   */
   extra?: ReactNode,
+  /**
+   * A function to convert errors into a readable format so they're properly rendered and logged.
+   */
   errorDescriptor?: DescriptionFn,
+  /**
+   * A function to run whenever an error is catch by an error boundary.
+   */
   onError?: ErrorHandler,
+  /**
+   * The options for the React Tour's tutorial.
+   */
   tourProps?: TourProps,
 }
 
+/**
+ * Renders the layout with the React elements passed in the props.
+ * @param props the component's props {@link RawProps}.
+ */
 export const RawLayout = (
   { menuSections, menuContent, header, children, tourProps,
-    extra, errorDescriptor, onError, className, style, anchorTag }:
+    extra, errorDescriptor, onError, className, style }:
     RawProps,
 ) => {
   // @ts-ignore
@@ -68,30 +116,28 @@ export const RawLayout = (
 
   return (
     <CSSToCitricAdapter>
-      <LayoutProvider anchorTag={anchorTag}>
-        <TourProvider config={tourPropsWithDefaults} >
-          <div id={elementIds.layout} className={listToClass(classes)} style={style}>
-            {children && <div id={elementIds.page}>
-              <article id={elementIds.content}><ErrorBoundary>{children}</ErrorBoundary></article>
-            </div>}
-            {extra && <SilentErrorBoundary>{extra}</SilentErrorBoundary>}
-            <aside id={elementIds.menu}>
-              <nav role="menu" id={elementIds.menuContent}><SilentErrorBoundary>{menuContent}</SilentErrorBoundary></nav>
-              {menuSections &&
-                <nav role="menu" id={elementIds.menuSections}><SilentErrorBoundary>{menuSections}</SilentErrorBoundary></nav>}
-            </aside>
-            {header && <header id={elementIds.header}><SilentErrorBoundary>{header}</SilentErrorBoundary></header>}
-            <div id={elementIds.bottomDialog} role="dialog"><ErrorBoundary>{bottomDialog}</ErrorBoundary></div>
-            <div id={elementIds.backdrop}>
-              <div id={elementIds.rightPanel} aria-modal role="dialog"><ErrorBoundary>{rightPanel}</ErrorBoundary></div>
-              <div id={elementIds.modal} aria-modal role="dialog"><ErrorBoundary>{modal}</ErrorBoundary></div>
-            </div>
-            <Toaster />
-            <div id={elementIds.accessibilityAnnouncer} aria-atomic aria-live="assertive">
-            </div>
+      <TourProvider config={tourPropsWithDefaults} >
+        <div id={elementIds.layout} className={listToClass(classes)} style={style}>
+          {children && <div id={elementIds.page}>
+            <article id={elementIds.content}><ErrorBoundary>{children}</ErrorBoundary></article>
+          </div>}
+          {extra && <SilentErrorBoundary>{extra}</SilentErrorBoundary>}
+          <aside id={elementIds.menu}>
+            <nav role="menu" id={elementIds.menuContent}><SilentErrorBoundary>{menuContent}</SilentErrorBoundary></nav>
+            {menuSections &&
+              <nav role="menu" id={elementIds.menuSections}><SilentErrorBoundary>{menuSections}</SilentErrorBoundary></nav>}
+          </aside>
+          {header && <header id={elementIds.header}><SilentErrorBoundary>{header}</SilentErrorBoundary></header>}
+          <div id={elementIds.bottomDialog} role="dialog"><ErrorBoundary>{bottomDialog}</ErrorBoundary></div>
+          <div id={elementIds.backdrop}>
+            <div id={elementIds.rightPanel} aria-modal role="dialog"><ErrorBoundary>{rightPanel}</ErrorBoundary></div>
+            <div id={elementIds.modal} aria-modal role="dialog"><ErrorBoundary>{modal}</ErrorBoundary></div>
           </div>
-        </TourProvider>
-      </LayoutProvider>
+          <Toaster />
+          <div id={elementIds.accessibilityAnnouncer} aria-atomic aria-live="assertive">
+          </div>
+        </div>
+      </TourProvider>
     </CSSToCitricAdapter>
   )
 }
@@ -101,7 +147,11 @@ const MenuContentRenderer = ({ content }: Required<Pick<Props['menu'], 'content'
   return <MenuContent {...menuContent} />
 }
 
-export const Layout = ({ menu, header, children, extra, errorDescriptor, onError, className, style, tourProps, anchorTag }: Props) => (
+/**
+ * Renders the layout with a menu and header that follow the config objects passed as parameter.
+ * @param props the component's props {@link Props}.
+ */
+export const Layout = ({ menu, header, children, extra, errorDescriptor, onError, className, style, tourProps }: Props) => (
   <RawLayout
     header={<Header {...header} />}
     menuSections={menu.sections ? <MenuSections {...menu} /> : undefined}
@@ -115,7 +165,6 @@ export const Layout = ({ menu, header, children, extra, errorDescriptor, onError
     className={className}
     style={style}
     tourProps={tourProps}
-    anchorTag={anchorTag}
   >
     {children}
   </RawLayout>