diff --git a/apps/admin-x-design-system/.storybook/preview.tsx b/apps/admin-x-design-system/.storybook/preview.tsx index 1aa732fd80..ce01ac67ad 100644 --- a/apps/admin-x-design-system/.storybook/preview.tsx +++ b/apps/admin-x-design-system/.storybook/preview.tsx @@ -59,7 +59,7 @@ const preview: Preview = { options: { storySort: { method: 'alphabetical', - order: ['Welcome', 'Foundations', ['Style Guide', 'Colors', 'Icons', 'ErrorHandling'], 'Global', ['Form', 'Chrome', 'Modal', 'Layout', 'List', 'Table', '*'], 'Settings', ['Setting Section', 'Setting Group', '*'], 'Experimental'], + order: ['Welcome', 'Foundations', ['Style Guide', 'Colors', 'Icons', 'ErrorHandling'], 'Global', ['Form', 'Chrome', 'Modal', 'Layout', ['View Container', 'Page Header', 'Page'], 'List', 'Table', '*'], 'Settings', ['Setting Section', 'Setting Group', '*'], 'Experimental'], }, }, docs: { diff --git a/apps/admin-x-design-system/src/docs/Layout.mdx b/apps/admin-x-design-system/src/docs/Layout.mdx new file mode 100644 index 0000000000..eb5d776f10 --- /dev/null +++ b/apps/admin-x-design-system/src/docs/Layout.mdx @@ -0,0 +1,31 @@ +import { Meta } from '@storybook/blocks'; +import SBPageViewContainer from './assets/page-viewcontainer.png'; + + + +
+ +# Layout + +

The goal of the layout system is to give a simple and flexible framework for pages in the Admin. It allows designs to be focused on primary functions yet stay consistent across the whole app.

+ +### Structure + +Below you can see a the most common Admin screen structure: it consists of a [Page component](/docs/global-layout-page--docs) as the main container of a screen and a `ViewContainer` that sets the typical view boundaries and patterns for consistency. + +#### Page +The purpose of this component is to set up the main container of a page. It defines/restricts scrolling and adds app/page level elements such as search, navigation or the main menu. And ofc. it also holds the contents of a screen. + + +#### ViewContainer +There's no restriction on what [component] should be used as the main contents of a page. However most pages would need similar constraints: setting a maximum width, a streamlined sticky header or the positioning of the primary action and so on. This is the main role of the [ViewContainer component](/docs/global-layout-view-container--docs). + +### Customisation + +It's not mandatory but it's advised to use this structure to maintain consistency as much as possible. The components have a bunch of documented parameters which allows customisation to be used in the current Admin and in future developments. + +
+ +
+ +
\ No newline at end of file diff --git a/apps/admin-x-design-system/src/docs/assets/page-viewcontainer.png b/apps/admin-x-design-system/src/docs/assets/page-viewcontainer.png new file mode 100644 index 0000000000..903465bfe3 Binary files /dev/null and b/apps/admin-x-design-system/src/docs/assets/page-viewcontainer.png differ diff --git a/apps/admin-x-design-system/src/global/Toast.stories.tsx b/apps/admin-x-design-system/src/global/Toast.stories.tsx index 6609b6c0b9..3206e6dbd6 100644 --- a/apps/admin-x-design-system/src/global/Toast.stories.tsx +++ b/apps/admin-x-design-system/src/global/Toast.stories.tsx @@ -5,6 +5,10 @@ import {Toaster} from 'react-hot-toast'; import Button from './Button'; import {ShowToastProps, showToast} from './Toast'; +/** + * This component uses `react-hot-toast` which requires the `` component to be included in the app. + * The design system already does this so you don't have to — just call `showToast()` in any event and it'll work. + */ const ToastContainer: React.FC = ({...props}) => { return ( <> diff --git a/apps/admin-x-design-system/src/global/Toast.tsx b/apps/admin-x-design-system/src/global/Toast.tsx index 2ca15b19ed..0d7662c69a 100644 --- a/apps/admin-x-design-system/src/global/Toast.tsx +++ b/apps/admin-x-design-system/src/global/Toast.tsx @@ -22,6 +22,10 @@ export interface ToastProps { props?: ShowToastProps; } +/** + * This component uses `react-hot-toast` which requires the `` component to be included in the app. + * The design system already does this so you don't have to — just call `showToast()` in any event and it'll work. + */ const Toast: React.FC = ({ t, children,