diff --git a/docs/deprecation-migration.mdx b/docs/deprecation-migration.mdx index 498c518773..0bfc5a7413 100644 --- a/docs/deprecation-migration.mdx +++ b/docs/deprecation-migration.mdx @@ -24,6 +24,7 @@ The following section provides migration guidance for deprecated components that - For `Hr`, [`Divider`](?path=/docs/divider--docs) is recommended as the preferred alternative. - For `VerticalDivider`, [`Divider`](?path=/docs/divider--docs) is recommended as the preferred alternative. - For `LoaderBar`, `LoaderStar` and `LoaderSpinner`: the new [`Loader`](?path=/docs/loader--docs) is recommended as the preferred alternative. +- For `TileSelect`, no like-for-like replacement has been validated. Do not reproduce its card-like selection treatment in new work; use the approved, product-specific Fusion pattern instead. Where the need is a conventional form choice, [`RadioButton`](?path=/docs/radio-button--docs) or [`Checkbox`](?path=/docs/checkbox--docs) may be appropriate, according to the selection semantics. ## Alternative Patterns @@ -40,6 +41,18 @@ The following sections provide migration guidance for deprecated components that - [Setting sRow](#settings-row) - [Hr](#hr) - [VerticalDivider](#vertical-divider) +- [Tile Select](#tile-select) + +## Tile Select + +`TileSelect` and `TileSelectGroup` are deprecated. The components have low adoption, their two known product implementations do not use the pattern as intended, and the pattern has not shown a good UX fit. Their overlap with existing Fusion patterns also creates unnecessary duplication and confusion. Carbon Tile Select is primarily a radio-style control, while the potentially overlapping Fusion pattern is more checkbox-like; they are not interchangeable. + +### Migration + +- There is no prescribed like-for-like replacement. Assess the user need and use the approved product-specific Fusion pattern rather than carrying the Carbon pattern forward. +- If the need is a conventional form choice, use `RadioButtonGroup` and `RadioButton` for mutually exclusive choices, or `CheckboxGroup` and `Checkbox` for independent choices. This is semantic guidance, not a replacement for Tile Select's card-like treatment. +- Keep the existing Report implementation unchanged until its approved replacement is available. Do not introduce Tile Select into new Report work. +- Migrate Client Management as part of its planned redesign; the redesign should use the approved Fusion pattern rather than a like-for-like Tile Select replacement. ## Alert @@ -187,4 +200,4 @@ The `Hr` component can be replaced by a `Divider` with type `horizontal`. The `D The `VerticalDivider` component can be replaced by a `Divider`. The `Divider` component will provide consistent styling while maintaining the same functionality. - \ No newline at end of file + diff --git a/skills/carbon-react/components/tile-select-group.md b/skills/carbon-react/components/tile-select-group.md index 1b5403473d..fd4a7c5bab 100644 --- a/skills/carbon-react/components/tile-select-group.md +++ b/skills/carbon-react/components/tile-select-group.md @@ -11,6 +11,10 @@ description: Carbon TileSelectGroup component props and usage examples. ## Source - Export: `./components/tile-select` - Props interface: `TileSelectGroupProps` +- Deprecated: Yes +- Deprecation reason: `TileSelectGroup` is deprecated with `TileSelect`. No +like-for-like replacement has been validated; use a product-specific Fusion +pattern. See the Carbon deprecation migration documentation for consumer-specific guidance. ## Props | Name | Type | Required | Literals | Description | Default | diff --git a/skills/carbon-react/components/tile-select.md b/skills/carbon-react/components/tile-select.md index 42b11a2f69..1d51c23d13 100644 --- a/skills/carbon-react/components/tile-select.md +++ b/skills/carbon-react/components/tile-select.md @@ -11,6 +11,11 @@ description: Carbon TileSelect component props and usage examples. ## Source - Export: `./components/tile-select` - Props interface: `TileSelectProps` +- Deprecated: Yes +- Deprecation reason: `TileSelect` has low adoption and is a poor fit for its intended +selection UX. No like-for-like replacement has been validated; use a +product-specific Fusion pattern. See the Carbon deprecation migration +documentation for consumer-specific guidance. ## Props | Name | Type | Required | Literals | Description | Default | diff --git a/skills/carbon-react/index.md b/skills/carbon-react/index.md index 448839f255..90451470f3 100644 --- a/skills/carbon-react/index.md +++ b/skills/carbon-react/index.md @@ -152,8 +152,8 @@ - [TileContent](components/tile-content.md) - [TileFooter](components/tile-footer.md) - [TileHeader](components/tile-header.md) -- [TileSelect](components/tile-select.md) -- [TileSelectGroup](components/tile-select-group.md) +- [TileSelect](components/tile-select.md) (deprecated) +- [TileSelectGroup](components/tile-select-group.md) (deprecated) - [Time](components/time.md) - [Toast](components/toast.md) (deprecated) - [Tooltip](components/tooltip.md) (deprecated) diff --git a/skills/carbon-react/references/docs/deprecation-migration.md b/skills/carbon-react/references/docs/deprecation-migration.md index 498c518773..0bfc5a7413 100644 --- a/skills/carbon-react/references/docs/deprecation-migration.md +++ b/skills/carbon-react/references/docs/deprecation-migration.md @@ -24,6 +24,7 @@ The following section provides migration guidance for deprecated components that - For `Hr`, [`Divider`](?path=/docs/divider--docs) is recommended as the preferred alternative. - For `VerticalDivider`, [`Divider`](?path=/docs/divider--docs) is recommended as the preferred alternative. - For `LoaderBar`, `LoaderStar` and `LoaderSpinner`: the new [`Loader`](?path=/docs/loader--docs) is recommended as the preferred alternative. +- For `TileSelect`, no like-for-like replacement has been validated. Do not reproduce its card-like selection treatment in new work; use the approved, product-specific Fusion pattern instead. Where the need is a conventional form choice, [`RadioButton`](?path=/docs/radio-button--docs) or [`Checkbox`](?path=/docs/checkbox--docs) may be appropriate, according to the selection semantics. ## Alternative Patterns @@ -40,6 +41,18 @@ The following sections provide migration guidance for deprecated components that - [Setting sRow](#settings-row) - [Hr](#hr) - [VerticalDivider](#vertical-divider) +- [Tile Select](#tile-select) + +## Tile Select + +`TileSelect` and `TileSelectGroup` are deprecated. The components have low adoption, their two known product implementations do not use the pattern as intended, and the pattern has not shown a good UX fit. Their overlap with existing Fusion patterns also creates unnecessary duplication and confusion. Carbon Tile Select is primarily a radio-style control, while the potentially overlapping Fusion pattern is more checkbox-like; they are not interchangeable. + +### Migration + +- There is no prescribed like-for-like replacement. Assess the user need and use the approved product-specific Fusion pattern rather than carrying the Carbon pattern forward. +- If the need is a conventional form choice, use `RadioButtonGroup` and `RadioButton` for mutually exclusive choices, or `CheckboxGroup` and `Checkbox` for independent choices. This is semantic guidance, not a replacement for Tile Select's card-like treatment. +- Keep the existing Report implementation unchanged until its approved replacement is available. Do not introduce Tile Select into new Report work. +- Migrate Client Management as part of its planned redesign; the redesign should use the approved Fusion pattern rather than a like-for-like Tile Select replacement. ## Alert @@ -187,4 +200,4 @@ The `Hr` component can be replaced by a `Divider` with type `horizontal`. The `D The `VerticalDivider` component can be replaced by a `Divider`. The `Divider` component will provide consistent styling while maintaining the same functionality. - \ No newline at end of file + diff --git a/src/components/tile-select/tile-select-group/tile-select-group.component.tsx b/src/components/tile-select/tile-select-group/tile-select-group.component.tsx index 7cd50ad563..f68bc54d76 100644 --- a/src/components/tile-select/tile-select-group/tile-select-group.component.tsx +++ b/src/components/tile-select/tile-select-group/tile-select-group.component.tsx @@ -12,6 +12,11 @@ import { import { filterStyledSystemMarginProps } from "../../../style/utils"; import { TileSelectDeselectEvent } from "../tile-select.component"; +/** + * @deprecated `TileSelectGroup` is deprecated with `TileSelect`. No + * like-for-like replacement has been validated; use a product-specific Fusion + * pattern. See the Carbon deprecation migration documentation for consumer-specific guidance. + */ export interface TileSelectGroupProps extends MarginProps, TagProps { /** The TileSelect components to be rendered in the group */ children: React.ReactNode; @@ -35,6 +40,11 @@ export interface TileSelectGroupProps extends MarginProps, TagProps { multiSelect?: boolean; } +/** + * @deprecated `TileSelectGroup` is deprecated with `TileSelect`. No + * like-for-like replacement has been validated; use a product-specific Fusion + * pattern. See the Carbon deprecation migration documentation for consumer-specific guidance. + */ export const TileSelectGroup = ({ children, name, diff --git a/src/components/tile-select/tile-select-interaction.stories.tsx b/src/components/tile-select/tile-select-interaction.stories.tsx index 12c327e899..47710a495c 100644 --- a/src/components/tile-select/tile-select-interaction.stories.tsx +++ b/src/components/tile-select/tile-select-interaction.stories.tsx @@ -17,7 +17,7 @@ import DefaultDecorator from "../../../.storybook/utils/default-decorator"; type Story = StoryObj; export default { - title: "Tile Select/Interactions", + title: "Deprecated/Tile Select/Interactions", parameters: { themeProvider: { chromatic: { theme: "sage" } }, }, diff --git a/src/components/tile-select/tile-select.component.tsx b/src/components/tile-select/tile-select.component.tsx index 980af997e1..a572760c35 100644 --- a/src/components/tile-select/tile-select.component.tsx +++ b/src/components/tile-select/tile-select.component.tsx @@ -38,6 +38,12 @@ export interface TileSelectDeselectEvent { }; } +/** + * @deprecated `TileSelect` has low adoption and is a poor fit for its intended + * selection UX. No like-for-like replacement has been validated; use a + * product-specific Fusion pattern. See the Carbon deprecation migration + * documentation for consumer-specific guidance. + */ export interface TileSelectProps extends MarginProps, TagProps { /** title of the TileSelect */ title?: React.ReactNode; @@ -85,6 +91,12 @@ export interface TileSelectProps extends MarginProps, TagProps { accordionExpanded?: boolean; } +/** + * @deprecated `TileSelect` has low adoption and is a poor fit for its intended + * selection UX. No like-for-like replacement has been validated; use a + * product-specific Fusion pattern. See the Carbon deprecation migration + * documentation for consumer-specific guidance. + */ const TileSelect = React.forwardRef( ( { diff --git a/src/components/tile-select/tile-select.mdx b/src/components/tile-select/tile-select.mdx index 8d02f517f6..2a2e38e80b 100644 --- a/src/components/tile-select/tile-select.mdx +++ b/src/components/tile-select/tile-select.mdx @@ -3,11 +3,16 @@ import TranslationKeysTable from "../../../.storybook/utils/translation-keys-tab import * as TileSelectGroupStories from "./tile-select-group/tile-select-group.stories"; import * as TileSelectStories from "./tile-select.stories"; +import DeprecationWarning from "../../../.storybook/utils/deprecation-warning.component"; # TileSelect + +Tile Select is deprecated. It has low adoption and has proved to be a poor fit for selection UX. No like-for-like replacement has been validated: use an approved product-specific Fusion pattern for new work. See the migration guidance for existing consumers. + + = { - title: "Tile Select", + title: "Deprecated/Tile Select", component: TileSelect, argTypes: { ...styledSystemProps,