DEV Community: Luiz Américo

TIL: How to reference the item type of an array type?

Luiz Américo — Sun, 30 Mar 2025 14:40:06 +0000

I have one array type and needed to use the type of its item

Directly from AI (Sonnet 3.7)

In TypeScript, you can reference the type of an item in an array type in several ways:

Method 1: Use indexed access type

type Messages = {
  date: Date;
  content: string;
  userId: string;
  userName: string;
}[]

type MessageItem = Messages[number];

The number index accesses the type of elements in the array.

Method 2: Define the item type separately first

type MessageItem = {
  date: Date;
  content: string;
  userId: string;
  userName: string;
};

type Messages = MessageItem[];

This approach is often clearer, especially if you need to reuse the item type elsewhere in your code.

Method 3: Use `ArrayType<T>` utility type (custom)

You can also create a utility type if you need to do this frequently:

type ArrayItem<T> = T extends Array<infer U> ? U : never;

type Messages = {
  date: Date;
  content: string;
  userId: string;
  userName: string;
}[]

type MessageItem = ArrayItem<Messages>;

The first method (Messages[number]) is the most direct and commonly used approach to extract the item type from an array type.

Adding copy code feature to code blocks in Astro

Luiz Américo — Sun, 18 Aug 2024 00:00:00 +0000

I was looking for a way to add a copy code feature to code blocks in my blog, built with Astro. A google search led me to a few articles. The first four suggested home made solutions. The fifth was not exactly an article on how to add the feature but a Astro development discussion that quoted, in passing, the package used by Starlight.

That's it, to add a copy code feature to your code blocks in Astro, just install astro-expressive-code:

yarn astro add astro-expressive-code

# or

npx astro add astro-expressive-code

Besides code copying, the package also provides other features.

WhatsApp webhook API types

Luiz Américo — Sun, 18 Aug 2024 00:00:00 +0000

The (Missing) WhatsApp webhook API types

I am working on a project that involves integrating with the WhatsApp Business API, and I noticed that there are no official TypeScript types for the webhook API. The documentation while detailed, lacks (or i could not find) the type definitions that would make it easier to work with the API in a type-safe manner.

So, I decided to create my own minimal set of types to help me with the integration.

Reverse engineering the webhook payload

The process was pretty simple: 1 - In my app webhook endpoint, i saved the received payloads to a database 2 - From this sample i created the types using a JSON to TypeScript converter 3 - I then refined the types to make them more readable and easier to work with.

Some notes:

The types are not exhaustive, they only cover the message types that I needed for my project i.e, 'messages' and 'message_template_status_update'.
My go to JSON to Typescript converter was from Transform.Tools which is based on json_typegen. But is lacking creation of enum / union types from fields with repeatable values. Fortunately i found quicktype that supports this feature.

The types

export interface NotificationPayload {
  object: "whatsapp_business_account";
  entry: Entry[];
}

export interface Entry {
  id: string;
  changes: Change[];
}

export type Change = MessagesChange | MessageTemplateStatusUpdateChange;

export interface MessagesChange {
  field: "messages";
  value: MessagesValue;
}

export interface MessageTemplateStatusUpdateChange {
  field: "message_template_status_update";
  value: MessageTemplateStatusUpdateValue;
}

export interface MessageTemplateStatusUpdateValue {
  reason: string;
  message_template_name: string;
  event: string;
  message_template_language: string;
  message_template_id: number;
}

export interface MessagesValue {
  metadata: Metadata;
  messaging_product: MessagingProduct;
  statuses?: StatusElement[];
  messages?: Message[];
  contacts?: Contact[];
}

export interface Contact {
  profile: Profile;
  wa_id: string;
}

export interface Profile {
  name: string;
}

export interface Message {
  from: string;
  id: string;
  text?: Text;
  type: string;
  timestamp: string;
  sticker?: Sticker;
}

export interface Sticker {
  sha256: string;
  mime_type: string;
  animated: boolean;
  id: string;
}

export interface Text {
  body: string;
}

export type MessagingProduct = "whatsapp";

export interface Metadata {
  phone_number_id: string;
  display_phone_number: string;
}

export interface StatusElement {
  biz_opaque_callback_data?: string;
  id: string;
  conversation?: Conversation;
  pricing?: Pricing;
  status: StatusEnum;
  timestamp: string;
  recipient_id: string;
  errors?: Error[];
}

export interface Conversation {
  origin: Origin;
  id: string;
  expiration_timestamp?: string;
}

export interface Origin {
  type: Category;
}

export type Category = "marketing" | "utility";

export interface Error {
  code: number;
  title: string;
  message: string;
  error_data: ErrorData;
}

export interface ErrorData {
  details: string;
}

export interface Pricing {
  pricing_model: PricingModel;
  category: Category;
  billable: boolean;
}

export type PricingModel = "CBP";

export type StatusEnum = "delivered" | "failed" | "read" | "sent";

Creating an input mask with Lit

Luiz Américo — Thu, 15 Aug 2024 00:00:00 +0000

I needed to create an input mask for a Lit project I am working on. After a little research, i choose IMask library. In this article, I'll show you how to create an input mask in a Lit template using a directive.

I could create a custom element to wrap the input element and handle the mask logic, but using a directive is a more elegant and flexible solution.

First, naive version

import { noChange } from "lit";
import { Directive, directive } from "lit/directive.js";
import IMask from "imask";

/**
 * @typedef { import('lit').ElementPart } ElementPart
 **/

export class InputMaskDirective extends Directive {
  /**
   * @param {ElementPart} part
   * @param {[string]} [mask] directive arguments
   * @return {*}
   */
  update(part, [mask]) {
    const inputEl = part.element.matches("input")
      ? part.element
      : part.element.querySelector("input");
    if (!inputEl) {
      console.warn("InputMaskDirective: input element not found");
      return noChange;
    }

    IMask(inputEl, {
      mask,
    });

    return noChange;
  }
}

export const inputMask = directive(InputMaskDirective);

It's a simple directive that receives a mask string as an argument and applies it to the input element using the IMask library. The class overrides update method so it can access the part element, checks if element or any of its children is an input and apply the mask to it. Since it does not render anything, it returns noChange.

It should be used as a element part:

import { html } from "lit";
import { inputMask } from "./input-mask.js";

const template = html`<input type="text" ${inputMask("00/00/0000")} /> `;

So far, so good. But there is a problem with this implementation. One of my requirements is to be able to be define the mask in a parent of the input element. Something like the below example:

const template = html`
  <div ${inputMask("00/00/0000")}>
    <input type="text" />
  </div>
`;

Still, the directive will work as expected. But the actual usage is not exactly like that. I have an input function that renders the input element:

import { html } from "lit";
import { inputMask } from "./input-mask.js";

function input(attr, title) {
  return html`<label>${title}</label> <input name=${attr} type="text" />`;
}

const template = html`
  <div ${inputMask("00/00/0000")}>${input("name", "Name")}</div>
`;

This time, the directive will not work as expected. The problem is that at the time update is called, the child input element is not yet rendered. So, querySelector("input") will return null. Check this Lit Playground to see the problem in action.

Second, improved version

Here is an improved version that uses a MutationObserver to wait for a input element to be added to the DOM:

export class InputMaskDirective extends Directive {
  /**
   * @param {ElementPart} part
   * @param {[string]} [mask] directive arguments
   * @return {*}
   */
  update(part, [mask]) {
    const inputEl = part.element.matches("input")
      ? part.element
      : part.element.querySelector("input");
    if (inputEl) {
      IMask(inputEl, {
        mask,
      });
    } else {
      const observer = new MutationObserver((mutations) => {
        mutations.forEach((mutation) => {
          mutation.addedNodes.forEach((node) => {
            if (node.nodeType === 1 && node.matches("input")) {
              IMask(node, {
                mask,
              });

              observer.disconnect();
            }
          });
        });
      });
      observer.observe(part.element, { childList: true, subtree: true });
    }

    return noChange;
  }
}

This works as expected in all cases.

Conclusion

This article shows how to create an input mask in a Lit template using a directive. It highlights a difference in the timing of the children rendering when using nested templates and how to handle it using a MutationObserver.

The same technique can be used to create other directives that need to access child elements.

pdfkit 0.15 released

Luiz Américo — Sun, 24 Mar 2024 21:07:21 +0000

Just released version 0.15 of pdfkit, a library to create pdf files in Node and browsers.

Alongside the bug fixes and performance tweaks, support for long time obsolete environments (hello Node v6 and IE11!) was dropped.

I'd like to thanks everyone that contributed submitting code.

The main changes:

Add subset for PDF/UA
Fix for line breaks in list items (#1486)
Fix for soft hyphen not being replaced by visible hyphen if necessary (#457)
Optimize output files by ignoring identity transforms
Fix for Acroforms - setting an option to false will still apply the flag (#1495)
Fix for text extraction in PDFium-based viewers due to invalid ToUnicodeMap (#1498)
Remove deprecated write method
Drop support for Node.js < 18 and for browsers released before 2020

Looking forward, in short time, i plan to improve the testing infrastructure and docs generation (broken for now).

On the other side, making pdfkit portable to browser (drop requirement of bundler) and other JS runtimes is a project i'm holding until find proper funding.

DRY form handling with Lit

Luiz Américo — Tue, 20 Feb 2024 02:58:04 +0000

The problem

One of the main compelling reasons to use web components is the possibility to use the web platform with as little abstraction as possible. It is a path that brings many benefits, but not without its problems. One of them is the handling of forms. Not that is hard, is simply tedious and counter productive.

In Lit world, there's not a standard way of handling forms. A long time discussion could not agree in a good / generic enough solution.

Here, i present my take, that tries to meet the following criteria:

the component state (property) is the source of truth of the form, i.e., use controlled inputs
use native HTML form markup as much as possible
leverage the DOM events to communication
DRY

Imperative approach

This uses native FormData to retrieve the form data on submit. Works for small form without initial values (based on component state) and do not need to interact with the data dynamically.

class ContactForm extends LitElement {
  formSubmit(e) {
    // prevents sending the form
    e.preventDefault()
    const form = e.target

    const formData = new FormData(form)
    const formValues = Object.fromEntries(formData.entries())

    console.log(formValues)
    // returns something like
    // {
    //   "name": "João Silva",
    //   "birthDate": "1978-06-21",
    //   "subject": "Reclamação",
    //   "acceptRules": "on"
    // }

    const name = formValues.name
    // converts to Date
    const birthDate = parseISO(formValues.birthDate)
    const subject = formValues.subject
    // converts to boolean
    const acceptRules = Boolean(formValues.acceptRules)

    // we have the form data
    const finalData = { name, birthDate, subject, acceptRules }
  }

  render() {
    return html`
      <form @submit=${this.formSubmit}>
        <label for="name">Nome:</label>
        <input type="text" id="name" name="name" required />

        <label for="birthDate">Data de nascimento:</label>
        <input type="date" id="birthDate" name="birthDate" required />

        <label for="subject">Assunto:</label>
        <select id="subject" name="subject" required>
          <option value="">-- Select One --</option>
          <option value="Reclamação">Reclamação</option>
          <option value="Elogio">Elogio</option>
        </select>

        <label for="acceptRules">Aceito as condições:</label>
        <input type="checkbox" id="acceptRules" name="acceptRules" />

        <input type="submit" value="Submit" />
      </form>
    `
  }
}

Hardcoded event approach

This version goes some steps further, making the component state (property) the form source of truth at the same time is being updated dynamically.

Basically it does:

Set the form input value declaratively to the corresponding property using lit template syntax
Attach a generic event listener to respective event ("change", "input") of each input
In the event listener:
- Format the value according to field type
- uses the input name attribute to update the property

class ContactForm extends LitElement {
  @property()
  contactData = {
    acceptRules: true,
  }

  inputHandler(e) {
    e.preventDefault()
    e.stopPropagation()
    const input = e.target

    let value

    switch (input.type) {
      case 'checkbox':
        // get boolean value
        value = input.checked
        break
      case 'date':
        // get Date value
        value = parseISO(input.value)
        break

      default:
        value = input.value
        break
    }

    // update property using name attribute
    const property = input.getAttribute('name')
    this.contactData = { ...this.contactData, [property]: value }
  }

  formSubmit(e) {
    e.preventDefault()
    console.log(this.contactData)
  }

  render() {
    return html`
      <form @submit=${this.formSubmit}>
        <label for="name">Nome:</label>
        <input
          type="text"
          id="name"
          name="name"
          required
          .value=${this.contactData.name || null}
          @input=${this.inputHandler}
        />

        <label for="birthDate">Data de nascimento:</label>
        <input
          type="date"
          id="birthDate"
          name="birthDate"
          required
          .valueAsDate=${this.contactData.birthDate || null}
          @input=${this.inputHandler}
        />

        <label for="subject">Assunto:</label>
        <select id="subject" name="subject" required @change=${this.inputHandler}>
          <option value="">-- Select One --</option>
          <option value="Reclamação" ?selected=${this.contactData.subject === 'Reclamação'}>
            Reclamação
          </option>
          <option value="Elogio" ?selected=${this.contactData.subject === 'Elogio'}>Elogio</option>
        </select>

        <label for="acceptRules">Aceito as condições:</label>
        <input
          type="checkbox"
          id="acceptRules"
          name="acceptRules"
          .checked=${this.contactData.acceptRules}
          @change=${this.inputHandler}
        />

        <input type="submit" value="Submit" />
      </form>
    `
  }
}

Reusable event approach

The third interaction is basically the previous one refactored to be used by any component / property.

It leverages the fact that lit template assigns the component to this in event handler

function createFormInputHandler(property) {
  return inputHandler(e) {
    e.preventDefault()
    e.stopPropagation()
    const input = e.target

    let value

    switch (input.type) {
      case 'checkbox':
        // get boolean value
        value = input.checked
        break
      case 'date':
        // get Date value
        value = parseISO(input.value)
        break

      default:
        value = input.value
        break
    }

    // update property using name attribute
    // could use lodash set to handle nested path
    const subProperty = input.getAttribute('name')
    this[property] = { ...(this[property] || {}), [subProperty]: value }
  }
}

const inputHandler = createFormInputHandler('contactData')

class ContactForm extends LitElement {
  @property()
  contactData = {
    acceptRules: true,
  }  

  formSubmit(e) {
    e.preventDefault()
    console.log(this.contactData)
  }

  render() {
    return html`
      <form @submit=${this.formSubmit}>
        <label for="name">Nome:</label>
        <input
          type="text"
          id="name"
          name="name"
          required
          .value=${this.contactData.name || null}
          @input=${inputHandler}
        />

        <label for="birthDate">Data de nascimento:</label>
        <input
          type="date"
          id="birthDate"
          name="birthDate"
          required
          .valueAsDate=${this.contactData.birthDate || null}
          @input=${inputHandler}
        />

        <label for="subject">Assunto:</label>
        <select id="subject" name="subject" required @change=${inputHandler}>
          <option value="">-- Select One --</option>
          <option value="Reclamação" ?selected=${this.contactData.subject === 'Reclamação'}>
            Reclamação
          </option>
          <option value="Elogio" ?selected=${this.contactData.subject === 'Elogio'}>Elogio</option>
        </select>

        <label for="acceptRules">Aceito as condições:</label>
        <input
          type="checkbox"
          id="acceptRules"
          name="acceptRules"
          .checked=${this.contactData.acceptRules}
          @change=${inputHandler}
        />

        <input type="submit" value="Submit" />
      </form>
    `
  }
}

The final solution?

The last approach meets the criteria, with a markup close to the metal but still with some room for improvement like removing the need to set the inputHandler for each field.

In fact, i already use such solution: FormState, a Reactive Controller that listen to form inputs 'change' and 'input' events, store touched and validation state. Unfortunately is tied to nextbone Model class. Hopefully i can make it generic someday...

Save a pdf created with pdfkit to Google Cloud Storage

Luiz Américo — Sun, 10 Sep 2023 20:24:45 +0000

While cleaning the cloud functions of one Firebase project, i found a set of routines to save a pdf file to Google Cloud Storage. I'm removing them because i moved the pdf generation to client side.

Posting here in hope it can be useful for someone or my future self.

Use case

The pdf is generated dynamically with pdfkit in a firebase cloud function and cached in Google Cloud Storage bucket.

Generate the Data URL

The first function is to generate a Data URL from a pdfkit document

async function generatePdfDataUrl(doc) {
  return new Promise((resolve, reject) => {
    const chunks = []

    doc.on('data', (chunk) => {
      chunks.push(chunk)
    })

    doc.on('end', () => {
      const result = Buffer.concat(chunks)
      resolve('data:application/pdf;base64,' + result.toString('base64'))
    })

    doc.on('error', (error) => {
      reject(error)
    })

    doc.end()
  })
}

It receives a pdf document and wraps the node stream events in a promise. Stores the file chunks and, at the end, concatenate them after converting to base64.

Save to Cloud Storage

const isEmulator = process.env.FUNCTIONS_EMULATOR

const baseFileURL = 'https://storage.googleapis.com/XXX.appspot.com/'

async function storePdfDoc(storage, path, doc) { 
  if (isEmulator) {
    const fileUrl = await generatePdfDataUrl(doc)
    return { fileUrl }
  }

  // toLocalDate converts cloud date (UTC) to local GMT-3 in my case
  const reportDate = toLocalDate(new Date())
  const formattedDate = format(reportDate, 'dd-MM-yy-kk-mm')

  const bucket = storage.bucket()
  const fileName = slugify(`${path}-${formattedDate}.pdf`)
  const file = bucket.file(fileName)
  const bucketFileStream = file.createWriteStream()

  return new Promise((resolve, reject) => {
    bucketFileStream.on('finish', () => {
      const link = `${baseFileURL}${fileName}`
      resolve({ fileUrl: link })
    })

    bucketFileStream.on('error', function bucketError(err) {
      reject(err)
    })

    doc.pipe(bucketFileStream)
    doc.end()
  })
}

The first step is to check if is running in firebase emulator and return the Data URL instead of storing the file

At the time i wrote this function the firebase Storage emulator was not available

This function also wrap node stream functions in a promise. This time, we create a file in the bucket using bucket.file and the corresponding writable stream, than pipe the pdfkit document to it.

The catch here is to resolve the promise in the destination stream 'finish' event instead of document 'end' event. This way we ensure the file is fully created / uploaded on the cloud.

From webpack to vite: custom module resolution, sass import, babel config

Luiz Américo — Sun, 30 Apr 2023 10:44:53 +0000

Background

Being a long time Webpack user and mastering most of its features, i was reluctant to migrate to other build tool.

On the other side, news like Storybook improving vite support or how Vite is getting fast lead me to consider migrating away from the ageing tool. The main Webpack developer moving to another project helped in the decision to modernize the build stack.

I could try Turbopack or Rspack that explicitly aims to be a webpack successor but i decided to go with Vite which is more mature at this time.

Below are the issues i faced and how i overcome them.

Custom module resolution

I have configured Webpack to lookup for modules in ./src and ./src/common. The resolve.modules option makes it straight forward:

 {
   //.. 
   resolve: {
     modules: [
        path.resolve(__dirname, './src/common'),
        path.resolve(__dirname, './src'),
        'node_modules',
     ],
   },
 }

This is an option that i was expecting to be exposed by Vite, but is not and will not be.

Following suggestion in the issue, i looked at vite-tsconfig-paths which is even better because i already have configured vscode through typescript config:

{
  "compilerOptions": {
    "experimentalDecorators": true,
    // This must be specified if "paths" is set
    "baseUrl": "./src/",
    // Relative to "baseUrl"
    "paths": {
      "*": [
        "./common/*",
        "*"
      ]
    }
  }
}

One small problem delayed a bit the migration: lack of support to jsconfig.json. Renaming jsconfig.json to tsconfig.json and adding allowJs option made it work.

As a bonus, the module lookup configuration is now in only one place.

Importing external sass modules

With Webpack i have to add a "~" in front of module name in order of a sass import.

Vite does not require it.

@import '~bootstrap/scss/bootstrap';

becomes

@import 'bootstrap/scss/bootstrap';

Babel configuration

I use decorators extensively in my projects, so Babel is required. vite-plugin-babel does what i need: transpile both in development and in production.

It worked at first just by following project instructions, but needs some tweaking to match my requirements:

Add source maps in development. Option babelConfig: { sourceMaps: mode === 'development' ? 'inline' : false } made it work.
Exclude node_modules. By default vite-plugin-babel transpile all javascript including the ones from external packages. Setting filter: /^(?!.*node_modules(?!.*luipack)).*\.jsx?$/ did the trick (luipack module needs to be transpiled)

Initial impressions

So far, the result is what i expected: faster startup and reload with less configuration.

I only migrated a starter application but i hope to get same benefits with the actual / big projects.

slick-router: a powerful router for web components

Luiz Américo — Fri, 24 Jan 2020 22:43:50 +0000

TL;DR;
slick-router is a client side router library with a flexible API and advanced features like fine grained routing control, code lazy loading, nested state / rendering, page transition animations among others. Take a look at the source code and live demo of a complete app that uses it.

Routing is an important part of a client side web application and choosing the right strategy to handle it is one of the keys to create a solid project.

There are many ways (and libraries) to handle routing, from the minimal one where developer chooses how to respond to navigation to opinionated one where application state, including UI tree, is derived automatically from the routing state using some sort of configuration. The best way depends on complexity of application, framework (if any) used and developer preference.

Being framework agnostic and with its flexible API, slick-router allows to implement both a minimal or an opinionated routing strategy.

Core Concepts

The first step to use slick-router is to create the route definitions tree as show below

const routes = [
  {
    name: 'app',
    path: '/',
    children: [
      {
        name: 'about'
      },
      {
        name: 'post',
        path: ':postId',
        children: [
          {
            name: 'show'
          },
          {
            name: 'edit'
          }
        ]
      }
    ]
  }
]

Each route must have a name property whose value must be unique. If path is not defined, the value of name is used as the path. The children property receives an array of route definitions defining nested routes. The route tree can be defined also using a callback mechanism

Beside these basic options, arbitrary ones, e.g. 'handler', can be added to each route definition to be used by the middlewares.

Now create the a router instance:

import { Router } from 'slick-router'

const router = new Router({routes})

The next step is to register a custom or a predefined middleware, a function that receives a transition object each time a navigation occurs:

router.use(transition => {
  // do whatever you want here
  // transition holds the matched path, pathname, query, params, routes
})

Last, call listen:

router.listen()

A Minimal Approach

The example below calls the function associated to the handler option. More than one handler can be associated to each route and the function can be async.

const user = {
  list () {},
  async load () {},
  show () {},
  edit () {}  
}

const routes = [
  {
    name: 'users',
    path: '/',
    handler: user.list    
  },
  {
    name: 'user.show',
    path: '/user/:id/edit',
    handler: [user.load, user.show]
  },
  ,
  {
    name: 'user.edit',
    path: '/user/:id/edit',
    handler: [user.load, user.edit]     
  }
]

const router = new Router({routes})

function normalizeHandlers(handlers) {
  return Array.isArray(handlers) ? handlers : [handlers]
}

router.use(async function(transition) {
  for (const route of transition.routes) {
    const handlers = normalizeHandlers(route.options.handler)
    for (const handler of handlers) {
      await handler(transition)
    }
  }  
})

That's all. Basically mimics the interface of minimal routing libraries like page.js

On top of it if necessary is possible to add new features on a needed basis, like declarative redirect:

router.use(function(transition) {
  // only redirect with the exact matched route
  const leafRoute = transition.routes[transition.routes.length - 1]
  if (leafRoute.options.redirect) {
    transition.redirectTo(leafRoute.options.redirect)
  }
})

or declarative authorization handling:

router.use(function(transition) {
  // if any matched route is private, the routing is cancelled
  for (const route of transition.routes) {    
    if (route.options.private && !authService.isLogged) {
       transition.cancel()
       // or 
       transition.redirectTo('login')
    }
  }  
})

Using wc (Web Component) Middleware

While the minimal approach can work for many projects, it can become cumbersome for middle to large sized applications.

slick-router ships with wc middleware that renders the UI tree using web components and have advanced functionality like code lazy loading, lifecycle hooks and component reuse. It has an interface similar to vue-router

Setup

import { wc } from 'slick-router/middlewares/wc'

const routes = [];

const Router = new Router({routes, outlet: 'app-root'})

router.use(wc)

Besides registering the wc middleware, the code above pass an 'outlet' option to define where the components will be rendered. It can be a selector or an element instance. Defaults to document.body.

Component Declaration

import './components/home-view.js'
import LoginView from './components/login-view.js'

function AboutView () {
  return import('./components/about-view.js')
}

const routes = [
  {
    name: 'home',
    component: 'home-view'
  },
  {
    name: 'login',
    component: LoginView
  },
  {
    name: 'about',
    component: AboutView
  }
]

The above example shows how components can be declared: as a string pointing to a tag name or as an HTMLElement descendant constructor. Is possible also to define as a function returning a string or a constructor that will be lazy loaded. The function can be async providing a seamless way to do code splitting when, e.g., used with a bundler or with manual async code loading.

Lifecycle Hooks

Is possible to define lifecycle hooks in the route definition:

const routes = [
  {
    name: 'home',
    component: 'home-view'
  },
  {
    name: 'admin',
    component: 'admin-view',
    beforeEnter: (transition) => {
      if (!authService.isLogged) transition.redirectTo('home')
    }
  }
]

or in the component class:

class AdminView extends HTMLElement {
  beforeRouteEnter(transition) {
    if (!authService.isLogged) transition.redirectTo('home')
  }
}

See here the existing hooks.

Nested Rendering

When a route is nested, its component is rendered in an outlet element from the parent component. By default, the outlet is a 'router-outlet' element.

const routes = [
  {
    name: 'app',
    component: 'app-shell'
    children: [
      {
        name: 'dashboard',
        component: 'dashboard-view'   
      },
      {
        name: 'about',
        component: 'about-view'   
      }
    ]
  }
]

class AppShell extends HTMLElement {
  connectedCallback() {
    this.innerHTML = `
      <h1>My App</h1>
      <a href="#dashboard">Dashboard</a>
      <a href="#about">About</a>
      <router-outlet></router-outlet>
    `
  }
}

customElements.define('app-shell', AppShell)

In the above example, when navigating to 'dashboard' route, 'dashboard-view' component will be rendered inside 'router-outlet' element from 'app-shell'. Transitioning from 'dashboard' to 'about' route will remove 'dashboard-view' and render 'about-view'. In this case 'app-shell' component will not be re-rendered.

The outlet selector can be configured using static outlet field:

class AppShell extends HTMLElement {
  static get outlet() {
    return '.pages'
  }

  connectedCallback() {
    this.innerHTML = `
      <h1>My App</h1>
      <a href="#dashboard">Dashboard</a>
      <a href="#about">About</a>
      <div class="pages"></div>
    `
  }
}

Animating Element Transitions

Animating element transitions can be accomplished by using AnimatedOutlet component. It must be explicitly registered to a HTML tag, more commonly to 'router-outlet'.

import { AnimatedOutlet } from 'slick-router/components/animated-outlet.js'

customElements.define('router-outlet', AnimatedOutlet)

To enable the animation, add an 'animation' attribute:

class AppShell extends HTMLElement {
  connectedCallback() {
    this.innerHTML = `
      <h1>My App</h1>
      <a href="#dashboard">Dashboard</a>
      <a href="#about">About</a>
      <router-outlet animation></router-outlet>
    `
  }
}

By default, it uses the same pattern as vue transitions adding 'outlet-enter', 'outlet-enter-active', 'outlet-enter-to' classes to element being added and 'outlet-leave', 'outlet-leave-active', 'outlet-leave-to' classes to element being removed.

The class names can be configured by setting a value to animation attribute, so <router-outlet animation="user"></router-outlet> will use 'user-enter', 'user-enter-active' etc classes.

See live demo

Is also possible to change how animation is done by descending AnimationHook class. Out of box, AnimateCSS class, that allows to use animate.css is provided.

import { AnimatedOutlet, setDefaultAnimation, AnimateCSS } from 'slick-router/components/animated-outlet.js'

setDefaultAnimation(AnimateCSS)

customElements.define('router-outlet', AnimatedOutlet)

See in action here

Finally, is possible to use JavaScript animation libraries as demoed here or use AnimatedOutlet component (without a router)

Final Notes

Not all features are described here as automatic link handling, component reuse or more granular middleware API. Refer to slick-router docs for more info.
slick-router is not exactly new since is basically a modernized and improved version of CherryTree, a six year old project.
nextbone-routing is another routing library for web components, built on top of slick-router and a bit more opinionated. It puts routing in a central place in the application architecture, acting as a kind of orchestrator.

From React to Web Components: using mobx

Luiz Américo — Thu, 12 Dec 2019 21:23:29 +0000

Mobx is a popular JavaScript state management library. Most of its documentation and examples revolves around React but at its core is framework agnostic and can be used for any web application.

I looked if and how i could use Mobx together with web components/LitElement, my favorite client side view stack.

Since simple, "todo app" like, demos do not show the full benefits, and possible drawbacks, of such technology, i decided to convert RealWorld React/mobx demo, a reasonably complex application.

The React Escape Route

The conversion from React to LitElement is not technically difficult, but is bit annoying since many of it must be done manually. Below are the steps to get the job done:

Build setup

The original app is built with Create React App which, obviously, does not work for web component project. A custom (minimal) webpack setup was used instead. The most complex part is to configure decorator support in babel:

{
  "plugins": [
    ["@babel/plugin-proposal-decorators", { "legacy": true }],
    ["@babel/plugin-proposal-class-properties", { "loose": true }]
  ]
}

HTML Rendering

LitElement uses html tagged template instead of JSX language for HTML rendering. The concepts are similar and seasoned React developers should not have issues making the transition. This tool can automate most of the conversion.

JSX:

<ul className="error-messages">
  {
    Object.keys(errors).map(key => {
      return (
        <li key={key}>
          {key} {errors[key]}
        </li>
      );
    })
  }
</ul>

lit-html:

html`
  <ul class="error-messages">
    ${Object.keys(errors).map(key => {
      return html`
        <li key=${key}>${key} ${errors[key]}</li>
      `;
    })}
  </ul>
`;

Mobx Integration

Mobx integrates with React through mobx-react package. It provides a way to re-render components on state change (observer decorator) and a specialized dependency injection system to expose state to components (Provider component + inject decorator).

For LitElement, lit-mobx provides a way to render components on state change and wc-context is used to expose the state to components.

Routing

Personally, i prefer to define the app router / routes in a separate data structure (out of component tree), but for sake of simplicity @stencil/router is used because its API is very similar to react-router one. Update: replace by slick-router, a smaller and more powerful solution.

Testing

The original demo does not have tests but it was something i really wanted to see how would work. I choose the test setup provided by open-wc which uses karma with a configuration tailored for web components and ES modules. The open-wc testing helpers are really helpful, something to look forward. Unfortunately, the setup breaks with third party packages distributed as commonjs modules without an effective workaround. Update: by using import-map support, i managed to get tests working.

Conclusion

Mobx works well with LitElement. There was no need to change the state management code at all to get the demo working. Also the Mobx / LitElement integration through lit-mobx works as expected, no issues founds in this aspect.

The converted code can be found here alongside a live demo and the bundle size composition.

Some notes

mobx-devtools works with a web component app!
People should really analyze the bundle output. The Promise.prototype.finally shim increases bundle size by 43Kb (minified) due to a dependency from which only three functions are used.
@stencil/router did the job but i would not recommend for non stencil projects since it brings together the stencil stack adding 62Kb of minified code. Also it lacks advanced features.
Mobx implements only the "legacy" decorator spec, so any project that uses the new spec is out of luck. Not Mobx fault at all because the decorator state is a great mess at this moment.
Testing web components apps is a Far West like world without an out of box solution. open-wc setup works only with projects where all dependencies are ES modules, something not realistic in many cases (like that). Jest does not support web components at all (and have no signs of doing so). The devs are left in the wonderful world of configuring karma with webpack / mocha / chai etc.

From React to Web Components: using hooks (part 2)

Luiz Américo — Wed, 27 Nov 2019 23:40:02 +0000

This is a follow up to the evaluation of hooks usage with web components using Haunted library.

Using third party (React) hooks

The use of third party React hook libraries is possible because Haunted provides an API with same signature as React. With some bundling setup is possible to make the library load Haunted instead of React.

Webpack can be configured as below:

module.exports = {
  resolve: {
    alias: {
      react: 'haunted'
    }
  }
}

To see if it works in practice, i converted this demo which depends on react-media-hook. The end result is here.

The code related to hooks worked flawlessly without any adaptation. Most of the conversion work was due to differences between React and web components concepts.

This approach (package alias using bundler) will not work if the project itself uses React or if the hook library relies on JSX / Virtual DOM.

An interoperability tale

The converted demo uses @stencil/router, a web component based router with an API similar to React Router. It is built with StencilJS, a component compiler featuring JSX, virtual dom, decorators etc.

It uses also wc-fontawesome, the web component version of React FontAwesome, built on top of RawElement which extends LitElement base class.

All working together. A demonstration of how web components built with different technology can work together.

Conclusion

It's feasible to work with Hooks using web components and take advantage of most of third party libraries. Haunted worked glitch free in the experiences i did, proving be a valuable tool.

Whether Hooks is better than classes for web components development is a matter of debate. Sure, is ergonomic, composable etc but, personally, i will still prefer, for the time being, classes due to ability to use (upcoming) decorators syntax and better attributes support.

All in all, it does not need to be one or other. Even in same project both approaches can coexist, allowing developer to choose the technology that better suits each situation.

From React to Web Components: using hooks

Luiz Américo — Wed, 09 Oct 2019 00:21:15 +0000

The recent rise of React Hooks, followed by a lot of people claiming all sort of benefits, raised my interest in it. There was just one problem: i don't use, nor i'm not interested in, React.

Hopefully there's haunted, a library that enables hooks for web components by providing an API similar to the React one.

What and why

I picked some non trivial React Hooks demos and converted to web components / haunted so i could:

evaluate how well it integrates with web components ecosystem
check how feasible is to reuse existing code
check if it matches my coding requirements / taste

A chat app with Firebase

The original project can be found at freeCodeCamp. It's a simple chat app that uses Firebase as backend.

Converting, and getting to work, was basically straight forward. In fact, it took a little more time because i did some changes like changing from Real Time Database to Firestore and using context to provides db instance.

The only issue related to hooks was the messages being pulled from the backend in a loop even without new data. The reason was a lack of understanding of how useEffect works. Below is the original code:

  useEffect(() => {
    const handleNewMessages = snap => {
      // avoid updating messages when there are no changes
      const changes = snap.docChanges()
      if (changes.length) {
        setMessages(snap.docs.map(doc => doc.data()))
      }      
    }
    const unsubscribe = chatRoomMessages.onSnapshot(handleNewMessages);
    return unsubscribe;
  });

To overcome this, just add an empty array as second parameter.

Adding a new feature

In the original app, when a new message is added to a full room it gets hidden. By scrolling the element that holds the messages is possible to fix that.

Such feature can be implemented with React Hooks using useEffect and useRef.

The only problem is that, in Haunted / lit-html, there's not a out of the box way to get an element reference. It needs a directive:

const ref = directive((refInstance) => (part) => {
  if (!(part instanceof AttributePart)) {
    throw new Error('ref directive can only be used as an attribute');
  }
  refInstance.current = part.committer.element;
});

So we can implement the feature:

  const messagesRef = useRef();

  useEffect(() => {
    if (messagesRef.current) {
      messagesRef.current.scrollTop = messagesRef.current.scrollHeight;
    }
  }, [messages]);

The final code, with setup instructions, can be found here. BTW, there's no build step, a benefit of web components world!

For fun, i also created a LitElement version of same app to see how implementations compare.

Final words

The process of converting from React to Haunted / lit-html was pretty much challengeless. Just minor issues like the need to map React onChange to native input event.

Regarding the Hooks feature itself, the only obstacle i faced was the lack of
an out of box way to declaratively access a element instance, like React ref feature.

And what about the supposed benefits of using hooks? Definitively, handling setup / teardown routines together (using useEffect) is better than adding such routines to connectedCallback / disconnectedCallback. I also like the declarative way to get an element instance instead of using CSS selectors.

On the other side, the class based approach allows to a more natural way to declare reactive properties / attributes and have the, yet not unleashed, potential of decorators.

Time allowing, i will convert one or two more apps based on React Hooks.

DEV Community: Luiz Américo

TIL: How to reference the item type of an array type?

Method 1: Use indexed access type

Method 2: Define the item type separately first

Method 3: Use ArrayType<T> utility type (custom)

Adding copy code feature to code blocks in Astro

WhatsApp webhook API types

The (Missing) WhatsApp webhook API types

Reverse engineering the webhook payload

The types

Creating an input mask with Lit

First, naive version

Second, improved version

Conclusion

pdfkit 0.15 released

DRY form handling with Lit

The problem

Imperative approach

Hardcoded event approach

Reusable event approach

The final solution?

Save a pdf created with pdfkit to Google Cloud Storage

Use case

Generate the Data URL

Save to Cloud Storage

From webpack to vite: custom module resolution, sass import, babel config

Background

Custom module resolution

Importing external sass modules

Babel configuration

Initial impressions

slick-router: a powerful router for web components

Core Concepts

A Minimal Approach

Using wc (Web Component) Middleware

Setup

Component Declaration

Lifecycle Hooks

Nested Rendering

Animating Element Transitions

Final Notes

From React to Web Components: using mobx

The React Escape Route

Build setup

HTML Rendering

Mobx Integration

Routing

Testing

Conclusion

Some notes

From React to Web Components: using hooks (part 2)

Using third party (React) hooks

An interoperability tale

Conclusion

From React to Web Components: using hooks

What and why

A chat app with Firebase

Adding a new feature

Final words

Method 3: Use `ArrayType<T>` utility type (custom)