lashman/cruciverb
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

screen reader grid and readout shortcuts

Browse Source
This commit is contained in:
lashman
2026-08-20 14:20:00 +03:00
parent ae28fd2dcb
commit 4689cb5971
7 changed files with 151 additions and 20 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+3 -1
View File
@@ -70,7 +70,9 @@ Instances talk to each other over ActivityPub, and nobody stands in the middle.
**Comfort and access**
- Light, dark, and system themes, warm palettes, and text scaling up to 200%
- Colorblind palettes, a screen-reader narrator, keyboard-only play, and reduced-motion cell animations
- A screen-reader native grid: every cell is focusable and announced with its number, letter, and state, and Alt+A / Alt+D read the across and down words aloud (/ reads the clue, space reads the cell, Ctrl+H the puzzle overview)
- A voice narrator with three verbosity levels and an output mode (voice, screen reader, or both) so blind players get the same flow through their own screen reader
- Colorblind palettes and reduced-motion cell animations
- Sound effects and a tor-friendly mode that keeps the page light for slow connections
---
frontend/src/components/Grid.tsx
+44 -11
View File
@@ -1,4 +1,4 @@
import { useRef } from 'react'
import { useRef, useEffect } from 'react'
import { useTranslation } from 'react-i18next'
import { motion, AnimatePresence } from 'motion/react'
import { useStore } from '../store'
@@ -17,6 +17,8 @@ function getCellSize(gridSize: number): number {
export default function Grid() {
const { t } = useTranslation()
const svgRef = useRef<SVGSVGElement>(null)
const wrapperRef = useRef<HTMLDivElement>(null)
const cellRefs = useRef<(HTMLButtonElement | null)[]>([])
const puzzle = useStore((s) => s.puzzle)
const entries = useStore((s) => s.entries)
const cellStatus = useStore((s) => s.cellStatus)
@@ -29,9 +31,17 @@ export default function Grid() {
const mpPlayers = useStore((s) => s.mpPlayers)
const inputMode = useStore((s) => s.inputMode)
const width = puzzle?.width ?? 0
const height = puzzle?.height ?? 0
useEffect(() => {
if (!selectedCell || !wrapperRef.current?.contains(document.activeElement)) return
const idx = selectedCell.row * width + selectedCell.col
cellRefs.current[idx]?.focus()
}, [selectedCell, width])
if (!puzzle) return null
const { width, height } = puzzle
const CELL = getCellSize(Math.max(width, height))
const NUM_SIZE = Math.round(CELL * 0.26)
const LETTER_SIZE = Math.round(CELL * 0.52)
@@ -45,6 +55,7 @@ export default function Grid() {
return (
<div
ref={wrapperRef}
className={`grid-wrapper${inputMode === 'stylus' ? ' stylus-active' : ''}`}
style={{ maxWidth: width * CELL, width: '100%' }}
onContextMenu={inputMode === 'stylus' ? (e => e.preventDefault()) : undefined}
@@ -53,10 +64,7 @@ export default function Grid() {
ref={svgRef}
viewBox={`0 0 ${width * CELL} ${height * CELL}`}
style={{ width: '100%', maxWidth: width * CELL, display: 'block' }}
tabIndex={0}
role="grid"
aria-label={t('grid.ariaLabel', { width, height })}
aria-activedescendant={selectedCell ? `cell-${selectedCell.row}-${selectedCell.col}` : undefined}
aria-hidden="true"
>
<defs>
<style>{`
@@ -87,9 +95,6 @@ export default function Grid() {
if (status === 'incorrect') textColor = 'var(--incorrect)'
if (status === 'revealed') textColor = 'var(--revealed)'
const ariaLabel = isBlack ? t('grid.blackCell') :
t('grid.cellLabel', { row: r + 1, col: c + 1 }) + (num ? t('grid.cellNumber', { num }) : '') + (letter ? t('grid.cellLetter', { letter }) : t('grid.cellEmpty'))
return (
<g
key={`${r},${c}`}
@@ -97,8 +102,6 @@ export default function Grid() {
data-cell={`${r},${c}`}
onClick={() => !isBlack && selectCell(r, c)}
style={{ cursor: isBlack ? 'default' : 'pointer' }}
role="gridcell"
aria-label={ariaLabel}
>
<rect
x={x} y={y}
@@ -190,6 +193,36 @@ export default function Grid() {
strokeWidth={1.5}
/>
</svg>
{/* screen reader layer: one focusable cell per grid cell, invisible to the eye */}
<div
className="grid-sr-grid"
style={{ gridTemplateColumns: `repeat(${width}, 1fr)`, aspectRatio: `${width} / ${height}` }}
>
{Array.from({ length: height }, (_, r) =>
Array.from({ length: width }, (_, c) => {
const isBlack = puzzle.cells[r][c] === 'black'
const isSelected = selectedCell?.row === r && selectedCell?.col === c
const num = puzzle.cell_numbers[`${r},${c}`]
const letter = entries[r]?.[c] || ''
const pencilLetter = !letter && pencilEntries[r]?.[c] ? pencilEntries[r][c] : ''
const status: CellStatus = cellStatus[r]?.[c] || 'default'
const label = isBlack ? t('grid.blackCell') :
t('grid.cellLabel', { row: r + 1, col: c + 1 }) + (num ? t('grid.cellNumber', { num }) : '') + (letter ? t('grid.cellLetter', { letter }) : t('grid.cellEmpty')) +
(status === 'correct' ? t('grid.cellCorrect') : status === 'incorrect' ? t('grid.cellIncorrect') : status === 'revealed' ? t('grid.cellRevealed') : pencilLetter ? t('grid.cellPencil', { letter: pencilLetter }) : '')
return (
<button
key={`sr-${r}-${c}`}
ref={el => { cellRefs.current[r * width + c] = el }}
type="button"
className="grid-sr-cell"
tabIndex={isSelected ? 0 : -1}
aria-label={label}
onClick={() => !isBlack && selectCell(r, c)}
/>
)
}),
)}
</div>
<CellFlip svgRef={svgRef} />
<InkOverlay svgRef={svgRef} />
</div>
frontend/src/components/SettingsPanel.tsx
+11
View File
@@ -164,6 +164,17 @@ function NarratorSettingsBlock() {
]} />
</div>
<div className="settings-narrator-item">
<label className="settings-sublabel">{t('settings.narrator.output')}</label>
<Select value={narratorSettings.mode}
onChange={v => { const s = String(v); if (s === 'voice' || s === 'screenreader' || s === 'both') setNarratorSettings({ mode: s }) }}
options={[
{ value: 'voice', label: t('settings.narrator.outputVoice') },
{ value: 'screenreader', label: t('settings.narrator.outputScreenReader') },
{ value: 'both', label: t('settings.narrator.outputBoth') },
]} />
</div>
<Toggle checked={narratorSettings.sounds} onChange={v => setNarratorSettings({ sounds: v })}
label={t('settings.narrator.soundEffects')} />
</motion.div>
frontend/src/hooks/useKeyboard.ts
+31 -3
View File
@@ -1,5 +1,6 @@
import { useEffect } from 'react'
import { useStore } from '../store'
import type { Direction } from '../types'
import * as narrator from '../narrator'
function readCurrentCell() {
@@ -23,6 +24,23 @@ function readCurrentCell() {
narrator.speak(msg)
}
function readWord(dir: Direction) {
const { puzzle, selectedCell, entries, wordSpans } = useStore.getState()
if (!puzzle || !selectedCell) {
narrator.speak('No cell selected')
return
}
const span = wordSpans.find(s =>
s.direction === dir && s.cells.some(([r, c]) => r === selectedCell.row && c === selectedCell.col)
)
if (!span) {
narrator.speak(`No ${dir} word here`, false)
return
}
const letters = span.cells.map(([r, c]) => entries[r]?.[c] || 'blank')
narrator.speak(`${dir === 'across' ? 'Across' : 'Down'} ${span.number}, ${span.cells.length} letters: ${letters.join(', ')}.`, false)
}
function readCurrentClue() {
const { puzzle, activeClue, direction, wordSpans, entries, narratorSettings } = useStore.getState()
if (!puzzle || activeClue === null) {
@@ -83,7 +101,7 @@ function getGridEl(): HTMLElement | null {
let gridHasFocus = false
function updateGridFocus(target: EventTarget | null) {
gridHasFocus = target instanceof Node && !!getGridEl()?.contains(target)
gridHasFocus = !!getGridEl()?.contains(document.activeElement) || (target instanceof Element && !!getGridEl()?.contains(target))
}
export function useKeyboard() {
@@ -109,8 +127,8 @@ export function useKeyboard() {
// give the grid initial keyboard focus when nothing else is focused
if (document.activeElement === document.body || document.activeElement === null) {
const svg = getGridEl()?.querySelector('svg')
if (svg instanceof SVGSVGElement) svg.focus()
const firstCell = getGridEl()?.querySelector('button.grid-sr-cell')
if (firstCell instanceof HTMLButtonElement) firstCell.focus()
}
function onKeyDown(e: KeyboardEvent) {
@@ -144,6 +162,16 @@ export function useKeyboard() {
readPuzzleOverview()
return
}
if (e.altKey && key.toLowerCase() === 'a') {
e.preventDefault()
readWord('across')
return
}
if (e.altKey && key.toLowerCase() === 'd') {
e.preventDefault()
readWord('down')
return
}
if (key === 'Tab') {
e.preventDefault()
tabClue(!e.shiftKey)
frontend/src/index.css
+16
View File
@@ -66,6 +66,22 @@
[data-colorblind="deuteranopia"] { --correct: #3b82f6; --incorrect: #f97316; }
[data-colorblind="tritanopia"] { --correct: #ef4444; --incorrect: #06b6d4; }
.grid-sr-grid {
position: absolute;
inset: 0;
display: grid;
}
.grid-sr-cell {
border: 0;
padding: 0;
margin: 0;
background: transparent;
pointer-events: none;
outline: none;
cursor: default;
}
.visually-hidden {
position: absolute; width: 1px; height: 1px;
padding: 0; margin: -1px; overflow: hidden;
frontend/src/locales/en.json
+8
View File
@@ -86,6 +86,10 @@
"cellNumber": ", number {{num}}",
"cellLetter": ", letter {{letter}}",
"cellEmpty": ", empty",
"cellCorrect": ", correct",
"cellIncorrect": ", incorrect",
"cellRevealed": ", revealed",
"cellPencil": ", pencil letter {{letter}}",
"handwritingCanvas": "Handwriting input area"
},
"welcome": {
@@ -544,6 +548,10 @@
"brief": "Brief",
"normal": "Normal",
"verbose": "Verbose",
"output": "Output",
"outputVoice": "Voice",
"outputScreenReader": "Screen reader",
"outputBoth": "Both",
"soundEffects": "Sound effects",
"notSupported": "Your browser does not support speech synthesis"
},
frontend/src/narrator.ts
+37 -4
View File
@@ -4,6 +4,7 @@ export interface NarratorSettings {
pitch: number
voice: string
verbosity: 'brief' | 'normal' | 'verbose'
mode: 'voice' | 'screenreader' | 'both'
sounds: boolean
}
@@ -13,6 +14,7 @@ export const defaultNarratorSettings: NarratorSettings = {
pitch: 1.0,
voice: '',
verbosity: 'normal',
mode: 'voice',
sounds: true,
}
@@ -36,8 +38,42 @@ export function cancel() {
window.speechSynthesis.cancel()
}
// a polite live region that screen readers announce from, created on demand
let srRegion: HTMLElement | null = null
function getSrRegion(): HTMLElement {
if (!srRegion) {
srRegion = document.createElement('div')
srRegion.setAttribute('aria-live', 'polite')
srRegion.setAttribute('role', 'status')
srRegion.className = 'visually-hidden'
document.body.appendChild(srRegion)
}
return srRegion
}
function announceToScreenReader(text: string) {
const region = getSrRegion()
const msg = document.createElement('span')
msg.textContent = `${text} `
region.appendChild(msg)
while (region.children.length > 6) {
const first = region.firstChild
if (first) region.removeChild(first)
}
setTimeout(() => msg.remove(), 15000)
}
export function speak(text: string, interrupt = true) {
if (!isSupported() || !settings.enabled) return
if (!settings.enabled) return
const mode = settings.mode
const wantsVoice = (mode === 'voice' || mode === 'both') && isSupported()
const wantsSr = mode === 'screenreader' || mode === 'both' || !isSupported()
if (wantsSr) announceToScreenReader(text)
if (!wantsVoice) return
if (interrupt) cancel()
const utterance = new SpeechSynthesisUtterance(text)
@@ -57,9 +93,6 @@ export function speak(text: string, interrupt = true) {
export function preloadVoices() {
if (!isSupported()) return
getVoices()
if (window.speechSynthesis.onvoiceschanged !== undefined) {
window.speechSynthesis.onvoiceschanged = () => {}
}
}
preloadVoices()