8
0

focuscycler.js 6.8 KB

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