Skip to content

Latest commit

 

History

History
228 lines (156 loc) · 8.04 KB

0.1.md

File metadata and controls

228 lines (156 loc) · 8.04 KB
Raw

The Typed Web Components Specification

The Typed Web Components Specification is a proposal for standarization on typing the public interface exposed by Web Components.

Version 0.1

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 RFC2119 RFC8174 when, and only when, they appear in all capitals, as shown here.

This document is licensed under The Apache License, Version 2.0.

Introduction

The Typed Web Component Specification (or TWC) is a proposal for adding optional type information to Web Components. This extra information will enhance the design-time, tooling-based experience for Web Component consumers.

Table of Contents

  • Definitions
    • Components
    • Properties
    • Methods
    • Events
  • Type information
  • Specification
  • Primitive types supported
  • Types in Typescript
  • Types in Flow
  • Types in JavaScript
  • License

Defintion

Component

In this document a Web Component as defined by the W3C will be refered as a component. Component expose a well-known class with a signature of:

  • attributes
  • methods, and
  • events

A component itself belongs to a specific type as the union of the types of the previous elements.

Inheritance between components at the implementation level are an option for the implementer, but a totally hidden implementation detail for the consumer: a consumer does not need to know implementation details about the implementation.

Example

<label>Select</label>
<acme-calendar></acme-calendar>

In the previous HTML markup, acme-calendar references a local name for a web component.

Attribute

Web Components define a mechanism for passing out-side world data into the component: the attributes.

In this proposal, the recommendation is to enforce a unique (inmutable design-time) type for each attribute. This auto-imposed constrain enables strong possibilities for tool design expericences.

Example

<label>Select</label>
<acme-calendar year="2018", month="11", show-weekends="true" title="Calendar">
</acme-calendar>

In the example year, month, show-weekends and title are attributes for the acme-calendar component. Using the current W3C specification we cannot know before-hand the property names and supported types. No standard reflection mechanism is provided to deliver such information.

A consumer can guest the types examining the example provided as:

Attribute Infered type
year integer
month integer [1..12]
show-weekends boolean
title string

But such suppositions can only be finally confirmed or discarded looking at the implementation source code and finding surprises like:

  • Months are zero-index in range [0..11]
  • Show Weekend is implemented as an string and not a boolean.
  • Year is mandatory
  • Month is optional

Method

In the same way, as attributes, components expose methods to execute behavior. These methods are just operations implemented as public functions inside the component class.

Such methods have a signature of received parameters and a return type.

Example

<div>
  <acme-video id="v1"></acme-video>
</div>
const video = document.select('#v1');
const result = video.play('sound.mp3', 15, 20, false);

In the sample, video is a reference to a web component used to reproduce video. The play method has the following signature:

Parameter Type Description
url string URL to resource to reproduce.
startAtSecond float Time position to start video reproduction.
endAtSecond float Time position to end video reproduction.
loop boolean Loop reproduction: true/false.
Return type Description
boolean True if reproduction can start, false if error.

Events

Events are the standard way an element in HTML can trigger messages for other to listen. Web components have this capability too. Therefore these messages also need type information to be fully described for a consumer to use it properly.

Example

<acme-calendar on-date-selected="dateSelected()"
               on-close="close()"
               on-next-month="nextMonth()"
>
</acme-calendar>

The previous example binds thre component events to JavaScript function handlers.

As any other standard HTML elemeent event, these events can provided an object (a message) as payload with extra information produced during the event.

In the first and second example, on-date-seleted and on-close, the payload could be:

Property Type Description
date date Selected date.

In the last one, on-next-month, the payload could be:

Property Type Description
oldMonth integer Previous month.
newMonth integer New current month.

Type Information

Signature and type information is useful independiently of the language used by the consumer (typed of not). An editor or IDE can use this information to assist the user on design-time.

Therefore, type information must be exposed in a way it is language-neutral way to encourage interoperability.

Primitive Data Types

For simplicity, supported primitives types are taken granted from the OpenAPI Specification and this spec is based on JSON Schema Specification. The following table applies:

Type Format Comments
integer int32 signed 32 bits
integer int64 signed 64 bits (a.k.a long)
number float
number double
string
string byte base64 encoded characters
string binary any sequence of octets
boolean
string date As defined by full-date - RFC3339
string date-time As defined by date-time - RFC3339
string password A hint to UIs to obscure input.

Composed Data Types

Complex data types must be specified using JSON Schema [3], arrays and Primite Data Types.

This mechanims provides a fully typed information able to decorate type's attributes, method signatures and event payloads.

Schema

The following section describes the normative schema for an information object contaning type-information for a web component. Document can be either represented using JSON or YAML.

TypedWebComponent Object

This is the root document object of the Typed Web Component document.

Field Name Type Description
typedwebcomponents string REQUIRED. Version of the Typed Web Components used in this document.
components [Component Object] Array of web components to be described.

Component Object

The component object describes types and optionally document a Web Component.

Field Name Type Description
name string REQUIRED. Name of the component.
source url URL where the component can be imported from.
externalDoc url URL where to obtain additional documentation for the component.
description string Documentation about the web component.
license string License for the component.
version string REQUIRED. Version number for the component. SemVer is recommended.
attributes [AttributeObject] Array of attributes exposed by the web component.
methods [MethodObject] Array of methods exposed by the web component.
events [EventObject] Array of events exposed by the web component.

Attribute Object

Method Object

Event Object

Samples

  1. Typed Calendar

References

  1. W3C Web Components.
  2. Open API Spec
  3. JSON Schema

License

The full specification is licensed under the Apache 2.0 Licence.