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
This commit is contained in:
2026-11-09 12:09:07 +01:00
committed by GitHub
parent 8df7ac982c
commit 805c2f1150
31 changed files with 812 additions and 136 deletions
@@ -72,6 +72,7 @@ defmodule ChesstrainerWeb.EndgameLive.GuestTrain do
:if={@endgame}
session={is_nil(@limit_reached)}
endgame={@endgame}
fen={@fen}
status={@status}
blocked_reason={@blocked_reason}
best_move={@best_move}
@@ -84,6 +85,10 @@ defmodule ChesstrainerWeb.EndgameLive.GuestTrain do
awaiting_reply={@awaiting_reply}
last_grade={@last_grade}
awaiting_best_line={@awaiting_best_line}
move_input={@move_input}
move_input_error={@move_input_error}
last_check={@last_check}
last_checkmate={@last_checkmate}
/>
<p :if={@loading} class="text-base-content/70">Picking a random puzzle…</p>
@@ -150,6 +155,13 @@ defmodule ChesstrainerWeb.EndgameLive.GuestTrain do
def handle_event("endgame_move_played", params, socket),
do: PlayCore.move_played(socket, params)
def handle_event("submit_move", params, socket), do: PlayCore.submit_move(socket, params)
def handle_event("move_input", params, socket), do: PlayCore.move_input_changed(socket, params)
def handle_event("move_input_error", params, socket),
do: PlayCore.move_input_error(socket, params)
def handle_event("opponent_reply_applied", params, socket),
do: PlayCore.opponent_reply_applied(socket, params)
@@ -43,7 +43,7 @@ defmodule ChesstrainerWeb.EndgameLive.Index do
type="button"
id="clear-endgame-search"
phx-click="clear_search"
class="text-sm text-primary underline underline-offset-4 hover:text-primary/80"
class="text-sm text-primary-text underline underline-offset-4 hover:text-primary-text/80"
>
Clear
</button>
+15 -1
View File
@@ -23,10 +23,12 @@ defmodule ChesstrainerWeb.EndgameLive.Play do
<span>FEN: {@endgame.fen}</span>
<button
id="copy-fen-btn"
type="button"
phx-hook="CopyFen"
data-fen={@endgame.fen}
class="inline-flex items-center cursor-pointer"
class="inline-flex items-center justify-center rounded p-1.5 cursor-pointer"
title="Copy FEN to clipboard"
aria-label="Copy FEN to clipboard"
>
<.icon name="hero-document-duplicate" class="w-3.5 h-3.5" />
</button>
@@ -44,6 +46,7 @@ defmodule ChesstrainerWeb.EndgameLive.Play do
<PlayComponents.play_surface
endgame={@endgame}
fen={@fen}
status={@status}
blocked_reason={@blocked_reason}
best_move={@best_move}
@@ -56,6 +59,10 @@ defmodule ChesstrainerWeb.EndgameLive.Play do
awaiting_reply={@awaiting_reply}
last_grade={@last_grade}
awaiting_best_line={@awaiting_best_line}
move_input={@move_input}
move_input_error={@move_input_error}
last_check={@last_check}
last_checkmate={@last_checkmate}
/>
<div :if={@user_rating} class="mb-4">
@@ -76,6 +83,13 @@ defmodule ChesstrainerWeb.EndgameLive.Play do
def handle_event("endgame_move_played", params, socket),
do: PlayCore.move_played(socket, params)
def handle_event("submit_move", params, socket), do: PlayCore.submit_move(socket, params)
def handle_event("move_input", params, socket), do: PlayCore.move_input_changed(socket, params)
def handle_event("move_input_error", params, socket),
do: PlayCore.move_input_error(socket, params)
def handle_event("opponent_reply_applied", params, socket),
do: PlayCore.opponent_reply_applied(socket, params)
@@ -20,6 +20,8 @@ defmodule ChesstrainerWeb.EndgameLive.PlayCore do
alias Chesstrainer.Endgames.Tablebase
alias Chesstrainer.Ratings
@uci_pattern ~r/^[a-h][1-8][a-h][1-8][qrbn]?$/
@doc """
Loads `endgame` and starts an attempt on it.
@@ -53,6 +55,10 @@ defmodule ChesstrainerWeb.EndgameLive.PlayCore do
|> assign(:last_grade, nil)
|> assign(:awaiting_reply, false)
|> assign(:last_rating_delta, nil)
|> assign(:last_check, false)
|> assign(:last_checkmate, false)
|> assign(:move_input, "")
|> assign(:move_input_error, nil)
|> load_attempt()
end
@@ -60,6 +66,8 @@ defmodule ChesstrainerWeb.EndgameLive.PlayCore do
%{"from" => from, "to" => to, "san" => san} = params
promotion = params["promotion"]
draw = params["draw"] || false
check = params["check"] || false
checkmate = params["checkmate"] || false
prev_fen = params["prev_fen"] || socket.assigns.fen
fen_after = params["fen"] || socket.assigns.fen
@@ -76,16 +84,72 @@ defmodule ChesstrainerWeb.EndgameLive.PlayCore do
put_flash(socket, :error, "That move is out of sequence. Press Reset to try again.")}
true ->
grade_and_record(socket, from, to, promotion, san, fen_after, draw)
grade_and_record(socket, from, to, promotion, san, fen_after, draw, check, checkmate)
end
end
@doc """
Plays the move typed into the keyboard move input.
The tablebase already knows every legal move in the position, so matching SAN
or UCI against it validates the input without a chess engine on the server.
The board hook applies the move and reports it through the normal move events.
"""
def submit_move(socket, %{"move" => input}) do
cond do
socket.assigns.reviewing ->
move_input_rejected(socket, "Leave review to make a move.")
socket.assigns.status != :playing ->
move_input_rejected(socket, "This puzzle is not open for moves right now.")
socket.assigns.awaiting_reply ->
move_input_rejected(socket, "Wait for the opponent's reply.")
true ->
case parse_move_input(socket.assigns.tablebase, input) do
%Tablebase.Move{} = move ->
{:noreply,
socket
|> assign(:move_input, "")
|> assign(:move_input_error, nil)
|> push_event("apply_move", reply_payload(move))}
_ ->
move_input_rejected(
socket,
"Not a legal move here. Try SAN like Nf3, or squares like g1f3."
)
end
end
end
def submit_move(socket, _params), do: {:noreply, socket}
def move_input_changed(socket, %{"move" => value}) when is_binary(value) do
{:noreply, socket |> assign(:move_input, value) |> assign(:move_input_error, nil)}
end
def move_input_changed(socket, _params), do: {:noreply, socket}
def move_input_error(socket, %{"message" => message}) when is_binary(message) do
{:noreply, assign(socket, :move_input_error, message)}
end
def move_input_error(socket, _params), do: {:noreply, socket}
def opponent_reply_applied(socket, params) do
%{"fen" => fen} = params
draw = params["draw"] || false
check = params["check"] || false
checkmate = params["checkmate"] || false
if socket.assigns.awaiting_reply do
socket = record_opponent_ply(socket, fen, params["san"])
socket =
socket
|> record_opponent_ply(fen, params["san"])
|> assign(:last_check, check)
|> assign(:last_checkmate, checkmate)
if draw and socket.assigns.endgame.result == :draw do
solve_attempt(socket)
@@ -100,6 +164,7 @@ defmodule ChesstrainerWeb.EndgameLive.PlayCore do
|> assign(:awaiting_reply, false)
|> assign(:status, :playing)
|> assign(:blocked_reason, nil)
|> assign(:move_input_error, nil)
|> push_event("resume_board", %{})}
other ->
@@ -141,6 +206,10 @@ defmodule ChesstrainerWeb.EndgameLive.PlayCore do
|> assign(:last_from_to, "None yet")
|> assign(:last_grade, nil)
|> assign(:last_rating_delta, nil)
|> assign(:last_check, false)
|> assign(:last_checkmate, false)
|> assign(:move_input, "")
|> assign(:move_input_error, nil)
{:noreply, load_attempt(socket)}
end
@@ -334,7 +403,7 @@ defmodule ChesstrainerWeb.EndgameLive.PlayCore do
"The tablebase is unavailable (#{inspect(reason)})."
end
defp grade_and_record(socket, from, to, promotion, san, fen_after, draw) do
defp grade_and_record(socket, from, to, promotion, san, fen_after, draw, check, checkmate) do
case find_move(socket.assigns.tablebase, from, to, promotion) do
nil ->
{:noreply, put_flash(socket, :error, "Could not identify that move in the tablebase.")}
@@ -354,6 +423,10 @@ defmodule ChesstrainerWeb.EndgameLive.PlayCore do
|> assign(:last_from_to, "#{from} ➔ #{to}")
|> assign(:last_san, san)
|> assign(:last_grade, grade)
|> assign(:last_check, check)
|> assign(:last_checkmate, checkmate)
|> assign(:move_input, "")
|> assign(:move_input_error, nil)
|> assign(:plies, socket.assigns.plies ++ [ply])
cond do
@@ -450,7 +523,7 @@ defmodule ChesstrainerWeb.EndgameLive.PlayCore do
|> assign(:last_rating_delta, nil)
|> put_flash(
:info,
"Replay recorded. Your rating is unchanged because you played this recently."
"Your rating is unchanged because you played this puzzle recently."
)
end
@@ -525,6 +598,38 @@ defmodule ChesstrainerWeb.EndgameLive.PlayCore do
defp find_move_by_uci(_tablebase, _uci), do: nil
defp parse_move_input(%Tablebase{} = tablebase, input) when is_binary(input) do
normalized = input |> String.trim() |> String.downcase() |> String.replace(" ", "")
uci = String.replace(normalized, "-", "")
cond do
normalized == "" -> nil
Regex.match?(@uci_pattern, uci) -> find_move_by_uci(tablebase, uci)
true -> find_move_by_san(tablebase, normalize_san(normalized))
end
end
defp parse_move_input(_tablebase, _input), do: nil
defp find_move_by_san(%Tablebase{moves: moves}, san) when is_list(moves) and is_binary(san) do
Enum.find(moves, &(normalize_san(&1.san) == san))
end
defp find_move_by_san(_tablebase, _san), do: nil
defp normalize_san(san) when is_binary(san) do
san
|> String.downcase()
|> String.replace("=", "")
|> String.replace(~r/[+#!?]/, "")
end
defp normalize_san(_san), do: nil
defp move_input_rejected(socket, message) do
{:noreply, assign(socket, :move_input_error, message)}
end
# Compare only the board and side to move: chess.js may normalise the rest
# (castling/en-passant/halfmove/fullmove) differently from the stored FEN.
defp same_position?(fen_a, fen_b), do: position_key(fen_a) == position_key(fen_b)
@@ -42,7 +42,7 @@ defmodule ChesstrainerWeb.EndgameLive.Show do
</:actions>
</.header>
<.board game={@game} myself="board" />
<.board game={@game} myself="board" interactive={false} />
<.list>
<:item title="Fen">{@endgame.fen}</:item>
@@ -54,8 +54,9 @@ defmodule ChesstrainerWeb.EndgameLive.Show do
type="button"
phx-hook=".CopyPublicCode"
data-code={@endgame.public_code}
class="ml-2 inline-flex cursor-pointer items-center"
class="ml-2 inline-flex cursor-pointer items-center justify-center rounded p-1.5"
title="Copy public code"
aria-label="Copy public code to clipboard"
>
<.icon name="hero-document-duplicate" class="w-3.5 h-3.5" />
</button>
@@ -82,6 +82,7 @@ defmodule ChesstrainerWeb.EndgameLive.Train do
<PlayComponents.play_surface
session={true}
endgame={@endgame}
fen={@fen}
status={@status}
blocked_reason={@blocked_reason}
best_move={@best_move}
@@ -94,6 +95,10 @@ defmodule ChesstrainerWeb.EndgameLive.Train do
awaiting_reply={@awaiting_reply}
last_grade={@last_grade}
awaiting_best_line={@awaiting_best_line}
move_input={@move_input}
move_input_error={@move_input_error}
last_check={@last_check}
last_checkmate={@last_checkmate}
/>
<% else %>
<div class="fixed inset-0 z-50 flex items-center justify-center bg-black/50 p-4">
@@ -164,7 +169,7 @@ defmodule ChesstrainerWeb.EndgameLive.Train do
<% end %>
</div>
<.button navigate={~p"/"} variant="ghost" class="mt-2 w-full justify-center">
Cancel
<.icon name="hero-arrow-left" />Return Home
</.button>
</div>
</div>
@@ -255,6 +260,13 @@ defmodule ChesstrainerWeb.EndgameLive.Train do
{:noreply, account_completion(socket)}
end
def handle_event("submit_move", params, socket), do: PlayCore.submit_move(socket, params)
def handle_event("move_input", params, socket), do: PlayCore.move_input_changed(socket, params)
def handle_event("move_input_error", params, socket),
do: PlayCore.move_input_error(socket, params)
def handle_event("opponent_reply_applied", params, socket) do
{:noreply, socket} = PlayCore.opponent_reply_applied(socket, params)
{:noreply, account_completion(socket)}
@@ -374,6 +386,6 @@ defmodule ChesstrainerWeb.EndgameLive.Train do
end
defp gain_class(delta) when is_number(delta) and delta > 0, do: "text-success-text"
defp gain_class(delta) when is_number(delta) and delta < 0, do: "text-error"
defp gain_class(delta) when is_number(delta) and delta < 0, do: "text-error-text"
defp gain_class(_delta), do: "text-muted"
end
+2 -2
View File
@@ -14,7 +14,7 @@ defmodule ChesstrainerWeb.UserLive.Login do
<p class="settings-subtitle my-4">
Don't have an account? <.link
navigate={~p"/users/register"}
class="font-semibold text-primary hover:underline"
class="font-semibold text-primary-text hover:underline"
phx-no-format
>Sign up</.link> for an account now.
</p>
@@ -56,7 +56,7 @@ defmodule ChesstrainerWeb.UserLive.Login do
<p class="text-center text-sm">
<.link
navigate={~p"/users/reset-password"}
class="font-semibold text-primary hover:underline"
class="font-semibold text-primary-text hover:underline"
>
Forgot your password?
</.link>
@@ -30,7 +30,7 @@ defmodule ChesstrainerWeb.UserLive.Profile do
class={[
"border-b-2 -mb-px px-3 py-2 text-sm font-semibold",
if(@live_action == tab.id,
do: "border-primary text-primary",
do: "border-primary text-primary-text",
else: "border-transparent text-base-content/60 hover:text-base-content"
)
]}
@@ -14,7 +14,10 @@ defmodule ChesstrainerWeb.UserLive.Registration do
<h1 class="settings-header">Register for an account</h1>
<p class="settings-subtitle my-4">
Already registered?
<.link navigate={~p"/users/log-in"} class="font-semibold text-primary hover:underline">
<.link
navigate={~p"/users/log-in"}
class="font-semibold text-primary-text hover:underline"
>
Log in
</.link>
to your account now
@@ -51,7 +51,7 @@ defmodule ChesstrainerWeb.UserLive.ResetPassword do
<p class="text-center text-sm">
<.link
navigate={~p"/users/log-in"}
class="font-semibold text-primary hover:underline"
class="font-semibold text-primary-text hover:underline"
>
Back to log in
</.link>