From 70a6c583ca8d95ecfa00ec2353259aa1de909fb2 Mon Sep 17 00:00:00 2001 From: Angelina Gadzhieva Date: Tue, 20 Aug 2024 18:54:06 +0300 Subject: [PATCH] docs(AsideHeader): add description (#295) * docs(AsideHeader): add description * docs: fix typos --- src/components/AsideHeader/README.md | 147 +++++++++++++++------------ 1 file changed, 80 insertions(+), 67 deletions(-) diff --git a/src/components/AsideHeader/README.md b/src/components/AsideHeader/README.md index 41f0198..a4c87dd 100644 --- a/src/components/AsideHeader/README.md +++ b/src/components/AsideHeader/README.md @@ -1,15 +1,24 @@ + + # AsideHeader -Including additional components like `FooterItem`, `Drawer`. + + +`AsideHeader` is provided a flexible and customizable navigation experience within your application. +Users can easily customize the appearance of the sidebar to match their branding colors also to add personalized links, icons that cater specifically to their application's functionality. -## Imports +The component offers a robust solution for creating intuitive and visually appealing navigation systems, enhancing user experience while providing the flexibility to adapt to various use cases. ```ts import {AsideHeader} from '@gravity-ui/navigation'; ``` + + ## Appearance + + ### State The component has two possible states: collapsed, expanded. @@ -70,7 +79,9 @@ 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: +you may need to switch usage of `AsideHeader` to advanced style with `PageLayout`. + + ```diff --- Main.tsx @@ -104,57 +115,59 @@ export const Aside: FC = () => { }; ``` + + ## Properties -| Name | Description | Type | Default | -| :------------------------ | :----------------------------------------------------------------------------------- | :------------------------------------------------------------------------: | :---------------------: | -| className | HTML `class` attribute of the Logo | `string` | | -| collapseTitle | `CollapseButton` title for collapsing navigation | `string` | `"Свернуть" "Collapse"` | -| compact | Navigation visual state | `boolean` | `false` | -| customBackground | `AsideHeader` background | `React.ReactNode` | | -| customBackgroundClassName | Override default background container's styles | `string` | | -| expandTitle | `CollapseButton` title for expanding navigation | `string` | `"Развернуть" "Expand"` | -| headerDecoration | Color background of the top section with logo and subheader items | `boolean` | | -| hideCollapseButton | Hiding `CollapseButton`. Use `compact` prop for setting default navigation state | `boolean` | `false` | -| logo | Logo container includes icon, title, handling clicks | [`Logo`](./../Logo/Readme.md#logo) | | -| menuItems | Items in the navigation middle section | `Array` | `[]` | -| menuMoreTitle | Additional element title of menuItems if elements don't fit | `string` | `"Ещё" "More"` | -| multipleTooltip | Show multiple tooltip by hovering elements of menuItems | `boolean` | `false` | -| onChangeCompact | Callback will be called when changing navigation visual state | `(compact: boolean) => void;` | | -| onClosePanel | Callback will be called when closing panel. You can add panels via `anelItems` prop | `() => void;` | | -| onMenuItemsChanged | Callback will be called when updating list of the menuItems in AllPagesPanel | `(items: Array) => void` | | -| openModalSubscriber | Function notifies `AsideHeader` about Modals visibility changes. (Example wip) | `( (open: boolean) => void) => void` | | -| panelItems | Items for `Drawer` component. Used for show additional information over main content | Array<[`DrawerItem`](./../Drawer/README.md#draweritem-props)> | `[]` | -| renderContent | Function rendering the main content at the right of the `AsideHeader` | `(data: {size: number}) => React.ReactNode` | | -| renderFooter | Function rendering the navigation bottom section | `(data: {size: number}) => React.ReactNode` | | -| ref | `ref` to target popup anchor | `React.ForwardedRef` | | -| subheaderItems | Items in the navigation top section under Logo | `Array<{item: MenuItem; enableTooltip?: boolean; bringForward?: boolean}>` | `[]` | -| topAlert | The container above the navigation based on the uikit `Alert` component | `TopAlert` | | -| qa | The value to be passed to `data-qa` attribute of the `AsideHeader` container | `string` | | +| Name | Description | Type | Default | +| :------------------------ | :----------------------------------------------------------------------------------- | :------------------------------------------------------------------------: | :-----------------------: | +| className | HTML `class` attribute of the Logo | `string` | | +| collapseTitle | `CollapseButton` title for collapsing navigation | `string` | `"Свернуть"` `"Collapse"` | +| compact | Navigation visual state | `boolean` | `false` | +| customBackground | `AsideHeader` background | `React.ReactNode` | | +| customBackgroundClassName | Override default background container's styles | `string` | | +| expandTitle | `CollapseButton` title for expanding navigation | `string` | `"Развернуть"` `"Expand"` | +| headerDecoration | Color background of the top section with logo and subheader items | `boolean` | `false` | +| hideCollapseButton | Hiding `CollapseButton`. Use `compact` prop for setting default navigation state | `boolean` | `false` | +| logo | Logo container includes icon, title, handling clicks | [`Logo`](./../Logo/Readme.md#logo) | | +| menuItems | Items in the navigation middle section | `Array` | `[]` | +| menuMoreTitle | Additional element title of menuItems if elements don't fit | `string` | `"Ещё"` `"More"` | +| multipleTooltip | Show multiple tooltip by hovering elements of menuItems | `boolean` | `false` | +| onChangeCompact | Callback will be called when changing navigation visual state | `(compact: boolean) => void;` | | +| onClosePanel | Callback will be called when closing panel. You can add panels via `PanelItems` prop | `() => void;` | | +| onMenuItemsChanged | Callback will be called when updating list of the menuItems in `AllPagesPanel` | `(items: Array) => void` | | +| openModalSubscriber | Function notifies `AsideHeader` about Modals visibility changes | `( (open: boolean) => void) => void` | | +| panelItems | Items for `Drawer` component. Used for show additional information over main content | [`Array`](./../Drawer/README.md#draweritem-props) | `[]` | +| renderContent | Function rendering the main content at the right of the `AsideHeader` | `(data: {size: number}) => React.ReactNode` | | +| renderFooter | Function rendering the navigation bottom section | `(data: {size: number}) => React.ReactNode` | | +| ref | `ref` to target popup anchor | `React.ForwardedRef` | | +| subheaderItems | Items in the navigation top section under Logo | `Array<{item: MenuItem; enableTooltip?: boolean; bringForward?: boolean}>` | `[]` | +| topAlert | The container above the navigation based on the uikit `Alert` component | `TopAlert` | | +| qa | The value to be passed to `data-qa` attribute of the `AsideHeader` container | `string` | | ### `MenuItem` -| Name | Description | Type | Default | -| :----------------- | :------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------: | :-----------------------: | -| 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 | `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` | -| iconQa | The value to be passed to `data-qa` attribute of the `Icon` container | `string` | | -| id | The menu item id | `string` | | -| itemWrapper | The menu item wrapper | [`ItemWrapper`](https://github.com/gravity-ui/navigation/blob/main/src/components/types.ts#L32-L41) | | -| link | HTML href attribute | `string` | | -| onItemClick | Callback will be called when clicking on the item | `(item: MenuItem, collapsed: boolean, event: React.MouseEvent) => void` | | -| onItemClickCapture | Callback will be called when clicking on the item | ` (event: React.SyntheticEvent) => void` | | -| order | Determine the display order in the navigation | `number` | | -| pinned | The parameter restricts hiding menu item in the AllPagesPanel | `boolean` | | -| rightAdornment | Customize right side of the menu item | `React.ReactNode` | | -| title | The menu item title | `React.ReactNode` | | -| tooltipText | Tooltip content | `React.ReactNode` | | -| type | The menu item type changes appearance: `"regular"`, `"action"`, `"divider"` | `string` | `"regular"` | -| qa | The value to be passed to `data-qa` attribute | `string` | | +| Name | Description | Type | Default | +| :----------------- | :------------------------------------------------------------------------------------------------------ | :-------------------------------------------------------------------------------------------------------------------------------------: | :-------------------------: | +| 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 | `boolean` | `false` | +| hidden | Visibility item in the menu | `boolean` | `false` | +| 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` | +| iconQa | The value to be passed to `data-qa` attribute of the `Icon` container | `string` | | +| id | The menu item id | `string` | | +| itemWrapper | The menu item wrapper | [`ItemWrapper`](https://github.com/gravity-ui/navigation/blob/b8367cf343fc20304bc3c8d9a337d9f7d803a9b3/src/components/types.ts#L32-L41) | | +| link | HTML href attribute | `string` | | +| onItemClick | Callback will be called when clicking on the item | `(item: MenuItem, collapsed: boolean, event: React.MouseEvent) => void` | | +| onItemClickCapture | Callback will be called when clicking on the item | ` (event: React.SyntheticEvent) => void` | | +| order | Determine the display order in the navigation | `number` | | +| pinned | The parameter restricts hiding menu item in the `AllPagesPanel` | `boolean` | `false` | +| rightAdornment | Customize right side of the menu item | `React.ReactNode` | | +| title | The menu item title | `React.ReactNode` | | +| tooltipText | Tooltip content | `React.ReactNode` | | +| type | The menu item type changes appearance: `"regular"`, `"action"`, `"divider"` | `string` | `"regular"` | +| qa | The value to be passed to `data-qa` attribute | `string` | | ### `TopAlert` @@ -162,18 +175,18 @@ Top Alert can be useful for displaying important information that users need to 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 | 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) | | -| message | Message of the alert | [`AlertMessage`](https://github.com/gravity-ui/uikit/tree/main/src/components/Alert#alert-message) | | -| onCloseTopAlert | Callback will be called when clicking on the close button | `() => void` | | -| title | Title of the alert | [`AlertTitle`](https://github.com/gravity-ui/uikit/tree/main/src/components/Alert#alert-title) | | -| theme | Alert appearance | [`AlertTheme`](https://github.com/gravity-ui/uikit/tree/main/src/components/Alert#theme) | | -| view | Enable/disable background color of the alert | [`AlertView`](https://github.com/gravity-ui/uikit/tree/main/src/components/Alert#view) | | +| 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 | Centering all content | `boolean` | `false` | +| closable | Show close button and make possible to pass `onCloseTopAlert` prop | `boolean` | `false` | +| dense | Add top, bottom paddings to `TopAlert` container | `boolean` | `false` | +| icon | Override default icon | [`AlertIcon`](https://github.com/gravity-ui/uikit/tree/main/src/components/Alert#properties) | | +| message | Message of the alert | [`AlertMessage`](https://github.com/gravity-ui/uikit/tree/main/src/components/Alert#alert-message) | | +| onCloseTopAlert | Callback will be called when clicking on the close button | `() => void` | | +| title | Title of the alert | [`AlertTitle`](https://github.com/gravity-ui/uikit/tree/main/src/components/Alert#alert-title) | | +| theme | Alert appearance | [`AlertTheme`](https://github.com/gravity-ui/uikit/tree/main/src/components/Alert#theme) | `"warning"` | +| view | Enable/disable background color of the alert | [`AlertView`](https://github.com/gravity-ui/uikit/tree/main/src/components/Alert#view) | `"filled"` | ## CSS API @@ -191,13 +204,13 @@ You can customize the inner content, make alert closeable if necessary. For read | Item | | | | `--gn-aside-header-general-item-icon-color` | Icon color for Subheader and Footer items | `--g-color-text-primary` | | `--gn-aside-header-item-icon-color` | Icon color for CompositeBar items | `--g-color-text-misc` | -| `--gn-aside-header-item-text-color` | | `--g-color-text-primary` | -| `--gn-aside-header-item-background-color-hover` | | `--g-color-base-simple-hover` | +| `--gn-aside-header-item-text-color` | Text item color | `--g-color-text-primary` | +| `--gn-aside-header-item-background-color-hover` | Text color on hover | `--g-color-base-simple-hover` | | Current Item | | | -| `--gn-aside-header-item-current-background-color` | | `--g-color-base-selection` | -| `--gn-aside-header-item-current-icon-color` | | | -| `--gn-aside-header-item-current-text-color` | | `--g-color-text-primary` | -| `--gn-aside-header-item-current-background-color-hover` | | | +| `--gn-aside-header-item-current-background-color` | Current item's background color | `--g-color-base-selection` | +| `--gn-aside-header-item-current-icon-color` | Current item's icon color | | +| `--gn-aside-header-item-current-text-color` | Current item's text color | `--g-color-text-primary` | +| `--gn-aside-header-item-current-background-color-hover` | Current item's icon color on hover | | | `--gn-aside-header-item-collapsed-radius` | Item border radius for collapsed navigation | 7px | | `--gn-aside-header-item-expanded-radius` | Item border radius for expanded navigation | | | z-indexes | | |