component status alignment

[agliga]

Introduce additional metadata in the ds-versions.json file to help us programmatically link ebayui-core component to the Design System components/patterns they implement.

Proposed changes to DS versions JSON

Instead of a 1:1 mapping of ebayui-core component name to version, map ebayui-core component name to an object containing multiple pieces of metadata about its design system relationship:

property	type	required?	description	example
name	string	yes	canonical name for this component in the eBay Design System (see internal reference doc)	"video"
version	string | number	strongly encouraged	version # of the DS component spec implemented	"2.4.0"
status	string	no	additional status info when applicable, e.g. as "alpha", "beta", "deprecated"	"beta"

If a component maps to multiple Design System components, map it to an array of metadata.

For example:

{
  "textbox": [
     { "name": "text-field", "version": "1.4" },
     { "name": "text-area", "version": "1.5" }
  ],
  "video": {
     "name": "video",
     "version": "2.4.0",
     "status": "beta"
  }
}

Proposed changes to DS versions script

This script pulls component-specific metadata from the ds-versions.json file and prepends it to the component's readme.

• Update script to support the refactored structure of the JSON file (as documented above)
• Add a step to the script that dynamically adds a link in the component's readme that navigates to the playbook.ebay.com design system documentation for that component

Proposed process changes

• Before each release, ensure that the metadata in ds-versions.json is up-to-date

[cordeliadillon]

@agliga, I updated the issue description with the approach we discussed earlier today. I'll work on changes to the JSON file and put up the PR. I'll also get you the appropriate playbook URL prefix to add to the script, and then you can start on script updates. Looking forward to working with you on this! Excited that the Playbook page and readmes will dynamically link to each other.

[HenriqueLimas]

@agliga @cordeliadillon, shouldn't the skin module be the primary entry point for determining the version of the Design System (DS) being used? The script should verify the existence of a component rather than checking which DS version is implemented, as the version is already specified by the skin module (see example).

My point is that the JavaScript libraries (ebayui-core and ui-core-react) shouldn't need to maintain a JSON file with DS version links, as this information is already managed by the skin module. The skin module defines the DS version, while the JS libraries handle behavior, not styling.

I understand that there may be cases where variants are missing or not fully compatible with the DS version implemented by the skin. However, maintaining these JSON files over time is a significant burden and may not always be accurate. Additionally, these JSON files can become outdated or incorrect.

[cordeliadillon]

I think there are 3 possible approaches here:

1. Current: eBay UI Core inherits Evo Version from Skin
   • Pros:
     • Only maintained in one place
   • Cons:
     • Some gaps, as not all components have a 1:1 mapping between Skin and eBayUI
     • Doesn’t reflect functionality change
2. eBay UI Core maintains Evo Version metadata separate from Skin
   • Pros:
     • Explicit, specific status per library
   • Cons:
     • A lot of redundancy
     • Can get stale if updating this is not a defined part of component dev process
     • Gets out of sync when there are Skin-only version updates
3. eBay UI Core specifies Evo Version metadata where needed
   • What this could look like:
     • Default to inheriting from Skin
     • If Core specifies a version, use the higher of Core & Skin version
     • Core defines metadata for components that don’t have 1:1 Skin mapping
   • Pros:
     • Reduce redundancy
     • Kind of matches Skin/Core's general model, where Core builds on top of Skin
   • Cons:
     • For code maintainers, I imagine it wouldn't be super clear when metadata needs to be explicitly added here, vs relying on what's in Skin. Requires some cross-referencing.

Let's discuss in our next meeting!