v4 to v5 upgrade guide

Major changes

Angular project has been updated from v7 to v12. Going forward only angular versions v12 and above will be supported. Due to this, we have enabled ivy compilation engine partially - partially due to npm. - With this change, angular switches from node-sass to sass (dart)

• IE is no longer supported, hence IE specific keys ('Down', 'Esc', 'Up', etc.) & conditions have been removed
• Peer dependency now lists @carbon/styles package instead of carbon-components
  • All class prefixes within components have been updated from bx-- to cds--

Changelog

Please note that components, that have not been listed have not been changed or have simply gone through a css class update (prefix)

• Accordion

  • Added new input properties:
    • disable - prevents accordion item from being expanded.
    • size - sets the size of the accordion item.

• Button

  • Button directive has major changes. The directive no longer supports standalone icons, instead use the newly ibm-icon-button component.
  • ibmButton (Directive)
    • size no longer supports normal value, instead use md. A new size option has also been added 2xl. Hence, following size options can now be used: sm, md, lg, xl, 2xl.
    • type (Button type), no longer accepts toolbar-action as a value.
    • Button directive no longer supports assitive text (tooltips for icon), hence hasAssistiveText, assistiveTextPlacement, assistiveTextAlignment input properties have been removed, if you use these options, please remove.
    • By making the button expressive (isExpressive to true), sizes sm (small) & md (medium) will not be assigned, instead predefined expressive sizing will be used.

  • Icon button (New)

    • With the changes to tooltip, standalone icon buttons have been separated into a new component. The component covers most of the use cases, but some may need to create a custom ibm-icon-button component. To do that, a BaseIconButton component has been created to help you get started.
    • You will be able to pass in attributes & global classes, see storybook & docs for examples.

• Checkbox

  • CheckboxChange class has been removed.
  • change output binding has been removed, instead use the checked two-way binding.
  • size and nested are no longer input properties.
  • aria-label input is now renamed too ariaLabel to avoid assigning aria property to component tag.
  • aria-labelledby input is now renamed to ariaLabelledby to avoid assigning aria property to component tag.

• Code snippet

  • Code snippet has been completely rewritten & now uses ibm-icon-button component.
  • There are more Input properties to customize code snippet.
  • Now uses the navigator (browser) API for copying.
  • Look at documentation for information on new features (min/max number of expanded rows, min/max number of collapsed rows, etc).

• Combobox

  • Now applies disabled styling to label/helper text.
  • All size classes are now applied, including md (default).
    • No longer accepts xl value for size, instead use lg.

• Content Switcher

  • theme input has been deprecated & removed.

• Datepicker Input

  • Now applies disabled styling to label/helper text.
  • All size classes are now applied, including md (default).
    • No longer accepts xl value for size, instead use lg.

• Date Picker

  • .dayContainer custom styling has been removed (no action required).
  • pattern input has been renamed to inputPattern for more clarity.
  • No longer accepts xl value for size, instead use lg.

• Dialog

  • closeAll function in dialog.service.ts has been removed, use the static DialogService.closeAll function instead.

• Dropdown

  • Now applies disabled styling to label/helper text.
  • All size classes are now applied, including md (default).
    • No longer accepts xl value for size, instead use lg.
  • value input has been removed, use itemValueKey instead.

  • Dropdown List

    • No longer accepts xl value for size, instead use lg.

• Grid/Row/Columns

  • Grid

    • Now supports css grid, set useCssGrid to true to enable. Enabling css grid will automatically update columns to css grid classes.
    • View documentation for more information.

  • Row

    • leftGutter, rightGutter, & condensed input have been removed as they are not supported in v11.

  • Column

    • New css grid input properties, view documentation.

• Input (Directive)

  • All size classes are now applied, including md (default).
    • No longer accepts xl value for size, instead use lg.

• Label

  • Now applies disabled styling to label/helper text.

• Layer

  • A directive that applies layering style to the element it is applied to. This component is an alternative way to apply light & dark theme to components. You'll notice that going forward, theme input has been marked as deprecated for some components.
  • Setting level via ibmLayer input will automatically update child levels.
  • View storybook & documentation for more information.

• Modal

  • FYI - Since we now use partial-ivy compilation, we removed a remote scoping error from ModalService. A BaseModalService is now introduced, but no change is required on your end.
  • Modal now accepts md as a size option and is the default value now.

• Notification

  • Notification components have been updated to be more accessible out of the box. inline-notification (default) & toast have the role attribute set to status by default, with additional role options of log & alert.
  • For notifications requiring actions, use the new ActionableNotification component, which has the role attribute set to alertdialog.
  • info-square & warning-alt types have been added to all notification variants (inline, toast, actionable).
  • For all notifications, vertical margin have been removed. You can assign the container the new ibmStack layout directive to evenly space the notifications.
  • Due to role changes, toast & inline-notification, no longer support interactive elements (Links, additional buttons, etc.). It is still possible to pass in buttons if you use templates, however, it is highly recommended you should switch to the new actionable-notification component.

    • Actionable-notification (New)

      • Supports interactive elements.
      • Set notificationObj.variant to inline or toast to enable respective styling variation.
      • Like toast & inline-notifcation, there are directives to help build custom actionable notifications (ActionableTitle, ActionableSubtitle, ActionableButton, etc.).

    • Notification (Inline)

      • Interactive elements should NOT be used with this component.
      • Now has two selectors, ibm-inline-notification & ibm-notification.

    • Toast

      • Interactive elements should NOT be used with this component.

• Pagination Nav

  • Now wraps icon in IconButton component. Additional props (icon button) have been added to allow customization.

• Popover (New)

  • Popover directive & popover content component.
  • Content that layers over all other elements on page.
    • All tooltips extend popover.
  • For more information view carbondesignsystem, documentation, or storybook.

• Progress bar (New)

  • Component to show the progression of a process such as file transfer, installation, etc.
  • Fore more information view carbondesignsystem, documentation, or storybook.

• Progress Indicator

  • Tooltips are no longer supported in V11.
    • Use secondary label.
  • Icons have been updated
  • Step interface has had some major changes to better manage state
    • text has been changed to label
    • optionalText is now secondaryLabel
    • state has been removed, instead we have created 2 additional properties complete & invalid that accept boolean values
    • Current state is now managed via current (index in array) input property. All steps preceding current are set to complete (Complete set to true) & following is set to incomplete (complete set to false).
    • Additionally, icons are now displayed in the following weighted order current -> invalid -> complete -> incomplete

• Search

  • Toolbar search is deprecated & removed in Carbon V11. (Wrapping ibm-search in div.cds--toolbar)
  • All size classes are now applied, including md (default).
    • No longer accepts xl value for size, instead use lg.

• Select

  • Now applies disabled styling to label/helper text.
    • All size classes are now applied, including md (default).
      • No longer accepts xl value for size, instead use lg.
  • Custom component style have been removed.

• Slider

  • Now applies disabled styling to label/helper text.
    • All size classes are now applied, including md (default).
      • No longer accepts xl value for size, instead use lg.

• Structured List

  • Improved accessibility, styles are now applied to row on focus event.

• Table

  • Drag & drop features (neutrino) has been commented out until Carbon supports it out of the box.
  • NOW Should we emit (checkedChange) in table-checkbox.component.ts? This would align with checkbox as change has been removed. :LOGBOOK: CLOCK: [2022-07-09 Sat 22:53:51] CLOCK: [2022-07-09 Sat 22:53:54] :END:
  • Filter button has been removed from TableHeadCell as this was most likely from neutrino.

• Tabs

  • Tabs have been rewritten to use buttons instead of nav elements, they now use buttons.
  • type now accepts contained (previously container) & line (previously default). This change is made to reflect the naming convention on carbondesignsystem.com.
  • ibm-tab-header component has been converted to a directive, hence a button with ibmTabHeader should be used (See storybook).
  • You can now use the new TabSkeleton component with ibm-tab-header-group to indicate loading (With *ngIf, see storybook).

• Theme

  • Directive that allows you to set the theme white, g10, g90, g100 to any element.
  • Theme resets the layer count to 1 (Starts from 0).
  • View story & docs for more information.

• Tile(s)

  • We have decided to not add theme input prop to ALL of the tiles as it will be removed in next major version, instead use layer directive to switch between light & dark theme.
  • theme property binding will be removed in next major version.

• Timepicker

  • Now applies disabled styling to label text.
  • theme property will be removed in next major version.
  • Added size input property which accepts sm, md, & lg.
    • All size classes are applied, including md (default).

• Toggle

  • Toggle has been completely rewritten to improve accessibility & flexibility of layout
  • In previous version, <input type="checkbox"> was used, this has now been switched to <button role="switch">
  • ToggleChange class is now removed
  • skeleton input property has been removed (Toggle no longer supports skeleton)
  • change event has been removed, now use checkedChange (Same as checkbox output)

• Tooltip

  • Tooltips no longer support interactive content, use Toggletip for such situations. The API for tooltip has been updated & the component has been rewritten to use the Popover component/directive.

  • Unlike previously, triggers are now predefined for all types of tooltip.

    • Tooltip opens on mouseenter (or programmatically)
    • Tooltip definition opens on mouse click (or programmatically)
    • Toggletip opens on mouse click (or programmatically)

  • API has been simplified to

  • Icon Tooltip - ibm-tooltip-icon (Removed)

    • Due to accessibility issues, this component has been removed.
    • You can use the new Icon Button component as a replacement.

  • Tooltip Ellipses - Removed

    • Use tooltip instead (View storybook example)

  • Certain input properties (auto-align) aren't available in V11 & will be available soon.

• UI Shell

  • Header Action (ibm-header-action)

    • Now uses icon buttons component, additional property bindings have been added to customize experience.

  • Panel

    • Css classes have been updated (Not just the prefix)

      Let us know if you run into any issues with the update on Slack :) We have a few things in the work to improve documentation & storybook experience.