Develop Component

src/components/<component-name>/
├── <component-name>.css           # 必須: スタイル
├── playground.html                # 必須: Playground用の基本HTML
├── <variation>.html               # 任意: 使い方が異なるバリエーション用HTML
├── <component-name>.stories.css   # 任意: Storybookストーリー専用のスタイル調整
├── <component-name>.stories.ts    # 必須: Storybookストーリー
├── <component-name>.vrt.js        # 必須: VRT（Visual Regression Test、Playwright）
├── <component-name>.test.js       # 任意: 機能テスト（Vitest browser mode、JSを含むコンポーネント）
├── <component-name>.unit.js       # 任意: ユニットテスト（Vitest jsdom、純粋関数のロジック検証）
├── <component-name>.mdx           # 必須: ドキュメント（write-documentスキルを使用）
└── <component-name>.js            # 任意: Custom Element（インタラクティブな場合）

.dads-<block-name>__<element-name>[data-<modifier-name>="<value>"]

/* DO: data属性でModifier */
.dads-button[data-type="solid-fill"] { }
.dads-button[data-size="lg"] { }

/* DO: ARIAステートでスタイリング */
.dads-button[aria-disabled="true"] { }
.dads-input-text__input[aria-invalid="true"] { }

/* DON'T: BEMのModifier記法 */
.dads-button_solid-fill { }

/* フォントサイズ・余白・サイズ: rem（calc(px / 16 * 1rem)パターン） */
.dads-component {
  font-size: calc(16 / 16 * 1rem);
  padding: calc(8 / 16 * 1rem) calc(16 / 16 * 1rem);
  border-radius: calc(8 / 16 * 1rem);
  min-height: calc(48 / 16 * 1rem);
  gap: calc(4 / 16 * 1rem);
}

/* 線の太さ: px */
.dads-component {
  border: 1px solid currentcolor;
}

.dads-component {
  color: var(--color-neutral-solid-gray-800);
  font-weight: normal;
  font-size: calc(16 / 16 * 1rem);
  line-height: 1.7;
  font-family: var(--font-family-sans);
  letter-spacing: 0.02em;
}

.dads-component__input {
  box-sizing: border-box;
  width: 100%;
  padding: calc(12 / 16 * 1rem);
  border: 1px solid var(--color-neutral-solid-gray-600);
}

.dads-divider {
  margin: 0;
  /* ... */
}

/* DO: 直感的で読みやすい */
.dads-button[data-type="solid-fill"]:hover {
  background-color: var(--button-hover-color);
}

/* DON'T: 詳細度を下げるための過剰な :where() */
.dads-button:where([data-type="solid-fill"]:hover) {
  background-color: var(--button-hover-color);
}

/* カラー */
var(--color-key-900)                  /* キーカラー */
var(--color-primitive-blue-900)       /* プリミティブカラー */
var(--color-neutral-solid-gray-800)   /* ニュートラルカラー */
var(--color-neutral-white)
var(--color-neutral-black)
var(--color-semantic-error-1)         /* セマンティックカラー */

/* フォント */
var(--font-family-sans)               /* Noto Sans JP */
var(--font-family-mono)               /* Noto Sans Mono */

/* エレベーション */
var(--elevation-1) 〜 var(--elevation-5)

/* プライベート: サイズバリエーションの内部値 */
.dads-checkbox[data-size="sm"] {
  --_gap: calc(4 / 16 * 1rem);
  --_checkbox-size: calc(24 / 16 * 1rem);
}
.dads-checkbox[data-size="md"] {
  --_gap: calc(8 / 16 * 1rem);
  --_checkbox-size: calc(32 / 16 * 1rem);
}

/* パブリック: 利用者がテーマカラーを変更できるAPI */
.dads-button {
  --button-color: var(--color-key-900);
  --button-hover-color: var(--color-key-1000);
}

/* DON'T: 全プロパティをCustom Propertiesに間接化 */
.dads-button {
  --dads-button-bg-color: var(--color-key-900);
  --dads-button-text-decoration: none;
  background-color: var(--dads-button-bg-color);
  text-decoration: var(--dads-button-text-decoration);
}

.dads-component:focus-visible {
  outline: calc(4 / 16 * 1rem) solid var(--color-neutral-black);
  outline-offset: calc(2 / 16 * 1rem);
  box-shadow: 0 0 0 calc(2 / 16 * 1rem) var(--color-primitive-yellow-300);
}

.dads-component:disabled,
.dads-component[aria-disabled="true"] {
  /* 無効スタイル */
}

.dads-component:is(:user-invalid, [aria-invalid="true"]) {
  border-color: var(--color-semantic-error-1);
}

.dads-component { /* モバイルスタイル */ }

@media (min-width: 48rem) {
  .dads-component { /* デスクトップスタイル */ }
}

@media (hover: hover) {
  .dads-component:hover {
    /* ホバースタイル */
  }
}

@media (forced-colors: active) {
  .dads-component {
    /* 強制カラーモード用のスタイル調整 */
  }
}

@media (prefers-reduced-motion: reduce) {
  .dads-component {
    transition: none;
  }
}

<!DOCTYPE html>
<html lang="ja">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Component Name</title>
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Noto+Sans+JP:wght@100..900&display=swap" rel="stylesheet">
<link rel="stylesheet" href="../../global.css">
<link rel="stylesheet" href="<component-name>.css">
</head>
<body>

<!-- コンポーネントのHTML -->

</body>
</html>

<body>

<button class="dads-button" data-size="md" data-type="solid-fill">ボタン</button>

</body>

<!-- エラーメッセージをdata属性で提供 -->
<dads-file-upload
  class="dads-file-upload"
  max-files="5"
  max-total-size="10MB"
  max-file-size="5MB"
  data-error-invalid-type="PNG/JPEG/GIF形式の画像、Excel/Word/PowerPoint/PDF形式のドキュメントだけが選択できます。"
>
  <!-- ... -->
</dads-file-upload>

// JavaScript側ではdata属性からメッセージを取得
#getMessage(category, key, variables = {}) {
  const datasetKey = `${category}${key.charAt(0).toUpperCase()}${key.slice(1)}`;
  let template = this.dataset[datasetKey];

  // data属性になければデフォルトメッセージを使用
  if (!template) {
    template = FileUpload.defaultMessages[category]?.[key] || "";
  }

  return template.replace(/\{(\w+)\}/g, (match, variable) => {
    return variables[variable] !== undefined ? variables[variable] : match;
  });
}

export class ComponentName extends HTMLElement {
  #abort = null;

  connectedCallback() {
    this.#abort = new AbortController();
    this.#setupEventListeners();
  }

  disconnectedCallback() {
    this.#abort.abort();
  }

  #setupEventListeners() {
    const signal = this.#abort.signal;

    this.#triggerButton.addEventListener(
      "click",
      (e) => this.#handleClick(e),
      { signal },
    );

    this.#someInput.addEventListener(
      "change",
      (e) => this.#handleChange(e),
      { signal },
    );

    // イベントデリゲーション
    this.addEventListener(
      "click",
      ({ target }) => {
        if (!target.closest("[data-js-remove-button]")) return;
        this.#handleRemove(target);
      },
      { signal },
    );
  }

  #handleClick(e) {
    // ...
  }

  #handleChange(e) {
    // ...
  }

  #handleRemove(target) {
    // ...
  }

  // DOM要素へのアクセスはgetterで定義
  get #triggerButton() {
    return this.querySelector("[data-js-trigger-button]");
  }

  get #someInput() {
    return this.querySelector("[data-js-input]");
  }
}

customElements.define("dads-component-name", ComponentName);

// ✅ public: DatePickerから this.calendar.setSelectedDate(date) と呼ばれる
setSelectedDate(date) { ... }

// ✅ public: 標準APIのオーバーライド（DatePickerから this.calendar.focus() と呼ばれる）
focus() { ... }

// ❌ private: イベントリスナー内で this.#renderCalendar() と呼ぶだけ
#renderCalendar() { ... }

// ❌ private: 同クラスの別インスタンスから呼ぶ場合もprivate化可能
// （JSではprivateフィールドは同クラスの他インスタンスからもアクセス可能）
#setExpandedDropArea(expanded) { ... }
// → activeExpandedComponent.#setExpandedDropArea(false) と呼べる

<button data-js-calendar-button>カレンダー</button>
<div data-js-calendar-popover>...</div>
<input data-js-input type="file">

get #calendarButton() {
  return this.querySelector("[data-js-calendar-button]");
}

import type { Meta, StoryObj } from "@storybook/html-vite";
import { HtmlFragment } from "../../helpers/html-fragment";

// CSSインポート（Storybookでのスタイル適用用）
import "./component-name.css";
// 依存コンポーネントのCSSもインポート
import "../button/button.css";

// HTMLファイルのインポート（?rawで文字列として取得）
import playground from "./playground.html?raw";
import withFormControlLabel from "./with-form-control-label.html?raw";

const meta = {
  title: "Components/コンポーネント名（日本語）",
} satisfies Meta;

export default meta;

interface ComponentPlaygroundProps {
  variant: string;
  size: string;
  disabled: boolean;
  // ...
}

export const Playground: StoryObj<ComponentPlaygroundProps> = {
  render: (args) => {
    const fragment = new HtmlFragment(playground, ".dads-component");
    const component = fragment.root;
    
    // 必要な要素の取得と確認
    const input = component.querySelector(".dads-component__input");
    const errorText = component.querySelector(".dads-component__error-text");
    if (!input) throw new Error();
    if (!errorText) throw new Error();

    // data属性の設定
    component.setAttribute("data-type", args.variant);
    component.setAttribute("data-size", args.size);

    // 子要素の操作
    if (args.disabled) {
      input.setAttribute("disabled", "");
    }

    // 条件付きの要素削除
    if (!args.errored) {
      errorText.remove();
    }

    return fragment.toString({ trimBlankLines: true });
  },
  argTypes: {
    variant: {
      control: { type: "radio" },
      options: ["solid-fill", "outline", "text"],
    },
    size: {
      control: { type: "radio" },
      options: ["lg", "md", "sm"],
    },
    disabled: { control: "boolean" },
  },
  args: {
    variant: "solid-fill",
    size: "md",
    disabled: false,
  },
};

// 第1引数: HTMLファイルの文字列（?rawインポート）
// 第2引数: 抽出するセレクタ（省略可）
const fragment = new HtmlFragment(playground, ".dads-component");

// rootプロパティで抽出した要素にアクセス
const component = fragment.root;

// 属性の操作
component.setAttribute("data-size", "lg");
component.removeAttribute("data-disabled");

// 子要素のクエリ
const input = component.querySelector(".dads-component__input");

// 文字列として出力
fragment.toString();
fragment.toString({ trimBlankLines: true });

// シンプルな表示のみのストーリー
export const WithFormControlLabel = () =>
  new HtmlFragment(withFormControlLabel, ".dads-form-control-label").toString();

export const Readonly = () =>
  new HtmlFragment(readonly, ".dads-form-control-label").toString();

import "./component-name.css";
import "./component-name.js"; // Custom Elementを登録

import playground from "./playground.html?raw";

import path from "node:path";
import { resetCssVrt } from "../../../tests/helpers/reset-css-vrt";

const { dirname } = import.meta;

resetCssVrt("component-name", path.join(dirname, "playground.html"));

import path from "node:path";
import { resetCssVrt } from "../../../tests/helpers/reset-css-vrt";

const { dirname } = import.meta;

resetCssVrt(
  "input-text-playground",
  path.join(dirname, "playground.html"),
);

resetCssVrt(
  "input-text-with-form-control-label",
  path.join(dirname, "with-form-control-label.html"),
);

resetCssVrt("stacked", path.join(dirname, "stacked.html"), {
  ignoreElements: [".dads-accordion__content"],
});

import { describe, test, expect, beforeEach, afterEach, vi } from "vitest";
import { page, userEvent } from "vitest/browser";
import "./component-name.js";

// 「今日」を固定する（時刻依存のコンポーネントの場合）
const FAKE_NOW = new Date(2025, 5, 15, 12, 0, 0);

// テスト用の最小限のHTML（playground.html から独立）
const componentHTML = (extraAttrs = "") => `
<dads-component class="dads-component" ${extraAttrs}>
  <button data-js-trigger-button>開く</button>
  <div data-js-content>コンテンツ</div>
</dads-component>`;

beforeEach(() => {
  // 時刻依存のコンポーネントの場合のみ
  vi.useFakeTimers({ toFake: ["Date"] });
  vi.setSystemTime(FAKE_NOW);
});

afterEach(() => {
  vi.useRealTimers();
  document.body.innerHTML = "";
});

/**
 * コンポーネントをDOMにマウントして返す。
 * 属性はHTML文字列に直接埋め込み、connectedCallback で1回だけ初期化させる。
 */
const mountComponent = async (options = {}) => {
  const attrs = [];
  if (options.minDate) attrs.push(`min-date="${options.minDate}"`);
  if (options.maxDate) attrs.push(`max-date="${options.maxDate}"`);
  document.body.innerHTML = componentHTML(attrs.join(" "));
  return document.querySelector("dads-component");
};

// DOM helpers — テスト対象のコンポーネントに合わせて定義
const enabledButtons = () =>
  [...document.querySelectorAll("[data-js-button]:not(:disabled)")];

const selectedButton = () =>
  document.querySelector('[data-selected="true"]');

describe("ComponentName", () => {
  test("ボタンクリックで開閉する", async () => {
    await mountComponent();
    await page.getByRole("button", { name: "開く" }).click();
    await expect
      .element(page.getByRole("button", { name: "開く" }))
      .toHaveAttribute("aria-expanded", "true");
  });
});