From 07734a782ffe15cf411f657724bd064dcee2e59e Mon Sep 17 00:00:00 2001 From: Anton Vikulov Date: Fri, 8 Sep 2023 17:13:19 +0500 Subject: [PATCH] docs(Breadcrumbs): add readme --- src/components/Breadcrumbs/README.OLD.md | 43 +++ src/components/Breadcrumbs/README.md | 348 +++++++++++++++++++++-- 2 files changed, 373 insertions(+), 18 deletions(-) create mode 100644 src/components/Breadcrumbs/README.OLD.md diff --git a/src/components/Breadcrumbs/README.OLD.md b/src/components/Breadcrumbs/README.OLD.md new file mode 100644 index 0000000000..84e7bdc179 --- /dev/null +++ b/src/components/Breadcrumbs/README.OLD.md @@ -0,0 +1,43 @@ +## Breadcrumbs + +Breadcrumbs component. Can collapse breadcrumbs that cause overflow. + +### PropTypes + +| Name | Type | Required | Default | Description | +| :----------------------- | :--------- | :------: | :------ | :--------------------------------------------------------------------------------------------------------------------------- | +| items | `Array` | ✓ | | Breadcrumb items array `BreadcrumbsItem[]` | +| className | `String` | | | CSS class name of root element | +| renderRootContent | `Function` | | | Custom render function of first item `(item: BreadcrumbsItem, isCurrent: boolean) => React.ReactNode;`) | +| renderItemContent | `Function` | | | Custom render function of N+1 item `(item: BreadcrumbsItem, isCurrent: boolean, isPrevCurrent: boolean) => React.ReactNode;` | +| renderItemDivider | `Function` | | | Custom render function of items separator `() => React.ReactNode;` | +| lastDisplayedItemsCount | `Enum` | ✓ | | Number of items to display after items collapse control: `LastDisplayedItemsCount` | +| firstDisplayedItemsCount | `Enum` | ✓ | | Number of items to display before items collapse control: `FirstDisplayedItemsCount` | +| popupStyle | `String` | | | Style of collapsed items popup `staircase` | + +### Examples + +```jsx +const breadcrumbs = [ + { + title: 'What is love', + }, + { + title: "Baby don't hurt me", + }, + { + title: "Don't hurt me", + }, + { + title: 'No more', + }, +]; + +return ( + +); +``` diff --git a/src/components/Breadcrumbs/README.md b/src/components/Breadcrumbs/README.md index 84e7bdc179..d2153fae0d 100644 --- a/src/components/Breadcrumbs/README.md +++ b/src/components/Breadcrumbs/README.md @@ -1,43 +1,355 @@ -## Breadcrumbs + -Breadcrumbs component. Can collapse breadcrumbs that cause overflow. +# Breadcrumbs -### PropTypes + -| Name | Type | Required | Default | Description | -| :----------------------- | :--------- | :------: | :------ | :--------------------------------------------------------------------------------------------------------------------------- | -| items | `Array` | ✓ | | Breadcrumb items array `BreadcrumbsItem[]` | -| className | `String` | | | CSS class name of root element | -| renderRootContent | `Function` | | | Custom render function of first item `(item: BreadcrumbsItem, isCurrent: boolean) => React.ReactNode;`) | -| renderItemContent | `Function` | | | Custom render function of N+1 item `(item: BreadcrumbsItem, isCurrent: boolean, isPrevCurrent: boolean) => React.ReactNode;` | -| renderItemDivider | `Function` | | | Custom render function of items separator `() => React.ReactNode;` | -| lastDisplayedItemsCount | `Enum` | ✓ | | Number of items to display after items collapse control: `LastDisplayedItemsCount` | -| firstDisplayedItemsCount | `Enum` | ✓ | | Number of items to display before items collapse control: `FirstDisplayedItemsCount` | -| popupStyle | `String` | | | Style of collapsed items popup `staircase` | +```tsx +import {Breadcrumbs} from '@gravity-ui/uikit'; +``` + +`Breadcrumbs` is a navigation element that shows the current location of a page within a website’s hierarchy. It provides links to users to go back to higher levels in the hierarchy, making it easier to navigate a site with multiple layers. Breadcrumbs are especially useful for large websites and applications with a hierarchical organization of pages. + +## Appearance + + -### Examples + ```jsx const breadcrumbs = [ { - title: 'What is love', + text: 'Region', + action: () => {}, + }, + { + text: 'Country', + action: () => {}, }, { - title: "Baby don't hurt me", + text: 'City', + action: () => {}, }, { - title: "Don't hurt me", + text: 'District', + action: () => {}, }, { - title: 'No more', + text: 'Street', + action: () => {}, }, ]; return ( +); +``` + + + +### Custom divider + + + + + +```jsx +const breadcrumbs = [ + { + text: 'Region', + action: () => {}, + }, + { + text: 'Country', + action: () => {}, + }, + { + text: 'City', + action: () => {}, + }, + { + text: 'District', + action: () => {}, + }, + { + text: 'Street', + action: () => {}, + }, +]; + +return ( + '>'} + firstDisplayedItemsCount={FirstDisplayedItemsCount.One} + lastDisplayedItemsCount={LastDisplayedItemsCount.One} + /> +); +``` + + + +### Custom title + + + + + +```jsx +const breadcrumbs = [ + { + text: 'Region', + title: 'Custom title for Region', + action: () => {}, + }, + { + text: 'Country', + title: 'Custom title for Country', + action: () => {}, + }, + { + text: 'City', + title: 'Custom title for City', + action: () => {}, + }, + { + text: 'District', + title: 'Custom title for District', + action: () => {}, + }, + { + text: 'Street', + title: 'Custom title for Street', + action: () => {}, + }, +]; + +return ( + ); ``` + + + +## Properties + +| Name | Description | Type | Default | +| :----------------------- | :------------------------------------------------------- | :------------------------------------------------------------------------------------------------------ | :------ | +| items | Breadcrumb items array | `BreadcrumbsItem[]` | | +| className | CSS class name of root element | `string` | | +| renderRootContent | Custom render function of first item | `((item: BreadcrumbsItem, isCurrent: boolean) => React.ReactNode) \| undefined` | | +| renderItemContent | Custom render function of N+1 item | `((item: BreadcrumbsItem, isCurrent: boolean, isPrevCurrent: boolean) => React.ReactNode) \| undefined` | | +| renderItemDivider | Custom render function of items separator | `(() => React.ReactNode) \| undefined` | | +| firstDisplayedItemsCount | Number of items to display before items collapse control | `FirstDisplayedItemsCount.Zero \| FirstDisplayedItemsCount.One` | | +| lastDisplayedItemsCount | Number of items to display after items collapse control | `LastDisplayedItemsCount.One \| LastDisplayedItemsCount.Two` | | +| popupStyle | Style of collapsed items popup | `"staircase" \| undefined` | | + +### BreadcrumbsItem + +| Name | Description | Type | Default | +| :----- | :--------------------- | :-------------------------------------------------------------------------------- | :------ | +| text | Breadcrumb content | `string` | | +| action | `click` event handler | `React.MouseEventHandler \| React.KeyboardEventHandler` | | +| href | HTML `href` attribute | `string \| undefined` | | +| items | Breadcrumb items array | `BreadcrumbsItem[] \| undefined` | | +| title | HTML `title` attribute | `string \| undefined` | |