@gravity-ui/navigation 6.2.0 → 6.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +4 -0
- package/build/docs/INDEX.md +89 -0
- package/build/docs/components/ActionBar.md +152 -0
- package/build/docs/components/AsideHeader/components/AllPagesPanel.md +80 -0
- package/build/docs/components/AsideHeader.md +351 -0
- package/build/docs/components/Footer.md +114 -0
- package/build/docs/components/HotkeysPanel.md +46 -0
- package/build/docs/components/Logo.md +22 -0
- package/build/docs/components/MobileHeader.md +82 -0
- package/build/docs/components/Settings.md +113 -0
- package/build/docs/hooks/useOverflowingHorizontalListItems.md +16 -0
- package/package.json +4 -2
package/README.md
CHANGED
|
@@ -114,3 +114,7 @@ Application-shell navigation components for Gravity UI apps — the collapsible
|
|
|
114
114
|
- **Peer dependencies are required.** `@gravity-ui/uikit`, `@gravity-ui/icons`, and `@bem-react/classname` must be installed alongside `react`/`react-dom`.
|
|
115
115
|
- **Needs uikit setup.** Render inside `ThemeProvider` and import `@gravity-ui/uikit/styles/styles.css`, or the shell renders unstyled.
|
|
116
116
|
- **Page content goes through `renderContent`.** Render your routed content via the `renderContent` prop / `PageLayout`, not as `children`.
|
|
117
|
+
|
|
118
|
+
## Documentation for AI agents
|
|
119
|
+
|
|
120
|
+
Agent-readable documentation for the installed version is located in `node_modules/@gravity-ui/navigation/build/docs/INDEX.md`.
|
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
# @gravity-ui/navigation documentation
|
|
2
|
+
|
|
3
|
+
Documentation for the **installed** version of `@gravity-ui/navigation`.
|
|
4
|
+
Your training data may be outdated — these files are the source of truth.
|
|
5
|
+
|
|
6
|
+
Paths are relative to this file (`node_modules/@gravity-ui/navigation/build/docs/`).
|
|
7
|
+
|
|
8
|
+
## For AI agents
|
|
9
|
+
|
|
10
|
+
Application-shell navigation components for Gravity UI apps — the collapsible `AsideHeader` sidebar plus footers, drawers, logo, hotkeys and settings panels that frame a whole page.
|
|
11
|
+
|
|
12
|
+
### When to use
|
|
13
|
+
|
|
14
|
+
- The app's primary navigation frame: `AsideHeader` (collapsible side navigation) with `menuItems`, subheader, and footer sections.
|
|
15
|
+
- Supporting shell UI: `Drawer`/`DrawerItem`, `Footer`/`MobileFooter`, `MobileHeader`, `HotkeysPanel`, `Settings`, `ActionBar`, `Logo`.
|
|
16
|
+
- Laying out page content inside the navigation frame via `renderContent` / `PageLayout`.
|
|
17
|
+
|
|
18
|
+
### When not to use
|
|
19
|
+
|
|
20
|
+
- Generic in-page controls (buttons, tabs, menus, breadcrumbs) — use [`@gravity-ui/uikit`](https://github.com/gravity-ui/uikit); this package is the outer app chrome, not general components.
|
|
21
|
+
- Rendering the page body itself from config — use [`@gravity-ui/page-constructor`](https://github.com/gravity-ui/page-constructor).
|
|
22
|
+
- Client-side routing — this provides the navigation UI only; wire clicks to your own router.
|
|
23
|
+
|
|
24
|
+
### Common pitfalls
|
|
25
|
+
|
|
26
|
+
- **`AsideHeader` is controlled.** You must own the collapsed state with `compact` and update it in `onChangeCompact`; passing `compact` without the handler freezes the sidebar.
|
|
27
|
+
- **Menu items are `menuItems`, keyed by `id`.** Each item is `{id, title, icon, current, onItemClick}`; `icon` takes an icon component (e.g. from `@gravity-ui/icons`), not a string name.
|
|
28
|
+
- **Peer dependencies are required.** `@gravity-ui/uikit`, `@gravity-ui/icons`, and `@bem-react/classname` must be installed alongside `react`/`react-dom`.
|
|
29
|
+
- **Needs uikit setup.** Render inside `ThemeProvider` and import `@gravity-ui/uikit/styles/styles.css`, or the shell renders unstyled.
|
|
30
|
+
- **Page content goes through `renderContent`.** Render your routed content via the `renderContent` prop / `PageLayout`, not as `children`.
|
|
31
|
+
|
|
32
|
+
## Install
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
npm install @gravity-ui/navigation
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
Ensure that peer dependencies are installed in your project
|
|
39
|
+
|
|
40
|
+
```bash
|
|
41
|
+
npm install --dev @gravity-ui/uikit@^7.2.0 @gravity-ui/icons@^2.2.0 @bem-react/classname@^1.6.0 react@^19.0.0 react-dom@^19.0.0
|
|
42
|
+
```
|
|
43
|
+
|
|
44
|
+
## Usage
|
|
45
|
+
|
|
46
|
+
Render `AsideHeader` as the app shell. It is a controlled component — you own the collapsed state via `compact`/`onChangeCompact` — and your page content goes through `renderContent`. Set up `@gravity-ui/uikit` styles and `ThemeProvider` first (see the [uikit styles guide](https://github.com/gravity-ui/uikit?tab=readme-ov-file#styles)).
|
|
47
|
+
|
|
48
|
+
```tsx
|
|
49
|
+
import React from 'react';
|
|
50
|
+
import {AsideHeader} from '@gravity-ui/navigation';
|
|
51
|
+
import {Gear, House} from '@gravity-ui/icons';
|
|
52
|
+
import {ThemeProvider} from '@gravity-ui/uikit';
|
|
53
|
+
|
|
54
|
+
import '@gravity-ui/uikit/styles/styles.css';
|
|
55
|
+
|
|
56
|
+
export function App() {
|
|
57
|
+
const [compact, setCompact] = React.useState(false);
|
|
58
|
+
|
|
59
|
+
return (
|
|
60
|
+
<ThemeProvider theme="light">
|
|
61
|
+
<AsideHeader
|
|
62
|
+
logo={{text: 'My App', href: '/'}}
|
|
63
|
+
compact={compact}
|
|
64
|
+
onChangeCompact={setCompact}
|
|
65
|
+
menuItems={[
|
|
66
|
+
{id: 'home', title: 'Home', icon: House, current: true},
|
|
67
|
+
{id: 'settings', title: 'Settings', icon: Gear},
|
|
68
|
+
]}
|
|
69
|
+
renderContent={() => <main>Page content</main>}
|
|
70
|
+
/>
|
|
71
|
+
</ThemeProvider>
|
|
72
|
+
);
|
|
73
|
+
}
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
## Components
|
|
77
|
+
|
|
78
|
+
- [ActionBar](./components/ActionBar.md) — The component is a flexible horizontal bar that provides a standardized layout for arranging navigation elements, actions, and informational content within an application. It serves as a container for organizing UI elements like breadcrumbs, buttons, and dropdown menus into defined sections and groups.
|
|
79
|
+
- [AsideHeader](./components/AsideHeader.md) — 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.
|
|
80
|
+
- [AsideHeader/components/AllPagesPanel](./components/AsideHeader/components/AllPagesPanel.md) — A navigation panel for managing and organizing application pages in the middle (menuItems) section of AsideHeader component. Panel provides drag-and-drop reordering, visibility toggles, pin/unpin and category grouping of menu items.
|
|
81
|
+
- [Footer](./components/Footer.md) — The page footer components. Use Footer for the desktop version and MobileFooter for the mobile version. Both components have the same properties.
|
|
82
|
+
- [HotkeysPanel](./components/HotkeysPanel.md) — A navigation panel for hotkeys documentation. The panel displays a set of hotkeys for your application with a description of their purpose.
|
|
83
|
+
- [Logo](./components/Logo.md) — Logo icon is wrapped in UIKit Button, text is wrapped in HTML tag a or div, when passing hasWrapper prop.
|
|
84
|
+
- [MobileHeader](./components/MobileHeader.md) — Header for Mobile navigation. MobileHeader provides maintaining Panels except for Modals.
|
|
85
|
+
- [Settings](./components/Settings.md) — The Settings component provides the layout for a settings panel with the following features.
|
|
86
|
+
|
|
87
|
+
## Hooks
|
|
88
|
+
|
|
89
|
+
- [useOverflowingHorizontalListItems](./hooks/useOverflowingHorizontalListItems.md) — A hook for determining which horizontal list items stay visible and which collapse into an overflow "more" dropdown.
|
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
# ActionBar
|
|
2
|
+
|
|
3
|
+
The component is a flexible horizontal bar that provides a standardized layout for arranging navigation elements, actions, and informational content within an application. It serves as a container for organizing UI elements like breadcrumbs, buttons, and dropdown menus into defined sections and groups.
|
|
4
|
+
|
|
5
|
+
## Usage
|
|
6
|
+
|
|
7
|
+
```typescript jsx
|
|
8
|
+
import {Button} from '@gravity-ui/uikit';
|
|
9
|
+
import {Breadcrumbs as LegacyBreadcrumbs} from '@gravity-ui/uikit/legacy';
|
|
10
|
+
import {ActionBar} from '@gravity-ui/navigation';
|
|
11
|
+
|
|
12
|
+
function Page() {
|
|
13
|
+
return (
|
|
14
|
+
<ActionBar aria-label="Actions bar">
|
|
15
|
+
<ActionBar.Section>
|
|
16
|
+
<ActionBar.Group>
|
|
17
|
+
<ActionBar.Item>
|
|
18
|
+
<LegacyBreadcrumbs
|
|
19
|
+
lastDisplayedItemsCount={1}
|
|
20
|
+
firstDisplayedItemsCount={1}
|
|
21
|
+
items={[{text: 'Root Item', action() {}}]}
|
|
22
|
+
/>
|
|
23
|
+
</ActionBar.Item>
|
|
24
|
+
</ActionBar.Group>
|
|
25
|
+
|
|
26
|
+
<ActionBar.Group pull="right">
|
|
27
|
+
<ActionBar.Item>
|
|
28
|
+
<Button>Do something</Button>
|
|
29
|
+
</ActionBar.Item>
|
|
30
|
+
</ActionBar.Group>
|
|
31
|
+
</ActionBar.Section>
|
|
32
|
+
</ActionBar>
|
|
33
|
+
);
|
|
34
|
+
}
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
The `ActionBar` provides several nested components that work together to create a structured layout: `ActionBar.Section`, `ActionBar.Group`, `ActionBar.Item`, `ActionBar.Separator`.
|
|
38
|
+
|
|
39
|
+
## Properties
|
|
40
|
+
|
|
41
|
+
| Name | Description | Type | Default |
|
|
42
|
+
| :--------- | :----------------------------------------- | :-------------------: | :-----: |
|
|
43
|
+
| aria-label | HTML `aria-label` attribute | `string` | |
|
|
44
|
+
| className | HTML `class` attribute | `string` | |
|
|
45
|
+
| style | HTML `style` attribute | `React.CSSProperties` | |
|
|
46
|
+
| qa | `data-qa` HTML attribute, used for testing | `string` | |
|
|
47
|
+
|
|
48
|
+
## ActionBar.Section
|
|
49
|
+
|
|
50
|
+
Decorative component to visually separate different kinds of navigation.
|
|
51
|
+
There is two kinds of sections presented — `primary` and `secondary`. We recommend an app to have at least `primary`
|
|
52
|
+
section. `secondary` could be used for app specific controls, that should be accented with smaller paddings and
|
|
53
|
+
horizontal separator from `primary` section.
|
|
54
|
+
|
|
55
|
+
### Properties
|
|
56
|
+
|
|
57
|
+
| Name | Description | Type | Default |
|
|
58
|
+
| :-------- | :----------------------------------------------- | :------------------------: | :---------: |
|
|
59
|
+
| type | Type specifies the visual styling of the section | `"primary"`, `"secondary"` | `"primary"` |
|
|
60
|
+
| className | HTML `class` attribute | `string` | |
|
|
61
|
+
| style | HTML `style` attribute | `React.CSSProperties` | |
|
|
62
|
+
| qa | `data-qa` HTML attribute, used for testing | `string` | |
|
|
63
|
+
|
|
64
|
+
```tsx
|
|
65
|
+
import {Button} from '@gravity-ui/uikit';
|
|
66
|
+
import {Breadcrumbs as LegacyBreadcrumbs} from '@gravity-ui/uikit/legacy';
|
|
67
|
+
import {ActionBar} from '@gravity-ui/navigation';
|
|
68
|
+
|
|
69
|
+
<ActionBar aria-label="Actions bar">
|
|
70
|
+
<ActionBar.Section type="secondary">
|
|
71
|
+
<ActionBar.Group>
|
|
72
|
+
<ActionBar.Item>
|
|
73
|
+
<Button>Toggle Article TOC</Button>
|
|
74
|
+
</ActionBar.Item>
|
|
75
|
+
</ActionBar.Group>
|
|
76
|
+
</ActionBar.Section>
|
|
77
|
+
|
|
78
|
+
<ActionBar.Section type="primary">
|
|
79
|
+
<ActionBar.Group>
|
|
80
|
+
<ActionBar.Item>
|
|
81
|
+
<LegacyBreadcrumbs
|
|
82
|
+
lastDisplayedItemsCount={1}
|
|
83
|
+
firstDisplayedItemsCount={1}
|
|
84
|
+
items={[
|
|
85
|
+
{text: 'Wiki Main Page', action() {}},
|
|
86
|
+
{text: 'Wiki Article', action() {}},
|
|
87
|
+
]}
|
|
88
|
+
/>
|
|
89
|
+
</ActionBar.Item>
|
|
90
|
+
</ActionBar.Group>
|
|
91
|
+
</ActionBar.Section>
|
|
92
|
+
</ActionBar>;
|
|
93
|
+
```
|
|
94
|
+
|
|
95
|
+
## ActionBar.Group
|
|
96
|
+
|
|
97
|
+
Groups organize `ActionBar.Item` within a section and control their alignment.
|
|
98
|
+
|
|
99
|
+
### Properties
|
|
100
|
+
|
|
101
|
+
| Name | Description | Type | Default |
|
|
102
|
+
| :--------------- | :---------------------------------------------------------------- | :-----------------------------------------------------------------------------: | :-----: |
|
|
103
|
+
| pull | Controls the alignment of the group | `"left"`, `"left-grow"`, `"right"`, `"right-grow"`, `"center"`, `"center-grow"` | |
|
|
104
|
+
| stretchContainer | Set `flex-grow: 1` for Group. Need to support UIKit@7 Breadcrumbs | `boolean` | |
|
|
105
|
+
| className | HTML `class` attribute | `string` | |
|
|
106
|
+
| style | HTML `style` attribute | `React.CSSProperties` | |
|
|
107
|
+
| qa | `data-qa` HTML attribute, used for testing | `string` | |
|
|
108
|
+
|
|
109
|
+
## ActionBar.Item
|
|
110
|
+
|
|
111
|
+
Container for UI elements like buttons, breadcrumbs or other components must be in `ActionBar.Group`. The component adds margins between items.
|
|
112
|
+
|
|
113
|
+
### Properties
|
|
114
|
+
|
|
115
|
+
| Name | Description | Type | Default |
|
|
116
|
+
| :-------- | :----------------------------------------- | :-------------------: | :-----: |
|
|
117
|
+
| spacing | Enable spacing with previous item | `boolean` | `true` |
|
|
118
|
+
| className | HTML `class` attribute | `string` | |
|
|
119
|
+
| style | HTML `style` attribute | `React.CSSProperties` | |
|
|
120
|
+
| qa | `data-qa` HTML attribute, used for testing | `string` | |
|
|
121
|
+
|
|
122
|
+
## ActionBar.Separator
|
|
123
|
+
|
|
124
|
+
Visual divider that can be placed between items in a group to separate them visually.
|
|
125
|
+
|
|
126
|
+
### Example
|
|
127
|
+
|
|
128
|
+
```typescript jsx
|
|
129
|
+
import {Button} from '@gravity-ui/uikit';
|
|
130
|
+
import {Breadcrumbs as LegacyBreadcrumbs} from '@gravity-ui/uikit/legacy';
|
|
131
|
+
import {ActionBar} from '@gravity-ui/navigation';
|
|
132
|
+
|
|
133
|
+
function Page() {
|
|
134
|
+
return (
|
|
135
|
+
<ActionBar aria-label="Actions bar">
|
|
136
|
+
<ActionBar.Section>
|
|
137
|
+
<ActionBar.Group pull="right">
|
|
138
|
+
<ActionBar.Item>
|
|
139
|
+
<Button>Do something</Button>
|
|
140
|
+
</ActionBar.Item>
|
|
141
|
+
|
|
142
|
+
<ActionBar.Separator />
|
|
143
|
+
|
|
144
|
+
<ActionBar.Item>
|
|
145
|
+
<Button>Do something</Button>
|
|
146
|
+
</ActionBar.Item>
|
|
147
|
+
</ActionBar.Group>
|
|
148
|
+
</ActionBar.Section>
|
|
149
|
+
</ActionBar>
|
|
150
|
+
);
|
|
151
|
+
}
|
|
152
|
+
```
|
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# AllPagesPanel
|
|
2
|
+
|
|
3
|
+
A navigation panel for managing and organizing application pages in the middle (menuItems) section of `AsideHeader` component. Panel provides drag-and-drop reordering, visibility toggles, pin/unpin and category grouping of menu items.
|
|
4
|
+
|
|
5
|
+
## Usage
|
|
6
|
+
|
|
7
|
+
```tsx
|
|
8
|
+
import React from 'react';
|
|
9
|
+
import {AsideHeader, type AsideHeaderProps} from '@gravity-ui/navigation';
|
|
10
|
+
|
|
11
|
+
const DEFAULT_MENU_ITEMS: AsideHeaderProps['menuItems'] = [
|
|
12
|
+
{item: {id: 'home', title: 'Home', icon: 'home'}},
|
|
13
|
+
{item: {id: 'analytics', title: 'Analytics', icon: 'chart'}},
|
|
14
|
+
{item: {id: 'settings', title: 'Settings', icon: 'gear'}},
|
|
15
|
+
];
|
|
16
|
+
|
|
17
|
+
const Navigation: React.FC<React.PropsWithChildren> = ({children}) => {
|
|
18
|
+
const {defaultMenuItems, menuItems, setMenuItems} = useMenuItems();
|
|
19
|
+
|
|
20
|
+
return (
|
|
21
|
+
<AsideHeader
|
|
22
|
+
className={b()}
|
|
23
|
+
logo={{
|
|
24
|
+
icon: GravityLogo,
|
|
25
|
+
iconSize: 30,
|
|
26
|
+
text: 'Gravity App',
|
|
27
|
+
href: '#',
|
|
28
|
+
}}
|
|
29
|
+
menuItems={menuItems}
|
|
30
|
+
compact={compact}
|
|
31
|
+
onChangeCompact={setCompact}
|
|
32
|
+
renderContent={() => children}
|
|
33
|
+
// All pages
|
|
34
|
+
defaultMenuItems={defaultMenuItems}
|
|
35
|
+
editMenuProps={{enableSorting: true}}
|
|
36
|
+
onMenuItemsChanged={setMenuItems}
|
|
37
|
+
/>
|
|
38
|
+
);
|
|
39
|
+
};
|
|
40
|
+
|
|
41
|
+
const useMenuItems = () => {
|
|
42
|
+
const location = useLocation();
|
|
43
|
+
|
|
44
|
+
const [menuItems, setMenuItems] = React.useState(DEFAULT_MENU_ITEMS);
|
|
45
|
+
|
|
46
|
+
const currentMenuItems = menuItems.map<AsideHeaderItem>((item, index) => {
|
|
47
|
+
if ('type' in item || index > 5) {
|
|
48
|
+
return item;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
return {
|
|
52
|
+
...item,
|
|
53
|
+
current: (item.href || '') === location.pathname,
|
|
54
|
+
};
|
|
55
|
+
});
|
|
56
|
+
|
|
57
|
+
return {defaultMenuItems: DEFAULT_MENU_ITEMS, menuItems: currentMenuItems, setMenuItems};
|
|
58
|
+
};
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
## Properties
|
|
62
|
+
|
|
63
|
+
| Name | Description | Type | Default |
|
|
64
|
+
| :----------------- | :----------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------: | :-----: |
|
|
65
|
+
| defaultMenuItems | Default items in the navigation middle section | [`Array<AsideHeaderItem>`](https://github.com/gravity-ui/navigation/blob/main/src/components/AsideHeader/README.md#menuitem) | `[]` |
|
|
66
|
+
| menuItems | Modifying items in the navigation middle section | [`Array<AsideHeaderItem>`](https://github.com/gravity-ui/navigation/blob/main/src/components/AsideHeader/README.md#menuitem) | `[]` |
|
|
67
|
+
| editMenuProps | desc | `type` | |
|
|
68
|
+
| onMenuItemsChanged | Callback will be called when updating list of the menuItems in `AllPagesPanel` | `(items: Array<AsideHeaderItem>) => void` | |
|
|
69
|
+
|
|
70
|
+
### `EditMenuProps`
|
|
71
|
+
|
|
72
|
+
Provides settings and callbacks for managing panel and menu items in the `AsideHeader`. Callbacks are optional, you can managing with `AsideHeader.onMenuItemsChanged` prop.
|
|
73
|
+
|
|
74
|
+
| Name | Description | Type | Default |
|
|
75
|
+
| :----------------------- | :------------------------------------------------------- | :---------------------------------------------------------------------------: | :-----: |
|
|
76
|
+
| enableSorting | Enable sorting functionality in the panel | `boolean` | |
|
|
77
|
+
| onOpenEditMode | Callback triggered when the edit mode is enabled | `() => void` | |
|
|
78
|
+
| onToggleMenuItem | Callback triggered when the menu item visible is toggled | `(changedItem: AsideHeaderItem) => void` | |
|
|
79
|
+
| onResetSettingsToDefault | Callback triggered when settings are reset to default | `() => void` | |
|
|
80
|
+
| onChangeItemsOrder | Callback triggered when the order of items is changed | `(changedItem: AsideHeaderItem, oldIndex: number, newIndex: number) => void;` | |
|
|
@@ -0,0 +1,351 @@
|
|
|
1
|
+
# AsideHeader
|
|
2
|
+
|
|
3
|
+
`AsideHeader` is provided a flexible and customizable navigation experience within your application.
|
|
4
|
+
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.
|
|
5
|
+
|
|
6
|
+
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.
|
|
7
|
+
|
|
8
|
+
```ts
|
|
9
|
+
import {AsideHeader} from '@gravity-ui/navigation';
|
|
10
|
+
```
|
|
11
|
+
|
|
12
|
+
## Appearance
|
|
13
|
+
|
|
14
|
+
### State
|
|
15
|
+
|
|
16
|
+
The component has two possible states: collapsed, expanded.
|
|
17
|
+
Уou can manage between states using `compact`, `onChangeCompact` props and also hide button with `hideCollapseButton`.
|
|
18
|
+
|
|
19
|
+
### Top decoration
|
|
20
|
+
|
|
21
|
+
Navigation highlights top section with Logo and Subheader items using `headerDecoration` props.
|
|
22
|
+
|
|
23
|
+
### Custom background
|
|
24
|
+
|
|
25
|
+
The component supports specific themization cases, e.g. image on background or splitting sections by color — using `customBackground`, `customBackgroundClassName` props.
|
|
26
|
+
|
|
27
|
+
## Sections
|
|
28
|
+
|
|
29
|
+
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.
|
|
30
|
+
**Important note**: A user manages the state of the elements.
|
|
31
|
+
|
|
32
|
+
### The Top
|
|
33
|
+
|
|
34
|
+
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.
|
|
35
|
+
|
|
36
|
+
### The Middle (menuItems)
|
|
37
|
+
|
|
38
|
+
The main section usually depends on context of the page — one of examples using navigation on the multipage sites.
|
|
39
|
+
The elements will collapse into three dots if there is no vertical space by default.
|
|
40
|
+
|
|
41
|
+
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.
|
|
42
|
+
|
|
43
|
+
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 - `hidden`. If item is pinned, it will always be displayed in the section.
|
|
44
|
+
|
|
45
|
+
The `onMenuItemsChanged` callback is required for adding extra component `All Pages` which displays panel for editing the list of visible menu items.
|
|
46
|
+
|
|
47
|
+
**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`.
|
|
48
|
+
|
|
49
|
+
The elements of this block can have multiple tooltips.
|
|
50
|
+
|
|
51
|
+
#### Content above the menu (`aboveMenuContent`)
|
|
52
|
+
|
|
53
|
+
Pass **`aboveMenuContent`** to render arbitrary content between the header (logo and `subheaderItems`) and the main **`menuItems`** list.
|
|
54
|
+
|
|
55
|
+
With **`menuOverflow="scroll"`**, that block stays fixed above the scrollable menu column; only the menu rows scroll.
|
|
56
|
+
|
|
57
|
+
**Example:**
|
|
58
|
+
|
|
59
|
+
```tsx
|
|
60
|
+
<AsideHeader
|
|
61
|
+
logo={logo}
|
|
62
|
+
menuItems={menuItems}
|
|
63
|
+
compact={compact}
|
|
64
|
+
onChangeCompact={setCompact}
|
|
65
|
+
aboveMenuContent={
|
|
66
|
+
compact ? null : (
|
|
67
|
+
<Box spacing={{p: 2}}>
|
|
68
|
+
<Select
|
|
69
|
+
placeholder="Select tenant"
|
|
70
|
+
options={tenantOptions}
|
|
71
|
+
value={tenant ? [tenant] : []}
|
|
72
|
+
onUpdate={(values) => setTenant(values[0])}
|
|
73
|
+
width="max"
|
|
74
|
+
/>
|
|
75
|
+
</Box>
|
|
76
|
+
)
|
|
77
|
+
}
|
|
78
|
+
/>
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
### The Bottom
|
|
82
|
+
|
|
83
|
+
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.
|
|
84
|
+
|
|
85
|
+
There can be both their own components inside, or also you can use `FooterItem`.
|
|
86
|
+
|
|
87
|
+
## Elements
|
|
88
|
+
|
|
89
|
+
The elements have access to tooltip, popup, drawers, it is enough to select the desired behavior when configuring this section.
|
|
90
|
+
|
|
91
|
+
#### Popup Windows
|
|
92
|
+
|
|
93
|
+
⚠️ **Important**: Built-in popup fields (`popupVisible`, `popupRef`, `popupPlacement`, `popupOffset`, `popupKeepMounted`, `renderPopupContent`, `onOpenChangePopup`) are marked as deprecated and will be removed in future versions.
|
|
94
|
+
|
|
95
|
+
For creating popup windows, it is now recommended to use the `itemWrapper` property. This provides more flexibility and control over element behavior.
|
|
96
|
+
|
|
97
|
+
**Example of using itemWrapper to create a popup:**
|
|
98
|
+
|
|
99
|
+
```tsx
|
|
100
|
+
import {Popup} from '@gravity-ui/uikit';
|
|
101
|
+
|
|
102
|
+
const menuItems: AsideHeaderItem[] = [
|
|
103
|
+
{
|
|
104
|
+
id: 'item-with-popup',
|
|
105
|
+
title: 'Item with popup',
|
|
106
|
+
icon: 'settings',
|
|
107
|
+
itemWrapper: (params, makeItem, opts) => {
|
|
108
|
+
const [popupOpen, setPopupOpen] = React.useState(false);
|
|
109
|
+
const anchorRef = React.useRef<HTMLElement>(null);
|
|
110
|
+
|
|
111
|
+
return (
|
|
112
|
+
<>
|
|
113
|
+
<div ref={anchorRef} onClick={() => setPopupOpen(!popupOpen)}>
|
|
114
|
+
{makeItem(params)}
|
|
115
|
+
</div>
|
|
116
|
+
<Popup
|
|
117
|
+
open={popupOpen}
|
|
118
|
+
anchorRef={anchorRef}
|
|
119
|
+
onOpenChange={setPopupOpen}
|
|
120
|
+
placement="right-start"
|
|
121
|
+
>
|
|
122
|
+
<div style={{padding: '12px'}}>Popup content</div>
|
|
123
|
+
</Popup>
|
|
124
|
+
</>
|
|
125
|
+
);
|
|
126
|
+
},
|
|
127
|
+
},
|
|
128
|
+
];
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
#### Highlighting element
|
|
132
|
+
|
|
133
|
+
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.
|
|
134
|
+
|
|
135
|
+
In the `FooterItem` component and in the configuration of the `menuItems` and `subheaderItems` elements, you can pass the `bringForward` property, which displays an icon on top of the modal windows. Additionally, in the `AsideHeader`, you need to pass a function that will notify you when the modal windows are opened.
|
|
136
|
+
|
|
137
|
+
## Rendering Content
|
|
138
|
+
|
|
139
|
+
Right part near to AsideHeader is place for main page content.
|
|
140
|
+
When expanding and collapsing navigation, navigation `size` will be changed. This knowledge may be helpful, e.g. recalculating layout in some components.
|
|
141
|
+
CSS-variable `--gn-aside-header-size` contains actual navigation size.
|
|
142
|
+
|
|
143
|
+
See below about alternative path of rendering content.
|
|
144
|
+
|
|
145
|
+
### Rendering optimization
|
|
146
|
+
|
|
147
|
+
If your app content needs to be rendered faster than by passing it throw `AsideHeader` props,
|
|
148
|
+
you may need to switch usage of `AsideHeader` to advanced style with `PageLayout`.
|
|
149
|
+
|
|
150
|
+
```diff
|
|
151
|
+
--- Main.tsx
|
|
152
|
+
+++ Main.tsx
|
|
153
|
+
-import {AsideHeader} from './AsideHeader'
|
|
154
|
+
+import {PageLayout, AsideFallback} from '@gravity-ui/navigation';
|
|
155
|
+
+const Aside = React.lazy(() =>
|
|
156
|
+
+ import('./Aside').then(({Aside}) => ({ default: Aside }))
|
|
157
|
+
+);
|
|
158
|
+
|
|
159
|
+
- <AsideHeader renderContent={renderContent} {...restProps} />
|
|
160
|
+
+ <PageLayout>
|
|
161
|
+
+ <Suspense fallback={<AsideFallback />}>
|
|
162
|
+
+ <Aside />
|
|
163
|
+
+ </Suspense>
|
|
164
|
+
+
|
|
165
|
+
+ <PageLayout.Content>
|
|
166
|
+
+ <ContentExample />
|
|
167
|
+
+ </PageLayout.Content>
|
|
168
|
+
+ </PageLayout>
|
|
169
|
+
--- Aside.tsx
|
|
170
|
+
+++ Aside.tsx
|
|
171
|
+
-import {AsideHeader} from '@gravity-ui/navigation';
|
|
172
|
+
+import {PageLayoutAside} from '@gravity-ui/navigation';
|
|
173
|
+
|
|
174
|
+
export const Aside: FC = () => {
|
|
175
|
+
return (
|
|
176
|
+
- <AsideHeader {...props}>
|
|
177
|
+
+ <PageLayoutAside {...props}/>
|
|
178
|
+
);
|
|
179
|
+
};
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
## Properties
|
|
183
|
+
|
|
184
|
+
| Name | Description | Type | Default |
|
|
185
|
+
| :--------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :---------------------------------------------------------------------------------------------------------------------------: | :-----------------------: |
|
|
186
|
+
| className | HTML `class` attribute of the Logo | `string` | |
|
|
187
|
+
| collapseButtonWrapper | Wrapper for `CollapseButton` allowing customization of the default button appearance | `(defaultButton: React.ReactNode, data: {compact: boolean; onChangeCompact?: (compact: boolean) => void}) => React.ReactNode` | |
|
|
188
|
+
| collapseTitle | `CollapseButton` title for collapsing navigation | `string` | `"Свернуть"` `"Collapse"` |
|
|
189
|
+
| compact | Navigation visual state | `boolean` | `false` |
|
|
190
|
+
| customBackground | `AsideHeader` background | `React.ReactNode` | |
|
|
191
|
+
| customBackgroundClassName | Override default background container's styles | `string` | |
|
|
192
|
+
| expandTitle | `CollapseButton` title for expanding navigation | `string` | `"Развернуть"` `"Expand"` |
|
|
193
|
+
| headerDecoration | Color background of the top section with logo and subheader items | `boolean` | `false` |
|
|
194
|
+
| hideCollapseButton | Hiding `CollapseButton`. Use `compact` prop for setting default navigation state | `boolean` | `false` |
|
|
195
|
+
| logo | Logo container includes icon, title, handling clicks | [`Logo`](https://github.com/gravity-ui/navigation/blob/main/src/components/Logo/Readme.md#logo) | |
|
|
196
|
+
| menuItems | Items in the navigation middle section | `Array<AsideHeaderItem>` | `[]` |
|
|
197
|
+
| menuGroups | Declares groups for the middle section; see [`MenuGroup`](#menugroup). Items attach via `AsideHeaderItem.groupId`. | `MenuGroup[]` | |
|
|
198
|
+
| defaultMenuItems | Default list for resetting **All pages** edits | `Array<AsideHeaderItem>` | |
|
|
199
|
+
| menuOverflow | Overflow behavior for the composite menu; see [`menuOverflow`](#composite-menu-overflow-menuoverflow). **`collapse`** (default): extras under «More». **`scroll`**: scrollable column. Compact sidebar always uses **`collapse`**. | `'collapse' \| 'scroll'` | `'collapse'` |
|
|
200
|
+
| collapsedMenuGroupIds | Controlled map (`MenuGroup.id` → collapsed) when `menuOverflow` is **`scroll`** | `Record<string, boolean>` | |
|
|
201
|
+
| defaultCollapsedMenuGroupIds | Initial group collapsed state when `collapsedMenuGroupIds` is uncontrolled | `Record<string, boolean>` | |
|
|
202
|
+
| editMenuProps | Optional hooks for the **All pages** panel; see [`editMenuProps`](#editmenuprops). | — | |
|
|
203
|
+
| menuMoreTitle | Additional element title of menuItems if elements don't fit | `string` | `"Ещё"` `"More"` |
|
|
204
|
+
| onChangeCompact | Callback will be called when changing navigation visual state | `(compact: boolean) => void;` | |
|
|
205
|
+
| onClosePanel | Callback will be called when closing panel. You can add panels via `PanelItems` prop | `() => void;` | |
|
|
206
|
+
| onMenuItemsChanged | Callback will be called when updating list of the menuItems in `AllPagesPanel` | `(items: Array<AsideHeaderItem>) => void` | |
|
|
207
|
+
| onMenuGroupsChanged | Callback **only from All pages**: user toggled **menu group** visibility (`MenuGroup.hidden`) via group header pin. Use controlled `menuGroups`; not emitted for programmatic updates unrelated to All pages. | `(menuGroups: Array<MenuGroup>) => void` | |
|
|
208
|
+
| onMenuMoreClick | Callback will be called when some items don't fit and "more" button is clicked | `() => void;` | |
|
|
209
|
+
| onToggleMenuGroupCollapsed | User toggled group expand/collapse in **`menuOverflow='scroll'`** layout; combine with **`collapsedMenuGroupIds`** when controlled | `(groupId: string) => void` | |
|
|
210
|
+
| onAllPagesClick | Callback will be called when "All pages" button is clicked | `() => void;` | |
|
|
211
|
+
| openModalSubscriber | Function notifies `AsideHeader` about Modals visibility changes | `( (open: boolean) => void) => void` | |
|
|
212
|
+
| aboveMenuContent | Optional content between the header and **`menuItems`**; stays fixed above the scrollable list when **`menuOverflow="scroll"`**. | `React.ReactNode` | |
|
|
213
|
+
| panelItems | Items for `Drawer` component. Used for show additional information over main content | [`Array<DrawerItem>`](https://github.com/gravity-ui/navigation/tree/main/src/components/Drawer#draweritem-props) | `[]` |
|
|
214
|
+
| renderContent | Function rendering the main content at the right of the `AsideHeader` | `(data: {size: number}) => React.ReactNode` | |
|
|
215
|
+
| renderFooter | Function rendering the navigation bottom section | `(data: {size: number}) => React.ReactNode` | |
|
|
216
|
+
| ref | `ref` to target popup anchor | `React.ForwardedRef<HTMLDivElement, AsideHeaderProps>` | |
|
|
217
|
+
| subheaderItems | Items in the navigation top section under Logo | `Array<AsideHeaderItem>` | `[]` |
|
|
218
|
+
| topAlert | The container above the navigation based on the uikit `Alert` component | `TopAlert` | |
|
|
219
|
+
| qa | The value to be passed to `data-qa` attribute of the `AsideHeader` container | `string` | |
|
|
220
|
+
|
|
221
|
+
### Composite menu overflow (`menuOverflow`)
|
|
222
|
+
|
|
223
|
+
The middle section uses a composite bar. **`menuOverflow`** chooses how overflow is handled when there is not enough vertical space:
|
|
224
|
+
|
|
225
|
+
| Value | Behavior |
|
|
226
|
+
| :------------- | :----------------------------------------------------------------------------------------- |
|
|
227
|
+
| **`collapse`** | Default. Items that do not fit are collected under a **«More»** entry (popup). |
|
|
228
|
+
| **`scroll`** | The menu list becomes a scrollable column so every row stays reachable without **«More»**. |
|
|
229
|
+
|
|
230
|
+
When the sidebar is **`compact`** (collapsed to icons), overflow **always** behaves like **`collapse`**, regardless of `menuOverflow`, because scrolling a strip of icon-only rows is awkward.
|
|
231
|
+
|
|
232
|
+
With **`menuOverflow="scroll"`** and **`menuGroups`**, group headers can expand/collapse inline. Use **`collapsedMenuGroupIds`** / **`defaultCollapsedMenuGroupIds`** and **`onToggleMenuGroupCollapsed`** to control or observe that state (keys are `MenuGroup.id`).
|
|
233
|
+
|
|
234
|
+
**`defaultMenuItems`** is the baseline list used when resetting **All pages** edits. Configure sorting, pins, group visibility toggles, and reset via **[`editMenuProps`](#editmenuprops)** below.
|
|
235
|
+
|
|
236
|
+
In compact mode, groups collapse to a single icon anchor (`MenuGroup.icon`); the group's children are revealed in a popup whose heading is taken from `MenuGroup.popupTitle`.
|
|
237
|
+
Inline expand/collapse (**`collapsedMenuGroupIds`** / **`onToggleMenuGroupCollapsed`**) does not apply here — it is only used when **`menuOverflow="scroll"`**.
|
|
238
|
+
|
|
239
|
+
### `MenuGroup`
|
|
240
|
+
|
|
241
|
+
Shape for entries in `menuGroups`. When `menuGroups` is set, middle-section items can reference a group with [`AsideHeaderItem.groupId`](#asideheaderitem) equal to `MenuGroup.id`. The composite bar renders group headers and nesting; visibility and collapse behavior are controlled via `AsideHeader` props (see `menuOverflow`, `onMenuGroupsChanged`, `collapsedMenuGroupIds`, etc.).
|
|
242
|
+
|
|
243
|
+
| Name | Description |
|
|
244
|
+
| :----------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
245
|
+
| `id` | Stable group identifier; must match `AsideHeaderItem.groupId` for items that belong to this group. |
|
|
246
|
+
| `title` | Group label shown on the inline group header in the expanded sidebar (and in flows that use this title). |
|
|
247
|
+
| `icon` | Optional [`Icon`](https://github.com/gravity-ui/uikit/tree/main/src/components/Icon) data for the group header. |
|
|
248
|
+
| `hidden` | When `true`, hides the group from the main navigation; items in that group are omitted there. The **All pages** panel can still surface the group row for visibility edits when callbacks like `onMenuGroupsChanged` are used. |
|
|
249
|
+
| `popupTitle` | Optional heading used **only** in the compact sidebar popup that lists a group’s children. Does not replace `title` for the inline group header or other surfaces. |
|
|
250
|
+
|
|
251
|
+
### `editMenuProps`
|
|
252
|
+
|
|
253
|
+
Optional configuration for the **All pages** panel (drag-and-drop, pins, reset). Use **`onToggleMenuGroup`** together with root **`onMenuGroupsChanged`** and controlled **`menuGroups`** when toggling group visibility from the group-header pin.
|
|
254
|
+
|
|
255
|
+
| Name | Description |
|
|
256
|
+
| :------------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
257
|
+
| `enableSorting` | Enables reordering menu entries via drag-and-drop while editing **All pages**. |
|
|
258
|
+
| `onChangeItemsOrder` | `(changedItem, oldIndex, newIndex)` — fired after the user changes item order when sorting is enabled. |
|
|
259
|
+
| `onOpenEditMode` | Called when **All pages** edit mode opens. |
|
|
260
|
+
| `onToggleMenuItem` | Fired when item visibility is toggled in **All pages** (e.g. pin / hide). |
|
|
261
|
+
| `onResetSettingsToDefault` | Invoked to reset saved menu settings to defaults from the editor UI. |
|
|
262
|
+
| `onToggleMenuGroup` | Fired when the user toggles a **menu group’s** visibility via the pin on the group header in **All pages**—keep **`menuGroups`** in sync with **`onMenuGroupsChanged`**. |
|
|
263
|
+
|
|
264
|
+
### `AsideHeaderItem`
|
|
265
|
+
|
|
266
|
+
| Name | Description | Type | Default |
|
|
267
|
+
| :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------: | :-----------------------------: |
|
|
268
|
+
| afterMoreButton | The menu item will be placed in the end, even item don't fit | `boolean` | |
|
|
269
|
+
| category | The category to which the menu item belongs. Need for grouping in the display/editing mode of all pages | `string` | `"Остальное"` `"All other"` |
|
|
270
|
+
| groupId | Optional `MenuGroup.id` when `menuGroups` is set; children of a group with `hidden: true` are omitted from the main nav | `string` | |
|
|
271
|
+
| current | The current/selected item | `boolean` | `false` |
|
|
272
|
+
| hidden | Visibility item in the menu, only for AllPages | `boolean` | `false` |
|
|
273
|
+
| icon | Menu icon based on the uikit `Icon` component | [`IconProps['data']`](https://github.com/gravity-ui/uikit/tree/main/src/components/Icon#properties) | |
|
|
274
|
+
| iconSize | Menu icon size | `number` `string` | `18` |
|
|
275
|
+
| iconQa | The value to be passed to `data-qa` attribute of the `Icon` container | `string` | |
|
|
276
|
+
| id | The menu item id | `string` | |
|
|
277
|
+
| itemWrapper | The menu item wrapper | [`ItemWrapper`](https://github.com/gravity-ui/navigation/blob/b8367cf343fc20304bc3c8d9a337d9f7d803a9b3/src/components/types.ts#L32-L41) | |
|
|
278
|
+
| href | HTML href attribute | `string` | |
|
|
279
|
+
| onItemClick | Callback will be called when clicking on the item. The `collapsed` parameter indicates state: `false` for regular items, `true` for items in collapsed popup or when clicking the "more" button. | `(item: AsideHeaderItem, collapsed: boolean, event: React.MouseEvent<HTMLDivElement, MouseEvent>) => void` | |
|
|
280
|
+
| onItemClickCapture | Callback will be called when clicking on the item | ` (event: React.SyntheticEvent) => void` | |
|
|
281
|
+
| order | Determine the display order in the navigation | `number` | |
|
|
282
|
+
| pinned | The parameter restricts hiding menu item | `boolean` | `false` |
|
|
283
|
+
| rightAdornment | Customize right side of the menu item | `React.ReactNode` | |
|
|
284
|
+
| title | The menu item title | `React.ReactNode` | |
|
|
285
|
+
| tooltipText | Tooltip content | `React.ReactNode` | |
|
|
286
|
+
| type | The menu item type changes appearance: `"regular"`, `"action"`, `"divider"` | `string` | `"regular"` |
|
|
287
|
+
| qa | The value to be passed to `data-qa` attribute | `string` | |
|
|
288
|
+
| enableTooltip | Whether to display a tooltip. | `boolean` | `true` |
|
|
289
|
+
| bringForward | Whether to display the icon on top of modal windows. | `boolean` | |
|
|
290
|
+
| compact | The flag responsible for displaying the menu item in a compact form. | `boolean` | |
|
|
291
|
+
| ~~popupVisible~~ | ⚠️ **Deprecated**: Use `itemWrapper` for popup functionality. The flag responsible for displaying the pop-up window. | `boolean` | `false` |
|
|
292
|
+
| ~~popupRef~~ | ⚠️ **Deprecated**: Use `itemWrapper` for popup functionality. Reference to anchor element for popup. | `React.RefObject<HTMLElement>` | |
|
|
293
|
+
| ~~popupPlacement~~ | ⚠️ **Deprecated**: Use `itemWrapper` for popup functionality. The location of the pop-up window relative to the anchor component. | [`PopupProps['placement']`](https://github.com/gravity-ui/uikit/blob/7748aaeec8dc7414487f7c06c899f16b275b25ef/src/components/Popup/Popup.tsx#L69) | |
|
|
294
|
+
| ~~popupOffset~~ | ⚠️ **Deprecated**: Use `itemWrapper` for popup functionality. The offset of the pop-up window relative to the anchor component. | [`PopupProps['offset']`](https://github.com/gravity-ui/uikit/blob/7748aaeec8dc7414487f7c06c899f16b275b25ef/src/components/Popup/Popup.tsx#L71) | `{mainAxis: 8, crossAxis: -20}` |
|
|
295
|
+
| ~~popupKeepMounted~~ | ⚠️ **Deprecated**: Use `itemWrapper` for popup functionality. The pop-up window will not be removed from the DOM when it is opened. | `boolean` | `false` |
|
|
296
|
+
| ~~renderPopupContent~~ | ⚠️ **Deprecated**: Use `itemWrapper` for popup functionality. This function is responsible for rendering content in a pop-up window. | `() => React.ReactNode` | |
|
|
297
|
+
| ~~onOpenChangePopup~~ | ⚠️ **Deprecated**: Use `itemWrapper` for popup functionality. A callback for changing the popupVisible state, such as when it is dismissed. | [`PopupProps['onOpenChange']`](https://github.com/gravity-ui/uikit/blob/7748aaeec8dc7414487f7c06c899f16b275b25ef/src/components/Popup/Popup.tsx#L61) | |
|
|
298
|
+
|
|
299
|
+
### `TopAlert`
|
|
300
|
+
|
|
301
|
+
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.
|
|
302
|
+
|
|
303
|
+
You can customize the inner content, make alert closeable if necessary. For reading top alert height see value from CSS variable `--gn-top-alert-height`.
|
|
304
|
+
|
|
305
|
+
| Name | Description | Type | Default |
|
|
306
|
+
| :-------------- | :------------------------------------------------------------------------------------------------------------------------ | :------------------------------------------------------------------------------------------------: | :----------: |
|
|
307
|
+
| actions | Array of buttons or full custom components | [`AlertActions`](https://github.com/gravity-ui/uikit/tree/main/src/components/Alert#properties) | |
|
|
308
|
+
| centered | Centering all content | `boolean` | `false` |
|
|
309
|
+
| align | Determines how content inside the Alert component is vertically aligned | [`AlertAlign`](https://github.com/gravity-ui/uikit/tree/main/src/components/Alert#align) | `"baseline"` |
|
|
310
|
+
| closable | Show close button and make possible to pass `onCloseTopAlert` prop | `boolean` | `false` |
|
|
311
|
+
| dense | Add top, bottom paddings to `TopAlert` container | `boolean` | `false` |
|
|
312
|
+
| icon | Override default icon | [`AlertIcon`](https://github.com/gravity-ui/uikit/tree/main/src/components/Alert#properties) | |
|
|
313
|
+
| message | Message of the alert | [`AlertMessage`](https://github.com/gravity-ui/uikit/tree/main/src/components/Alert#alert-message) | |
|
|
314
|
+
| onCloseTopAlert | Callback will be called when clicking on the close button | `() => void` | |
|
|
315
|
+
| title | Title of the alert | [`AlertTitle`](https://github.com/gravity-ui/uikit/tree/main/src/components/Alert#alert-title) | |
|
|
316
|
+
| theme | Alert appearance | [`AlertTheme`](https://github.com/gravity-ui/uikit/tree/main/src/components/Alert#theme) | "warning" |
|
|
317
|
+
| view | Enable/disable background color of the alert | [`AlertView`](https://github.com/gravity-ui/uikit/tree/main/src/components/Alert#view) | "filled" |
|
|
318
|
+
| preloadHeight | Preload TopAlert height on SSR to prevent layout shift. `true` uses estimated height; a number sets explicit height in px | `boolean` `number` | `false` |
|
|
319
|
+
|
|
320
|
+
## CSS API
|
|
321
|
+
|
|
322
|
+
| Name | Description |
|
|
323
|
+
| :-------------------------------------------------------- | :------------------------------------------------------------------------ |
|
|
324
|
+
| `--gn-aside-header-decoration-collapsed-background-color` | Decoration color for collapsed navigation |
|
|
325
|
+
| `--gn-aside-header-decoration-expanded-background-color` | Decoration color for expanded navigation |
|
|
326
|
+
| `--gn-aside-header-background-color` | Navigation background color |
|
|
327
|
+
| `--gn-aside-header-collapsed-background-color` | Collapsed navigation background color |
|
|
328
|
+
| `--gn-aside-header-expanded-background-color` | Expanded navigation background color |
|
|
329
|
+
| `--gn-aside-header-divider-horizontal-color` | All horizontal divider line color |
|
|
330
|
+
| `--gn-aside-header-divider-vertical-color` | Vertical divider line color between `AsideHeader` and content |
|
|
331
|
+
| `--gn-aside-header-menu-group-tree-line-color` | Tree connector lines for nested menu groups (inactive segments) |
|
|
332
|
+
| `--gn-aside-header-menu-group-tree-line-active-color` | Tree connector lines for the active branch in nested menu groups |
|
|
333
|
+
| `--gn-top-alert-height` | **Read only**.`AsideHeader` top alert height |
|
|
334
|
+
| `--gn-aside-header-padding-top` | Navigation top padding. May be helpful when logo and subheader items hide |
|
|
335
|
+
| Item | |
|
|
336
|
+
| `--gn-aside-header-general-item-icon-color` | Icon color for Subheader and Footer items |
|
|
337
|
+
| `--gn-aside-header-item-icon-color` | Icon color for CompositeBar items |
|
|
338
|
+
| `--gn-aside-header-item-text-color` | Text item color |
|
|
339
|
+
| `--gn-aside-header-item-background-color-hover` | Text color on hover |
|
|
340
|
+
| Current Item | |
|
|
341
|
+
| `--gn-aside-header-item-current-background-color` | Current item's background color |
|
|
342
|
+
| `--gn-aside-header-item-current-icon-color` | Current item's icon color |
|
|
343
|
+
| `--gn-aside-header-item-current-text-color` | Current item's text color |
|
|
344
|
+
| `--gn-aside-header-item-current-background-color-hover` | Current item's icon color on hover |
|
|
345
|
+
| `--gn-aside-header-item-collapsed-radius` | Item border radius for collapsed navigation |
|
|
346
|
+
| `--gn-aside-header-item-expanded-radius` | Item border radius for expanded navigation |
|
|
347
|
+
| z-indexes | |
|
|
348
|
+
| `--gn-aside-header-z-index` | Aside header z-index |
|
|
349
|
+
| `--gn-aside-header-panel-z-index` | Aside header panel (Drawer component) z-index |
|
|
350
|
+
| `--gn-aside-header-pane-top-z-index` | Top pane z-index |
|
|
351
|
+
| `--gn-aside-header-content-z-index` | Content (right part) z-index |
|
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
# Footer and MobileFooter
|
|
2
|
+
|
|
3
|
+
The page footer components. Use `Footer` for the desktop version and `MobileFooter` for the mobile version.
|
|
4
|
+
Both components have the same properties.
|
|
5
|
+
|
|
6
|
+
## Properties
|
|
7
|
+
|
|
8
|
+
| Property | Type | Required | Default | Description |
|
|
9
|
+
| :--------------------------------------------------------------------------------------- | :------------------------------- | :------: | :------ | :---------------------------- |
|
|
10
|
+
| className | `String` | | | Footer class name |
|
|
11
|
+
| [menuItems](https://github.com/gravity-ui/uikit/tree/main/src/components/Menu) | `FooterMenuItem[]` | | | List of footer menu items |
|
|
12
|
+
| withDivider | `Boolean` | | | Show top border on the footer |
|
|
13
|
+
| moreButtonTitle | `String` | | | The more items button title |
|
|
14
|
+
| onMoreButtonClick | `MouseEventHandler<HTMLElement>` | | | The more button click handler |
|
|
15
|
+
| [view](#view) | `normal` or `clear` | | | The footer view |
|
|
16
|
+
| [logo](https://preview.gravity-ui.com/navigation/?path=/story/components-logo--showcase) | `LogoProps` | | | The service logo properties |
|
|
17
|
+
| logoWrapperClassName | `string` | | | The logo wrapper class name |
|
|
18
|
+
| copyright | `string` | | | The copyright |
|
|
19
|
+
|
|
20
|
+
### view
|
|
21
|
+
|
|
22
|
+
- normal - white background and all the configured elements
|
|
23
|
+
- clear - transparent background and only the copyright
|
|
24
|
+
|
|
25
|
+
### Usage
|
|
26
|
+
|
|
27
|
+
See demos
|
|
28
|
+
|
|
29
|
+
- Desktop: `src/components/Footer/desktop/__stories__/FooterShowcase.tsx`,
|
|
30
|
+
- Mobile: `src/components/Footer/mobile/__stories__/MobileFooterShowcase.tsx`.
|
|
31
|
+
|
|
32
|
+
### Examples
|
|
33
|
+
|
|
34
|
+
#### Footer
|
|
35
|
+
|
|
36
|
+
```tsx
|
|
37
|
+
import { Footer } from '@gravity-ui/navigation';
|
|
38
|
+
|
|
39
|
+
<Footer
|
|
40
|
+
className="page-footer"
|
|
41
|
+
withDivider={false}
|
|
42
|
+
moreButtonTitle="Show more"
|
|
43
|
+
copyright={`@ ${new Date().getFullYear()} "My Service"`}
|
|
44
|
+
logo={{
|
|
45
|
+
icon: logoIcon,
|
|
46
|
+
iconSize: 24,
|
|
47
|
+
text: 'My Service'
|
|
48
|
+
}}
|
|
49
|
+
menuItems={[
|
|
50
|
+
{
|
|
51
|
+
text: 'About Service',
|
|
52
|
+
href: 'https://gravity-ui.com/',
|
|
53
|
+
target: 'blank',
|
|
54
|
+
},
|
|
55
|
+
{
|
|
56
|
+
text: 'Documentation',
|
|
57
|
+
href: 'https://gravity-ui.com/',
|
|
58
|
+
target: 'blank',
|
|
59
|
+
},
|
|
60
|
+
{
|
|
61
|
+
text: 'Confidential',
|
|
62
|
+
href: 'https://gravity-ui.com/',
|
|
63
|
+
target: 'blank',
|
|
64
|
+
},
|
|
65
|
+
]}
|
|
66
|
+
/>
|
|
67
|
+
|
|
68
|
+
<Footer
|
|
69
|
+
className="page-footer"
|
|
70
|
+
copyright={`@ ${new Date().getFullYear()} "My Service"`}
|
|
71
|
+
view="clear"
|
|
72
|
+
/>
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
#### MobileFooter
|
|
76
|
+
|
|
77
|
+
```tsx
|
|
78
|
+
import { MobileFooter } from '@gravity-ui/navigation';
|
|
79
|
+
|
|
80
|
+
<MobileFooter
|
|
81
|
+
className="page-footer"
|
|
82
|
+
withDivider={false}
|
|
83
|
+
moreButtonTitle="Show more"
|
|
84
|
+
copyright={`@ ${new Date().getFullYear()} "My Service"`}
|
|
85
|
+
logo={{
|
|
86
|
+
icon: logoIcon,
|
|
87
|
+
iconSize: 24,
|
|
88
|
+
text: 'My Service'
|
|
89
|
+
}}
|
|
90
|
+
menuItems={[
|
|
91
|
+
{
|
|
92
|
+
text: 'About Service',
|
|
93
|
+
href: 'https://gravity-ui.com/',
|
|
94
|
+
target: 'blank',
|
|
95
|
+
},
|
|
96
|
+
{
|
|
97
|
+
text: 'Documentation',
|
|
98
|
+
href: 'https://gravity-ui.com/',
|
|
99
|
+
target: 'blank',
|
|
100
|
+
},
|
|
101
|
+
{
|
|
102
|
+
text: 'Confidential',
|
|
103
|
+
href: 'https://gravity-ui.com/',
|
|
104
|
+
target: 'blank',
|
|
105
|
+
},
|
|
106
|
+
]}
|
|
107
|
+
/>
|
|
108
|
+
|
|
109
|
+
<MobileFooter
|
|
110
|
+
className="page-footer"
|
|
111
|
+
copyright={`@ ${new Date().getFullYear()} "My Service"`}
|
|
112
|
+
view="clear"
|
|
113
|
+
/>
|
|
114
|
+
```
|
|
@@ -0,0 +1,46 @@
|
|
|
1
|
+
# HotkeysPanel
|
|
2
|
+
|
|
3
|
+
A navigation panel for hotkeys documentation.
|
|
4
|
+
The panel displays a set of hotkeys for your application with a description of their purpose.
|
|
5
|
+
|
|
6
|
+
```ts
|
|
7
|
+
import {HotkeysPanel} from '@gravity-ui/navigation';
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
## Properties
|
|
11
|
+
|
|
12
|
+
| Property | Type | Required | Default | Description |
|
|
13
|
+
| :---------------------- | :-------------- | :------: | :------ | :--------------------------------------------------------------------------- |
|
|
14
|
+
| hotkeys | `Array` | yes | | List of hotkey groups |
|
|
15
|
+
| title | `ReactNode` | | | The panel title |
|
|
16
|
+
| togglePanelHotkey | `String` | | | The panel open hotkey |
|
|
17
|
+
| open | `Boolean` | yes | | Whether drawer open or not |
|
|
18
|
+
| onClose | `Function` | | | Close drawer handler |
|
|
19
|
+
| filterable | `Boolean` | | true | Whether show search input or not |
|
|
20
|
+
| filterPlaceholder | `String` | | | Search input placeholder |
|
|
21
|
+
| filterClassName | `String` | | | Search input class name |
|
|
22
|
+
| leftOffset | `Number/String` | | | Drawer left offset |
|
|
23
|
+
| topOffset | `Number/String` | | | Drawer top offset |
|
|
24
|
+
| emptyState | `ReactNode` | | | No search results placeholder |
|
|
25
|
+
| className | `String` | | | Drawer class name |
|
|
26
|
+
| drawerItemClassName | `String` | | | Drawer item class name |
|
|
27
|
+
| titleClassName | `String` | | | Title class name |
|
|
28
|
+
| itemContentClassName | `String` | | | List item content class name |
|
|
29
|
+
| listClassName | `String` | | | List class name |
|
|
30
|
+
| platform | `'pc'`/`'mac'` | | auto | Platform for hotkey display format |
|
|
31
|
+
| drawerProps | `DrawerProps` | | | Additional props for the Drawer component (style, container, hideVeil, etc.) |
|
|
32
|
+
| disableNavigationOffset | `Boolean` | | false | Whether to disable automatic left offset based on AsideHeader size |
|
|
33
|
+
|
|
34
|
+
And all the `List` PropTypes, but not `items` and filter props (you can find them [here](https://github.com/gravity-ui/uikit/blob/main/src/components/List/README.md))
|
|
35
|
+
|
|
36
|
+
## CSS API
|
|
37
|
+
|
|
38
|
+
| Name | Description | Default |
|
|
39
|
+
| :----------------------------------- | :-------------------------------- | :-----: |
|
|
40
|
+
| `--hotkeys-panel-width` | The width of the panel | `400px` |
|
|
41
|
+
| `--hotkeys-panel-vertical-padding` | The panel top and bottom paddings | `18px` |
|
|
42
|
+
| `--hotkeys-panel-horizontal-padding` | The panel left and right paddings | `24px` |
|
|
43
|
+
|
|
44
|
+
### Usage
|
|
45
|
+
|
|
46
|
+
See storybook example `src/components/HotkeysPanel/__stories__/HotkeysPanelShowcase`.
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
# Logo
|
|
2
|
+
|
|
3
|
+
Logo icon is wrapped in UIKit Button, text is wrapped in HTML tag `a` or `div`, when passing `hasWrapper` prop.
|
|
4
|
+
|
|
5
|
+
| Name | Description | Type | Default |
|
|
6
|
+
| :--------------------- | :-------------------------------------------------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------: | :-------: |
|
|
7
|
+
| aria-label | HTML `aria-label` attribute passed to tag `a` | `string` | |
|
|
8
|
+
| aria-labelledby | HTML `aria-labelledby` attribute passed to tag `a` | `string` | |
|
|
9
|
+
| buttonClassName | HTML `class` for UIKit Button | `string` | |
|
|
10
|
+
| buttonWrapperClassName | HTML `class` attribute for UIKit Button wrapper | `string` | |
|
|
11
|
+
| compact | Logo view state: `true` shows icon, `false` — icon and text | `boolean` | |
|
|
12
|
+
| className | HTML `class` attribute | `string` | |
|
|
13
|
+
| href | HTML `href` attribute for UIKit Button in the compact state and HTML tag `a` for the collapsed state without defining `hasWrapper` prop | `string` | |
|
|
14
|
+
| icon | | [IconProps['data']](https://github.com/gravity-ui/uikit/blob/610e49b6d4b9d1b4eae46841a9c1ab87ccc591fb/src/components/Icon/Icon.tsx#L26) | |
|
|
15
|
+
| iconClassName | HTML `class` attribute of the icon container | `string` | |
|
|
16
|
+
| iconSize | `width` and `height` attribute | `number` | `24` |
|
|
17
|
+
| iconSrc | HTML `src` attribute of the tag `img` | `string` | |
|
|
18
|
+
| onClick | Callback function called when the user clicks the Logo | `(event: React.MouseEvent<HTMLElement, MouseEvent>) => void` | |
|
|
19
|
+
| target | HTML `target` attribute of the tag `a` | `HTMLAttributeAnchorTarget` | `"_self"` |
|
|
20
|
+
| text | Text displays only when `compact` prop is `false` | `() => React.ReactNode` or `string` | |
|
|
21
|
+
| textSize | Text font size | `number` | `15` |
|
|
22
|
+
| wrapper | Wrapper function. Wrapping icon and text in two separated containers | `(node: React.ReactNode, compact: boolean) => React.ReactNode` | |
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
# MobileHeader
|
|
2
|
+
|
|
3
|
+
Header for Mobile navigation. MobileHeader provides maintaining Panels except for Modals.
|
|
4
|
+
|
|
5
|
+
Includes auxiliary `MobileHeaderFooterItem` component.
|
|
6
|
+
|
|
7
|
+
## Properties
|
|
8
|
+
|
|
9
|
+
| Name | Description | Type |
|
|
10
|
+
| :-------------------- | :-------------------------------------------------------------- | :--------------------------------------------------------- |
|
|
11
|
+
| logo | Service logo properties | `LogoProps` |
|
|
12
|
+
| burgerMenu | Burger menu properties | `BurgerMenuProps` |
|
|
13
|
+
| overlapPanel | Overlap panel properties | `OverlapPanelProps` |
|
|
14
|
+
| burgerCloseTitle | Burger close button title (a11y) | `string` |
|
|
15
|
+
| burgerOpenTitle | Burger open button title (a11y) | `string` |
|
|
16
|
+
| panelItems | Custom panels rendered in the header | `PanelItemProps[]` |
|
|
17
|
+
| topAlert | Top alert properties | `TopAlertProps` |
|
|
18
|
+
| renderContent | Render function for the header content | `RenderContentType` |
|
|
19
|
+
| sideItemRenderContent | Render function for the side item content | `RenderContentType` |
|
|
20
|
+
| onEvent | Inner event handler — receives the item name and the event name | `(itemName: string, eventName: MobileHeaderEvent) => void` |
|
|
21
|
+
| onClosePanel | Close panel handler | `() => void` |
|
|
22
|
+
| className | Header class name | `string` |
|
|
23
|
+
| contentClassName | Header content class name | `string` |
|
|
24
|
+
|
|
25
|
+
### Usage
|
|
26
|
+
|
|
27
|
+
See storybook example `src/components/MobileHeader/__stories__/MobileHeaderShowcase`.
|
|
28
|
+
|
|
29
|
+
#### onEvent prop
|
|
30
|
+
|
|
31
|
+
[onEvent](https://github.com/gravity-ui/navigation/blob/32c6a6f58e0307745e92b041b3d96517e57589c1/src/components/MobileHeader/MobileHeader.tsx#L41) handles MobileHeader inner events.
|
|
32
|
+
|
|
33
|
+
**Custom events**
|
|
34
|
+
|
|
35
|
+
You can initiate the event via `CustomEvent`. Support values:
|
|
36
|
+
|
|
37
|
+
- `MOBILE_PANEL_TOGGLE`
|
|
38
|
+
- `MOBILE_PANEL_OPEN`
|
|
39
|
+
- `MOBILE_PANEL_CLOSE`
|
|
40
|
+
- `MOBILE_BURGER_OPEN`
|
|
41
|
+
- `MOBILE_BURGER_CLOSE`
|
|
42
|
+
|
|
43
|
+
Panel events in constant [MOBILE_HEADER_EVENT_NAMES](https://github.com/gravity-ui/navigation/blob/main/src/components/MobileHeader/constants.ts#L8-L12)
|
|
44
|
+
|
|
45
|
+
##### Examples
|
|
46
|
+
|
|
47
|
+
**Simple event, open burger**
|
|
48
|
+
|
|
49
|
+
```js
|
|
50
|
+
const customEvent = new CustomEvent('MOBILE_BURGER_OPEN');
|
|
51
|
+
const navRef = React.useRef < HTMLDivElement > null;
|
|
52
|
+
navRef?.current?.dispatchEvent(customEvent);
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
**Panel event, open custom panel**
|
|
56
|
+
|
|
57
|
+
```js
|
|
58
|
+
import {getMobileHeaderCustomEvent, MOBILE_HEADER_EVENT_NAMES} from '@gravity-ui/navigation';
|
|
59
|
+
|
|
60
|
+
const customEvent = getMobileHeaderCustomEvent(MOBILE_HEADER_EVENT_NAMES.closeEvent, {
|
|
61
|
+
panelName: 'user',
|
|
62
|
+
});
|
|
63
|
+
|
|
64
|
+
const navRef = React.useRef < HTMLDivElement > null;
|
|
65
|
+
navRef?.current?.dispatchEvent(customEvent);
|
|
66
|
+
|
|
67
|
+
const customEvent2 = getMobileHeaderCustomEvent('MOBILE_PANEL_TOGGLE', {panelName: 'user'});
|
|
68
|
+
navRef?.current?.dispatchEvent(customEvent2);
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Available panelName
|
|
72
|
+
|
|
73
|
+
1. 'burger'
|
|
74
|
+
2. `id` of element [panelItems prop](https://github.com/gravity-ui/navigation/blob/main/src/components/MobileHeader/MobileHeader.tsx#L38C5-L38C15)
|
|
75
|
+
|
|
76
|
+
## MobileHeader vars
|
|
77
|
+
|
|
78
|
+
| Name | Description | Default |
|
|
79
|
+
| :--------------------------------- | :--------------------------------------------- | :-----: |
|
|
80
|
+
| z-indexes | | |
|
|
81
|
+
| `--gn-mobile-header-z-index` | Mobile header z-index | `100` |
|
|
82
|
+
| `--gn-mobile-header-panel-z-index` | Mobile header panel (Drawer component) z-index | `98` |
|
|
@@ -0,0 +1,113 @@
|
|
|
1
|
+
# Settings
|
|
2
|
+
|
|
3
|
+
The Settings component provides the layout for a settings panel with the following features.
|
|
4
|
+
|
|
5
|
+
- single-level and two-level grouping of items
|
|
6
|
+
- filtering of the panel's content by headers of items
|
|
7
|
+
- displaying of loading status and content
|
|
8
|
+
|
|
9
|
+
## Usage
|
|
10
|
+
|
|
11
|
+
One-level settings example:
|
|
12
|
+
|
|
13
|
+
```tsx
|
|
14
|
+
<Settings>
|
|
15
|
+
<Settings.Page title="Appearance">...</Settings.Page>
|
|
16
|
+
<Settings.Page title="Notifications">...</Settings.Page>
|
|
17
|
+
</Settings>
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
Two-level settings example:
|
|
21
|
+
_Note:_ `Settings` with `view=mobile` groups `Settings.Group` are ignored.
|
|
22
|
+
|
|
23
|
+
```tsx
|
|
24
|
+
<Settings>
|
|
25
|
+
<Settings.Group groupTitle="My service">
|
|
26
|
+
<Settings.Page title="Appearance">...</Settings.Page>
|
|
27
|
+
<Settings.Page title="Notifications">...</Settings.Page>
|
|
28
|
+
</Settings.Group>
|
|
29
|
+
<Settings.Group groupTitle="General">
|
|
30
|
+
<Settings.Page title="Appearance">...</Settings.Page>
|
|
31
|
+
<Settings.Page title="Notifications">...</Settings.Page>
|
|
32
|
+
</Settings.Group>
|
|
33
|
+
</Settings>
|
|
34
|
+
```
|
|
35
|
+
|
|
36
|
+
Pages with sections example:
|
|
37
|
+
|
|
38
|
+
```tsx
|
|
39
|
+
<Settings.Page title="Features" icon={'...'}>
|
|
40
|
+
<Settings.Section title="Common">
|
|
41
|
+
<Settings.Item title="Default VCS">...</Settings.Item>
|
|
42
|
+
<Settings.Item title="Search root">...</Settings.Item>
|
|
43
|
+
</Settings.Section>
|
|
44
|
+
<Settings.Section title="Beta functionality">...</Settings.Section>
|
|
45
|
+
</Settings.Page>
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
## Properties
|
|
49
|
+
|
|
50
|
+
| Name | Description | Type | Default |
|
|
51
|
+
| :----------------------------- | :------------------------------------------------------------ | :--------------------------- | :----------------- |
|
|
52
|
+
| loading | Flag of loading status | `boolean` | |
|
|
53
|
+
| renderLoading | content for loading status | `() => React.ReactNode` | |
|
|
54
|
+
| renderNotFound | Empty panel content | `() => React.ReactNode` | |
|
|
55
|
+
| initialPage | Inititial page in `/groupId/pageId` format | `string` | |
|
|
56
|
+
| view | Change view for Mobile | `"normal"`, `"mobile"` | `"normal"` |
|
|
57
|
+
| onPageChange | Page change handler | `(newPage?: string) => void` | |
|
|
58
|
+
| onClose | Settings close handler | `() => void` | |
|
|
59
|
+
| title | Page title | `string` | 'Settings' |
|
|
60
|
+
| filterPlaceholder | Filter placeholder text | `string` | 'Search settings' |
|
|
61
|
+
| emptyPlaceholder | Filter empty text | `string` | 'No results found' |
|
|
62
|
+
| enableMobileSettingsTabsScroll | In mobile view tabs will overflow with scroll instead of wrap | `boolean` | |
|
|
63
|
+
|
|
64
|
+
## Settings.Group
|
|
65
|
+
|
|
66
|
+
Optional level for organizing related pages, e.g. "General" vs "Application specific".
|
|
67
|
+
|
|
68
|
+
### Properties
|
|
69
|
+
|
|
70
|
+
| Name | Description | Type | Default |
|
|
71
|
+
| :--------- | :----------------- | :------- | :------ |
|
|
72
|
+
| id | Unique id of group | `string` | |
|
|
73
|
+
| groupTitle | Header of group | `string` | |
|
|
74
|
+
|
|
75
|
+
## Settings.Page
|
|
76
|
+
|
|
77
|
+
Collection of related settings sections, e.g. "Appearance" in General group.
|
|
78
|
+
|
|
79
|
+
### Properties
|
|
80
|
+
|
|
81
|
+
| Name | Description | Type | Default |
|
|
82
|
+
| :---- | :--------------------------- | :------------------------------------------------------------------------------------------ | :------ |
|
|
83
|
+
| id | Unique id of page in a group | `string` | |
|
|
84
|
+
| title | Title of page | `string` | |
|
|
85
|
+
| icon | Properties of icon of page | [`IconProps`](https://github.com/gravity-ui/uikit/tree/main/src/components/Icon#properties) | |
|
|
86
|
+
|
|
87
|
+
## Settings.Section
|
|
88
|
+
|
|
89
|
+
Category of related settings, e.g. "Theme settings" in Appearance page.
|
|
90
|
+
|
|
91
|
+
### Properties
|
|
92
|
+
|
|
93
|
+
| Name | Description | Type | Default |
|
|
94
|
+
| :-------- | :---------------------------------------------------------------------------- | :---------------- | :------ |
|
|
95
|
+
| title | Title of section | `string` | |
|
|
96
|
+
| header | Header of section | `React.ReactNode` | |
|
|
97
|
+
| withBadge | Show badge on a section and menu | `boolean` | |
|
|
98
|
+
| hideTitle | Hide section title. Prop is needed to hide title in simple settings on Mobile | `boolean` | |
|
|
99
|
+
|
|
100
|
+
## Settings.Item
|
|
101
|
+
|
|
102
|
+
Individual setting with a title and control component.
|
|
103
|
+
⚠️ In case with only one `Settings.Item` in `Settings.Section` the title is not shown.
|
|
104
|
+
|
|
105
|
+
### Properties
|
|
106
|
+
|
|
107
|
+
| Name | Description | Type | Default |
|
|
108
|
+
| :------------------- | :--------------------------------------------------------- | :-------------------------------------------------------- | :--------- |
|
|
109
|
+
| title | Title of item | `string` | |
|
|
110
|
+
| renderTitleComponent | Cusomt header of | `(highlightedTitle?: React.ReactNode) => React.ReactNode` |
|
|
111
|
+
| align | Item alignment | `"top"`, `"center"` | `"center"` |
|
|
112
|
+
| mode | Layout for mobile. Title and control will be placed in row | `"row"` | |
|
|
113
|
+
| description | Description of item | `React.ReactNode` | |
|
|
@@ -0,0 +1,16 @@
|
|
|
1
|
+
# useOverflowingHorizontalListItems
|
|
2
|
+
|
|
3
|
+
A hook for determining which horizontal list items stay visible and which collapse into an overflow "more" dropdown.
|
|
4
|
+
|
|
5
|
+
```tsx
|
|
6
|
+
import {useOverflowingHorizontalListItems} from '@gravity-ui/navigation';
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
## Properties
|
|
10
|
+
|
|
11
|
+
| Property | Type | Required | Default | Description |
|
|
12
|
+
| :-------------- | :----------------------- | :------: | :------ | :----------------------- |
|
|
13
|
+
| containerRef | `RefObject<HTMLElement>` | | | List container ref |
|
|
14
|
+
| items | `Array` | | | List items |
|
|
15
|
+
| itemSelector | `String` | | | List item selector |
|
|
16
|
+
| moreButtonWidth | `Number` | | | The width of more button |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@gravity-ui/navigation",
|
|
3
|
-
"version": "6.
|
|
3
|
+
"version": "6.3.0",
|
|
4
4
|
"description": "Gravity UI Navigation components",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -32,6 +32,7 @@
|
|
|
32
32
|
"test": "node --experimental-vm-modules ./node_modules/jest/bin/jest.js --passWithNoTests",
|
|
33
33
|
"test-storybook": "test-storybook --url ${PR_PREVIEW_URL:-http://localhost:7008}",
|
|
34
34
|
"build": "rimraf build && rollup -c",
|
|
35
|
+
"build:docs": "node scripts/build-docs.js",
|
|
35
36
|
"lint:js": "eslint src --ext .js,.jsx,.ts,.tsx",
|
|
36
37
|
"lint:styles": "stylelint '{styles,src}/**/*.scss'",
|
|
37
38
|
"lint:prettier": "prettier --check '**/*.md'",
|
|
@@ -39,7 +40,7 @@
|
|
|
39
40
|
"packages:check": "knip",
|
|
40
41
|
"build-storybook": "storybook build",
|
|
41
42
|
"start": "cross-env TS_NODE_PROJECT=.storybook/tsconfig.json storybook dev -p 7008",
|
|
42
|
-
"prepublishOnly": "npm run build",
|
|
43
|
+
"prepublishOnly": "npm run build && npm run build:docs",
|
|
43
44
|
"playwright:install": "playwright install --with-deps",
|
|
44
45
|
"playwright": "playwright test --config=playwright/playwright.config.ts",
|
|
45
46
|
"playwright:update": "npm run playwright -- -u",
|
|
@@ -67,6 +68,7 @@
|
|
|
67
68
|
"@commitlint/config-conventional": "^19.6.0",
|
|
68
69
|
"@doc-tools/transform": "^3.11.0",
|
|
69
70
|
"@gravity-ui/eslint-config": "^3.3.0",
|
|
71
|
+
"@gravity-ui/gulp-utils": "^1.1.1",
|
|
70
72
|
"@gravity-ui/icons": "^2.8.1",
|
|
71
73
|
"@gravity-ui/prettier-config": "^1.0.0",
|
|
72
74
|
"@gravity-ui/stylelint-config": "^4.0.1",
|