webcomponents / webcomponents/custom-elements-manifest

[Proposal] Extend the `type` object with more detailed information

Open
#88 4 comments 1 reaction 0 assignees View on GitHub
Dominant language
TypeScript
Stars
502
Forks
27
PR merge metrics
No merged PRs in 30d

Description

Currently the [type def](https://github.com/webcomponents/custom-elements-manifest/blob/master/schema.d.ts#L356) for the type object has only `text`, `references`, and `sources` as available data.

Given that `text` is meant to be type definition's text as is, there could be more detail added (and more features provided from analysis tools like cem/analyzer) if the type object is changd/expanded to something like:

```js
export interface Type {
name?: string;
definition?: string;
values?: string[]
references?: TypeReference[];
source?: SourceReference;
}
```

Consider a case like this:

```js
export type MyCustomType = 'valueA' | 'valueB';

@property() myProp: MyCustomType = 'valueA';
```

```js
// cem.json
{
...
{
kind: field,
type: {
name: 'MyCustomType',
definition: `'valueA' | 'valueB'`,
values: [ 'valueA', 'valueB']
}
}
...
}
```

All the type properties would be optional to support different kinds of type definitions where not all parts would be able to be determined.

```js
export type MyCustomType = { someProp: string; someOtherProp: number};

@property() myProp: MyCustomType;
```

```js
// cem.json
{
...
{
kind: field,
type: {
name: 'MyCustomType',
definition: `{ someProp: string; someOtherProp: number}`,
values: undefined
}
}
...
}
```

If analysis tools can "unwrap" the named type definition and get at the actual values, those could be provided in js structures in the cem.json and unlock a TON of potential for the cem.json to be used in lots of different documentation implementations. Getting a list of the type values from the type itself isnt that easy, but getting it from the `cem.json` would be trivial, but the schema as is doesnt have a place to put such information if it could be retrieved.

Contributor guide

No contributing guide indexed for this repository

Research direction

Start with schema.d.ts around line 356, then compare the current Type definition with the proposed shapes and cem.json examples in the issue. Done means the expanded Type schema and the expected representation of names, definitions, and values are agreed and specified for analysis tools.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
30/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.