@enact/spotlight 3.4.9-experimental-3 → 3.4.9-experimental-7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (68) hide show
  1. package/{build/Accelerator → Accelerator}/Accelerator.d.ts +0 -0
  2. package/Accelerator/Accelerator.js +149 -156
  3. package/CHANGELOG.md +22 -0
  4. package/{build/Pause → Pause}/Pause.d.ts +0 -0
  5. package/Pause/Pause.js +102 -80
  6. package/Pause/tests/Pause-specs.js +65 -97
  7. package/SpotlightContainerDecorator/SpotlightContainer.js +175 -140
  8. package/{build/SpotlightContainerDecorator → SpotlightContainerDecorator}/SpotlightContainerDecorator.d.ts +0 -0
  9. package/SpotlightContainerDecorator/SpotlightContainerDecorator.js +222 -176
  10. package/SpotlightContainerDecorator/tests/Element.prototype.closest.js +44 -40
  11. package/SpotlightContainerDecorator/tests/SpotlightContainerDecorator-specs.js +221 -210
  12. package/SpotlightContainerDecorator/tests/useSpotlightContainer-specs.js +150 -243
  13. package/SpotlightContainerDecorator/useSpotlightContainer.js +47 -28
  14. package/{build/SpotlightRootDecorator → SpotlightRootDecorator}/SpotlightRootDecorator.d.ts +0 -0
  15. package/SpotlightRootDecorator/SpotlightRootDecorator.js +206 -111
  16. package/{build/Spottable → Spottable}/Spottable.d.ts +0 -0
  17. package/Spottable/Spottable.js +448 -410
  18. package/Spottable/tests/Spottable-specs.js +90 -117
  19. package/package.json +3 -2
  20. package/src/container.js +718 -653
  21. package/src/navigate.js +406 -491
  22. package/src/pointer.js +86 -78
  23. package/{build/src → src}/spotlight.d.ts +0 -0
  24. package/src/spotlight.js +846 -885
  25. package/src/target.js +448 -474
  26. package/src/tests/container-specs.js +643 -1251
  27. package/src/tests/navigate-specs.js +77 -134
  28. package/src/tests/pointer-specs.js +126 -182
  29. package/src/tests/spotlight-specs.js +103 -133
  30. package/src/tests/target-specs.js +597 -960
  31. package/src/tests/utils.js +89 -67
  32. package/src/utils.js +155 -158
  33. package/build/Accelerator/Accelerator.js +0 -162
  34. package/build/Accelerator/package.json +0 -3
  35. package/build/CHANGELOG.md +0 -838
  36. package/build/Pause/Pause.js +0 -164
  37. package/build/Pause/package.json +0 -3
  38. package/build/Pause/tests/Pause-specs.js +0 -65
  39. package/build/README.md +0 -61
  40. package/build/SpotlightContainerDecorator/SpotlightContainer.js +0 -176
  41. package/build/SpotlightContainerDecorator/SpotlightContainerDecorator.js +0 -282
  42. package/build/SpotlightContainerDecorator/package.json +0 -3
  43. package/build/SpotlightContainerDecorator/tests/Element.prototype.closest.js +0 -45
  44. package/build/SpotlightContainerDecorator/tests/SpotlightContainerDecorator-specs.js +0 -221
  45. package/build/SpotlightContainerDecorator/tests/useSpotlightContainer-specs.js +0 -160
  46. package/build/SpotlightContainerDecorator/useSpotlightContainer.js +0 -133
  47. package/build/SpotlightRootDecorator/SpotlightRootDecorator.js +0 -189
  48. package/build/SpotlightRootDecorator/package.json +0 -3
  49. package/build/Spottable/Spottable.js +0 -491
  50. package/build/Spottable/package.json +0 -3
  51. package/build/Spottable/tests/Spottable-specs.js +0 -90
  52. package/build/package-lock.json +0 -229
  53. package/build/package.json +0 -28
  54. package/build/src/container.js +0 -1201
  55. package/build/src/navigate.js +0 -419
  56. package/build/src/pointer.js +0 -183
  57. package/build/src/spotlight.js +0 -896
  58. package/build/src/target.js +0 -507
  59. package/build/src/tests/container-specs.js +0 -653
  60. package/build/src/tests/navigate-specs.js +0 -87
  61. package/build/src/tests/pointer-specs.js +0 -130
  62. package/build/src/tests/spotlight-specs.js +0 -112
  63. package/build/src/tests/target-specs.js +0 -614
  64. package/build/src/tests/utils.js +0 -104
  65. package/build/src/utils.js +0 -180
  66. package/build/styles/debug.less +0 -97
  67. package/build/styles/mixins.less +0 -63
  68. package/docs/index.md +0 -364
package/docs/index.md DELETED
@@ -1,364 +0,0 @@
1
- ---
2
- title: Spotlight
3
- toc: 2
4
- ---
5
-
6
-
7
- ## What Is Spotlight?
8
-
9
- Spotlight is an extensible utility that enables users to navigate
10
- applications using a keyboard or television remote control. Responding to input
11
- from the **UP**, **DOWN**, **LEFT**, **RIGHT**, and **RETURN** keys, Spotlight
12
- provides a navigation experience that compares favorably to that of a
13
- computer-with-mouse.
14
-
15
- It was developed for use with the [Enact JavaScript framework](http://enactjs.com), but is useful as a standalone
16
- library.
17
-
18
- Spotlight is based on a fork of [JavaScript SpatialNavigation](https://github.com/luke-chang/js-spatial-navigation)
19
- (c) 2016 Luke Chang, under the terms of the [Mozilla Public License](https://www.mozilla.org/en-US/MPL/2.0/).
20
-
21
- ## Modes
22
-
23
- Spotlight operates in two mutually exclusive modes: **5-way mode** and **Pointer
24
- mode**. By default, Spotlight is configured to switch between these modes
25
- whenever suitable input is received--i.e.: it switches to pointer mode on
26
- `mousemove` and back to 5-way mode on `keydown`.
27
-
28
- Spotlight initializes in 5-way mode. On webOS, the platform's current pointer mode is used instead.
29
-
30
- ## Navigation
31
-
32
- Spotlight enables navigation between controls by assigning focus to one control
33
- at a time. Focus-enabled controls are considered to be "spottable". These spottable
34
- controls take on the CSS class `.spottable`, which allow focused controls to be styled
35
- on a per-kind basis using `.<kindClass>.spottable:focus` selectors.
36
-
37
- Spotlight uses the native HTML DOM `focus` method to assign focus to controls. Form
38
- elements can gain focus by default, but Spotlight designates a `tabindex` value to its
39
- controls, meaning even a simple `div` can be a spottable control.
40
-
41
- When an application loads, Spotlight will initially spot the first spottable
42
- control. If a control has been programmatically spotted via `Spotlight.focus(element)`
43
- immediately after being rendered, that control will be spotted instead.
44
-
45
- In 5-way mode, Spotlight uses an algorithm to determine which spottable control
46
- is the nearest one in the direction of navigation. The coordinates of a
47
- spottable control are derived from its actual position on the screen.
48
-
49
- It's worth noting that spottable controls may be found on different hierarchical
50
- levels of a component tree. Spotlight facilitates seamless navigation
51
- among the topmost spottable components found in the tree.
52
-
53
- Spottable controls can receive `onSpotlight[Direction]` properties to handle custom
54
- navigation actions. This is mainly a convenience function used for preventing natural
55
- 5-way behavior and setting focus on specific spottable components that may not normally
56
- be in the next component to be spotted.
57
-
58
- ```js
59
- handleSpotlightDown = (e) => {
60
- e.preventDefault();
61
- e.stopPropagation();
62
- Spotlight.focus('[data-component-id="myButton"]');
63
- }
64
- ```
65
- ```js
66
- <Button data-component-id='myButton'>Source Button</Button>
67
- <Button onSpotlightDown={this.handleSpotlightDown}>Target Button</Button>
68
- ```
69
-
70
- ## Selectors
71
-
72
- Spotlight identifies spottable controls via selectors. A selector can be any of the
73
- following types:
74
- - a valid selector string for `querySelectorAll`
75
- - a NodeList or an array containing DOM elements
76
- - a single DOM element
77
- - a string `'@<containerId>'` to indicate the specified container
78
- - the string `'@'` to indicate the default container
79
-
80
- There may be times where it is preferable to specify a selector instead of relying on a reference to an element
81
- or `@<containerId>`. Each time a Spottable control receives focus via 5-way or pointer navigation, Spotlight updates
82
- its cache of available Spottable controls. So for example, if your container DOM is updated programmatically, followed
83
- by the need to set focus on a newly-created default Spottable control, you will be unable to spot the control by
84
- calling focus on the container.
85
-
86
- ```js
87
- Spotlight.focus('container-name');
88
- ```
89
-
90
- Be default, Spotlight will not always update its cache of available Spottable controls when simply attempting to
91
- set focus. This is done for performance reasons. Instead, you can supply a `querySelector` string that will allow
92
- Spotlight to parse the selector, re-indexing the available Spottable controls.
93
-
94
- ```js
95
- Spotlight.focus('[data-container-id="container-name"] .spottable');
96
- ```
97
-
98
- ## SpotlightRootDecorator
99
- The `SpotlightRootDecorator` is a top-level HOC (Higher Order Component) that is
100
- required to use Spotlight. It is responsible for initializing the Spotlight instance
101
- and managing navigation event listeners.
102
-
103
- To use Spotlight in an application, simply import and wrap the `SpotlightRootDecorator`
104
- HOC around your application view:
105
-
106
- ```js
107
- import ApplicationView from './ApplicationView';
108
- import SpotlightRootDecorator from '@enact/spotlight/SpotlightRootDecorator';
109
- const App = SpotlightRootDecorator(ApplicationView);
110
- ```
111
-
112
- It's worth noting that `@enact/moonstone` applications include `SpotlightRootDecorator`
113
- by default in its `MoonstoneDecorator` HOC.
114
-
115
- ## Spottable
116
-
117
- In order to make a control focus-enabled (or "spottable") with Spotlight, simply
118
- wrap your base control with the `Spottable` HOC, like so:
119
-
120
- ```js
121
- import Spottable from '@enact/spotlight/Spottable';
122
- import Component from './Component';
123
- const SpottableComponent = Spottable(Component);
124
- ```
125
-
126
- ## Containers
127
-
128
- In order to organize controls into navigation groups, we have created Spotlight
129
- containers.
130
-
131
- A good example of how containers should be used is a set of radio buttons that
132
- must be navigable separately from the rest of the app's controls.
133
-
134
- When a Spotlight container is focused, it passes the focus to its own configurable
135
- hierarchy of spottable child controls--specifically, to the last spottable child to
136
- hold focus before the focus moved outside of the container. If the container in
137
- question has never been focused, it passes focus to its first spottable child.
138
-
139
- To define a container, wrap your base control with the `SpotlightContainerDecorator`
140
- HOC:
141
-
142
- ```js
143
- import kind from '@enact/core/kind';
144
- import SpotlightContainerDecorator from '@enact/spotlight/SpotlightContainerDecorator';
145
- const Container = SpotlightContainerDecorator(kind({
146
- name: 'Container',
147
- render: (props) => {
148
- return (
149
- <div {...props}>
150
- {/* A list of spottable controls */}
151
- </div>
152
- );
153
- }
154
- }));
155
- ```
156
-
157
- In a way, containers may be thought of as the branches--and spottable controls
158
- as the leaves--of the Spotlight navigation tree.
159
-
160
- A `spotlightDisabled` property may be applied to the container to temporarily disable the specified container's
161
- spottable controls:
162
-
163
- ```js
164
- import kind from '@enact/core/kind';
165
- import SpotlightContainerDecorator from '@enact/spotlight/SpotlightContainerDecorator';
166
- const Container = SpotlightContainerDecorator('div');
167
- const App = kind({
168
- name: 'App',
169
- render: (props) => {
170
- return (
171
- <Container {...props} spotlightDisabled>
172
- {/* A list of spottable controls */}
173
- </Container>
174
- );
175
- }
176
- });
177
- ```
178
-
179
-
180
- ## Events
181
-
182
- Spotlight uses native DOM events to navigate the available spottable controls and does not
183
- directly dispatch synthetic events to the currently spotted control.
184
-
185
- To determine if spotlight is the cause of a specific spotted control's key event, you can
186
- validate the native `target` property of the key event against `document.activeElement`.
187
-
188
-
189
- ## Spotlight API
190
-
191
- In order to use the Spotlight API, simply import Spotlight into your application and call
192
- any of its available methods to manipulate how your application responds to navigation
193
- events.
194
-
195
- ```js
196
- import Spotlight from '@enact/spotlight';
197
- ```
198
-
199
- #### `Spotlight.pause()`
200
- Temporarily pauses Spotlight until `resume()` is called.
201
-
202
- #### `Spotlight.resume()`
203
- Resumes Spotlight navigation.
204
-
205
- #### `Spotlight.focus([containerId/selector])`
206
- + `containerId/selector`: (optional) String / Selector (without @ syntax)
207
-
208
- Dispatches focus to the specified containerId or the first spottable child that
209
- matches `selector`. This method has no effect if Spotlight is paused.
210
-
211
- #### `Spotlight.move(direction, [selector])`
212
- + `direction`: `'left'`, `'right'`, `'up'` or `'down'`
213
- + `selector`: (optional) Selector (without @ syntax)
214
-
215
- Moves focus in the specified direction of `selector`. If `selector` is not specified,
216
- Spotlight will move in the given direction of the currently spotted control.
217
-
218
- ## HOC Parameters And Properties
219
-
220
- ##### Spotlight HOC Parameters
221
-
222
- Parameters in the form of an object can be passed as an initial argument to a HOC when creating a
223
- Spotlight control. In these cases, the HOC parameter should remain static and unchanged in the
224
- life-cycle of the control.
225
-
226
- ```js
227
- import Spottable from '@enact/spotlight/Spottable';
228
- // spottable control that doesn't emit `onClick` events when pressing the enter key
229
- const Control = Spottable({emulateMouse: false}, 'div');
230
- ```
231
-
232
- ##### Spotlight HOC Properties
233
-
234
- Spotlight HOCs are able to use properties that are passed to them via parent controls. These properties
235
- are passed like in any other Enact component.
236
-
237
- ```js
238
- import kind from '@enact/core/kind';
239
- import Spottable from '@enact/spotlight/Spottable';
240
-
241
- const SpottableComponent = Spottable('div');
242
- const App = kind({
243
- render: () => (<SpottableComponent spotlightDisabled />)
244
- });
245
- ```
246
-
247
- ### Spottable
248
-
249
- ##### Parameters
250
-
251
- `emulateMouse`
252
- + Type: [boolean]
253
- + Default: `true`
254
-
255
- Whether or not the component should emulate mouse events as a response to Spotlight 5-way events.
256
-
257
- ##### Properties
258
- `spotlightDisabled`
259
- + Type: [boolean]
260
- + Default: `false`
261
-
262
- May be added to temporarily make a control not spottable.
263
-
264
- `onSpotlightLeft`
265
- `onSpotlightRight`
266
- `onSpotlightUp`
267
- `onSpotlightDown`
268
- + Type: [function]
269
-
270
- A callback function to override default spotlight behavior when exiting the spottable control.
271
-
272
- `onSpotlightDisappear`
273
- + Type: [function]
274
-
275
- A callback function to be called when the component is removed while retaining focus.
276
-
277
- ### Container
278
-
279
- ##### Parameters
280
-
281
- `defaultElement`
282
- + Type: [string|string[]]
283
- + Default: `'.spottable-default'`
284
-
285
- The selector for the default spottable element within the container. When an array of selectors is
286
- provided, the first selector that successfully matches a node is used.
287
-
288
- `enterTo`
289
- + Type: [string]
290
- + Values: [`''`, `'last-focused'`, or `'default-element'`]
291
- + Default: `''`
292
-
293
- If the focus originates from another container, you can define which element in
294
- this container receives focus first.
295
-
296
- `preserveId`
297
- + Type: [boolean]
298
- + Default: `false`
299
-
300
- Whether the container will preserve the id when it unmounts.
301
-
302
- #### Properties
303
-
304
- `containerId`
305
- + Type: [string]
306
-
307
- Specifies the container id. If the value is `null`, an id will be generated.
308
-
309
- `spotlightDisabled`
310
- + Type: [boolean]
311
- + Default: `false`
312
-
313
- When `true`, controls in the container cannot be navigated.
314
-
315
- `spotlightMuted`
316
- + Type: [boolean]
317
- + Default: `false`
318
-
319
- Whether or not the container is in muted mode. When in muted mode, Spottable controls within the container
320
- can still gain focus, however their `:focus` CSS styles will not be applied, giving them the appearance
321
- of not having focus. Muting a container is generally done to temporarily disable CSS changes and
322
- default `onFocus` and `onBlur` events without removing focus from the container itself - which would
323
- happen if you disabled the container using `spotlightDisabled`.
324
-
325
- `spotlightRestrict`
326
- + Type: [string]
327
- + Values: [`'none'`, `'self-first'`, or `'self-only'`]
328
- + Default: `'none'`
329
-
330
- Restricts or prioritizes focus to the controls in the current container.
331
-
332
- ```js
333
- import SpotlightContainerDecorator from '@enact/spotlight/SpotlightContainerDecorator';
334
- import Component from './Component';
335
- const Container = SpotlightContainerDecorator({enterTo: 'last-focused', restrict: 'self-only'}, Component);
336
- ```
337
-
338
- ## Examples
339
-
340
- #### Basic usage
341
-
342
- ```js
343
- import kind from '@enact/core/kind';
344
- import SpotlightRootDecorator from '@enact/spotlight/SpotlightRootDecorator';
345
- import Spottable from '@enact/spotlight/Spottable';
346
-
347
- const SpottableComponent = Spottable(kind({
348
- name: 'SpottableComponent',
349
- render: (props) => {
350
- return (
351
- <div {...props} />
352
- );
353
- }
354
- }));
355
-
356
- const App = SpotlightRootDecorator(kind({
357
- name: 'SpotlightRootDecorator',
358
- render: (props) => {
359
- return (
360
- <SpottableComponent {...props} />
361
- );
362
- }
363
- }));
364
- ```