Thymeleaflet

Thymeleaflet は Thymeleaf フラグメント向けの Storybook 風 UI です。
フラグメントを見つけてサクッとプレビューし、HTML 内の JavaDoc 風コメントから使用例も自動生成します。

概要

Thymeleaf フラグメントを素早く、しかも確実に確認できるプレビュー UI です。
ストーリーとライブプレビューで、実装の意図をいつでも見える化します。

ストーリー、プレビュー、フラグメント詳細をまとめて確認。

ストーリー作成 ({templatePath}.stories.yml)

{templatePath}.stories.yml で UI のバリエーションを定義し、状態をわかりやすく管理できます。
保存先は src/main/resources/META-INF/thymeleaflet/stories/ 配下です。
詳細は stories.ja.md を参照してください。

storyGroups:
  accordionItem:
    title: Accordion Item
    description: Vanilla JS accordion using inline handlers
    stories:
      - name: default
        title: Closed
        parameters:
          title: Shipping details
          body: Ships in 2-3 business days.
          open: false
      - name: open
        title: Open
        parameters:
          title: Returns
          body: Returns are accepted within 14 days of delivery.
          open: true

実際の {templatePath}.stories.yml での定義例。

UI に反映されたストーリー一覧。

ライブプレビュー

ストーリーを選ぶとプレビューがすぐに更新され、パラメータやモデルの編集も同じ画面で完結します。
ストーリーが無い場合でもフォールバックでプレビューできるので安心です。

ストーリー選択と同時にプレビューが更新。

ビューポート切替

Fit / Mobile Small / Tablet / Desktop など、幅のプリセットでレスポンシブ表示を手早く確認できます。
高さは自動なので、全体の見え方をそのまま確認できます。

Mobile Small 幅

Tablet 幅

フルスクリーン

もっと広く見たいときはフルスクリーン表示に切り替えれば、細部までじっくり確認できます。

フローティングのフルスクリーンプレビュー。

カスタムパラメータ

ストーリーが無くても、パラメータを直接編集して検証できます。
すぐ試したいときに便利です。

カスタムパラメータの入力。

入力内容がプレビューに反映。

カスタムモデル

Object 形式のモデルを渡して、モデル依存のフラグメントも UI 内で検証できます。
画面を切り替えずに完結します。

モデル仕様に合わせた入力。

モデル値がプレビューに反映。

背景切り替え

明るい/暗い背景を切り替えて、コントラストや輪郭の見え方をチェックできます。
仕上げの確認にぴったりです。

フラグメント詳細 (JavaDoc)

JavaDoc 風コメントから説明やモデル仕様を抽出し、意図をそのまま UI に表示します。
共有もしやすくなります。

/**
 * Select input (selectInput)
 *
 * @param label {@code String} [required] Field label
 * @param name {@code String} [required] Select name
 * @param selected {@code String} [optional=] Selected value
 * @param help {@code String} [optional=] Help text
 * @param error {@code String} [optional=] Error message
 * @param required {@code Boolean} [optional=false] Required flag
 * @param disabled {@code Boolean} [optional=false] Disabled flag
* @model options {@code List<Map<String, Object>>} [required] Options with value/label
 * @example <div th:replace="~{components/form-select :: selectInput(label='Plan', name='plan', selected='pro', help='Choose your plan', error='', required=true, disabled=false)}"></div>
 */

フラグメントのソースに記載した JavaDoc コメント。

抽出されたフラグメント詳細とモデル仕様。

はじめに

スターターをビルドせずに使えるので、依存を追加したらすぐ試せます。
詳細は getting-started.ja.md を参照してください。

依存関係

Maven

<dependency>
  <groupId>io.github.wamukat</groupId>
  <artifactId>thymeleaflet-spring-boot-starter</artifactId>
  <version>x.y.z</version>
</dependency>

Gradle (Groovy)

implementation 'io.github.wamukat:thymeleaflet-spring-boot-starter:x.y.z'

設定の概要

application.yml でプレビューの幅プリセットや背景色を設定できます。
詳細は configuration.ja.md を参照してください。

thymeleaflet:
  preview:
    backgroundLight: "#f6f7fb"
    backgroundDark: "#1f2331"
    viewports:
      - id: mobileSmall
        labelKey: thymeleaflet.preview.viewport.mobileSmall
        width: 360
      - id: tablet
        labelKey: thymeleaflet.preview.viewport.tablet
        width: 834