KeyExplorer.ts 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460
  1. /*************************************************************
  2. *
  3. * Copyright (c) 2009-2022 The MathJax Consortium
  4. *
  5. * Licensed under the Apache License, Version 2.0 (the "License");
  6. * you may not use this file except in compliance with the License.
  7. * You may obtain a copy of the License at
  8. *
  9. * http://www.apache.org/licenses/LICENSE-2.0
  10. *
  11. * Unless required by applicable law or agreed to in writing, software
  12. * distributed under the License is distributed on an "AS IS" BASIS,
  13. * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14. * See the License for the specific language governing permissions and
  15. * limitations under the License.
  16. */
  17. /**
  18. * @fileoverview Explorers based on keyboard events.
  19. *
  20. * @author v.sorge@mathjax.org (Volker Sorge)
  21. */
  22. import {A11yDocument, Region} from './Region.js';
  23. import {Explorer, AbstractExplorer} from './Explorer.js';
  24. import Sre from '../sre.js';
  25. /**
  26. * Interface for keyboard explorers. Adds the necessary keyboard events.
  27. * @interface
  28. * @extends {Explorer}
  29. */
  30. export interface KeyExplorer extends Explorer {
  31. /**
  32. * Function to be executed on key down.
  33. * @param {KeyboardEvent} event The keyboard event.
  34. */
  35. KeyDown(event: KeyboardEvent): void;
  36. /**
  37. * Function to be executed on focus in.
  38. * @param {KeyboardEvent} event The keyboard event.
  39. */
  40. FocusIn(event: FocusEvent): void;
  41. /**
  42. * Function to be executed on focus out.
  43. * @param {KeyboardEvent} event The keyboard event.
  44. */
  45. FocusOut(event: FocusEvent): void;
  46. }
  47. /**
  48. * @constructor
  49. * @extends {AbstractExplorer}
  50. *
  51. * @template T The type that is consumed by the Region of this explorer.
  52. */
  53. export abstract class AbstractKeyExplorer<T> extends AbstractExplorer<T> implements KeyExplorer {
  54. /**
  55. * Flag indicating if the explorer is attached to an object.
  56. */
  57. public attached: boolean = false;
  58. /**
  59. * The attached Sre walker.
  60. * @type {Walker}
  61. */
  62. protected walker: Sre.walker;
  63. private eventsAttached: boolean = false;
  64. /**
  65. * @override
  66. */
  67. protected events: [string, (x: Event) => void][] =
  68. super.Events().concat(
  69. [['keydown', this.KeyDown.bind(this)],
  70. ['focusin', this.FocusIn.bind(this)],
  71. ['focusout', this.FocusOut.bind(this)]]);
  72. /**
  73. * The original tabindex value before explorer was attached.
  74. * @type {boolean}
  75. */
  76. private oldIndex: number = null;
  77. /**
  78. * @override
  79. */
  80. public abstract KeyDown(event: KeyboardEvent): void;
  81. /**
  82. * @override
  83. */
  84. public FocusIn(_event: FocusEvent) {
  85. }
  86. /**
  87. * @override
  88. */
  89. public FocusOut(_event: FocusEvent) {
  90. this.Stop();
  91. }
  92. /**
  93. * @override
  94. */
  95. public Update(force: boolean = false) {
  96. if (!this.active && !force) return;
  97. this.highlighter.unhighlight();
  98. let nodes = this.walker.getFocus(true).getNodes();
  99. if (!nodes.length) {
  100. this.walker.refocus();
  101. nodes = this.walker.getFocus().getNodes();
  102. }
  103. this.highlighter.highlight(nodes as HTMLElement[]);
  104. }
  105. /**
  106. * @override
  107. */
  108. public Attach() {
  109. super.Attach();
  110. this.attached = true;
  111. this.oldIndex = this.node.tabIndex;
  112. this.node.tabIndex = 1;
  113. this.node.setAttribute('role', 'application');
  114. }
  115. /**
  116. * @override
  117. */
  118. public AddEvents() {
  119. if (!this.eventsAttached) {
  120. super.AddEvents();
  121. this.eventsAttached = true;
  122. }
  123. }
  124. /**
  125. * @override
  126. */
  127. public Detach() {
  128. if (this.active) {
  129. this.node.tabIndex = this.oldIndex;
  130. this.oldIndex = null;
  131. this.node.removeAttribute('role');
  132. }
  133. this.attached = false;
  134. }
  135. /**
  136. * @override
  137. */
  138. public Stop() {
  139. if (this.active) {
  140. this.highlighter.unhighlight();
  141. this.walker.deactivate();
  142. }
  143. super.Stop();
  144. }
  145. }
  146. /**
  147. * Explorer that pushes speech to live region.
  148. * @constructor
  149. * @extends {AbstractKeyExplorer}
  150. */
  151. export class SpeechExplorer extends AbstractKeyExplorer<string> {
  152. private static updatePromise = Promise.resolve();
  153. /**
  154. * The Sre speech generator associated with the walker.
  155. * @type {SpeechGenerator}
  156. */
  157. public speechGenerator: Sre.speechGenerator;
  158. /**
  159. * The name of the option used to control when this is being shown
  160. * @type {string}
  161. */
  162. public showRegion: string = 'subtitles';
  163. private init: boolean = false;
  164. /**
  165. * Flag in case the start method is triggered before the walker is fully
  166. * initialised. I.e., we have to wait for Sre. Then region is re-shown if
  167. * necessary, as otherwise it leads to incorrect stacking.
  168. * @type {boolean}
  169. */
  170. private restarted: boolean = false;
  171. /**
  172. * @constructor
  173. * @extends {AbstractKeyExplorer}
  174. */
  175. constructor(public document: A11yDocument,
  176. protected region: Region<string>,
  177. protected node: HTMLElement,
  178. private mml: string) {
  179. super(document, region, node);
  180. this.initWalker();
  181. }
  182. /**
  183. * @override
  184. */
  185. public Start() {
  186. if (!this.attached) return;
  187. let options = this.getOptions();
  188. if (!this.init) {
  189. this.init = true;
  190. SpeechExplorer.updatePromise = SpeechExplorer.updatePromise.then(async () => {
  191. return Sre.sreReady()
  192. .then(() => Sre.setupEngine({locale: options.locale}))
  193. .then(() => {
  194. // Important that both are in the same block so speech explorers
  195. // are restarted sequentially.
  196. this.Speech(this.walker);
  197. this.Start();
  198. });
  199. })
  200. .catch((error: Error) => console.log(error.message));
  201. return;
  202. }
  203. super.Start();
  204. this.speechGenerator = Sre.getSpeechGenerator('Direct');
  205. this.speechGenerator.setOptions(options);
  206. this.walker = Sre.getWalker(
  207. 'table', this.node, this.speechGenerator, this.highlighter, this.mml);
  208. this.walker.activate();
  209. this.Update();
  210. if (this.document.options.a11y[this.showRegion]) {
  211. SpeechExplorer.updatePromise.then(
  212. () => this.region.Show(this.node, this.highlighter));
  213. }
  214. this.restarted = true;
  215. }
  216. /**
  217. * @override
  218. */
  219. public Update(force: boolean = false) {
  220. super.Update(force);
  221. let options = this.speechGenerator.getOptions();
  222. // This is a necessary in case speech options have changed via keypress
  223. // during walking.
  224. if (options.modality === 'speech') {
  225. this.document.options.sre.domain = options.domain;
  226. this.document.options.sre.style = options.style;
  227. this.document.options.a11y.speechRules =
  228. options.domain + '-' + options.style;
  229. }
  230. SpeechExplorer.updatePromise = SpeechExplorer.updatePromise.then(async () => {
  231. return Sre.sreReady()
  232. .then(() => Sre.setupEngine({modality: options.modality,
  233. locale: options.locale}))
  234. .then(() => this.region.Update(this.walker.speech()));
  235. });
  236. }
  237. /**
  238. * Computes the speech for the current expression once Sre is ready.
  239. * @param {Walker} walker The sre walker.
  240. */
  241. public Speech(walker: Sre.walker) {
  242. SpeechExplorer.updatePromise.then(() => {
  243. walker.speech();
  244. this.node.setAttribute('hasspeech', 'true');
  245. this.Update();
  246. if (this.restarted && this.document.options.a11y[this.showRegion]) {
  247. this.region.Show(this.node, this.highlighter);
  248. }
  249. });
  250. }
  251. /**
  252. * @override
  253. */
  254. public KeyDown(event: KeyboardEvent) {
  255. const code = event.keyCode;
  256. this.walker.modifier = event.shiftKey;
  257. if (code === 27) {
  258. this.Stop();
  259. this.stopEvent(event);
  260. return;
  261. }
  262. if (this.active) {
  263. this.Move(code);
  264. if (this.triggerLink(code)) return;
  265. this.stopEvent(event);
  266. return;
  267. }
  268. if (code === 32 && event.shiftKey || code === 13) {
  269. this.Start();
  270. this.stopEvent(event);
  271. }
  272. }
  273. /**
  274. * Programmatically triggers a link if the focused node contains one.
  275. * @param {number} code The keycode of the last key pressed.
  276. */
  277. protected triggerLink(code: number) {
  278. if (code !== 13) {
  279. return false;
  280. }
  281. let node = this.walker.getFocus().getNodes()?.[0];
  282. let focus = node?.
  283. getAttribute('data-semantic-postfix')?.
  284. match(/(^| )link($| )/);
  285. if (focus) {
  286. node.parentNode.dispatchEvent(new MouseEvent('click'));
  287. return true;
  288. }
  289. return false;
  290. }
  291. /**
  292. * @override
  293. */
  294. public Move(key: number) {
  295. this.walker.move(key);
  296. this.Update();
  297. }
  298. /**
  299. * Initialises the Sre walker.
  300. */
  301. private initWalker() {
  302. this.speechGenerator = Sre.getSpeechGenerator('Tree');
  303. let dummy = Sre.getWalker(
  304. 'dummy', this.node, this.speechGenerator, this.highlighter, this.mml);
  305. this.walker = dummy;
  306. }
  307. /**
  308. * Retrieves the speech options to sync with document options.
  309. * @return {{[key: string]: string}} The options settings for the speech
  310. * generator.
  311. */
  312. private getOptions(): {[key: string]: string} {
  313. let options = this.speechGenerator.getOptions();
  314. let sreOptions = this.document.options.sre;
  315. if (options.modality === 'speech' &&
  316. (options.locale !== sreOptions.locale ||
  317. options.domain !== sreOptions.domain ||
  318. options.style !== sreOptions.style)) {
  319. options.domain = sreOptions.domain;
  320. options.style = sreOptions.style;
  321. options.locale = sreOptions.locale;
  322. this.walker.update(options);
  323. }
  324. return options;
  325. }
  326. }
  327. /**
  328. * Explorer that magnifies what is currently explored. Uses a hover region.
  329. * @constructor
  330. * @extends {AbstractKeyExplorer}
  331. */
  332. export class Magnifier extends AbstractKeyExplorer<HTMLElement> {
  333. /**
  334. * @constructor
  335. * @extends {AbstractKeyExplorer}
  336. */
  337. constructor(public document: A11yDocument,
  338. protected region: Region<HTMLElement>,
  339. protected node: HTMLElement,
  340. private mml: string) {
  341. super(document, region, node);
  342. this.walker = Sre.getWalker(
  343. 'table', this.node, Sre.getSpeechGenerator('Dummy'),
  344. this.highlighter, this.mml);
  345. }
  346. /**
  347. * @override
  348. */
  349. public Update(force: boolean = false) {
  350. super.Update(force);
  351. this.showFocus();
  352. }
  353. /**
  354. * @override
  355. */
  356. public Start() {
  357. super.Start();
  358. if (!this.attached) return;
  359. this.region.Show(this.node, this.highlighter);
  360. this.walker.activate();
  361. this.Update();
  362. }
  363. /**
  364. * Shows the nodes that are currently focused.
  365. */
  366. private showFocus() {
  367. let node = this.walker.getFocus().getNodes()[0] as HTMLElement;
  368. this.region.Show(node, this.highlighter);
  369. }
  370. /**
  371. * @override
  372. */
  373. public Move(key: number) {
  374. let result = this.walker.move(key);
  375. if (result) {
  376. this.Update();
  377. }
  378. }
  379. /**
  380. * @override
  381. */
  382. public KeyDown(event: KeyboardEvent) {
  383. const code = event.keyCode;
  384. this.walker.modifier = event.shiftKey;
  385. if (code === 27) {
  386. this.Stop();
  387. this.stopEvent(event);
  388. return;
  389. }
  390. if (this.active && code !== 13) {
  391. this.Move(code);
  392. this.stopEvent(event);
  393. return;
  394. }
  395. if (code === 32 && event.shiftKey || code === 13) {
  396. this.Start();
  397. this.stopEvent(event);
  398. }
  399. }
  400. }