Skip to content

Added MIGRATION.md to the Breadcrumb #27846

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ValentinaKozlova merged 2 commits into from
May 16, 2023
Merged

Added MIGRATION.md to the Breadcrumb #27846

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8a8cdfd
Added MIGRATION.md
ValentinaKozlova May 15, 2023
039aea8
Added changes to the MIGRATION.md
ValentinaKozlova May 15, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
113 changes: 113 additions & 0 deletions packages/react-components/react-breadcrumb/docs/MIGRATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,113 @@
# Breadcrumb Migration

### Fabric (v8) property mapping

While the logic in the V8 Breadcrumb component was cooked in, V9 offers partners more flexibility in implementation.
Here's how the API of v8's `Breadcrumb` compares to the one from v9's `Breadcrumb` component:

#### New props

- `appearance`
- `size`
- `iconPosition`

#### Props no longer supported with an equivalent functionality in Breadcrumb V9:

- `maxDisplayedItems`and `overflowIndex` - will be part of `partitionBreadcrumbItems` method.
- `className` => Slot system supports it by default. We don't need to provide it explicitly.
- `items` => Use `children` prop instead.
- `componentRef` => NOT SUPPORTED - use `ref` instead.
- `dividerAs` => Divider is a separate component. Type of divider is passed to the Breadcrumb component as `dividerType`.
- `focusZoneProps` => use `focusMode` instead.
- `overflowButtonAs` => Custom component for the overflow button - use custom overflow button instead.
- `styles` => Use style customization through `className` instead.
- `theme`
- `overflowAriaLabel` => Aria label for the overflow button.

#### Props no longer supported

- `onRenderOverflowIcon` => Render a custom overflow icon in place of the default icon `...`.
- `onGrowData` => Method that determines how to group the length of the breadcrumb. Return undefined to never increase breadcrumb length.
- `onReduceData` => Method that determines how to reduce the length of the breadcrumb. Return undefined to never reduce breadcrumb length.

As BreadcrumbItem part of `children` prop, a user decides how to render an item.
The following props are not needed anymore.

- `onRenderItem` => Custom render function to render each crumb. Default renders as a link.
- `onRenderItemContent` => Custom render function to render the content within a crumb. Default renders the text.
- `tooltipHostProps` => Extra props for the TooltipHost which wraps each breadcrumb item.

Fabric Breadcrumb `items` prop as part of `IBreadcrumbData` interface contains the following props:
BreadcrumbItem component contains similar props in V9.

- `key` => not supported
- `text` => use `children` prop of BreadcrumbItem component.
- `as` => type('h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'a') - Optional prop to render the item as a heading of your choice. You can also use this to force items to render as links instead of buttons (by default, any item with a href renders as a link, and any item without a href renders as a button). This is not generally recommended because it may prevent activating the link using the keyboard. In V9 It's part of BreadcrumbItem prop.
- `href` => URL to navigate to when this breadcrumb item is clicked. If provided, the breadcrumb will be rendered as a link.
- `isCurrentItem` => Whether this is the breadcrumb item the user is currently navigated to. If true, aria-current="page" will be applied to this breadcrumb item.
- `onClick` => Callback for when the breadcrumb item is selected.
- `onRender` => A function to render the outer content of the crumb (the link).
- `onRenderContent` => A function to render the inner content of the crumb (the text inside the link).
- `role` => Optional role for the breadcrumb item (which renders as a button by default)

#### Property Mapping

| v8 `Breadcrumb` | v9 `Breadcrumb` |
| ------------------- | --------------- |
| `ariaLabel` | |
| | `appearance` |
| `className` | |
| `componentRef` | |
| `dividerAs` | `dividerType` |
| `focusZoneProps` | |
| | `iconPosition` |
| `maxDisplayedItems` | |
| | `size` |

### Northstar property mapping

#### Props which are repeating in each component

These props are the same in all the components.
`as` prop had different defaults in different components.
BreadcrumbDivider has default `span`. BreadcrumbLink has `a` and Breadcrumb has `nav`.

- `accessibility` => Accessibility behavior if overridden by the user.
- `as` => type React.ElementType - An element type to render as (string or component).
- `className`
- `content` => Shorthand for primary content.
- `design` => type ComponentDesignProp
- `styles` =>
- `variables` => Override for theme site variables to allow modifications of component styling via themes.

#### Property Mapping

| Northstar `Breadcrumb` | v9 `Breadcrumb` |
| ---------------------- | --------------- |
| `accessibility` | |
| | `appearance` |
| `as` | |
| `className` | |
| `content` | |
| `design` | |
| | `dividerType` |
| | `iconPosition` |
| `size` | `size` |
| `styles` | |
| `variables` | |

#### Breadcrumb component:

- `size` => use as it is.

#### BreadcrumbItem component:

- `active` => Indicates if the link is the active. Use `current` instead.
- `disabled` => The Breadcrumb Item can be disabled.

#### Property Mapping

| Northstar `BreadcrumbItem` | v9 `BreadcrumbItem` |
| -------------------------- | ------------------- |
| `active` | `current` |
| `disabled` | `disabled` |
108 changes: 2 additions & 106 deletions packages/react-components/react-breadcrumb/docs/Spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -279,7 +279,7 @@ Usage
```

Type of the divider is passed from the `Breadcrumb` component. In case if partner wants to have a custom divider it should be passed as `children` prop.
Slash divider can be only for small Breadcrumb.
The slash divider is only used in a small breadcrumb.

```jsx
<Breadcrumb size="large" >
Expand Down Expand Up @@ -322,111 +322,6 @@ Under the hood @fluentui/react-button component is used.

For Link @fluentui/react-link component is used.

## Migration

### Fabric (v8) property mapping

This should be moved to MIGRATION.md later.
Here's how the API of v8's `Breadcrumb` compares to the one from v9's `Breadcrumb` component:

#### New props

- `appearance`

#### Props no longer supported with an equivalent functionality in Breadcrumb V9:

- `maxDisplayedItems`and `overflowIndex` - will be part of `partitionBreadcrumbItems` method
- `className` => Slot system supports it by default. We don't need to provide it explicitly.
- `items` => Use `children` prop instead.
- `componentRef`
- `dividerAs` => Divider is a separate component. Type of divider is passed to the Breadcrumb component.
- `focusZoneProps` => use `focusMode` instead.
- `overflowButtonAs` => Custom component for the overflow button. - use custom overflow button instead.
- `styles`
- `theme`
- `overflowAriaLabel` => Aria label for the overflow button.

#### Props no longer supported

- `onRenderOverflowIcon` => Render a custom overflow icon in place of the default icon `...`.
- `onGrowData` => Method that determines how to group the length of the breadcrumb. Return undefined to never increase breadcrumb length.
- `onReduceData` => Method that determines how to reduce the length of the breadcrumb. Return undefined to never reduce breadcrumb length.

As BreadcrumbItem part of `children` prop, a user decides how to render an item.
The following props are not needed anymore.

- `onRenderItem` => Custom render function to render each crumb. Default renders as a link.
- `onRenderItemContent` => Custom render function to render the content within a crumb. Default renders the text.
- `tooltipHostProps` => Extra props for the TooltipHost which wraps each breadcrumb item.

Fabric Breadcrumb `items` prop as part of `IBreadcrumbData` interface contains the following props:
BreadcrumbItem component contains similar props in V9.

- `key` => not supported
- `text` => use `children` prop of BreadcrumbItem component.
- `as` => type('h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'a') - Optional prop to render the item as a heading of your choice. You can also use this to force items to render as links instead of buttons (by default, any item with a href renders as a link, and any item without a href renders as a button). This is not generally recommended because it may prevent activating the link using the keyboard. In V9 It's part of BreadcrumbItem prop.
- `href` => URL to navigate to when this breadcrumb item is clicked. If provided, the breadcrumb will be rendered as a link.
- `isCurrentItem` => Whether this is the breadcrumb item the user is currently navigated to. If true, aria-current="page" will be applied to this breadcrumb item.
- `onClick` => Callback for when the breadcrumb item is selected.
- `onRender` => A function to render the outer content of the crumb (the link).
- `onRenderContent` => A function to render the inner content of the crumb (the text inside the link).
- `role` => Optional role for the breadcrumb item (which renders as a button by default)

#### Property Mapping

| v8 `Breadcrumb` | v9 `Breadcrumb` |
| ------------------- | --------------- |
| `ariaLabel` | |
| `className` | |
| `componentRef` | |
| `dividerAs` | |
| `focusZoneProps` | |
| `maxDisplayedItems` | |

### Northstar property mapping

#### Props which are repeating in each component

These props are the same in all the components.
`as` prop had different defaults in different components.
BreadcrumbDivider has default `span`. BreadcrumbLink has `a` and Breadcrumb has `nav`.

- `accessibility` => Accessibility behavior if overridden by the user.
- `as` => type React.ElementType - An element type to render as (string or component).
- `className`
- `content` => Shorthand for primary content.
- `design` => type ComponentDesignProp
- `styles` =>
- `variables` => Override for theme site variables to allow modifications of component styling via themes.

#### Property Mapping

| Northstar `Breadcrumb` | v9 `Breadcrumb` |
| ---------------------- | --------------- |
| `accessibility` | |
| `as` | |
| `className` | |
| `content` | |
| `design` | |
| `styles` | |
| `variables` | |

#### Breadcrumb component:

- `size` => use as it is.

#### BreadcrumbItem component:

- `active` => Indicates if the link is the active.
- `disabled` => The Breadcrumb Item can be disabled.

#### Property Mapping

| Northstar `BreadcrumbItem` | v9 `BreadcrumbItem` |
| -------------------------- | ------------------- |
| `active` | `current` |
| `disabled` | `disabled` |

## Behaviors

#### Overflow
Expand Down Expand Up @@ -500,6 +395,7 @@ It should be done by the partners using JSX composition.
For Menu `@fluentui/react-menu` component should be used.

`maxDisplayedItems` and `overflowIndex` are part of `partitionBreadcrumbItems` which is helper in Breadcrumb utils.
For non-clickable items tooltip is shown instead of overflow menu.

#### Truncate long names:

Expand Down