Huge News!Announcing our $40M Series B led by Abstract Ventures.Learn More
Socket
Sign inDemoInstall
Socket

@clds/common-definitions

Package Overview
Dependencies
Maintainers
0
Versions
120
Alerts
File Explorer

Advanced tools

Socket logo

Install Socket

Detect and block malicious and high-risk dependencies

Install

@clds/common-definitions

Common Design System TypeScript definitions

  • 0.49.0
  • Source
  • npm
  • Socket score

Version published
Maintainers
0
Created
Source

@clds/common-definitions


npm version

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

FAQs

Package last updated on 06 Dec 2024

Did you know?

Socket

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

Related posts

SocketSocket SOC 2 Logo

Product

  • Package Alerts
  • Integrations
  • Docs
  • Pricing
  • FAQ
  • Roadmap
  • Changelog

Packages

npm

Stay in touch

Get open source security insights delivered straight into your inbox.


  • Terms
  • Privacy
  • Security

Made with ⚡️ by Socket Inc