Skip to content

developing-components.md

Latest commit

 

History

History
80 lines (52 loc) · 5.19 KB

developing-components.md

File metadata and controls

80 lines (52 loc) · 5.19 KB
Raw

Developing Components

We follow the Stencil Style Guide for naming and code style conventions. Please read through it.

Some important guidelines are:

  • Create a separate directory for each component. The directories name should be the same as the elements Custom Element name (ino-component-name).
  • Each component consists at least of the files .tsx and .scss. The name of the files are the same as the Custom Element name.
  • The readme.md is auto-generated by Stencil.
  • Your commit message will be linted as soon as you open a new Pull Request. Make sure to follow conventional commits.

Stateless / Controlled / Dumb Components

We decided to use stateless components to provide a top to bottom data flow. This makes sense as most of the frameworks do a DOM diffing and do not see what a component itself is doing. Hence, instead of changing the state directly, we always emit events to denote that something should change. Thus, if the consumer ignores such an event, nothing will happen.

  • Only the attributes and children with their attributes describe the current state of the component.
  • The state never changes as long as the input properties are the same.
  • The component never modifies its host attributes.
  • User actions (clicks, key events, ...) only trigger events. The state remains untouched.

For examples and details please refer to the Events section below.

Properties

For each property, we provide a short jsdoc when defining a property. This comment should contain a short and precise description of the property's functionality. Take some time when writing this description, since it will be used as a references by other developers.

Events

We differentiate between native and Custom Events. Native events are triggered by native HTML elements like <input> and bubble out of the scope automatically. For example, the <button> element uses a HTMLButtonElement internally that emits click events. Custom Events are our way to inform the consumer about internal changes. Every time we provide a Custom Event for a component we always set their action in present tense.

Here are some examples to make the naming easier for you:

Example 1: The ino-input Component

  • Input: value (Attribute, @Prop())
  • Output: valueChange (Custom Event, @Event())

The name of the input param value is contained in the name of the event param valueChange to denote the relation between them. In this example, this means that if the value should change, the consumer decides if the value should change or not. Speaking for the ino-input: If the user types any key into the input field, the component will not change the value, but will instead emit an event that says:

Hey consumer, the value should change. Here is the value. But you decide if you want to change the value. You can set the @Input value with the value I gave you, then I will update my value. If you do not update the value, I will not update the value und the old value remains the same.

Custom Properties (a.k.a. CSS-Variables)

Custom properties allow us to provide a CSS interface to style our components. These custom properties are declared on the component side and can then be used at runtime.

For instance, to give the <ino-button> a custom property, the following snippet is all you need:

/**
    * @prop --my-background-color: Some description about the variable
   */
ino-button button {
  background-color: var(--my-background-color, #fff); // the #fff is the fallback value
}

Stencil will automatically put the name of the variable and its description into the docs.

Testing

All of our components should be tested to ensure correct functionality. The following two types of tests should be present if possible.

Type Description Frameworks
Unit (spec) Unit tests focus on testing a component's methods in isolation. For example, when a method is given the argument X, it should return Y. Jest
End-To-End (e2e) End-to-end tests focus on how the components are rendered in the DOM and how the individual components work together. For example, when my-component has the X attribute, the child component then renders the text Y, and expects to receive the event Z. Jest, Puppeteer

Documentation

Stencil generates a readme.md for each component which consists of two parts:

  • An editable header.
  • An auto-generated documentation of attributes and properties as a table.

We extend the generated docs by adding more information of how to use the component in the header section.