Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

wip: add custom-element-manifest documentation #8123

Closed
wants to merge 1 commit into from
+326 −0
Closed

wip: add custom-element-manifest documentation #8123

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
326 changes: 326 additions & 0 deletions docs/5-development/08-describing-UI5-Web-Components.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,326 @@
# Custom elements manifest

The Custom Elements Manifest is a file format that describes custom elements. UI5 Web Components are custom elements, and starting from version 1.22.0, we provide a custom elements manifest that details these elements within their respective package. With this we introduce a new format for describing components and their metadata.

**Note:** The information provided here is applicable specifically to TypeScript projects, as it relies on TypeScript decorators introduced by the UI5 Web Components.

## Components

### Class tags
| Tag | Description | Accepted types | Examples |
|---|---|---|---|
| `@class` | Defines the class | boolean | `@class` |
| `@constructor` | | Defines the class | `@constructor` |
| `@public` / `@protected` / `@private` | Defines the privacy of the class | boolean | `@public` <br /> `@protected` <br /> `@private` |
| `@since` | Defines the version when the class was introduced | string | `@since` 1.2.0 |
| `@deprecated` | Defines whether the class is deprecated | boolean \| string | `@depreaceted` <br /> `@deprecated` version 1.4.0 |
| `@abstract` | Defines whether the component is abstract (when the component doesn't have template) | boolean | `@abstract` |
| `@implements` | Defines the interfaces that the component implements | - | `@implements` \{ShowcaseType\} |
| `@extends` | Defines the superclass of the component | - | `@extends` ShowcaseType |
| `@slot` | - | - | <a href="#unnamed-slot">See more</a> |
| `@csspart` | - | - | <a href="#css-part">See more</a> |

```ts
/**
* @class
* Class description showcase
*
* @slot {ShowcaseType[]} default - Unnamed slot description showcase
*
* @csspart testPart - CSS Part description showcase
*
* @constructor
* @extends UI5Element
* @since 1.22.0
* @deprecated 1.22.0
* @public
* @abstract
* @implements {ShowcaseType}
* @implements {ShowcaseType2}
*/
@customElement("ui5-test-component")
class TestComponent extends UI5Element implements ShowcaseType, ShowcaseType2 {
```

**Note**: The `@customElement` decorator points to whether the class is a custom element or not.

**Note**: Tag name is automatically generated by the `@customElement` TypeScript decorator.

**Note**: If the component implements more than 1 interface use the `@implements` tag for every interface. Listed interfaces are considered as public and they will appear in the custom elements manifest.

### Property tags
| Tag | Description | Accepted types | Examples |
|---|---|---|---|
| `@public` / `@protected` / `@private` | Defines the privacy of the property | boolean | `@public` <br /> `@protected` <br /> `@private` |
| `@since` | Defines the version when the property was introduced | string | `@since` 1.2.0 |
| `@deprecated` | Defines whether the property is deprecated | boolean \| string | `@depreaceted` <br /> `@deprecated` version 1.4.0 |
| `@default` | Defines the default value of the property | string | `@default` "myDefaultValue"
| `@formProperty` | Defines whether the property value should be used in a form | boolean | `@formProperty`
| `@formEvents` | Defines which events should change property value | string | `@formEvents` change input
```ts
/**
* Property description showcase
*
* @public
* @since 1.2.0
* @deprecated 1.4.0
* @default "myDefaultValue"
* @formProperty
* @formEvents change input
*/
@property({ defaultValue: "myDefaultValue" })
property!: string;
```

**Note**: A `@property` decorator is required for public properties that have to be listed in the manifest.

**Note**: Type is automatically calculated from the used TypeScript type.

**Note**: Default tag is required for all public properties because the value isn't able to be automatically calculated.

### Getters tags
| Tag | Description | Accepted types | Examples |
|---|---|---|---|
| `@public` / `@protected` / `@private` | Defines the privacy of the property | boolean | `@public` <br /> `@protected` <br /> `@private` |
| `@since` | Defines the version when the property was introduced | string | `@since` 1.2.0 |
| `@deprecated` | Defines whether the property is deprecated | boolean \| string | `@depreaceted` <br /> `@deprecated` version 1.4.0 |
| `@default` | Defines the default value of the property | string | `@default` "myDefaultValue"
| `@formProperty` | Defines whether the property value should be used in a form | boolean | `@formProperty`
| `@formEvents` | Defines which events should change property value | string | `@formEvents` change input
```ts
/**
* Property description showcase
*
* @public
* @since 1.2.0
* @deprecated 1.4.0
* @default "myDefaultValue"
* @formProperty
* @formEvents change input
*/
get readonlyProperty(): string {
return "some string"
}
```

**Note**: New format requires return type to be explicitly set for every public read-only property (described getter).

**Note**: A default tag is required for all public read-only properties because their value isn't able to be automatically calculated.

### Property slot
A property slot is a slot that has an accessor.

| Tag | Description | Accepted types | Examples |
|---|---|---|---|
| `@public` / `@protected` / `@private` | Defines the privacy of the slot | boolean | `@public` <br /> `@protected` <br /> `@private` |
| `@since` | Defines the version when the slot was introduced | string | `@since` 1.2.0 |
| `@deprecated` | Defines whether the slot is deprecated | boolean \| string | `@depreaceted` <br /> `@deprecated` version 1.4.0 |

```ts
/**
* Property slot description showcase
*
* @public
* @since 1.2.0
* @deprecated 1.4.0
*/
@slot({ type: HTMLElement, "default": true })
propertySlot!: Array<IIcon>;
```

**Note**: `@slot` decorator is required for public properties that have to be listed in the manifest.

**Note**: Type is automatically calculated from the used TypeScript type.

### Unnamed slot
An unnamed slot is the default slot that doesn't have an accessor. This slot is declared inside the class comment using `@slot` tag.

```ts
/**
* @class
* ...
*
* @slot {ShowcaseType[]} default - Unnamed slot description showcase
* ...
*/
@customElement("ui5-test-component")
class TestComponent extends UI5Element {
```

### Event tags
| Tag | Description | Accepted types | Examples |
|---|---|---|---|
| `@param` | Defines the event details parameters | - | `@param` \{ShowcaseType\} testParameter description
| `@public` / `@protected` / `@private` | Defines the privacy of the event | boolean | `@public` <br /> `@protected` <br /> `@private` |
| `@since` | Defines the version when the event was introduced | string | `@since` 1.2.0 |
| `@deprecated` | Defines whether the event is deprecated | boolean \| string | `@depreaceted` <br /> `@deprecated` version 1.4.0 |
| `@allowPreventDefault` | Defines whether the event is preventable | boolean | `@allowPreventDefault` |
| `@native` | Defines whether the event is native event | boolean | `@native` |
```ts
/**
* Event description showcase
* @public
* @since 1.2.0
* @deprecated 1.4.0
* @param {ShowcaseType} testParameter description
* @allowPreventDefault
* @native
*/
@event("eventWithDetails", {
detail: {
/**
* @public
* @since 1.2.0
* @deprecated 1.4.0
*/
testParameter: { type: HTMLElement }
},
})
class TestComponent extends UI5Element {
```

<br />
<br />

### Event parameter tags
Now, you can specify

| Tag | Description | Accepted types | Examples |
|---|---|---|---|
| `@public` / `@protected` / `@private` | Defines the privacy of the event parameter | boolean | `@public` <br /> `@protected` <br /> `@private` |
| `@since` | Defines the version when the event parameter was introduced | string | `@since` 1.2.0 |
| `@deprecated` | Defines whether the event parameter is deprecated | boolean \| string | `@depreaceted` <br /> `@deprecated` version 1.4.0 |
```ts
@event("eventWithDetails", {
detail: {
/**
* @public
* @since 1.2.0
* @deprecated 1.4.0
*/
testParameter: { type: HTMLElement }
},
})
class TestComponent extends UI5Element {
```

**Note**: With these tags only deprecated, since and privacy could be changed. If you want to change the description use `@param` tag in the event description.
**Note**: If the parameter exists as `@param` tag in the event description, its privacy has to be specified explicitly for the parameter.

<br />
<br />

## Method tags

| Tag | Description | Accepted types | Examples |
|---|---|---|---|
| `@param` | Defines the method's parameters | - | `@param` param1 parameter description showcase <br />`@param` \{ShowcaseType\} [param2] optional parameter description showcase
| `@public` / `@protected` / `@private` | Defines the privacy of the method | boolean | `@public` <br /> `@protected` <br /> `@private` |
| `@since` | Defines the version when the method was introduced | string | `@since` 1.2.0 |
| `@deprecated` | Defines whether the method is deprecated | boolean \| string | `@depreaceted` <br /> `@deprecated` version 1.4.0 |
| `@returns` | Defines the return value description | - | `@returns` return description showcase |

```ts
/**
* Shows the popover.
* @param param1 parameter description showcase
* @param [param2="Type1"] optional parameter description showcase
* @public
* @since 1.2.0
* @deprecated 1.4.0
* @returns description of return
*/
static methodName(param1: Array<ShowcaseType>, param2 = ShowcaseType.Type1): boolean {}
```
**Note**: Parameters should have explicitly set TypeScript type.

**Note**: Method should have explicitly set TypeScript type.

**Note**: Parameters that have respective `@param` tag inside the method description will be considered as public.

**Note**: The optional parameter's default value should be specified in the `@param` tag.

<br />
<br />

## CSS Part
CSS parts are declared inside class comments using `@csspart` tag

```ts
/**
* @class
* ...
*
* @csspart testPart - CSS Part description showcase
* ...
*/
@customElement("ui5-test-component")
class TestComponent extends UI5Element {
```

<br />
<br />

## Enums
### Enum tags
| Tag | Description | Accepted types | Examples |
|---|---|---|---|
| `@public` / `@protected` / `@private` | Defines the privacy of the enum | boolean | `@public` <br /> `@protected` <br /> `@private` |
| `@since` | Defines the version when the enum was introduced | string | `@since` 1.2.0 |
| `@deprecated` | Defines whether the enum is deprecated | boolean \| string | `@depreaceted` <br /> `@deprecated` version 1.4.0 |
```ts
/**
* Enum description showcase
*
* @public
* @since 1.2.0
* @deprecated 1.4.0
*/
enum ShowcaseType {
Type1 = "Type1",
}
```

### Enum member tags
| Tag | Description | Accepted types | Examples |
|---|---|---|---|
| `@public` / `@protected` / `@private` | Defines the privacy of the enum member | boolean | `@public` <br /> `@protected` <br /> `@private` |
| `@since` | Defines the version when the enum member was introduced | string | `@since` 1.2.0 |
| `@deprecated` | Defines whether the enum member is deprecated | boolean \| string | `@depreaceted` <br /> `@deprecated` version 1.4.0 |
```ts

enum ShowcaseType {
/**
* Enum member description showcase
*
* @public
* @since 1.2.0
* @deprecated 1.4.0
*/
Type1 = "Type1",
}
```

<br />
<br />


## Interfaces
### Interface tags
| Tag | Description | Accepted types | Examples |
|---|---|---|---|
| `@public` / `@protected` / `@private` | Defines the privacy of the interface | boolean | `@public` <br /> `@protected` <br /> `@private` |
| `@since` | Defines the version when the interface was introduced | string | `@since` 1.2.0 |
| `@deprecated` | Defines whether the interface is deprecated | boolean \| string | `@depreaceted` <br /> `@deprecated` version 1.4.0 |
```ts
/**
* Interface description showcase
*
* @public
* @since 1.2.0
* @deprecated 1.4.0
*/
interface ShowcaseType {
property: string;
}
```