@kiwa-test/component 0.2.0

package/dist/index.d.cts

@@ -0,0 +1,534 @@
+/**
+ * Shared types for `@kiwa-test/component` — the 3-integration unified mock
+ * harness for Storybook 8 + Playwright Component Testing + Chromatic.
+ *
+ * v1.16 milestone (Issue #762, sub #763) 新設。 kiwa の思想 =
+ * 「1 度書けば Storybook / Playwright CT / Chromatic の 3 SDK 同一挙動で
+ * 回せる mock」 を実現するため、 3 統合非依存な共通契約を SSOT として定義する。
+ *
+ * 各 module (`storybook.ts` / `playwright-ct.ts` / `chromatic.ts`) は本 file
+ * の共通型を SDK 固有 shape に変換する薄い層に留める。
+ */
+/**
+ * どの integration が emit した mock かを識別する。 release-gate 11 軸 dispatch
+ * の provider prefix として使う。
+ */
+type ComponentProvider = 'storybook' | 'playwright-ct' | 'chromatic';
+/**
+ * Storybook 8 の `StoryObj` (CSF3) と互換な最小 shape。 args + play + parameters
+ * の 3 field を持ち、 story 登録後に registry から名前指定で resolve できる。
+ *
+ * Storybook 8 の実際の `StoryObj` は component / render / decorators 等の
+ * 追加 field を持つが、 mock harness は「args を解決して play を回して
+ * DOM を触る」 core loop だけを模倣する。
+ */
+interface StoryObj<TArgs = Record<string, unknown>> {
+    /** story 表示名 (未指定時は export 名を使う想定、 mock では登録時に必須)。 */
+    name?: string;
+    /** default args (registry で resolve 時 override args と shallow merge)。 */
+    args?: Partial<TArgs>;
+    /**
+     * play function — story mount 後に interaction を実行する。 Storybook 8 の
+     * PlayFunction と互換な `{ canvasElement, args, step }` を受ける。
+     */
+    play?: (context: PlayContext<TArgs>) => Promise<void> | void;
+    /** story 単位の parameters (chromatic viewport, layout 等)。 */
+    parameters?: StoryParameters;
+}
+/** Storybook 8 の `parameters` field の最小 shape。 mock で意味のある値のみ抽出。 */
+interface StoryParameters {
+    /** chromatic diffThreshold (0-1)、 viewport 名一覧、 delay ms 等。 */
+    chromatic?: {
+        /** pixel diff の許容率 (0-1)、 default 0)。 */
+        diffThreshold?: number;
+        /** capture 時の viewport 名一覧 (ChromaticVisualMock で切替)。 */
+        viewports?: string[];
+        /** capture 前に待つ ms、 mock では noop。 */
+        delay?: number;
+        /** true なら chromatic capture 対象外。 */
+        disable?: boolean;
+    };
+    /** a11y addon parameters (rules disable/enable、 mock で violations を模倣)。 */
+    a11y?: {
+        disable?: boolean;
+        /** violation を 1 件模倣、 test で violations 検出を assert できる。 */
+        injectViolations?: A11yViolation[];
+    };
+    /** layout hint (centered / fullscreen / padded)、 mock では未使用。 */
+    layout?: 'centered' | 'fullscreen' | 'padded';
+}
+/** Storybook 8 の PlayFunction が受ける context。 mock 互換用に最小 shape のみ。 */
+interface PlayContext<TArgs = Record<string, unknown>> {
+    /** mount 済 root element (mock では in-memory DOM の抽象 handle)。 */
+    canvasElement: CanvasElement;
+    /** resolve 済 args (default + override の merge 後)。 */
+    args: TArgs;
+    /**
+     * step wrapper — Storybook 8 の `step('label', async () => {...})` 互換。
+     * mock では single-thread に順次実行、 label を trace に記録する。
+     */
+    step: (label: string, fn: () => Promise<void> | void) => Promise<void>;
+}
+/**
+ * mount 済 root の抽象 handle。 実 DOM ではなく、 in-memory な要素 tree として
+ * 扱う。 test は `getByText` / `getByRole` / `querySelector` の subset を通じて
+ * 要素を取り出し、 `click` / `fill` / `assert` を実行する。
+ */
+interface CanvasElement {
+    /** mount 時に render された root node。 */
+    root: MockNode;
+    /** 要素 lookup helpers (最小 subset)。 */
+    getByText(text: string): MockNode;
+    getByRole(role: string, options?: {
+        name?: string;
+    }): MockNode;
+    querySelector(selector: string): MockNode | null;
+    querySelectorAll(selector: string): MockNode[];
+    /** capture 時のセルフ dump (Chromatic に渡す markup 表現)。 */
+    toMarkup(): string;
+}
+/**
+ * mount 対象の component 表現。 実 React / Vue / Svelte component を直接
+ * 扱わず、 純関数 `(args) => MockNode` として抽象化する。 mock harness は
+ * framework agnostic — Storybook の render callback / Playwright CT の
+ * component 引数 / Chromatic の capture 対象を同じ関数で表現する。
+ */
+type ComponentRender<TArgs = Record<string, unknown>> = (args: TArgs) => MockNode;
+/**
+ * in-memory な DOM node 表現。 実 DOM を使わず tag / attrs / children /
+ * text で tree を組む。 test で `click` / `fill` / `text` 操作を行うため
+ * event listener + value state だけ持たせる。
+ */
+interface MockNode {
+    tag: string;
+    attrs: Record<string, string>;
+    text?: string;
+    children: MockNode[];
+    /** input / textarea の value (fill 操作で更新)。 */
+    value?: string;
+    /** on{event} handlers ({ click: [fn1, fn2], input: [fn3] })。 */
+    handlers: Record<string, Array<(event: MockEvent) => void>>;
+    /** parent への back reference (querySelector traversal 用)。 */
+    parent: MockNode | null;
+}
+/** event handler に渡す minimal event object。 */
+interface MockEvent {
+    type: string;
+    target: MockNode;
+    /** input event 時の value。 */
+    value?: string;
+}
+/**
+ * a11y violation を 1 件模倣。 実 axe-core の Result と field を揃える。
+ * (mock harness では injectViolations で外部から注入して test 対象にする)
+ */
+interface A11yViolation {
+    id: string;
+    impact: 'minor' | 'moderate' | 'serious' | 'critical';
+    description: string;
+    helpUrl?: string;
+    nodes: Array<{
+        target: string[];
+        html: string;
+    }>;
+}
+/**
+ * StoryRegistry の 1 entry — story ID → StoryObj + render + meta の bind。
+ * Storybook 8 の `Meta` + `StoryObj` を 1 record に flatten した shape。
+ */
+interface StoryEntry<TArgs = Record<string, unknown>> {
+    id: string;
+    title: string;
+    storyName: string;
+    args: TArgs;
+    render: ComponentRender<TArgs>;
+    play?: (context: PlayContext<TArgs>) => Promise<void> | void;
+    parameters: StoryParameters;
+}
+/**
+ * Playwright CT の `mount(component)` が返す ComponentLocator の subset。
+ * 実 Playwright CT は `Locator` を返して page 全体を操作するが、 mock は
+ * mount 済 canvas を直接返して interact に集中する。
+ */
+interface ComponentLocator {
+    /** mount 時に生成された canvas。 */
+    canvas: CanvasElement;
+    /** locator chain の起点 element。 */
+    root: MockNode;
+    /** テキスト locator の subset。 */
+    getByText(text: string): NodeLocator;
+    getByRole(role: string, options?: {
+        name?: string;
+    }): NodeLocator;
+    /** element を unmount して event handler を全 clear する。 */
+    unmount(): void;
+}
+/**
+ * Playwright Locator の subset — click / fill / textContent / count / expect。
+ * mock は同一 API で real Playwright test と表面互換にする。
+ */
+interface NodeLocator {
+    click(): Promise<void>;
+    fill(value: string): Promise<void>;
+    textContent(): Promise<string | null>;
+    count(): Promise<number>;
+    /** 対象 node への直接 access (mock 側 assert 用)。 */
+    node(): MockNode | null;
+}
+/**
+ * Chromatic の 1 baseline entry — story id + viewport + markup + hash。
+ * baseline JSON store に永続化される (mock は in-memory Map で代替)。
+ */
+interface VisualBaseline {
+    storyId: string;
+    viewport: string;
+    markup: string;
+    /** markup の deterministic hash (SHA-256 hex substring)。 */
+    hash: string;
+    /** baseline 生成時刻 (ms)、 accept workflow で比較に使う。 */
+    capturedAt: number;
+}
+/**
+ * Chromatic の diff 結果 1 件。 changed=true なら pixel diff 検出、
+ * pixelDiffRatio が threshold を超えると status=failed になる。
+ */
+interface VisualDiff {
+    storyId: string;
+    viewport: string;
+    baselineHash: string;
+    currentHash: string;
+    changed: boolean;
+    /** markup 差分 (0-1)、 hash 完全一致で 0、 完全不一致で 1。 */
+    pixelDiffRatio: number;
+    status: 'passed' | 'failed' | 'new';
+    /** threshold 判定に使った値 (parameters.chromatic.diffThreshold or default)。 */
+    threshold: number;
+}
+/**
+ * accept / reject workflow の 1 action。 accept は baseline を current で
+ * 置換、 reject は baseline を保持したまま diff status を残す。
+ */
+type VisualReviewAction = 'accept' | 'reject';
+interface VisualReviewEntry {
+    storyId: string;
+    viewport: string;
+    action: VisualReviewAction;
+    reviewedAt: number;
+}
+
+/**
+ * MockNode + CanvasElement の生成 / traversal / event 発火 helper 群。
+ *
+ * 実 DOM (jsdom / happy-dom) を使わない理由 = (1) Storybook 8 / Playwright CT /
+ * Chromatic の 3 統合 mock で共通の抽象を提供したい、 (2) framework agnostic
+ * (React / Vue / Svelte / Solid) にする、 (3) test 速度と決定性を最優先する。
+ *
+ * MockNode tree は tag / attrs / text / children で表現、 実 DOM の subset を
+ * 網羅する (querySelector 相当の tag / .class / #id / attr selector、 getByText、
+ * getByRole)。 fill / click は event handler を synchronously 呼ぶ。
+ */
+/** node factory — attrs / children / text / value を任意で与える。 */
+declare function createNode(tag: string, options?: NodeOptions): MockNode;
+interface NodeOptions {
+    attrs?: Record<string, string>;
+    text?: string;
+    value?: string;
+    children?: MockNode[];
+    on?: Record<string, (event: MockEvent) => void>;
+}
+/** node に child を追加、 parent back reference も更新する。 */
+declare function appendChild(parent: MockNode, child: MockNode): void;
+/** event handler を登録、 同一 event に複数 handler を許容する。 */
+declare function addHandler(node: MockNode, event: string, handler: (event: MockEvent) => void): void;
+/**
+ * event を発火する。 実 DOM のような bubble はせず target 単発、 mock harness
+ * では component 側で bubble 相当を実装する。 fill 相当は input event を発火。
+ */
+declare function fireEvent(node: MockNode, event: MockEvent): void;
+/**
+ * CanvasElement 生成 — root node と lookup helpers を wrap する。 mount 完了後
+ * story / component test / visual capture の全経路で使う。
+ */
+declare function createCanvas(root: MockNode): CanvasElement;
+/**
+ * MockNode subtree を deterministic な pseudo-HTML 文字列に変換する。
+ * event handler は含めず、 tag / attrs / text / children のみ。
+ * Chromatic の hash / markup 保存に使う。
+ */
+declare function renderMarkup(node: MockNode): string;
+/** markup 文字列を deterministic SHA-256 hex substring (先頭 16) に変換。 */
+declare function hashMarkup(markup: string): string;
+/**
+ * text 一致で最初に見つかった node を返す。 深い node を優先する — root 側の
+ * aggregated text ではなく、 実際に text を持つ leaf 相当の node を先に返す
+ * (Storybook / Testing Library の getByText 挙動と揃える)。
+ */
+declare function findByText(node: MockNode, text: string): MockNode | null;
+/**
+ * role 属性 (`role="button"`) or implicit role (button tag) と、 aria-label /
+ * text で一致する node を返す。 mock は最小 subset (button / link / heading /
+ * textbox / checkbox) のみ。
+ */
+declare function findByRole(node: MockNode, role: string, accessibleName?: string): MockNode | null;
+/**
+ * querySelector の最小 subset。 tag / .class / #id / [attr=value] / 子孫 (space)
+ * 結合子を support する。 実 CSS selector 全対応ではないが、 mock 用途では十分。
+ *
+ * MockNode tree では canvas.root が component 自体を指すため、 root も検査対象
+ * に含める (実 DOM の `document.querySelector` は container を除くが、 mock は
+ * component rendering root = 検索対象という semantics に揃える)。
+ */
+declare function query(root: MockNode, selector: string, all: boolean): MockNode[];
+
+/**
+ * Storybook 8 の CSF3 と互換な最小 mock。 real Storybook (SB8) は Meta +
+ * StoryObj 単位で `.stories.tsx` を書き、 storybook が collect して registry
+ * を作る。 mock はその registry 相当を in-memory Map で表現する。
+ *
+ * 使い方 ...
+ * ```ts
+ * const registry = createStoryRegistry();
+ * registry.register({
+ *   title: 'Button',
+ *   render: (args) => createNode('button', { text: args.label }),
+ *   stories: {
+ *     Primary: { args: { label: 'Click me' } },
+ *     Disabled: { args: { label: 'nope', disabled: true } },
+ *   },
+ * });
+ * const canvas = await registry.mount('Button', 'Primary');
+ * await registry.play('Button', 'Primary', canvas);
+ * ```
+ *
+ * SB8 の実 API 互換で意識するのは (1) StoryObj.args の merge (2) play の
+ * step wrapper (3) parameters.chromatic / parameters.a11y の透過保持
+ * の 3 点。 実 SB8 の docs mode / decorators / loaders / addons は mock 対象外
+ * (テストが吸収する semantic は絞る)。
+ */
+interface StoryMeta<TArgs = Record<string, unknown>> {
+    /** Storybook の title (e.g. 'Components/Button')。 */
+    title: string;
+    /** args → MockNode の render 関数、 framework agnostic。 */
+    render: ComponentRender<TArgs>;
+    /** meta 単位の default args (story 単位で override 可)。 */
+    args?: Partial<TArgs>;
+    /** meta 単位の default parameters (story 単位で shallow merge)。 */
+    parameters?: StoryParameters;
+    /** 登録する story 群、 key が story 名になる。 */
+    stories: Record<string, StoryObj<TArgs>>;
+}
+interface StoryMountResult {
+    canvas: CanvasElement;
+    entry: StoryEntry<Record<string, unknown>>;
+}
+interface StoryPlayResult {
+    steps: Array<{
+        label: string;
+        ok: boolean;
+        error?: string;
+    }>;
+    ok: boolean;
+}
+interface StoryRegistry {
+    register<TArgs>(meta: StoryMeta<TArgs>): void;
+    list(): StoryEntry[];
+    get(title: string, storyName: string): StoryEntry;
+    mount(title: string, storyName: string, overrideArgs?: Record<string, unknown>): StoryMountResult;
+    play(title: string, storyName: string, canvas: CanvasElement, args?: Record<string, unknown>): Promise<StoryPlayResult>;
+    runA11y(title: string, storyName: string, canvas: CanvasElement): {
+        violations: A11yViolation[];
+    };
+}
+/**
+ * Registry を新規作成する。 内部は `Map<storyId, StoryEntry>`、 story id は
+ * `title--storyName` (Storybook 8 の SB URL param 互換 lowercase / kebab-case)。
+ */
+declare function createStoryRegistry(): StoryRegistry;
+
+/**
+ * Playwright Component Testing (CT) 互換の最小 mock。 real Playwright CT は
+ * `mount(component)` → `Locator` を返し、 `page.getByText().click()` 等で
+ * interact する。 mock は同じ API 表面 (mount / getByText / getByRole / click /
+ * fill / textContent / count) を持ち、 real vs mock で同じ test を回せる。
+ *
+ * 実 Playwright CT との差分 = (1) browser process を起動しない (in-memory)、
+ * (2) network request の intercept / route は非 support (別の kiwa mock で
+ * 対応)、 (3) screenshot は Chromatic 経路に一本化する。
+ *
+ * 使い方 ...
+ * ```ts
+ * const ct = createPlaywrightCTMock();
+ * const button = ct.mount((args) => createNode('button', { text: args.label, on: { click: args.onClick } }), { label: 'ok', onClick: () => hits++ });
+ * await button.getByRole('button', { name: 'ok' }).click();
+ * expect(hits).toBe(1);
+ * ```
+ */
+interface PlaywrightCTMock {
+    mount<TArgs>(render: ComponentRender<TArgs>, args: TArgs): ComponentLocator;
+    /** mount 済 locator 一覧 (test teardown で全 unmount する時使う)。 */
+    activeMounts(): number;
+    /** 全 mount を解放する — vitest afterEach 相当の cleanup。 */
+    unmountAll(): void;
+}
+/**
+ * PlaywrightCTMock を新規作成する。 mount 毎に in-memory canvas を組み、
+ * ComponentLocator に wrap して返す。 activeMounts count は resource leak
+ * 検出用 (test で unmount 忘れを assert できる)。
+ */
+declare function createPlaywrightCTMock(): PlaywrightCTMock;
+
+/**
+ * Chromatic 型の visual regression mock。 real Chromatic は Storybook 8 を
+ * headless で snapshot 撮り、 baseline JSON を server 側に置いて diff を
+ * pixel single で計算する。 mock harness は browser を起動せず、 mount 後の
+ * MockNode を `renderMarkup` で pseudo-HTML 化 → SHA-256 hash → hash 比較で
+ * changed 判定を行う (pixel diff は hash 完全一致 = 0、 不一致 = 1、
+ * partial diff の連続値は mock 対象外)。
+ *
+ * mock で意味のある semantic は 4 つ ...
+ * (1) baseline capture (未登録なら status='new'、 hash を保存)
+ * (2) current capture + diff (hash 一致で passed、 不一致で failed / changed)
+ * (3) diffThreshold の適用 (StoryEntry.parameters.chromatic.diffThreshold)
+ * (4) accept / reject workflow (accept で baseline を current で置換)
+ *
+ * multi viewport support = parameters.chromatic.viewports に列挙された viewport
+ * 名を 1 回ずつ capture し、 viewport × storyId 単位で baseline / diff を管理。
+ */
+interface ChromaticVisualMock {
+    /** baseline / current 群を全 clear。 test 間の isolation 用。 */
+    reset(): void;
+    /** baseline を明示 seed (test setup で初期状態を作る時使う)。 */
+    seedBaseline(input: {
+        storyId: string;
+        viewport: string;
+        markup: string;
+        capturedAt?: number;
+    }): VisualBaseline;
+    /** 1 story × 1 viewport を capture、 baseline 不在なら status='new'。 */
+    capture(input: {
+        entry: StoryEntry;
+        canvas: CanvasElement;
+        viewport?: string;
+        now?: number;
+    }): VisualDiff;
+    /**
+     * 1 story を parameters.chromatic.viewports 全 viewport で一括 capture。
+     * viewports 未指定 or 空なら 'default' viewport 1 件のみ。 disabled story は
+     * skip (空配列を返す)。
+     */
+    captureAll(input: {
+        entry: StoryEntry;
+        canvas: CanvasElement;
+        now?: number;
+    }): VisualDiff[];
+    /** accept / reject 1 件。 accept は baseline を current 相当で置換する。 */
+    review(input: {
+        storyId: string;
+        viewport: string;
+        action: VisualReviewAction;
+        reviewedAt?: number;
+    }): VisualReviewEntry;
+    /** review 履歴一覧 (test で workflow を assert する時使う)。 */
+    reviewHistory(): VisualReviewEntry[];
+    /** baseline 一覧 (test 用 introspection)。 */
+    baselines(): VisualBaseline[];
+}
+/**
+ * ChromaticVisualMock を新規作成する。 baseline / current / review を全て
+ * in-memory Map で保持し、 reset() で全 clear できる (test isolation 用)。
+ */
+declare function createChromaticVisualMock(config?: ChromaticConfig): ChromaticVisualMock;
+interface ChromaticConfig {
+    /** viewport 名の default (未指定 story の 1 件 capture 時に使う)。 */
+    defaultViewport?: string;
+    /** parameters.chromatic.diffThreshold 未指定時の default。 default = 0 (完全一致で pass)。 */
+    defaultDiffThreshold?: number;
+    /** capturedAt / reviewedAt 用の deterministic time source (test 決定性)。 */
+    now?: () => number;
+}
+
+/**
+ * 5 pattern の共通 component fixture。 Storybook story / Playwright CT mount /
+ * Chromatic capture の 3 経路で共有できる framework agnostic renderer。 実 SB /
+ * PW CT / Chromatic に持込む時は各 framework (React / Vue / Svelte / Solid) の
+ * component として書換えるが、 test だけ回す用途はこの fixture で完結する。
+ *
+ * 5 pattern の選定理由 = SaaS frontend で頻出する 5 primitive を全 cover する。
+ * - Button (interactive、 click event、 disabled state)
+ * - Input (controlled、 input event、 label association)
+ * - Form (submit event、 field 集約、 validation)
+ * - Modal (open/close state、 backdrop click、 escape close)
+ * - Card (content wrapping、 title + body、 optional footer)
+ */
+interface ButtonArgs {
+    label: string;
+    disabled?: boolean;
+    variant?: 'primary' | 'secondary' | 'danger';
+    onClick?: (event: MockEvent) => void;
+}
+/**
+ * Button — text label + optional click handler + disabled state。
+ * variant は class 属性に反映 (chromatic diff で variant 別 baseline を持てる)。
+ */
+declare const buildButton: ComponentRender<ButtonArgs>;
+interface InputArgs {
+    id: string;
+    label: string;
+    value?: string;
+    type?: 'text' | 'email' | 'password' | 'number';
+    required?: boolean;
+    placeholder?: string;
+    onChange?: (event: MockEvent) => void;
+}
+/**
+ * Input — label + input の pair、 label[for] で id を関連付ける (a11y label
+ * rule を pass する)。 onChange は input event で発火。
+ */
+declare const buildInput: ComponentRender<InputArgs>;
+interface FormField {
+    id: string;
+    label: string;
+    type?: InputArgs['type'];
+    required?: boolean;
+    value?: string;
+}
+interface FormArgs {
+    title: string;
+    fields: FormField[];
+    submitLabel?: string;
+    onSubmit?: (data: Record<string, string>) => void;
+}
+/**
+ * Form — title + 複数 input + submit button。 submit 時に全 field の value を
+ * 集めて onSubmit に渡す。 required field 未入力なら submit を発火しない
+ * (validation)、 UI 側で「必須」 表示を出す責務。
+ */
+declare const buildForm: ComponentRender<FormArgs>;
+interface ModalArgs {
+    open: boolean;
+    title: string;
+    body: string;
+    onClose?: () => void;
+    closeOnBackdrop?: boolean;
+}
+/**
+ * Modal — open=false なら空 div を返す (closed 状態を表現)。 open=true で
+ * backdrop + dialog を組む。 backdrop click / close button click で
+ * onClose を発火。
+ */
+declare const buildModal: ComponentRender<ModalArgs>;
+interface CardArgs {
+    title: string;
+    body: string;
+    footer?: string;
+    variant?: 'default' | 'outlined' | 'elevated';
+}
+/**
+ * Card — title / body / optional footer の 3 slot。 chromatic diff で variant
+ * 別 baseline を持つ用途の代表 pattern。
+ */
+declare const buildCard: ComponentRender<CardArgs>;
+/** 全 component の render function を 1 record にまとめる (test 一括登録用)。 */
+declare const componentFixtures: Record<string, ComponentRender<Record<string, unknown>>>;
+
+export { type A11yViolation, type ButtonArgs, type CanvasElement, type CardArgs, type ChromaticConfig, type ChromaticVisualMock, type ComponentLocator, type ComponentProvider, type ComponentRender, type FormArgs, type FormField, type InputArgs, type MockEvent, type MockNode, type ModalArgs, type NodeLocator, type NodeOptions, type PlayContext, type PlaywrightCTMock, type StoryEntry, type StoryMeta, type StoryMountResult, type StoryObj, type StoryParameters, type StoryPlayResult, type StoryRegistry, type VisualBaseline, type VisualDiff, type VisualReviewAction, type VisualReviewEntry, addHandler, appendChild, buildButton, buildCard, buildForm, buildInput, buildModal, componentFixtures, createCanvas, createChromaticVisualMock, createNode, createPlaywrightCTMock, createStoryRegistry, findByRole, findByText, fireEvent, hashMarkup, query, renderMarkup };