webcomponents / webcomponents/custom-elements-manifest

Add `commands` array to `CustomElementDeclaration`

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

Description

With https://developer.mozilla.org/en-US/docs/Web/API/Invoker_Commands_API being available in all browsers, we are able to define custom commands for custom elements. However, the custom-elements-manifest schema currently has no support for storing such information.

For example you could have a `command` jsdoc like this:

```js
/**
* @command --show-modal - Calls `showModal()` on the `` element when invoked.
*/
export class Dialog extends LitElement { ... }
```

To be able to store this information in `custom-elements.json`, a schema change is necessary.

I propose adding the following property to the `CustomElementDeclaration`:

```json
"commands": {
"description": "The commands that this element will respond to.",
"items": {
"$ref": "#/definitions/Command"
},
"type": "array"
}
```

with the following being the `Command` definition:

```json
"Command": {
"properties": {
"description": {
"description": "A markdown description what the command does when invoked.",
"type": "string"
},
"inheritedFrom": {
"$ref": "#/definitions/Reference"
},
"name": {
"type": "string"
}
},
"required": [
"name"
],
"type": "object"
}
```

Contributor guide

No contributing guide indexed for this repository

Research direction

Locate the schema definition for CustomElementDeclaration and the related definitions used for custom-elements.json. Compare the proposed commands array and Command definition with existing schema patterns, then find the validation tests or fixtures that cover schema changes. Done means the schema accepts commands with a required name and optional description and inheritedFrom fields.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
tooling
Issue type
Feature
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.