feat: add support for styles debugging

[kuzhelov]

This PR introduces first version of the toolset to debug Stardust styles (for most commonly reported debug scenarios).

Usage

Toolset is working in development builds only, and this is the set of steps to obtain debug information about Stardust component's styles:

• open React Dev Tools tab in browser
• in the elements tree select Stardust component which styles should be inspected
• enter a query in console, e.g. $stardust.whosProp('...'), $stardust.whosValue('..') (or other supported API method)
  • result output will be provided with all the requested insights for the selected component

API

List of commands

• $stardust.whosProp(propName | (propName) => boolean)
  • filters all the siteVariables, variables and styles values to remain only those that have propName as a prop name.
  • supports predicate function being passed as argument.
• $stardust.whosPropContains(propNameSubstring)
  • filters siteVariables, variables and styles entries to only those that contain propNameSubstring in their prop names
• $stardust.whosValue(value | (value) => boolean)
  • filters all the siteVariables, variables and styles values to remain only those that have value as value
  • supports predicate function being passed as argument.
• $stardust.whosValueContains(valueSubstring)
  • filters siteVariables, variables and styles entries to only those that contain string values that contain valueSubstring.
• $stardust()
  • this command provides extensive summary of all the available debug information about component's styles. This output is used by the rest commands from the list as an input for filtering.

Output

Each of these methods filters the debugData object (which could be accessed by $stardust() with the component being selected in the React Dev Tools - this object contains extensive information about all the style ingredients of the component).

The result of this filtering generally contains the following props: componentName, siteVariables, variables, styles. Each of these categories contains resolved values grouped in the following categories:

• themes - an array of theme values, in the same order as those are defined by Provider components, starting from the root-level component down to the component which is debugged
• instanceOverrides - values that are defined directly for component's instance by, for example, styles or variables prop
• result - contains result of all the values from all the sources being merged. This reflects the final value that is passed to component.

It is worth to notice that empty categories are omitted from the output of filtering. For example, if there are only component styles that satisfy filtering conditions, then the following object will be provided as an output:

// EXAMPLE: only `styles` contain data that satisfy filter condition
> $stardust.whosProp(' ... ')

// outputs
{
  componentName: ...
  styles: {
     themes: [ 
        0: { ... },
        1: { }   // empty object - if there are no matching values defined in this theme
     ],
     instanceOverrides: { ... }
     result: { ... }
  }
}

And, if there is no filtered data in both siteVariables, variables and stylescategories, then the empty object will be returned as a result:

// EXAMPLE: nor `styles`, `siteVariables` or `variables` contain data that satisfy filter condition
> $stardust.whosProp(' ... ')

// outputs
{ }

Implementation Notes

Below there is a list of criterias the implementation approach was aiming on:

• minimal changes to existing API to instrument debug scenarios
• modular implementation, easy to extend
• minimal affect on the existing component's scenarios and functionality
• minimal possible runtime costs
  • zero costs for production builds
  • for development builds
    • 0% CPU cost, as all the debug data is evaluated on-demand
    • 2% memory increase for development builds (tested on Stardust docs site's pages)

[codecov]

Codecov Report

Merging #1726 into master will decrease coverage by 1.1%.
The diff coverage is 30.72%.

@@            Coverage Diff             @@
##           master    #1726      +/-   ##
==========================================
- Coverage   71.05%   69.94%   -1.11%     
==========================================
  Files         862      868       +6     
  Lines        7169     7347     +178     
  Branches     2062     2118      +56     
==========================================
+ Hits         5094     5139      +45     
- Misses       2069     2202     +133     
  Partials        6        6

Impacted Files	Coverage Δ
packages/react/src/types.ts	50% <ø> (ø)	⬆️
packages/react/src/lib/debug/debugData.ts	0% <0%> (ø)
packages/react/src/lib/debug/debugDataTraversal.ts	10% <10%> (ø)
packages/react/src/lib/mergeThemes.ts	100% <100%> (ø)	⬆️
packages/react/src/lib/debug/index.ts	100% <100%> (ø)
packages/react/src/lib/mergeProviderContexts.ts	100% <100%> (ø)	⬆️
packages/react/src/lib/UIComponent.tsx	82.35% <100%> (+1.1%)	⬆️
packages/react/src/lib/createComponent.tsx	95% <100%> (+0.55%)	⬆️
packages/react/src/lib/debug/debugDataProvider.ts	19.44% <19.44%> (ø)
packages/react/src/lib/debug/utils.ts	20.68% <20.68%> (ø)
... and 8 more

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update a2a850d...d43b535. Read the comment docs.