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
@@ -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"""
<div class={["m-auto left-0 right-0", @class]}>
<div class="border border-2 border-zinc-700 grid grid-rows-8 grid-cols-8">
<div
class="border border-2 border-zinc-700 grid grid-rows-8 grid-cols-8"
role="img"
aria-label={"Chess position. #{PositionText.summary(Map.get(@game, :fen))}"}
>
<%= for rank <- @ranks do %>
<%= for file <- @files do %>
<% square = {file, rank} %>
@@ -12,7 +12,7 @@ defmodule ChesstrainerWeb.Board.PieceComponent do
~H"""
<%= if @path do %>
<img src={@path} class={@class} />
<img src={@path} class={@class} alt="" aria-hidden="true" />
<% end %>
"""
end
@@ -0,0 +1,93 @@
defmodule ChesstrainerWeb.Board.PositionText do
@moduledoc """
Plain-language descriptions of a chess position for assistive technology.
A chessground board is a picture to a screen reader, so the play surface and
the static boards use this text as their accessible name or description.
"""
alias Chesstrainer.FEN
@files ~w(a b c d e f g h)
@names %{
"k" => "king",
"q" => "queen",
"r" => "rook",
"b" => "bishop",
"n" => "knight",
"p" => "pawn"
}
@doc """
Describes whose turn it is and where every piece stands.
Returns a generic description when the FEN cannot be read.
## Examples
iex> ChesstrainerWeb.Board.PositionText.summary("8/8/3k4/8/8/3K1R2/8/8 w - - 0 1")
"White to move. White: king on d3, rook on f3. Black: king on d6."
"""
@spec summary(String.t() | nil) :: String.t()
def summary(fen) when is_binary(fen) do
case FEN.board(fen) do
nil ->
"Chess position."
rows ->
["#{turn(fen)}." | piece_groups(rows)]
|> Enum.join(" ")
end
end
def summary(_fen), do: "Chess position."
defp turn(fen) do
case FEN.color_from_fen(fen) do
:white -> "White to move"
:black -> "Black to move"
_ -> "Side to move unknown"
end
end
defp piece_groups(rows) do
["White", "Black"]
|> Enum.map(fn label -> group(label, rows) end)
|> Enum.reject(&is_nil/1)
end
defp group(label, rows) do
colour = if label == "White", do: :white, else: :black
case pieces(rows, colour) do
[] -> nil
pieces -> "#{label}: #{Enum.join(pieces, ", ")}."
end
end
defp pieces(rows, colour) do
rows
|> Enum.with_index()
|> Enum.flat_map(fn {row, rank_index} ->
row
|> Enum.with_index()
|> Enum.flat_map(fn
{nil, _file_index} ->
[]
{piece, file_index} ->
if piece_colour(piece) == colour do
square = "#{Enum.at(@files, file_index)}#{8 - rank_index}"
["#{Map.fetch!(@names, String.downcase(piece))} on #{square}"]
else
[]
end
end)
end)
end
defp piece_colour(piece) do
if piece == String.upcase(piece), do: :white, else: :black
end
end