v11 Prop Changes

[joshblack]

Goal

We want the props for the components in our React library to be consistent and predictable. Props should follow common or familiar conventions and should be consistent across components in the design system.

Links & Resources

• https://carbon-react-explorer.vercel.app/

Related issues

• [carbon-react] Input className prop inconsistencies #5853
• React component API inconsistency between SelectableTile and RadioTile (misc properties) #5972
• Clarify default component spacings #5367
• Removing placeholder text from Carbon Design System #5022
• Form spacing inconsistencies  #2343
• [Research] Prop name consistency #2529
• v11 proposed changes for React #4356

Checklist

• Change instances of handle* to on*
  • handleClick
  • handleKeyDown
  • handleOpen - Only exists in ModalWrapper - component no longer maintained.
  • handleOverflowMenuItemFocus - Only exists in OverflowMenu and is not consumable by the user.
  • handleSubmit - Only exists in ModalWrapper - component no longer maintained.
  • handleTabClick - Is a child of Tabs and is not consumable by the user.
  • handleTabKeyDown - Is a child of Tabs and is not consumable by the user.
• Rename "expando" to "expand" #10317
• Decide on initial* vs default* conventions for v11 #9622
• Decide on convention of type, kind, and variant for v11 #9623
• Deprecate usage of iconDescription for v11 #9624
• Create a consistent API for event handlers in v11 #9641
  • Find a list of components that share state in a event handler and change them
• Update light prop usage with Layer component #9763
• Update any handlers that use evt.persist()
• titleText vs labelText, different for dropdown and number input
• placeholder vs placeholderText
  • Check-in with DA/Taylor because they may be removing this
• ariaLabel to aria-label: https://carbon-react-explorer.vercel.app/props/ariaLabel

Questions

• Does the defaultToggled prop make sense? Can you have something be in a "toggled" state or should we indicate that as on/open instead?

[joshblack]

Patterns

Deprecating a prop

• Use the deprecate() helper

The <old-prop-name> prop for <component-name> has been deprecated in favor of <new-prop-name>.
It will be removed in the next major release.

    handleClick: deprecate(
      PropTypes.func,
      'The handleClick prop for ClickableTile has been deprecated in favor of onClick. It will be removed in the next major release.'
    ),

Scenarios

• You are replacing a prop with a new prop
  • The prop can be added safely in v10
  • The prop can not be added safely in v10 (maybe there is a conflicting prop)
• You are removing a prop in the next major release
• You are changing the type of a specific prop
• You are repurposing a prop, the prop will be used for something else
• Event handlers (prop signature changes)
  • onChange, onClick, onKeyDown
  • (event) => void, (event, state) => void, (state, event) => void, (state) => void
  • Option 1: (event) => void, (event, state) => void
    • What type should state be?
  • Option 2: we won't ever give you state information in a handler, you must subscribe to onChange, onStateChange

Deprecations

• Deprecate a prop type (deprecate() helper)
• Display a deprecation warning (ad-hoc messages)

Feature flags

• Sometimes we won't need these at all
• Sometimes we'll need hooks (useFeatureFlag)
• Sometimes we'll need @carbon/feature-flags