Angular UI パターン

コア原則

1. 古いUIを決して表示しない - 実際にロード中の場合のみロード状態を表示
2. 常にエラーを表示する - ユーザーは何か失敗したことを知る必要があります
3. 楽観的な更新 - UIを瞬時に感じさせる
4. 段階的な情報開示 - @defer を使用して利用可能な内容を表示
5. 段階的な機能低下 - 部分的なデータはデータがないよりは良い

---

ロード状態パターン

黄金ルール

表示するデータがない場合に限り、ロード指示器を表示してください。

@Component({
  template: `
    @if (error()) {
      <app-error-state [error]="error()" (retry)="load()" />
    } @else if (loading() && !items().length) {
      <app-skeleton-list />
    } @else if (!items().length) {
      <app-empty-state message="No items found" />
    } @else {
      <app-item-list [items]="items()" />
    }
  `,
})
export class ItemListComponent {
  private store = inject(ItemStore);

  items = this.store.items;
  loading = this.store.loading;
  error = this.store.error;
}

ロード状態判定フロー図

エラーが発生していますか?
  → はい: リトライオプション付きのエラー状態を表示
  → いいえ: 続行

ロード中で、かつデータがありませんか?
  → はい: ロード指示器（スピナー/スケルトン）を表示
  → いいえ: 続行

データがありますか?
  → はい、アイテムあり: データを表示
  → はい、ただし空: 空状態を表示
  → いいえ: ロード状態を表示（フォールバック）

スケルトン vs スピナー

スケルトンを使用する場合	スピナーを使用する場合
既知のコンテンツ形状	未知のコンテンツ形状
リスト/カードレイアウト	モーダルアクション
初期ページロード	ボタン送信
コンテンツプレースホルダー	インライン操作

---

制御フローパターン

条件付きレンダリング用 @if/@else

@if (user(); as user) {
<span>Welcome, {{ user.name }}</span>
} @else if (loading()) {
<app-spinner size="small" />
} @else {
<a routerLink="/login">Sign In</a>
}

@for とトラック

@for (item of items(); track item.id) {
<app-item-card [item]="item" (delete)="remove(item.id)" />
} @empty {
<app-empty-state
  icon="inbox"
  message="No items yet"
  actionLabel="Create Item"
  (action)="create()"
/>
}

段階的なロード用 @defer

<!-- 重要なコンテンツは即座にロード -->
<app-header />
<app-hero-section />

<!-- 重要でないコンテンツは遅延ロード -->
@defer (on viewport) {
<app-comments [postId]="postId()" />
} @placeholder {
<div class="h-32 bg-gray-100 animate-pulse"></div>
} @loading (minimum 200ms) {
<app-spinner />
} @error {
<app-error-state message="Failed to load comments" />
}

---

エラーハンドリングパターン

エラーハンドリング階層

1. インラインエラー（フィールドレベル） → フォーム検証エラー
2. トースト通知 → 回復可能なエラー、ユーザーが再試行可能
3. エラーバナー → ページレベルのエラー、データは部分的に使用可能
4. 全画面エラー → 回復不可、ユーザーアクションが必要

常にエラーを表示

重要: エラーを黙ったまま飲み込まないでください。

// 正しい - エラーは常にユーザーに表示される
@Component({...})
export class CreateItemComponent {
  private store = inject(ItemStore);
  private toast = inject(ToastService);

  async create(data: CreateItemDto) {
    try {
      await this.store.create(data);
      this.toast.success('Item created successfully');
      this.router.navigate(['/items']);
    } catch (error) {
      console.error('createItem failed:', error);
      this.toast.error('Failed to create item. Please try again.');
    }
  }
}

// 間違い - エラーが黙ったまま処理される
async create(data: CreateItemDto) {
  try {
    await this.store.create(data);
  } catch (error) {
    console.error(error); // ユーザーには何も見えない！
  }
}

エラー状態コンポーネントパターン

@Component({
  selector: "app-error-state",
  standalone: true,
  imports: [NgOptimizedImage],
  template: `
    <div class="error-state">
      <img ngSrc="/assets/error-icon.svg" width="64" height="64" alt="" />
      <h3>{{ title() }}</h3>
      <p>{{ message() }}</p>
      @if (retry.observed) {
        <button (click)="retry.emit()" class="btn-primary">Try Again</button>
      }
    </div>
  `,
})
export class ErrorStateComponent {
  title = input("Something went wrong");
  message = input("An unexpected error occurred");
  retry = output<void>();
}

---

ボタン状態パターン

ボタンロード状態

<button
  (click)="handleSubmit()"
  [disabled]="isSubmitting() || !form.valid"
  class="btn-primary"
>
  @if (isSubmitting()) {
  <app-spinner size="small" class="mr-2" />
  Saving... } @else { Save Changes }
</button>

非同期操作中の無効化

重要: 非同期操作中は常にトリガーを無効にしてください。

// 正しい - ロード中はボタンが無効
@Component({
  template: `
    <button
      [disabled]="saving()"
      (click)="save()"
    >
      @if (saving()) {
        <app-spinner size="sm" /> Saving...
      } @else {
        Save
      }
    </button>
  `
})
export class SaveButtonComponent {
  saving = signal(false);

  async save() {
    this.saving.set(true);
    try {
      await this.service.save();
    } finally {
      this.saving.set(false);
    }
  }
}

// 間違い - ユーザーは複数回クリック可能
<button (click)="save()">
  {{ saving() ? 'Saving...' : 'Save' }}
</button>

---

空状態

空状態の要件

すべてのリスト/コレクションには空状態が必須です:

@for (item of items(); track item.id) {
<app-item-card [item]="item" />
} @empty {
<app-empty-state
  icon="folder-open"
  title="No items yet"
  description="Create your first item to get started"
  actionLabel="Create Item"
  (action)="openCreateDialog()"
/>
}

コンテキストに応じた空状態

@Component({
  selector: "app-empty-state",
  template: `
    <div class="empty-state">
      <span class="icon" [class]="icon()"></span>
      <h3>{{ title() }}</h3>
      <p>{{ description() }}</p>
      @if (actionLabel()) {
        <button (click)="action.emit()" class="btn-primary">
          {{ actionLabel() }}
        </button>
      }
    </div>
  `,
})
export class EmptyStateComponent {
  icon = input("inbox");
  title = input.required<string>();
  description = input("");
  actionLabel = input<string | null>(null);
  action = output<void>();
}

---

フォームパターン

ロードと検証を含むフォーム

@Component({
  template: `
    <form [formGroup]="form" (ngSubmit)="onSubmit()">
      <div class="form-field">
        <label for="name">Name</label>
        <input
          id="name"
          formControlName="name"
          [class.error]="isFieldInvalid('name')"
        />
        @if (isFieldInvalid("name")) {
          <span class="error-text">
            {{ getFieldError("name") }}
          </span>
        }
      </div>

      <div class="form-field">
        <label for="email">Email</label>
        <input id="email" type="email" formControlName="email" />
        @if (isFieldInvalid("email")) {
          <span class="error-text">
            {{ getFieldError("email") }}
          </span>
        }
      </div>

      <button type="submit" [disabled]="form.invalid || submitting()">
        @if (submitting()) {
          <app-spinner size="sm" /> Submitting...
        } @else {
          Submit
        }
      </button>
    </form>
  `,
})
export class UserFormComponent {
  private fb = inject(FormBuilder);

  submitting = signal(false);

  form = this.fb.group({
    name: ["", [Validators.required, Validators.minLength(2)]],
    email: ["", [Validators.required, Validators.email]],
  });

  isFieldInvalid(field: string): boolean {
    const control = this.form.get(field);
    return control ? control.invalid && control.touched : false;
  }

  getFieldError(field: string): string {
    const control = this.form.get(field);
    if (control?.hasError("required")) return "This field is required";
    if (control?.hasError("email")) return "Invalid email format";
    if (control?.hasError("minlength")) return "Too short";
    return "";
  }

  async onSubmit() {
    if (this.form.invalid) return;

    this.submitting.set(true);
    try {
      await this.service.submit(this.form.value);
      this.toast.success("Submitted successfully");
    } catch {
      this.toast.error("Submission failed");
    } finally {
      this.submitting.set(false);
    }
  }
}

---

ダイアログ/モーダルパターン

確認ダイアログ

// dialog.service.ts
@Injectable({ providedIn: 'root' })
export class DialogService {
  private dialog = inject(Dialog); // CDK Dialog またはカスタム

  async confirm(options: {
    title: string;
    message: string;
    confirmText?: string;
    cancelText?: string;
  }): Promise<boolean> {
    const dialogRef = this.dialog.open(ConfirmDialogComponent, {
      data: options,
    });

    return await firstValueFrom(dialogRef.closed) ?? false;
  }
}

// 使用方法
async deleteItem(item: Item) {
  const confirmed = await this.dialog.confirm({
    title: 'Delete Item',
    message: `Are you sure you want to delete "${item.name}"?`,
    confirmText: 'Delete',
  });

  if (confirmed) {
    await this.store.delete(item.id);
  }
}

---

アンチパターン

ロード状態

// 間違い - データが存在する時にスピナーを表示（リフェッチ時にフラッシュが発生）
@if (loading()) {
  <app-spinner />
}

// 正しい - データがない場合のみロード状態を表示
@if (loading() && !items().length) {
  <app-spinner />
}

エラーハンドリング

// 間違い - エラーが無視される
try {
  await this.service.save();
} catch (e) {
  console.log(e); // ユーザーは何も知らない！
}

// 正しい - エラーが表示される
try {
  await this.service.save();
} catch (e) {
  console.error("Save failed:", e);
  this.toast.error("Failed to save. Please try again.");
}

ボタン状態

<!-- 間違い - 送信中にボタンが無効にされていない -->
<button (click)="submit()">Submit</button>

<!-- 正しい - 無効で、ロード中を表示 -->
<button (click)="submit()" [disabled]="loading()">
  @if (loading()) {
  <app-spinner size="sm" />
  } Submit
</button>

---

UI 状態チェックリスト

コンポーネント完成前に確認してください:

UI 状態

• エラー状態が処理され、ユーザーに表示される
• ロード状態はデータが存在しない場合のみ表示される
• コレクション用に空状態が提供されている（@empty ブロック）
• 非同期操作中はボタンが無効になる
• 必要に応じてボタンがロード指示器を表示する

データと変更

• すべての非同期操作にエラーハンドリングがある
• すべてのユーザーアクションにフィードバックがある（トースト/ビジュアル）
• 楽観的な更新は失敗時にロールバックする

アクセシビリティ

• ロード状態がスクリーンリーダーにアナウンスされる
• エラーメッセージがフォームフィールドにリンクされている
• 状態変更後のフォーカス管理が行われている

---

他のスキルとの統合

• angular-state-management: State管理用に Signal ストアを使用
• angular: モダンパターン（Signals、@defer）を適用
• testing-patterns: すべての UI 状態をテスト

使用する場合

このスキルは概要に記載されたワークフローまたはアクションを実行する際に適用されます。

制限事項

• このスキルは上記の説明に明確に合致するタスクのみで使用してください。
• 出力を環境固有の検証、テスト、または専門家のレビューの代替として扱わないでください。
• 必要な入力、権限、安全境界、または成功基準が不足している場合は、立ち止まって明確化を求めてください。