@workday/canvas-kit-react
Version:
The parent module that contains all Workday Canvas Kit React components
154 lines (153 loc) • 6.31 kB
JavaScript
import * as React from 'react';
import { createContainer } from '@workday/canvas-kit-react/common';
import { Menu } from '@workday/canvas-kit-react/menu';
import { useBreadcrumbsModel } from './hooks/useBreadcrumbsModel';
import { BreadcrumbsList } from './BreadcrumbsList';
import { BreadcrumbsOverflowButton } from './BreadcrumbsOverflowButton';
import { BreadcrumbsItem } from './BreadcrumbsItem';
import { BreadcrumbsLink } from './BreadcrumbsLink';
import { BreadcrumbsCurrentItem } from './BreadcrumbsCurrentItem';
import { BreadcrumbsMenu } from './BreadcrumbsMenu';
/**
* `Breadcrumbs` is a container component that is responsible for creating a
* {@link BreadcrumbsModel} and sharing it with its subcomponents using React context. It also
* renders `nav` element, and `aria-label` attribute must be provided for this element.
*
* ```tsx
* <Breadcrumbs aria-label="Breadcrumbs">
* <Breadcrumbs.List>
* <Breadcrumbs.Item>
* <Breadcrumbs.Link href="/docs">Docs</Breadcrumbs.Link>
* <Breadcrumbs.Item>
* <Breadcrumbs.Item>
* <Breadcrumbs.Link href="/docs/components">Components</Breadcrumbs.Link>
* <Breadcrumbs.Item>
* <Breadcrumbs.CurrentItem>
* <Breadcrumbs.Link href="/docs/components/breadcrumbs">Breadcrumbs</Breadcrumbs.Link>
* <Breadcrumbs.CurrentItem>
* <Breadcrumbs.List>
* </Breadcrumbs>
* ```
*
* You may pass {@link BreadcrumbsModelConfig} directly to the `Breadcrumbs` component.
*
* ```tsx
* <Breadcrumbs items={[]} aria-label="Breadcrumbs">
* {Child components}
* </Breadcrumbs>
* ```
*
* Alternatively, you may pass in a model using the hoisted model pattern.
*
* ```tsx
* const model = useBreadcrumbsModel({
* items: [],
* });
*
* <Breadcrumbs model={model} aria-label="Breadcrumbs">
* {Child components}
* </Breadcrumbs>;
* ```
*
* Note that if you pass in a `model` configured with {@link useBreadcrumbsModel}, configuration
* props passed to `Breadcrumbs` will be ignored. `aria-label` attribute must be provided for `nav`
* element.
*/
export const Breadcrumbs = createContainer('nav')({
displayName: 'Breadcrumbs',
modelHook: useBreadcrumbsModel,
subComponents: {
/**
* `Breadcrumbs.List` is a `Flex` component rendered as a `<ul>` element. It is a container for
* `Breadcrumbs.Item` subcomponents. It also renders overflow button if `overflowButton` prop
* has been passed;
*
* ```tsx
* // without overflow
* <Breadcrumbs.List>{Breadcrumbs.Items}</Breadcrumbs.List>
* ```
*
* ```tsx
* // with overflow
* <Breadcrumbs.List overflowButton={<Breadcrumbs.OverflowButton aria-label="More links" />}>
* {Breadcrumbs.Items}
* </Breadcrumbs.List>
* ```
*
* `Breadcrumbs.List` accepts a `overflowButton` prop allowing to pass specific overflow button.
* Breadcrumbs.List with overflow behavior should contain `overflowButton` component with
* `aria-label` to render overflow button.
*/
List: BreadcrumbsList,
/**
* `Breadcrumbs.Item` is a {@link Flex} component rendered as an `<li>` element. It is a
* container for the `Breadcrumbs.Link` subcomponent which provides correct overflow behavior
* across all items.
*
* List items in {@link BreadcrumbsList Breadcrumbs.List}. By default, this item is truncated
* with a tooltip at `350px`, but that can be customized with the `maxWidth` prop.
*
* ```tsx
* <Breadcrumbs.Item maxWidth={200}>
* <Breadcrumbs.Link href="/docs">Docs</Breadcrumbs.Link>
* </Breadcrumbs.Item>
* ```
*/
Item: BreadcrumbsItem,
/**
* `Breadcrumbs.Link` is a styled `<a>` element that also renders a tooltip if the text is
* truncated. The built-in truncation and tooltip functionality provides an easy-to-use,
* accessible feature for managing the length of link text. The `maxWidth` is set to `350px` by
* default and can be adjusted as needed. Note that tooltips will only render when text is
* truncated
*/
Link: BreadcrumbsLink,
/**
* The last element in the list of `Breadcrumbs.Item`s. By default, this item is truncated with
* a tooltip at `350px`, But that can be customized with the `maxWidth` prop.
*
* ```tsx
* <Breadcrumbs.CurrentItem maxWidth={200}>
* Current Item Text
* </Breadcrumbs.CurrentItem>
* ```
*/
CurrentItem: BreadcrumbsCurrentItem,
/**
* The toggle button for the Breadcrumbs Menu. This button is rendered in the
* {@link BreadcrumbsList Breadcrumbs.List} when `overflowButtonProps` passed and becomes
* visible when the list overflows. `overflowButtonProps must contain at least `aria-label`. If
* you need to pass other props to it, you can do so by adding it to `overflowButtonProps`
* passed to the List.
*
* ```tsx
* <Breadcrumbs.List
* overflowButtonProps={{
* 'aria-label': 'More links',
* onClick={handleOverflowButtonClick}
* }}
* >
* ```
*/
OverflowButton: BreadcrumbsOverflowButton,
/**
* The `Breadcrumbs.Menu` uses the {@link Menu} component under the hood. The overflow menu for
* Breadcrumbs. If there isn't enough room to render all links, it will automatically overflow
* items into this menu.
*
* ```tsx
* <Breadcrumbs.Menu.Popper>
* <Breadcrumbs.Menu.Card>
* <Breadcrumbs.Menu.List>
* {(item: MyActionItem) => <Breadcrumbs.Menu.Item>{item.text}</Breadcrumbs.Menu.Item>}
* </Breadcrumbs.Menu.List>
* </Breadcrumbs.Menu.Card>
* </Breadcrumbs.Menu.Popper>
* ```
*/
Menu: BreadcrumbsMenu,
},
})(({ children, ...elemProps }, _, model) => {
return (React.createElement(Menu, { model: model.menu },
React.createElement("nav", { role: "navigation", ...elemProps }, children)));
});