From 805c2f115025c36474e85f746c7b18899d1b1bc2 Mon Sep 17 00:00:00 2001 From: Owen Rees Date: Mon, 9 Nov 2026 12:09:07 +0100 Subject: [PATCH] Accessibility: keyboard move entry and screen reader support (#72) (#115) * commented out lesson and learning strip until lessons are established * reword the hero section * change layout and working on puzzle section - remove top div as it was redundant * amend flash message on replay * switch cancel session for return home * remove system theme toggle since this is the default, leaving only light and dark toggles * add keyboard and screen reader support for play (#72) First draft covering the accessibility work in #72:\n\n- labelled SAN/UCI move input, validated against the tablebase and applied\n by the board hook, plus an accessible promotion picker\n- live-region announcements for moves, checks, checkmates and solve/fail,\n and a hidden text summary of the position\n- accessible labels, focus ring, skip link, keyboard-friendly review table\n and non-colour grade cues\n- WCAG AA text contrast roles and a responsive play surface\n- regression tests for move entry, announcements and link-style CTAs --- assets/css/base/_globals.css | 4 + assets/css/base/_theme.css | 10 +- assets/css/components/_board.css | 9 +- assets/js/hooks/chessBoard.js | 81 ++++- .../components/board/board_component.ex | 8 +- .../components/board/piece_component.ex | 2 +- .../components/board/position_text.ex | 93 ++++++ .../components/core_components.ex | 10 +- .../components/endgame_list.ex | 1 + .../components/landing_components.ex | 26 +- lib/chesstrainer_web/components/layouts.ex | 28 +- .../components/layouts/root.html.heex | 6 + .../components/layouts/theme_script.html.heex | 30 +- .../components/play_components.ex | 292 +++++++++++++++--- .../controllers/page_html/home.html.heex | 25 +- .../live/endgame_live/guest_train.ex | 12 + .../live/endgame_live/index.ex | 2 +- .../live/endgame_live/play.ex | 16 +- .../live/endgame_live/play_core.ex | 113 ++++++- .../live/endgame_live/show.ex | 5 +- .../live/endgame_live/train.ex | 16 +- lib/chesstrainer_web/live/user_live/login.ex | 4 +- .../live/user_live/profile.ex | 2 +- .../live/user_live/registration.ex | 5 +- .../live/user_live/reset_password.ex | 2 +- .../components/landing_components_test.exs | 8 + .../components/layouts_test.exs | 13 +- .../components/position_text_test.exs | 27 ++ .../controllers/page_controller_test.exs | 14 +- .../live/endgame_live/play_test.exs | 82 ++++- .../live/endgame_live/train_test.exs | 2 +- 31 files changed, 812 insertions(+), 136 deletions(-) create mode 100644 lib/chesstrainer_web/components/board/position_text.ex create mode 100644 test/chesstrainer_web/components/position_text_test.exs diff --git a/assets/css/base/_globals.css b/assets/css/base/_globals.css index fb6af15..6bd3c3b 100644 --- a/assets/css/base/_globals.css +++ b/assets/css/base/_globals.css @@ -16,6 +16,10 @@ } button, a { -webkit-tap-highlight-color: transparent; } button { cursor: pointer; } + + /* A consistent focus ring for links, buttons and native controls. Components + that provide their own ring (form inputs) override this through utilities. */ + :focus-visible { outline: 2px solid var(--color-coral-text); outline-offset: 2px; } } main { overflow: hidden; flex: 1 0 auto; } diff --git a/assets/css/base/_theme.css b/assets/css/base/_theme.css index 332554a..d132086 100644 --- a/assets/css/base/_theme.css +++ b/assets/css/base/_theme.css @@ -10,8 +10,11 @@ --color-coral: var(--coral); --color-coral-control: var(--coral); --color-coral-control-hover: var(--coral-dark); - --color-coral-text: var(--coral-dark); - --color-success-text: var(--mint-deep); + --color-coral-text: #b8432c; + --color-success-text: #3f6d5a; + --color-warning-text: #8a5a00; + --color-primary-text: #b8432c; + --color-error-text: #b8432c; --color-mint-chip: var(--mint); --color-on-accent-muted: #5f2c23; @@ -71,6 +74,9 @@ html[data-theme="dark"] { --color-coral-control-hover: #b8432c; --color-coral-text: #ff9c85; --color-success-text: #8fd3b5; + --color-warning-text: #f0b35a; + --color-primary-text: #f2816b; + --color-error-text: #f2816b; --color-mint-chip: #24403a; --color-on-accent-muted: rgba(255, 255, 255, 0.97); --color-promotion-surface: #1b2822; diff --git a/assets/css/components/_board.css b/assets/css/components/_board.css index fb94a80..9fb30e0 100644 --- a/assets/css/components/_board.css +++ b/assets/css/components/_board.css @@ -38,4 +38,11 @@ /* Admin Chessboard */ .bg-boardwhite { background-color: #f2f5f3; /* light square */ } -.bg-boardblack { background-color: #71828f; /* dark square */ } \ No newline at end of file +.bg-boardblack { background-color: #71828f; /* dark square */ } + +/* Play board */ +#endgame-board { position: relative; } + +/* Chessground's wrapper has no intrinsic height; let it fill the sized + aspect-ratio container so the board scales with the viewport. */ +#endgame-board .cg-wrap { width: 100%; height: 100%; } \ No newline at end of file diff --git a/assets/js/hooks/chessBoard.js b/assets/js/hooks/chessBoard.js index 6c6f030..6896ad0 100644 --- a/assets/js/hooks/chessBoard.js +++ b/assets/js/hooks/chessBoard.js @@ -22,7 +22,20 @@ export const ChessBoard = { this.applyBestLineMove({ from, to, promotion, san }); }); + this.handleEvent("apply_move", ({ from, to, promotion }) => { + if (this.reviewing) return; + this.executeMove(from, to, promotion); + }); + this.handleKeyDown = (event) => { + if (this.pendingPromotion) { + if (event.key === "Escape") { + event.preventDefault(); + this.cancelPromotion(); + } + return; + } + if (!this.reviewing) return; if (event.key === "ArrowLeft") { @@ -31,6 +44,12 @@ export const ChessBoard = { } else if (event.key === "ArrowRight") { event.preventDefault(); this.pushEvent("review_next", {}); + } else if (event.key === "Home") { + event.preventDefault(); + this.pushEvent("review_start", {}); + } else if (event.key === "End") { + event.preventDefault(); + this.pushEvent("review_end", {}); } }; @@ -185,9 +204,13 @@ export const ChessBoard = { showPromotionDialog(orig, dest) { this.pendingPromotion = { orig, dest }; + this.previousFocus = document.activeElement; const color = this.chess.turn() === "w" ? "white" : "black"; const overlay = document.createElement("div"); overlay.className = "promotion-overlay"; + overlay.setAttribute("role", "dialog"); + overlay.setAttribute("aria-modal", "true"); + overlay.setAttribute("aria-label", "Choose a promotion piece"); const picker = document.createElement("div"); picker.className = "promotion-picker"; const pieces = [ @@ -198,22 +221,64 @@ export const ChessBoard = { ]; pieces.forEach(({ type, code }) => { const btn = document.createElement("button"); + btn.type = "button"; btn.className = `promotion-piece ${type} ${color}`; + btn.setAttribute("aria-label", `Promote to ${type}`); btn.addEventListener("click", () => this.completePromotion(code)); picker.appendChild(btn); }); + overlay.addEventListener("keydown", (event) => { + if (event.key === "Escape") { + event.preventDefault(); + this.cancelPromotion(); + return; + } + + if (event.key !== "Tab") return; + + const buttons = Array.from(picker.querySelectorAll("button")); + const first = buttons[0]; + const last = buttons[buttons.length - 1]; + + if (event.shiftKey && document.activeElement === first) { + event.preventDefault(); + last.focus(); + } else if (!event.shiftKey && document.activeElement === last) { + event.preventDefault(); + first.focus(); + } + }); overlay.appendChild(picker); - const boardContainer = this.el.closest(".shadow-inner"); - boardContainer.style.position = "relative"; - boardContainer.appendChild(overlay); + const container = this.el.parentElement; + container.style.position = "relative"; + container.appendChild(overlay); + picker.querySelector("button")?.focus(); + }, + + cancelPromotion() { + this.pendingPromotion = null; + const overlay = this.el.parentElement?.querySelector(".promotion-overlay"); + if (overlay) overlay.remove(); + this.restoreFocus(); + }, + + restoreFocus() { + if (this.previousFocus instanceof HTMLElement) { + this.previousFocus.focus(); + } else { + document.getElementById("move-input")?.focus(); + } + + this.previousFocus = null; }, completePromotion(pieceType) { const { orig, dest } = this.pendingPromotion; this.pendingPromotion = null; - const picker = this.el.closest(".shadow-inner")?.querySelector(".promotion-overlay"); + const picker = this.el.parentElement?.querySelector(".promotion-overlay"); if (picker) picker.remove(); this.executeMove(orig, dest, pieceType); + document.getElementById("move-input")?.focus(); }, executeMove(orig, dest, promotion) { @@ -234,6 +299,7 @@ export const ChessBoard = { san: move.san, promotion: promotion || null, draw: this.chess.isDraw(), + check: this.chess.isCheck(), checkmate: this.chess.isCheckmate(), }; @@ -252,8 +318,14 @@ export const ChessBoard = { ? { color: null, dests: new Map() } : { color: nextTurnColor, dests: this.getValidDests() }, }); + + return true; } else { this.ground.set({ fen: this.chess.fen() }); + this.pushEvent("move_input_error", { + message: "That move is not legal in this position.", + }); + return false; } }, @@ -279,6 +351,7 @@ export const ChessBoard = { fen: this.chess.fen(), san: move.san, draw: this.chess.isDraw(), + check: this.chess.isCheck(), checkmate: this.chess.isCheckmate(), }); }, diff --git a/lib/chesstrainer_web/components/board/board_component.ex b/lib/chesstrainer_web/components/board/board_component.ex index cb37619..f406bb7 100644 --- a/lib/chesstrainer_web/components/board/board_component.ex +++ b/lib/chesstrainer_web/components/board/board_component.ex @@ -6,6 +6,8 @@ defmodule ChesstrainerWeb.Board.BoardComponent do use Phoenix.Component import ChesstrainerWeb.Board.SquareComponent + alias ChesstrainerWeb.Board.PositionText + attr :game, :map, required: true attr :myself, :any, default: nil @@ -41,7 +43,11 @@ defmodule ChesstrainerWeb.Board.BoardComponent do ~H"""
-
+