8
0

focuscycler.js 7.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292
  1. /**
  2. * @license Copyright (c) 2003-2020, CKSource - Frederico Knabben. All rights reserved.
  3. * For licensing, see LICENSE.md or https://ckeditor.com/legal/ckeditor-oss-license
  4. */
  5. /**
  6. * @module ui/focuscycler
  7. */
  8. import global from '@ckeditor/ckeditor5-utils/src/dom/global';
  9. /**
  10. * A utility class that helps cycling over focusable {@link module:ui/view~View views} in a
  11. * {@link module:ui/viewcollection~ViewCollection} when the focus is tracked by the
  12. * {@link module:utils/focustracker~FocusTracker} instance. It helps implementing keyboard
  13. * navigation in HTML forms, toolbars, lists and the like.
  14. *
  15. * To work properly it requires:
  16. * * a collection of focusable (HTML `tabindex` attribute) views that implement the `focus()` method,
  17. * * an associated focus tracker to determine which view is focused.
  18. *
  19. * A simple cycler setup can look like this:
  20. *
  21. * const focusables = new ViewCollection();
  22. * const focusTracker = new FocusTracker();
  23. *
  24. * // Add focusable views to the focus tracker.
  25. * focusTracker.add( ... );
  26. *
  27. * Then, the cycler can be used manually:
  28. *
  29. * const cycler = new FocusCycler( { focusables, focusTracker } );
  30. *
  31. * // Will focus the first focusable view in #focusables.
  32. * cycler.focusFirst();
  33. *
  34. * // Will log the next focusable item in #focusables.
  35. * console.log( cycler.next );
  36. *
  37. * Alternatively, it can work side by side with the {@link module:utils/keystrokehandler~KeystrokeHandler}:
  38. *
  39. * const keystrokeHandler = new KeystrokeHandler();
  40. *
  41. * // Activate the keystroke handler.
  42. * keystrokeHandler.listenTo( sourceOfEvents );
  43. *
  44. * const cycler = new FocusCycler( {
  45. * focusables, focusTracker, keystrokeHandler,
  46. * actions: {
  47. * // When arrowup of arrowleft is detected by the #keystrokeHandler,
  48. * // focusPrevious() will be called on the cycler.
  49. * focusPrevious: [ 'arrowup', 'arrowleft' ],
  50. * }
  51. * } );
  52. *
  53. * Check out the {@glink framework/guides/deep-dive/ui/focus-tracking "Deep dive into focus tracking" guide} to learn more.
  54. */
  55. export default class FocusCycler {
  56. /**
  57. * Creates an instance of the focus cycler utility.
  58. *
  59. * @param {Object} options Configuration options.
  60. * @param {module:utils/collection~Collection|Object} options.focusables
  61. * @param {module:utils/focustracker~FocusTracker} options.focusTracker
  62. * @param {module:utils/keystrokehandler~KeystrokeHandler} [options.keystrokeHandler]
  63. * @param {Object} [options.actions]
  64. */
  65. constructor( options ) {
  66. Object.assign( this, options );
  67. /**
  68. * A {@link module:ui/view~View view} collection that the cycler operates on.
  69. *
  70. * @readonly
  71. * @member {module:utils/collection~Collection} #focusables
  72. */
  73. /**
  74. * A focus tracker instance that the cycler uses to determine the current focus
  75. * state in {@link #focusables}.
  76. *
  77. * @readonly
  78. * @member {module:utils/focustracker~FocusTracker} #focusTracker
  79. */
  80. /**
  81. * An instance of the {@link module:utils/keystrokehandler~KeystrokeHandler}
  82. * which can respond to certain keystrokes and cycle the focus.
  83. *
  84. * @readonly
  85. * @member {module:utils/keystrokehandler~KeystrokeHandler} #keystrokeHandler
  86. */
  87. /**
  88. * Actions that the cycler can take when a keystroke is pressed. Requires
  89. * `options.keystrokeHandler` to be passed and working. When an action is
  90. * performed, `preventDefault` and `stopPropagation` will be called on the event
  91. * the keystroke fired in the DOM.
  92. *
  93. * actions: {
  94. * // Will call #focusPrevious() when arrowleft or arrowup is pressed.
  95. * focusPrevious: [ 'arrowleft', 'arrowup' ],
  96. *
  97. * // Will call #focusNext() when arrowdown is pressed.
  98. * focusNext: 'arrowdown'
  99. * }
  100. *
  101. * @readonly
  102. * @member {Object} #actions
  103. */
  104. if ( options.actions && options.keystrokeHandler ) {
  105. for ( const methodName in options.actions ) {
  106. let actions = options.actions[ methodName ];
  107. if ( typeof actions == 'string' ) {
  108. actions = [ actions ];
  109. }
  110. for ( const keystroke of actions ) {
  111. options.keystrokeHandler.set( keystroke, ( data, cancel ) => {
  112. this[ methodName ]();
  113. cancel();
  114. } );
  115. }
  116. }
  117. }
  118. }
  119. /**
  120. * Returns the first focusable view in {@link #focusables}.
  121. * Returns `null` if there is none.
  122. *
  123. * @readonly
  124. * @member {module:ui/view~View|null} #first
  125. */
  126. get first() {
  127. return this.focusables.find( isFocusable ) || null;
  128. }
  129. /**
  130. * Returns the last focusable view in {@link #focusables}.
  131. * Returns `null` if there is none.
  132. *
  133. * @readonly
  134. * @member {module:ui/view~View|null} #last
  135. */
  136. get last() {
  137. return this.focusables.filter( isFocusable ).slice( -1 )[ 0 ] || null;
  138. }
  139. /**
  140. * Returns the next focusable view in {@link #focusables} based on {@link #current}.
  141. * Returns `null` if there is none.
  142. *
  143. * @readonly
  144. * @member {module:ui/view~View|null} #next
  145. */
  146. get next() {
  147. return this._getFocusableItem( 1 );
  148. }
  149. /**
  150. * Returns the previous focusable view in {@link #focusables} based on {@link #current}.
  151. * Returns `null` if there is none.
  152. *
  153. * @readonly
  154. * @member {module:ui/view~View|null} #previous
  155. */
  156. get previous() {
  157. return this._getFocusableItem( -1 );
  158. }
  159. /**
  160. * An index of the view in the {@link #focusables} which is focused according
  161. * to {@link #focusTracker}. Returns `null` when there is no such view.
  162. *
  163. * @readonly
  164. * @member {Number|null} #current
  165. */
  166. get current() {
  167. let index = null;
  168. // There's no focused view in the focusables.
  169. if ( this.focusTracker.focusedElement === null ) {
  170. return null;
  171. }
  172. this.focusables.find( ( view, viewIndex ) => {
  173. const focused = view.element === this.focusTracker.focusedElement;
  174. if ( focused ) {
  175. index = viewIndex;
  176. }
  177. return focused;
  178. } );
  179. return index;
  180. }
  181. /**
  182. * Focuses the {@link #first} item in {@link #focusables}.
  183. */
  184. focusFirst() {
  185. this._focus( this.first );
  186. }
  187. /**
  188. * Focuses the {@link #last} item in {@link #focusables}.
  189. */
  190. focusLast() {
  191. this._focus( this.last );
  192. }
  193. /**
  194. * Focuses the {@link #next} item in {@link #focusables}.
  195. */
  196. focusNext() {
  197. this._focus( this.next );
  198. }
  199. /**
  200. * Focuses the {@link #previous} item in {@link #focusables}.
  201. */
  202. focusPrevious() {
  203. this._focus( this.previous );
  204. }
  205. /**
  206. * Focuses the given view if it exists.
  207. *
  208. * @protected
  209. * @param {module:ui/view~View} view
  210. */
  211. _focus( view ) {
  212. if ( view ) {
  213. view.focus();
  214. }
  215. }
  216. /**
  217. * Returns the next or previous focusable view in {@link #focusables} with respect
  218. * to {@link #current}.
  219. *
  220. * @protected
  221. * @param {Number} step Either `1` for checking forward from {@link #current} or
  222. * `-1` for checking backwards.
  223. * @returns {module:ui/view~View|null}
  224. */
  225. _getFocusableItem( step ) {
  226. // Cache for speed.
  227. const current = this.current;
  228. const collectionLength = this.focusables.length;
  229. if ( !collectionLength ) {
  230. return null;
  231. }
  232. // Start from the beginning if no view is focused.
  233. // https://github.com/ckeditor/ckeditor5-ui/issues/206
  234. if ( current === null ) {
  235. return this[ step === 1 ? 'first' : 'last' ];
  236. }
  237. // Cycle in both directions.
  238. let index = ( current + collectionLength + step ) % collectionLength;
  239. do {
  240. const view = this.focusables.get( index );
  241. // TODO: Check if view is visible.
  242. if ( isFocusable( view ) ) {
  243. return view;
  244. }
  245. // Cycle in both directions.
  246. index = ( index + collectionLength + step ) % collectionLength;
  247. } while ( index !== current );
  248. return null;
  249. }
  250. }
  251. // Checks whether a view is focusable.
  252. //
  253. // @private
  254. // @param {module:ui/view~View} view A view to be checked.
  255. // @returns {Boolean}
  256. function isFocusable( view ) {
  257. return !!( view.focus && global.window.getComputedStyle( view.element ).display != 'none' );
  258. }