From b8367cf343fc20304bc3c8d9a337d9f7d803a9b3 Mon Sep 17 00:00:00 2001 From: Angelina Gadzhieva Date: Mon, 19 Aug 2024 11:57:55 +0300 Subject: [PATCH] docs(AsideHeader): describe component (#293) * docs(AsideHeader): describe component * docs(AsideHeader): fix typos --- src/components/AsideHeader/README.md | 69 ++++++++++++++++++++++++---- 1 file changed, 61 insertions(+), 8 deletions(-) diff --git a/src/components/AsideHeader/README.md b/src/components/AsideHeader/README.md index 6a17aa2..41f0198 100644 --- a/src/components/AsideHeader/README.md +++ b/src/components/AsideHeader/README.md @@ -8,15 +8,66 @@ Including additional components like `FooterItem`, `Drawer`. import {AsideHeader} from '@gravity-ui/navigation'; ``` -## Rendering Content +## Appearance + +### State + +The component has two possible states: collapsed, expanded. +Уou can manage between states using `compact`, `onChangeCompact` props and also hide button with `hideCollapseButton`. + +### Top decoration + +Navigation highlights top section with Logo and Subheader items using `headerDecoration` props. + +### Custom background + +The component supports specific themization cases, e.g. image on background or splitting sections by color — using `customBackground`, `customBackgroundClassName` props. + +## Sections + +Navigation includes 3 parts: the top, the middle and the bottom. These sections are similar with a few variations of possibilities based on frequency user cases. +**Important note**: A user manages the state of the elements. + +### The Top + +The section usually contains general elements for all site pages and includes the logo and the elements below it. Clickable logo can be useful for a quick navigation to the home page, if necessary the element (e.g. search, catalogue) is placed under it. + +The elements have access to tooltip, popup, drawers, it is enough to select the desired behavior when configuring this section. + +### The Middle (menuItems) -`WIP` +The main section usually depends on context of the page — one of examples using navigation on the multipage sites. +The elements will collapse into three dots if there is no vertical space by default. -## Rendering Footer +Navigation elements can be in one of two states: collapsed (isCollapsed), where only the icon is visible, and expanded. There is some space for customization of the entire item through a wrapper. -`WIP` +With additional configuration via `AllPages` users can further customize menu to their preference by hiding unnecessary items. This brings in a new state for items - pinned/hidden. If item is pinned, it will always be displayed in the section. -## Rendering optimization +The `onMenuItemsChanged` callback is required for adding extra component `All Pages` which displays panel for editing the list of visible menu items. + +**Important note**: A user manages a modified list of the menu items that they receive from the callback and provides the new state of items to `AsideHeader`. + +### The Bottom + +The Footer improves user experience by offering easy access to the elements and supplementary resources. It gives opportunity to connect with support add custom information to be sure that user will not get lost. + +There can be both their own components inside, or also you can use `AsideHeaderFooterItem`. + +#### Highlighting element + +Highlighting an element over modal windows can be useful when a user wants to report an error via a feedback form, and the form with bug is opened in a modal window. + +In the `AsideHeaderFooterItem` component, you can pass a `bringForward` prop, which renders the icon above modal windows. Additionally, you need to pass a function to `AsideHeader` that will notify about the opening of modal windows. + +## Rendering Content + +Right part near to AsideHeader is place for main page content. +When expanding and collapsing navigation, navigation `size` will be changed. This knowledge may be helpful, e.g. recalculating layout in some components. +CSS-variable `--gn-aside-header-size` contains actual navigation size. + +See below about alternative path of rendering content. + +### Rendering optimization If your app content needs to be rendered faster than by passing it throw `AsideHeader` props, you may need to switch usage of `AsideHeader` to advanced style with `PageLayout` like this: @@ -87,7 +138,7 @@ export const Aside: FC = () => { | :----------------- | :------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------: | :-----------------------: | | afterMoreButton | The menu item will be placed in the end, even item don't fit | `boolean` | | | category | The category to which the menu item belongs. Need for grouping in the display/editing mode of all pages | `string` | `"Остальное" "All other"` | -| current | The current/selected item | `boolen` | `false` | +| current | The current/selected item | `boolean` | `false` | | hidden | Visibility item in the menu | `boolean` | | | icon | Menu icon based on the uikit `Icon` component | [`IconProps['data']`](https://github.com/gravity-ui/uikit/tree/main/src/components/Icon#properties) | | | iconSize | Menu icon size | `number` `string` | `18` | @@ -107,12 +158,14 @@ export const Aside: FC = () => { ### `TopAlert` -`Description WIP` +Top Alert can be useful for displaying important information that users need to know. This alert is often appeared in all pages like call to action or warning. + +You can customize the inner content, make alert closeable if necessary. For reading top alert height see value from CSS variable `--gn-aside-top-panel-height`. | Name | Description | Type | Default | | :-------------- | :----------------------------------------------------------------- | :------------------------------------------------------------------------------------------------: | :-----: | | actions | Array of buttons or full custom components | [`AlertActions`](https://github.com/gravity-ui/uikit/tree/main/src/components/Alert#properties) | | -| centered | Cetering all content | `boolean` | | +| centered | Centering all content | `boolean` | | | closable | Show close button and make possible to pass `onCloseTopAlert` prop | `boolean` | | | dense | Add top, bottom paddings to `TopAlert` container | `boolean` | | | icon | Override default icon | [`AlertIcon`](https://github.com/gravity-ui/uikit/tree/main/src/components/Alert#properties) | |