Add help dialog

src/app/app.component.html

@@ -2,6 +2,15 @@
   <amaze-logo [sizePx]="36" [color]="iconColor" />
 
   <div>
+    <button
+      class="material-symbols icon-button"
+      title="Instructions"
+      (click)="showHelpDialog()"
+      data-test-id="help-dialog-button"
+    >
+      help
+    </button>
+
     <button
       class="material-symbols icon-button"
       title="Solve the maze"
@@ -61,3 +70,24 @@
 <div class="snack-bar" [class.visible]="snackBarText()">
   {{ snackBarText() }}
 </div>
+
+<dialog #helpDialog (click)="closeHelpDialog($event)">
+  <div class="dialog-header">
+    <h2>Instructions</h2>
+    <button class="material-symbols icon-button" (click)="helpDialog.close()">
+      close
+    </button>
+  </div>
+
+  <p>Use your arrow or WASD keys to move through the maze.</p>
+
+  <p>
+    Click the <i class="material-symbols">conversion_path</i> button to solve
+    the maze.
+  </p>
+
+  <p>
+    Click the <i class="material-symbols">refresh</i> button to generate a new
+    maze.
+  </p>
+</dialog>

src/app/app.component.scss

@@ -40,3 +40,31 @@ header {
     opacity: 1;
   }
 }
+
+dialog {
+  background: var(--dialog-background-color);
+  color: inherit;
+  left: 50%;
+  position: absolute;
+  top: 50%;
+  transform: translate(-50%, -50%);
+  width: 40%;
+
+  &::backdrop {
+    background: #000;
+    opacity: 0.3;
+
+    ::ng-deep .dark-mode & {
+      opacity: 0.8;
+    }
+  }
+
+  .dialog-header {
+    display: flex;
+    justify-content: space-between;
+  }
+
+  p {
+    margin: 1rem 0;
+  }
+}

src/app/app.component.spec.ts

@@ -164,6 +164,38 @@ describe('AppComponent', () => {
     });
   });
 
+  describe('help dialog', () => {
+    const openDialog = () =>
+      fixture.debugElement
+        .query(By.css('[data-test-id="help-dialog-button"]'))
+        .nativeElement.click();
+
+    const getDialog = () =>
+      fixture.debugElement.query(By.css('dialog'))
+        .nativeElement as HTMLDialogElement;
+
+    beforeEach(() => {
+      fixture.detectChanges();
+    });
+
+    it('should be opened by the help dialog button', () => {
+      openDialog();
+      expect(getDialog().open).toBeTrue();
+    });
+
+    it('should be closed by its close button', () => {
+      openDialog();
+      getDialog().querySelector('button')?.click();
+      expect(getDialog().open).toBeFalse();
+    });
+
+    it('should be closed by clicking outside of the dialog', () => {
+      openDialog();
+      (document.elementFromPoint(0, 0)! as HTMLElement).click();
+      expect(getDialog().open).toBeFalse();
+    });
+  });
+
   describe('solve maze button', () => {
     it('should use the GameStateService to solve the maze with an animation', () => {
       fixture.debugElement

src/app/app.component.ts

@@ -7,6 +7,7 @@ import {
   signal,
   ElementRef,
   effect,
+  ViewChild,
 } from '@angular/core';
 
 import { MazeComponent } from './maze/maze.component';
@@ -51,6 +52,8 @@ export class AppComponent implements OnInit {
   /** Whether the viewport is too small to use the app. */
   viewportTooSmall = signal(false);
 
+  @ViewChild('helpDialog') readonly helpDialog!: ElementRef<HTMLDialogElement>;
+
   constructor() {
     // When the user reaches the end of the maze, show a confetti animation.
     effect(() => {
@@ -104,6 +107,27 @@ export class AppComponent implements OnInit {
     return this.gameStateService.maze;
   }
 
+  /** Show the help dialog. */
+  showHelpDialog(): void {
+    this.helpDialog.nativeElement.showModal();
+  }
+
+  /**
+   * Close the dialog if the provided mouse event occurred outside the dialog element's bounding
+   * rect.
+   */
+  closeHelpDialog(evt: MouseEvent): void {
+    const rect = this.helpDialog.nativeElement.getBoundingClientRect();
+
+    const clickedInDialog =
+      rect.top <= evt.clientY &&
+      evt.clientY <= rect.top + rect.height &&
+      rect.left <= evt.clientX &&
+      evt.clientX <= rect.left + rect.width;
+
+    if (!clickedInDialog) this.helpDialog.nativeElement.close();
+  }
+
   /** Solves the maze and displays the solution. */
   solveMaze(): void {
     if (this.gameStateService.inAnimation) return;

src/styles.scss

@@ -15,6 +15,7 @@ body {
   --background-color: white;
   --border-color: black;
   --current-position-color: #204ed6;
+  --dialog-background-color: #fffffff0;
   --hover-color: rgba(0, 0, 0, 0.2);
   --path-color: #87ceea;
   --text-color: black;
@@ -27,6 +28,7 @@ body {
     --background-color: #060606;
     --border-color: white;
     --current-position-color: #ff2b2b;
+    --dialog-background-color: #000000f0;
     --hover-color: rgba(255, 255, 255, 0.2);
     --path-color: #f08080;
     --text-color: white;
@@ -57,6 +59,11 @@ a {
   }
 }
 
+i {
+  font-style: normal;
+  vertical-align: bottom;
+}
+
 .material-symbols {
   font-family: 'Material Symbols Outlined';
 }