@gravity-ui/navigation 6.1.2 → 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 +64 -0
- package/build/cjs/components/AsideHeader/components/FirstPanel.js +2 -1
- package/build/cjs/components/AsideHeader/components/FirstPanel.js.map +1 -1
- package/build/cjs/components/AsideHeader/types.d.ts +1 -0
- package/build/cjs/components/AsideHeader/types.js.map +1 -1
- 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/build/esm/components/AsideHeader/components/FirstPanel.js +2 -1
- package/build/esm/components/AsideHeader/components/FirstPanel.js.map +1 -1
- package/build/esm/components/AsideHeader/types.d.ts +1 -0
- package/build/esm/components/AsideHeader/types.js.map +1 -1
- package/package.json +4 -2
|
@@ -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` | |
|