Stencil Elm Output Target

React in TypeScript is nice. Elm is very nice. If you're like us, you have a lot of both, and you need to build a sustainable component library for your design system. Web components to the rescue!

The problems with web components in React are well documented, but are also well solved by Stencil's React Output Target, which auto-generates a React component with TypeScript types for each of your web components, that manages the interop between React's events system and DOM events.

Web components in Elm have problems too:

• They provide no type-safe API out of the box
• Invoking methods on DOM nodes requires ports, which have friction
• Component properties must be serializable as JSON (e.g. no functions)

This package seeks to solve as many of these problems as possible, by generating an Elm module for each of your Stencil components, that defines a type-safe API to use it in your Elm programs.

So instead of using a stencil-button element like this:

view : Html Msg
view =
    Html.node "stencil-button"
        [ Html.Attributes.attribute "variant" "primary"
        , Html.Events.on "buttonClick" (Json.Decode.succeed ButtonClick)
        ]
        [ Html.text "Click me" ]

you can import Components.StencilButton and have the compiler guarantee that you're passing all the right attributes:

import Components.StencilButton as StencilButton

view : Html Msg
view =
    StencilButton.view
        { variant = Just StencilButton.Primary
        , onClick = Just ButtonClick
        }
        [ Html.text "Click me" ]

The StencilButton module here is automatically generated by Stencil when you build your component library.

Nice, right?

Configuration

To use the Elm output target, add this package to your Stencil project's dependencies, and then add it to your Stencil configuration file:

import { Config } from "@stencil/core";
import { elmOutputTarget } from "stencil-elm-output-target";

export const config: Config = {
  namespace: "stencil-components",
  outputTargets: [
    elmOutputTarget({
      excludeComponents: ["ignore-this-component"],
      proxiesModuleDir: "../stencil-in-elm/src/Components",
    }),
    {
      type: "dist",
    }
  ]
};

elmOutputTarget takes an object with two properties:

• excludeComponents: a list of components for which you do not want to generate Elm "wrapper" modules (e.g. if these are only used internally by other components)
• proxiesModuleDir: the path into which you want to write Elm modules. The final directory name in the path should be a valid Elm module name, since it is used as the namespace for all of your components. In the above example, a stencil-button component will generate a module named Components.StencilButton as a StencilButton.elm file in the Components directory. The parent directory (src in the above example) should be included in your elm.json files's source-directories.

Features

Not all possible web component APIs translate directly to Elm, and some mappings are impractical to generate automatically within the Stencil compiler.

We currently support the following @Prop types:

• boolean → Bool
• number → Int (get in touch if you need Float!)
• string → String
• "union" | "of" | "strings" → type PropName = Union | Of | Strings
• { foo: SupportedType; bar?: AnotherType; } → type alias = { … }
• Union | Of | Supported | Types → type PropName = PropName0 PropName0Value | … (caveat 1)
• SupportedType[] → List SupportedType (caveat 2)
• object or any otherwise unsupported type → Json.Encode.Value
• optional props → Maybe

We currently support custom DOM event emitters, but we do not yet permit access to the data value in the event object. (This is a relatively straightforward enhancement that we intend to make when we need it.)

Caveat 1: Constructor and type names for union types

Currently we generate pretty ugly generic names for the constructors and types of the members of a union type.

For example, for this prop:

  @Prop() primaryAction: PrimaryAction;

type PrimaryAction = ActionButton | ActionMenu;

type ActionButton = {
  …
}

type ActionMenu = {
  …
}

we currently don't use the names ActionButton and ActionMenu from the TypeScript source code to generate the Elm custom type constructors or their value types. Instead, we generate generic names based on the prop name (primaryAction):

type PrimaryAction
    = PrimaryAction0 PrimaryAction0Value
    | PrimaryAction1 PrimaryAction1Value

type alias PrimaryAction0Value =
    { …
    }

type alias PrimaryAction0Value =
    { …
    }

This is something we hope to improve later, as the Stencil compiler does give us access to the type names (ActionButton and ActionMenu in the above example). We just need to build the plumbing to consume them.

Caveat 2: Non-primitive array types

Currently arrays of primitive types (e.g. string[]) are translated perfectly to Elm (e.g. List String).

Unfortunately, due to an apparent bug/limitation of the Stencil compiler, or the TypeScript compiler upon which it depends, we are unable to get access to the details of named array types.

For example:

  @Prop() menuItems: MenuItem[];

type MenuItem = {
  …
}

We would like to expose this as a List MenuItem, along with a type alias MenuItem = { … }; however, the Stencil compiler only tells us the type is MenuItem[], and we have not yet found a way to get the details of MenuItem from the compiler.

Until we can fix this, we are forced to interpret all such types as Json.Encode.Value. In the above example, the prop's type in Elm is List Json.Encode.Value.

Get in touch!

If you're using this, or even thinking of using this, we'd love to hear from you!

Contact Kevin Yank on either the Stencil or Elm Slack communities, or @sentience via GitHub.