Forem: Rúnar Berg Baugsson Sigríðarson

: Adding The Dropdown Feature

Rúnar Berg Baugsson Sigríðarson — Tue, 30 Mar 2021 00:32:45 +0000

A dropdown menu is really just a menu inside a non-modal dialog. So
lets create our dialog wrapper (like before select CSS and skip spec
and E2E tests):

npm run generate my-dialog

Lets be wishful and wrap our menu inside it (as if it was ready
already):

// src/components/my-menu/my-menu.tsx

@Component(/* ... */)
export class MyMenu implements ComponentInterface {
  // ...

  render() {
    return (
      <Host>
        <slot></slot>

        <my-dialog>
          <slot slot="activator" name="label">
            Actions
          </slot>

          <menu>
            {this.items.map((_, i) => (
              <li>
                <slot name={`item-${i}`}></slot>
              </li>
            ))}
          </menu>
        </my-dialog>
      </Host>
    );
  }
}

So <my-dialog> should have an activator slot—where we will place
our label for toggling the menu—and a main slot for the dialog
body—where we will place the menu it self.

Event Handling

Lets create the <my-dialog> component:

npm run generate my-dialog
# Select CSS, unselect spec and E2E

And edit src/components/my-dialog/my-dialog.tsx like this:

import { Component, ComponentInterface, Host, Prop, h } from "@stencil/core";

@Component({
  tag: "my-dialog",
  styleUrl: "my-dialog.css",
  shadow: true,
})
export class MyDialog implements ComponentInterface {
  @Prop({ reflect: true, mutable: true }) open: boolean = false;

  render() {
    return (
      <Host>
        {/* Add a button with a click listener */}
        <my-button
          onClick={() => {
            this.open = !this.open;
          }}
        >
          <slot name="activator">Activate</slot>
        </my-button>

        <dialog open={this.open}>
          <slot></slot>
        </dialog>
      </Host>
    );
  }
}

The <dialog> element has mixed support between browsers so lets add
some styles in src/components/my-dialog/my-dialog.css now to make it
consistent:

:host {
  position: relative;
}

dialog {
  border: 1px solid thistle;
  border-radius: 1ex;
  display: none;
  inline-size: max-content;
  inset-block-start: calc(100% + 5px);
  inset-inline-end: auto;
  inset-inline-start: 0;
  padding: 0;
  position: absolute;
}

dialog[open] {
  display: block;
}

Notice in the tsx file that the activator button has an onClick
attribute that mutates this.open. This is one way to attach an event
listener. When we click the activator button on our demo page the
function inside the handler will run. Another way is with the
@Listen decorator, lets use that one closes the
dialog when the user hits Esc, and another that closes when
the user clicks outside the menu:

// src/components/my-dialog/my-dialog.tsx

import { Element, Listen /* ... */ } from "@stencil/core";

@Component(/* ... */)
export class MyDialog implements ComponentInterface {
  @Element() el: HTMLElement;

  // ...

  @Listen("keydown", { target: "window" })
  handleKeyDown(event: KeyboardEvent) {
    if (event.key === "Escape") {
      this.open = false;
    }
  }

  @Listen("click", { target: "window" })
  handleWindowClick(event: MouseEvent) {
    // Only close if we click outside the shadow root
    if (!event.composedPath().includes(this.el.shadowRoot)) {
      this.open = false;
    }
  }

  // ...
}

Emitting Events

Say we want to add an icon at the end of the toggle button that points
down when the menu is collapsed, and up when it is expanded. I guess
<my-dialog> will need to tell <my-menu> when it opens or closes.
We can do that with the @Event decorated method
that we’ll fire inside a @Watch decorated method.
Let’s add these to src/components/my-dialog/my-dialog.tsx:

import { Event, EventEmitter, Watch /* ... */ } from "@stencil/core";

@Component(/* ... */)
export class MyDialog implements ComponentInterface {
  // ...

  @Watch("open")
  openChangedHandler(open: boolean) {
    this.openChanged.emit({ open });
  }

  @Event() openChanged: EventEmitter;

  // ...
}

Now listen for this event on the menu in
src/components/my-menu/my-menu.tsx:

@Component(/* ... */)
export class MyMenu implements ComponentInterface {
  // ...

  @State() open = false;

  private handleToggle(event: CustomEvent) {
    this.open = event.detail.open;
  }

  render() {
    return (
      <Host>
        {/* ... */}

        <my-dialog onOpenChanged={(event) => this.handleToggle(event)}>
          <slot slot="activator" name="label">
            Actions
            <svg
              viewBox="0 0 100 66"
              aria-label={this.open ? "Expanded" : "Collapsed"}
            >
              <polygon
                points={
                  this.open ? "0 66.6, 100 66.6, 50 0" : "0 0, 100 0, 50 66.6"
                }
              />
            </svg>
          </slot>

          {/* ... */}
        </my-dialog>
      </Host>
    );
  }
}

And add some styles:

// src/components/my-menu/my-menu.css

/* ... */

slot[name="label"] {
  align-items: center;
  display: flex;
}

slot[name="label"] svg {
  fill: currentcolor;
  block-size: 1em;
  inline-size: 0.666em;
  margin-inline-start: 1ex;
}

And there we have it: A simple dropdown menu component written in
Stencil.

: A More Involved Stencil Component

Rúnar Berg Baugsson Sigríðarson — Tue, 30 Mar 2021 00:32:35 +0000

Next up are the menu components. These are actually two components,
<my-menu> and <my-menu-item>. You will see why we need two
seperate components in a bit. Let’s scaffold them just like we did
with the button (we will only need CSS for my-menu).

npm run generate my-menu-item
# Uncheck CSS, spec, and E2E

npm run generate my-menu
# Keep CSS, but uncheck spec and E2E

We don’t need to touch my-menu-item for now, so lets concentrate on
my-menu for a bit. We know we want to add a <menu> there somewhere
in the render method. But then we hit a snag, how can we express each
child <my-menu-item> as an item of that menu:

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

@Component({
  tag: 'my-menu',
  styleUrl: 'my-menu.css',
  shadow: true,
})
export class MyMenu implements ComponentInterface {
  render() {
    return (
      <Host>
        <menu>
          <li>
            <!-- XXX: All children are inside one `<li>` -->
            <slot></slot>
          </li>
        </menu>
      </Host>
    );
  }
}

We will need to collect all the menu-items into an array so we can map
the contents (now you see why we created that component earlier).
Enter the @State decorator.

Managing Internal State

Stencil has a few lifecycle methods. For now
let’s concern us with the componentWillLoad which fires after the
component is first connected to the DOM. We can use that to collect
the contents of the host. We also need access to component element it
self to find all the child <my-menu-item>s. For that we use the
@Element decorator:

import {
  Component,
  ComponentInterface,
  Element,
  Host,
  State,
  h,
} from "@stencil/core";

@Component({
  tag: "my-menu",
  styleUrl: "my-menu.css",
  shadow: true,
})
export class MyMenu implements ComponentInterface {
  // This will be our host element.
  @Element() el: HTMLElement;

  @State() items: HTMLMyMenuItemElement[] = [];

  // This will fire once after the component is connected.
  componentWillLoad() {
    // Collect all `<my-menu-item>`s into an array.
    this.items = Array.from(this.el.querySelectorAll("my-menu-item"));
  }

  render() {
    return (
      <Host>
        <menu>
          {this.items.map((item) => (
            <li>{item.textContent}</li>
          ))}
        </menu>
      </Host>
    );
  }
}

This is an improvement, but now we lost our buttons. Notice how we’ve
swapped the <slot> for this.items.map; and how the mapping
function only returns the text content of each element. Thats a
problem. We somehow need to keep a slot for each found menu item and
assign it to that item specifically. Lucky for us, slots can be named,
and if we add a slot attribute with a matching value of
a named slot, it will be added to that slot. For example:

<template>
  <em><slot name="em"></slot></em>
  <strong><slot name="strong"></slot></strong>
</template>
<span slot="strong">
  This will go to the “strong” slot above
</span>
<span slot="em">
  This will go to the “em” slot above
</span>

In our demo we can dynamically add as many slot as we need in our
render function; each with a specific name. We can then manipulate the
slot attribute of each found <my-menu-item> element to match a
specific named slot. So in essence:

import {
  Component,
  ComponentInterface,
  Element,
  Host,
  State,
  h,
} from "@stencil/core";

@Component({
  tag: "my-menu",
  styleUrl: "my-menu.css",
  shadow: true,
})
export class MyMenu implements ComponentInterface {
  @Element() el: HTMLElement;

  @State() items: HTMLMyMenuItemElement[] = [];

  componentWillLoad() {
    this.items = Array.from(this.el.querySelectorAll("my-menu-item"));
    this.items.forEach((item, i) => {
      item.slot = `item-${i}`;
    });
  }

  render() {
    return (
      <Host>
        <menu>
          {this.items.map((_, i) => (
            <li>
              <slot name={`item-${i}`}></slot>
            </li>
          ))}
        </menu>
      </Host>
    );
  }
}

Bingo! But there is a problem. If the consumer changes the slot (say
adds a menu item) after it connected the custom element to the DOM, we
won’t have a slot for it. Or if it removes an item, we are stuck with
an extra list item. I’ll leave it as an exercise to recreate the
bug. But to fix it we’ll re-intruduce the main <slot> and attach a
[slotchange event] listener, which will fire whenever one of our
slots changes.

import {
  Component,
  ComponentInterface,
  Element,
  Host,
  State,
  h,
} from "@stencil/core";

@Component({
  tag: "my-menu",
  styleUrl: "my-menu.css",
  shadow: true,
})
export class MyMenu implements ComponentInterface {
  @Element() el: HTMLElement;

  @State() items: HTMLMyMenuItemElement[] = [];

  componentWillLoad() {
    this.el.shadowRoot.addEventListener("slotchange", () => {
      this.items = Array.from(this.el.querySelectorAll("my-menu-item"));
      this.items.forEach((item, i) => {
        item.slot = `item-${i}`;
      });
    });
  }

  render() {
    return (
      <Host>
        <slot></slot>
        <menu>
          {this.items.map((_, i) => (
            <li>
              <slot name={`item-${i}`}></slot>
            </li>
          ))}
        </menu>
      </Host>
    );
  }
}

Now that we have our menu we can style it in my-menu.css.

Styling (Part 2)

Buttons inside the menu should look differently then normal
buttons. In particular the borders are visually distructive so we must
get rid of them. Lets try to do that in my-menu.css:

/* src/components/my-menu/my-menu.css */

menu {
  list-style: none;
  padding: 0;
  margin: 0;
}

my-button {
  /* This won’t work */
  border: none;
}

This fixed the menu style, but the borders are still there, why? Turns
out that we put the borders on the child button element inside the
shadow DOM, and styles inside the shadow DOM are isolated from style
rules defined outside of it. So even if we’d select my-button button
it still wouldn’t work. What can we do?

Shadow Parts

We saw when we styled the button previously that CSS custom properties
can penetrate the shadow barrier, so we could define the border in
my-button.css with:

/* src/components/my-button/my-button.css */

:host {
  --border-width: var(--button-border-width, 2px);
}

button {
  border-color: var(--color);
  border-style: solid;
  border-width: var(--border-width);
}

But there is another way. Authors can also mark parts of the structure
as available for styling using the part attribute. In a
stylesheet consumer can then access the part using the ::part
pseudo-element. So lets try that.

First add the part attribute to our button in my-button.tsx, lets
name it intuitively “button”:

// src/components/my-button/my-button.tsx

@Component(/* ... */)
export class MyButton implements ComponentInterface {
  // ...

  render() {
    // ...

    return (
      <Host>
        <button
          class={classMap}
          type={this.type}
          disabled={this.disabled}
          part="button"
        >
          <slot></slot>
        </button>
      </Host>
    );
  }
}

Now lets try to access it in my-menu.css:

/* src/components/my-menu/my-menu.css */

/* ... */

my-button::part(button) {
  /* This still won’t work */
  border: none;
}

This still won’t work because my-menu isn’t actually the consumer of
the my-button component. We have to go all the way back to
index.html to find the real consumer. So we need to export something
like a global stylesheet that the users of our component library can
import. So let’s to that.

Global Stylesheets

Stencil provides a way to export global styles. First
let’s create the stylesheet in src/global/style.css:

my-menu my-menu-item my-button::part(button) {
  border: none;
}

Then add this file to the globalStyle field in stencil.config.ts.

export const config: Config = {
  // ...
  globalStyle: "src/global/style.css",
};

Finally import it in your src/index.html:

<head>
  <!-- ... -->
  <link rel="stylesheet" href="/build/my-components.css" />
</head>

Now restart the stencil server, refresh the page and see your
borderless menu buttons.

: My First Stencil Component

Rúnar Berg Baugsson Sigríðarson — Tue, 30 Mar 2021 00:32:14 +0000

We are going to start with the simplest of the three components
<my-button>. Honestly it might be an overkill writing this out as a
component as it will be a simple styled wrapper around the native
<button>. But the purpose here is to get you acquainted with Stencil
before we write out more involved components:

We can get the component scaffolded by writing in our terminal:

npm run generate my-button

The Stencil tool will ask you if you want to create a stylesheet, spec
tests, and E2E tests for your component as well. We’re not focising on
automated tests for this tutorial, so you can uncheck the E2E and spec
test options. Leave the stylesheet option checked though, we’ll use it
later:

> my-components@0.0.1 generate /home/username/dropdown-menu
> stencil generate "my-button"

? Which additional files do you want to generate? ›
Instructions:
    ↑/↓: Highlight option
    ←/→/[space]: Toggle selection
    a: Toggle all
    enter/return: Complete answer
◉   Stylesheet (.css)
◯   Spec Test  (.spec.tsx)
◯   E2E Test (.e2e.ts)

Open the newly created src/components/my-button.tsx. You will see it
contains a few imports from the @stencil/core and an exported class
decorated with @Component. You’ll also notice that the class
contains a single render method.

Now let’s start the development server again:

npm run start

Let’s make the <my-button> elements actual buttons. So dig into the
render method and wrap a <button> around the <slot>.

import { Component, ComponentInterface, Host, h } from "@stencil/core";

@Component({
  tag: "my-button",
  styleUrl: "my-button.css",
  shadow: true,
})
export class MyButton implements ComponentInterface {
  render() {
    return (
      <Host>
        <button>
          <slot></slot>
        </button>
      </Host>
    );
  }
}

Refresh your browser window and see we now have buttons.

There are a few takeaways here. First is the <slot>
element we put inside the <button>. Slots let
consumers write their own markup inside our component. Notice how our
consumer in src/index.html says:

<my-button>Action 1</my-button>

Well… Our <slot> will be replaced by the text “Action 1”. Slots can
include custom markup as well, meaning if a consumer writes:

<my-button>
  <strong>Warning</strong>
  This is <em>dangerous</em>!
</my-button>

The correct parts will by strong and emphasized. Go ahead and try it!

The next new takeaway here is the <Host> element.
This is a functional component provided by Stencil. We can use it to
set attributes and listeners to the host element (in our case
<my-button>). We’re not really using it for anything now but it does
us no harm to leave it standing.

Thirdly is the render method. This method—as the name
suggests—renders our component to the DOM tree. We can think of it as
the means to keep our component in sync with all the state we provide
to it. We can pass conditionals, loops, or reactive data inside it and
it will render the component to match whatever the state is at any
time.

And Finally we have the @Component decorator.
This will tell the Stencil compiler to create a web component out of
this class. We provide this decorator with a tag name my-button, and
optionally with a path to a stylesheet (which we’ll be using in a
moment). The shadow: true part makes sure our component is isolated
from the rest of the DOM tree. If we set it to false we risk global
styles bleeding into our component, or an ID collision with a
different element on the page.

Styling the Button

Phew! Now lets do something more fun. Open my-button.css and make
our button a lot prettier. Notice the default style says:

:host {
  display: block;
}

The :host pseudo-class refers to the
my-button element it self (the host). We don’t really care how it is
displayed, so lets remove the display rule. But the :host block is
handy for defining our custom properties (or CSS
variables).

:host {
  --background: var(--button-background, ivory);
  --background-hover: var(--button-background-hover, gold);
  --color: var(--button-color, rebeccapurple);
}

button {
  background: var(--background);
  border: 2px solid currentcolor;
  border-radius: 1ex;
  color: var(--color);
  cursor: pointer;
  padding: 0.5ex 1em;
}

button:hover {
  --background: var(--background-hover);
}

Refresh the page and now our buttons look much nicer.

Notice how we define our custom properties in terms of other custom
properties:

--color: var(--button-color, rebeccapurple);

This is so a parent can set the --button-color and it will overwrite
our default value (rebeccapurple). Unlike other styles custom
properties will cascade down into the shadow dom.

You can try it by opening the style inspector in your browser’s
developer tools and adding a rule to you root html element:

--button-color: firebrick;

Passing Properties

Sometimes buttons can be disabled. Say that an action is not allowed
at the moment then disabling the button will prevent user frustration
when they click the button and nothing happens. Lets disable the last
button in the demo menu (index.html).

<!-- src/index.html -->

<my-menu>
  <!-- ... -->
  <my-menu-item>
    <my-button disabled>Action 3</my-button>
  </my-menu-item>
</my-menu>

Uh-oh! We can still click it, what’s wrong? It turns out that we
neglected to define what happens when our custom button has any
attributes. We can fix that by importing the @Prop
decorator and adding it to our class.

First lets add some styles so we can better tell when we have
succeeded our mission:

/* src/components/my-button/my-button.css */

:host {
  /* ... */
  --background-disabled: var(--button-background-disabled, ivory);
  --color-disabled: var(--button-color-disabled, thistle);
}

/* ... */

button:disabled {
  --background: var(--background-disabled);
  --color: var(--color-disabled);

  cursor: not-allowed;
}

Next we must import the @Prop decorator from @stencil/core which
we use to decorate a new boolean property in our class named
disabled. We’ll then use this new property to conditionally set the
disabled attribute on the child button in the render function:

// src/components/my-button/my-button.tsx

import { Prop /* ... */ } from "@stencil/core";

@Component(/* ... */)
export class MyButton implements ComponentInterface {
  // Setting reflect to true, adds the attribute on the host
  // element (`<my-button>`) as well.
  @Prop({ reflect: true }) disabled: boolean;

  render() {
    return (
      <Host>
        <button disabled={this.disabled}>
          <slot></slot>
        </button>
      </Host>
    );
  }
}

Mirroring a string attribute is similar. This time type which
defaults to submit:

export class MyButton implements ComponentInterface {
  @Prop({ reflect: true }) disabled: boolean;
  @Prop({ reflect: true }) type: "button" | "reset" | "submit" = "submit";

  render() {
    return (
      <Host>
        <button disabled={this.disabled} type={this.type}>
          <slot></slot>
        </button>
      </Host>
    );
  }
}

Lets add one more property weight which allows us to control the
visual weight of the button (slim, normal, or strong):

export class MyButton implements ComponentInterface {
  @Prop({ reflect: true }) disabled: boolean;
  @Prop({ reflect: true }) type: "button" | "reset" | "submit" = "submit";
  @Prop() weight: "slim" | "normal" | "strong" = "normal";

  render() {
    const classMap = {
      "weight-slim": this.weight === "slim",
      "weight-normal": this.weight === "normal",
      "weight-strong": this.weight === "strong",
    };

    return (
      <Host>
        <button class={classMap} disabled={this.disabled} type={this.type}>
          <slot></slot>
        </button>
      </Host>
    );
  }
}

/* src/components/my-button/my-button.css */

/* ... */

button.weight-slim {
  border: none;
  background: transparent;
  padding: 0;
  text-decoration: underline;
}

button.weight-strong {
  background: var(--color);
  border-color: var(--color);
  color: white;
}

Feel free to alter the attributes your <my-button>s in
src/index.html to test out these new properties.

Write A Custom Dropdown Menu With Stencil

Rúnar Berg Baugsson Sigríðarson — Tue, 30 Mar 2021 00:31:24 +0000

Our goal for this tutorial is to write a custom dropdown menu in
Stencil that compiles to a custom element <my-menu>
where consumers can write something like:

<my-menu>
  <my-menu-item>
    <my-button>Action 1</my-button>
  </my-menu-item>

  <my-menu-item>
    <my-button>Action 2</my-button>
  </my-menu-item>

  <my-menu-item>
    <my-button>Action 3</my-button>
  </my-menu-item>
</my-menu>

By the end of this tutorial you should have some basic understanding
of how to create basic web components using Stencil, as well as give
you the foundational understanding of web components needed for the
task.

This tutorial will not go into detail for every feature that Stencil
provides, nor will it try to give you complete understanding of web
components. Refer to the Stencil docs for the former,
and MDN for the latter.

Kickstart the Project

We begin our project by writing:

npm init stencil component my-components

This pulls the Stencil starter pack and tells it to start a new
component library called my-component. It will also create basic
Hello, World! component under src/components/my-component. You can
see it in action by typing:

npm start

This will open up a browser window in http://localhost:3333 showing
your component in action.

If you open src/index.html you will see how this component is consumed:

<!DOCTYPE html>
<html>
  <!-- ... -->

  <body>
    <my-component
      first="Stencil"
      last="'Don't call me a framework' JS"
    ></my-component>
  </body>
</html>

We are going to write our goal structure there now and worry about
implementing each component later. So go ahead and add this to the
body of the HTML file:

<!-- src/index.html -->

<!-- ... -->

<body>
  <my-menu>
    <my-menu-item>
      <my-button>Action 1</my-button>
    </my-menu-item>

    <my-menu-item>
      <my-button>Action 2</my-button>
    </my-menu-item>

    <my-menu-item>
      <my-button>Action 3</my-button>
    </my-menu-item>
  </my-menu>
</body>

You can also go ahead and delete the src/components/my-component
directory as well as src/utils, we won’t be needing these during
this tutorial.