@xenabiz/xena-designsystem

Xena Design System

This project is part of the new strategy for further development of the current Xena UI.

It is Xena's Design System containing dumb components used in Xena's Classic UI. These components can be used in Vanilla HTML/Javascript and even most Javascript frameworks (Angular/Vue/React).

Environment	Website
Production	https://ds.xena.biz
Development	https://ds-dev.xena.biz
Locally	http://localhost:4000

Getting Started

To start building a new web component in this repository, clone this repo to a new directory:

git clone https://github.com/EG-BRS/Xena.DesignSystem.git
cd Xena.DesignSystem

and run:

npm install
npm start

To build the component for production, run:

npm run build

To run the unit tests for the components, run:

npm test

Usage in local development:

<link
  rel="stylesheet"
  href="http://localhost:4000/dist/xenads/xenads.css"
/>
<script
  type="module"
  src="http://localhost:4000/dist/xenads/xenads.esm.js"
></script>

Debugging tests in VSCode

Add this to .vscode/launch.json.

{
    "configurations": [
        {
            "type": "node",
            "request": "launch",
            "name": "E2E Test Current File",
            "cwd": "${workspaceFolder}",
            "program": "${workspaceFolder}/node_modules/.bin/stencil",
            "args": [
                "test",
                "--e2e",
                "--devtools",
                "${fileBasename}"
            ],
            "console": "integratedTerminal",
            "internalConsoleOptions": "neverOpen",
            "disableOptimisticBPs": true,
            "autoAttachChildProcesses": false,
            "windows": {
              "program": "${workspaceFolder}/node_modules/@stencil/core/bin/stencil"
            }
        },
        {
            "type": "node",
            "request": "launch",
            "name": "Spec Test Current File",
            "cwd": "${workspaceFolder}",
            "program": "${workspaceFolder}/node_modules/.bin/stencil",
            "args": [
                "test",
                "--spec",
                "${fileBasename}"
            ],
            "console": "integratedTerminal",
            "internalConsoleOptions": "neverOpen",
            "disableOptimisticBPs": true,
            "windows": {
              "program": "${workspaceFolder}/node_modules/@stencil/core/bin/stencil"
            }
        }
    ]
}

This will make it possible to run and debug tests inside VSCode.

Creating Components

When you want to create a new component you have to 1) create the component and 2) document the component. This is how you do both.

Create component.

Start by creating a folder under src/components. Give the folder the name of you component, fx. my-component. In the folder you add a tsx file with the name of your component fx. my-component.tsx.

Add this basic component class to the file (again, name it with the name you like for your component instead of MyComponent):

import { Component, h, Prop } from '@stencil/core';

/**
 * @since 1.0
 * @status stable
 *
 * @slot - The componments's content.
 *
 * @part base - The component's base wrapper.
 *
 */
@Component({
  tag: 'xena-my-component',
  shadow: true
})
export class MyComponent {

  render() {
    return (
      <div part="base">
        <slot />
      </div>
    );
  }
}

Lets walk through the details of this basic component.

Metadata

At the beginning of the class you'll notice some JSDoc information. This is not required for the component to function, but it is required in order to document the component later on. The different tags are described in the table below.

Tag	Description
@since	The version of the design system in which this component was introduced.
@status	The status of the component. stable, experimental, planned or deprecated.
@slot	An HTML slot for inserting an HTML element into the component.
@part	An HTML part within the shadow dom, referenceable from CSS outside of the shadow dom.

@Component

The @Component annotation is a Stencil annotation that describes to Stencil the technical details about this component. The tag property defines the tag this component will be exposed as (must always be prefixed with 'xena-'). The shadow property defines whether this component should be contained in a shadow dom - which in this project should be true for all components.

render()

The render() method is the heart of this component. This method will render the HTML. It will run every time the state of the component changes. In our test component the state never changes, so it will only render once, but more complex components will have changes to their state and then this method would run at every state change.

In order to know more about how to develop your component, please turn to the StencilJs Documentation.

Document your component

In order to add your component to the documentation, you need to create a markdown file in docs/components. Name it after your component fx. my-component.md. The add the following basic documentation.

# MyComponent

[component-header:xena-my-component]

MyComponent can be used anywhere you like.

```html preview
<xena-my-component></xena-my-component>
```

[component-metadata:xena-my-cmmponent]

Lets go through what the different elements does. But please remember to elaborate more on your component and add more examples to the documentation.

[component-header:xena-my-component]

The component-header tag adds the primary metadata from the component to the top of the page. That includes the name, the version it was introduced and the current status of the component.

html preview

When adding a codeblock of the type html preview an example of the component will be shown, along with the HTML you enter as an example. This makes it easy for the reader to see what the component looks like and how to use it in HTML.

[component-metadata:xena-my-cmmponent]

This part adds the secondary metadata from the component. This consists of slots, parts, properties and more.

Now the only thing lacking is a reference to this in the menu of the documentation site. Edit docs/_sidebar.md and add a reference to your component. Now your component is ready to roll!