@clds/common-definitions

Common interfaces/types for other packages.

Installation

Install the package using Yarn:

pnpm install @clds/common-definitions

Interfaces

CommonComponentProps

Interface for props of all UI components.

CommonFieldProps

Interface for props of all form field components (requires implementation of mixed field control).

StylableComponentProps

Interface for props of components that can be wrapped with styled() from styled-components.

Mixed control mode

Mixed control mode refers to how the component deals with specific state that is required by the component. There are two types of components:

• Stateful - control the state internally (local useState() call)
• Statelss - accept value via props, as well as the callback that will be used to trigger the change in the parent state. In this case the state (can be also useState() call) is defined higher in the component hierarchy.

Mixed control mode is about making the component to support both cases:

• when someone wants to have full control of specific state (ie. combobox search value),
• when someone isn't interested in specific state and expects the component to manage that state on its own

Design system components should expose useful API that supports both use cases at the same time. For example, when creating <DropdownMenu items={...}/> we don't want control the opened state, we just expect that the dropdown opens on click and closes when menu item is selected. But there could be something special, like "in-app onboarding", when we want to open this menu programatically. Then we need something like <DropdownMenu isOpened={stateWeControl} onOpenedChange={ourOwnLogic} items={...}/>.

MixedControlProps is a group of types that will help to create those props in the conventional way. The goal is to support type-level API consistency of components.

Examples of sets of mixed control props

• defaultValue, value, onChange,
• isSelected, onSelect, defaultSelected,
• color, onColorChange, defaultColor
• selectedItem, onSelect, defaultSelectedItem

We cover all naming conventions and forbid impossible state like having defaultValue and value at the same time. There are 3 main types:

• ExplicitMixedControlProps
  • for safety, require either value or defaultValue to prevent edge cases when undefined-like values can be misleading from the API point of view
  • don't allow to pass onChange callback without value prop - to prevent common mistake that someone has uncontrolled component and synchronizes the state in the parent
• ImplicitMixedControlProps
  • for some cases ExplicitMixedControlProps can be problematic, for example some props are additional, so forcing ie. <DropdownMenu defaultOpened={false} seems an overkill since for DropdownMenu defaultOpened should be just false and passing it explicitly isn't convenient.
  • this type allows to not pass any prop to indicate uncontrolled mode (component will have private default value)
  • this type still doesn't allow to use onChange callback in uncontrolled mode (can only exist when value is also provided)
• ImplicitTraceableMixedControlProps
  • this type allows onChange callback to be passed any time
  • useful for callbacks for ie. analytics, like <DropdownMenu onFocusedIdChange={analytics.track('focused')} ... /> but please use it carefully to not encourage trying to use this prop as a source of truth.

Usage

Import one of the interfaces and extend.

Versioning

This library follows Semantic Versioning.

License

See LICENSE