ショーケースにデモを追加する

ドキュメントのホームページには、wcbで作られたコンポーネントのライブデモごとに1枚ずつカードが並ぶショーケースがあります。誰でも新しいエントリを追加して、自分のデモページへのリンクを載せられます。

このガイドでは、コンポーネントの雛形作成からデモページの公開、エントリの送信まで、一通りの手順を案内します。すでに公開ページで動いているコンポーネントがあるなら、ステップ3から始めてください。

カードに必要なもの

カードが指すのはデモページです。次を満たしていれば掲載できます。

公開されたページであること — https://でアクセスでき、今後も公開が続くこと。プロジェクトサイト、GitHub Pagesへのデプロイ、自分のドメインの1ページ、いずれでも構いません。
そのコンポーネントがwcbで作られていること — WebComponentを継承しているか、部分だけを使う（html、createElement）形で使っていること。
カスタム要素のタグ名があること — これがカードのタイトルになります。1枚のカードにつき1つの要素です。
webcomponent.ioへのリンクがあること — 目に見えるリンクが1つあれば十分です。たとえばフッターの「A web-component-base component」。npm create wcb@latestの雛形には最初から入っています。

npmへの公開は必要ありませんし、デモページが凝ったものである必要もありません。デモが表示されなくなったエントリは削除されるので、閉じる予定のあるページやまだ公開していないページは掲載を見送ってください。

準備するもの

次のものが必要です。

Node.js（現行のLTS）。npmが同梱されています
pnpm。ドキュメントサイトが要求します。他のパッケージマネージャーではインストールできません
プルリクエストのためのGitHubアカウント

1. コンポーネントを作る

すでにある場合はステップ2へ進んでください。

npm create wcb@latest my-element
cd my-element
npm install
npm run dev

ViteがローカルのURLを表示します。プロジェクト直下のindex.htmlがデモページで、すでに<my-element>をレンダリングしています。その中身はsrc/my-element.tsです。このファイルを編集すると、保存するたびにページが更新されます。

雛形が他に何を用意するかははじめるに、コンポーネントの書き方そのものは使い方にあります。

2. デモページを公開する

npm run build

これでindex.htmlとそのアセットがdist/にビルドされます（npm run build:libは別物で、コンポーネントをnpm向けにパッケージ化するだけでページは生成しません）。

dist/は任意の静的ホスティングにデプロイできます。Netlify、GitHub Pages、Cloudflare Pages、あるいは自分のサーバー上のディレクトリでも構いません。

ドメイン直下ではなくサブパス（https://you.github.io/my-element/）で配信する場合は、ビルド時にその接頭辞を渡す必要があります。渡さないと、スタイルもスクリプトも読み込まれないページになります。

npm run build -- --base=/my-element/

デプロイしたURLを開き、コンポーネントが表示されること、そしてページからwebcomponent.ioへリンクしていることを確認してください（雛形のフッターに入っています）。そのURLがカードのリンク先になります。

3. エントリを追加する

GitHubでayo-run/wcbをフォークし、フォークをクローンして、変更用のブランチを作ります。すべてのカードは1つのファイルに入っています。

export const showcase = {
  'mastodon-content': {
    href: 'https://mastodon-content.webcomponent.io',
    description:
      'Progressively enhances a Mastodon status: rewrites hashtag links and marks hashtag bars',
  },
  'status-indicator': {
    href: 'https://status-indicator.webcomponent.io',
    description: 'Colored circles that can pulse',
  },
}

自分のコンポーネントを、アルファベット順の位置にキーとして追加します。

  'my-element': {
    href: 'https://my-element.example.com',
    description: 'One line on what the component does',
  },

変更はこれだけです。キーはタグ名であり、<my-element>としてカードのタイトルに描画されます。hrefには外部リンクの印が付き、新しいタブで開きます。ホームページとその3つの翻訳はすべてこのオブジェクトから描画されるので、編集するページはありません。

フィールド

フィールド	必須	内容
キー	はい	HTMLに書くとおりのカスタム要素のタグ名。ハイフンを含むためクォートします。カードのタイトルになり、他のエントリと重複できません。
`href`	はい	デモページの絶対`https://` URL。
`description`	はい	コンポーネントの説明を英語で1行。カードの本文になります。目安は15語程度。
`translations`	いいえ	同じ説明の他ロケール版。ロケール接頭辞（`ja`、`zh-cn`、`tl`）をキーにします。省略したロケールでは英語の行が表示されます。

書ける言語があれば、翻訳を添えてください。

  'my-element': {
    href: 'https://my-element.example.com',
    description: 'One line on what the component does',
    translations: {
      ja: 'コンポーネントの説明を一行で',
    },
  },

4. サイトをプレビューする

クローンしたリポジトリのルートで:

pnpm install
pnpm docs

Astroがhttp://localhost:4321でサイトを配信します。ショーケースはホームページの一番下にあり、/ja/、/zh-cn/、/tl/でも該当する説明文でカードが表示されます。

pnpm test

エントリにフィールドが欠けている場合、hrefがhttps://のURLでない場合、キーがアルファベット順から外れている場合は、このテストが失敗します。

5. プルリクエストを開く

変更した1ファイルをコミットし、ayo-run/wcbに対してプルリクエストを開きます。

git commit -am "docs: add <my-element> to the showcase"

説明はこのタイトルで十分です。レビュアーが確認するのは3点、デモページが開けること、そこにあるコンポーネントがwcbで作られていること、そしてページからwebcomponent.ioへリンクしていることです。マージされれば、次のビルドでカードが表示されます。

リポジトリはSourceHutにもミラーされています。そちらで作業したい場合はどうぞ。