Skip to content

Commit

Permalink
docs(AsideHeader): describe component (#293)
Browse files Browse the repository at this point in the history 
* docs(AsideHeader): describe component

* docs(AsideHeader): fix typos
  • Loading branch information
@Lunory
Lunory authored Aug 19, 2024
1 parent 2833dbe commit b8367cf
Showing 1 changed file with 61 additions and 8 deletions.
69 changes: 61 additions & 8 deletions src/components/AsideHeader/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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` |
Expand All @@ -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) | |
Expand Down

0 comments on commit b8367cf

Please sign in to comment.