Tutorial de Alpine.js

O Lily para Alpine são fragmentos HTML que você cola na página, mais um plugin que dá aos interativos o seu teclado e o seu estado.

O que você vai construir

Um pequeno formulário de definições: dois campos rotulados, um interruptor e um botão de guardar, com comportamento real de teclado e leitor de tela, primeiro simples e depois estilizado, em cerca de 10 minutos.

Antes de começar

Precisa de Node.js e de uma página que já carregue o Alpine.js 3. O Alpine não tem modelo de componentes, por isso aqui um componente Lily é marcação que se copia, não um import.

Passo 1 — Instalar e registar o plugin

npm install alpinejs @lilydesignsystem/alpine-headless
<script type="module">
  import Alpine from "alpinejs";
  import lily from "@lilydesignsystem/alpine-headless/plugin";
  Alpine.plugin(lily);
  Alpine.start();
</script>

O plugin regista um comportamento Alpine.data() por componente interativo, com o nome lily mais o nome do componente: lilySwitchButton, lilyTabs, lilyCombobox. Os fragmentos de todos os componentes estão na pasta components/ do pacote, cada um com um comentário inicial que indica o elemento, a classe, as teclas e o ARIA.

Passo 2 — O seu primeiro componente

A maioria dos componentes é marcação simples e não precisa de nada do plugin:

<button class="button" type="submit">Save</button>

Um interativo acrescenta o seu comportamento com x-data e liga-o com x-bind:

<button
  class="switch-button"
  x-data="lilySwitchButton(false)"
  x-bind="button"
  aria-label="Email me about appointments"
>
  Email me about appointments
</button>

O comportamento dá-lhe role="switch" e mantém aria-checked atualizado quando Enter, Espaço ou um clique o alternam. As palavras são suas: o Lily nunca fornece um rótulo.

Passo 3 — Compor um pequeno formulário

<form class="form" aria-label="Settings">
  <div class="field">
    <label class="label" for="name">Full name</label>
    <input class="text-input" type="text" id="name" name="name" autocomplete="name" required />
  </div>
  <div class="field">
    <label class="label" for="email">Email</label>
    <input class="email-input" type="email" id="email" name="email" autocomplete="email" required />
  </div>
  <button
    class="switch-button"
    type="button"
    x-data="lilySwitchButton(true)"
    x-bind="button"
    aria-label="Email me about appointments"
  >
    Email me about appointments
  </button>
  <button class="button" type="submit">Save</button>
</form>

Verifique o seu trabalho: abra a página e prima Tab. O foco percorre os dois campos, o interruptor e o botão. No interruptor, Space alterna-o e um leitor de tela diz «interruptor, ligado» ou «desligado». Parece simples, e está certo: o aspeto vem a seguir.

Passo 4 — Estilizar

Ligue um dos 63 temas prontos, que visam as mesmas classes:

<link rel="stylesheet" href="/themes/light.css" />

Ou escreva o seu próprio CSS sobre as classes e o estado que o comportamento define:

.switch-button[aria-checked="true"] { background: var(--color-primary); }
.switch-button:focus-visible { outline: 2px solid var(--lily-focus-ring); outline-offset: 2px; }

Estilize o estado ARIA, não uma classe sua: assim o aspeto nunca contradiz o que um leitor de tela ouve.

Passo 5 — Ver tudo a funcionar

  • A aplicação de exemplo de Alpine.js, lily-design-system-alpine-examples, mostra todos os componentes estilizados: pnpm install && pnpm run build.
  • Há seis ajudantes para Alpine: a grelha de dados, o quadro kanban, o calendário, o gráfico de Gantt e os editores de Markdown e Org (@lilydesignsystem/alpine-*).

Próximos passos