Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

WRO-745: Clean up Spotlight document #3069

Merged
merged 7 commits into from Jul 7, 2022
Merged

WRO-745: Clean up Spotlight document #3069

Show file tree
Hide file tree
Changes from 4 commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
9509634
WRO-745: remove redundant api list on Spotlight document
jeonghee27 Jun 30, 2022
4fea6ba
add default prop value for restrict
jeonghee27 Jun 30, 2022
9f06bd9
apply review
jeonghee27 Jul 1, 2022
725487a
minor changes of doc
seunghoh Jul 6, 2022
ac911f0
Apply review
jeonghee27 Jul 7, 2022
ec5a9c7
remove space
jeonghee27 Jul 7, 2022
6f6d55b
fix mistake
jeonghee27 Jul 7, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
31 changes: 28 additions & 3 deletions packages/spotlight/SpotlightContainerDecorator/SpotlightContainerDecorator.js
View file
Open in desktop
Expand Up @@ -61,8 +61,10 @@ const defaultConfig = {

/**
* The selector for the default spottable element within the container.
* When an array of selectors is provided, the first selector that successfully matches a
* node is used.
*
* @type {String}
* @type {String|String[]}
* @default '.spottable-default'
* @memberof spotlight/SpotlightContainerDecorator.SpotlightContainerDecorator.defaultConfig
* @public
Expand Down Expand Up @@ -99,7 +101,23 @@ const defaultConfig = {
* @memberof spotlight/SpotlightContainerDecorator.SpotlightContainerDecorator.defaultConfig
* @public
*/
preserveId: false
preserveId: false,

/**
* Restricts or prioritizes navigation when focus attempts to leave the container. It
* can be either 'none', 'self-first', or 'self-only'. Specifying 'self-first' indicates that
* elements within the container will have a higher likelihood to be chosen as the next
* navigable element. Specifying 'self-only' indicates that elements in other containers
* cannot be navigated to by using 5-way navigation - however, elements in other containers
* can still receive focus by calling `Spotlight.focus(elem)` explicitly. Specifying 'none'
* indicates there should be no restrictions when 5-way navigating the container.
seunghoh marked this conversation as resolved.
Show resolved Hide resolved
*
* @type {String}
* @default 'self-first'
* @memberof spotlight/SpotlightContainerDecorator.SpotlightContainerDecorator.defaultConfig
* @public
*/
restrict: PropTypes.oneOf(['none', 'self-first', 'self-only'])
};

/**
Expand Down Expand Up @@ -182,6 +200,8 @@ const SpotlightContainerDecorator = hoc(defaultConfig, (config, Wrapped) => {
* Used to identify this component within the Spotlight system.
*
* If the value is `null`, an id will be generated.
* To keep the container information for restoring focus, it is required to specify
* a unique identifier.
*
* @type {String}
* @public
Expand All @@ -191,6 +211,10 @@ const SpotlightContainerDecorator = hoc(defaultConfig, (config, Wrapped) => {
/**
* Whether or not the container is in muted mode.
*
* In muted mode, `:focus` CSS styles will not be applied to the
* Spottable controls giving them the appearance of not having focus
* while they still have focus.
*
* @type {Boolean}
* @default false
* @public
Expand All @@ -204,9 +228,10 @@ const SpotlightContainerDecorator = hoc(defaultConfig, (config, Wrapped) => {
* navigable element. Specifying 'self-only' indicates that elements in other containers
* cannot be navigated to by using 5-way navigation - however, elements in other containers
* can still receive focus by calling `Spotlight.focus(elem)` explicitly. Specifying 'none'
* indicates there should be no restrictions when 5-way navigating the container.
* indicates there is no restrictions when 5-way navigating the container.
MikyungKim marked this conversation as resolved.
Show resolved Hide resolved
*
* @type {String}
* @default 'self-first'
* @public
*/
spotlightRestrict: PropTypes.oneOf(['none', 'self-first', 'self-only'])
Expand Down
59 changes: 11 additions & 48 deletions packages/spotlight/docs/index.md
View file
Open in desktop
Expand Up @@ -215,12 +215,12 @@ matches `selector`. This method has no effect if Spotlight is paused.
Moves focus in the specified direction of `selector`. If `selector` is not specified,
Spotlight will move in the given direction of the currently spotted control.

## HOC Parameters And Properties
## HOC Configuration And Properties
MikyungKim marked this conversation as resolved.
Show resolved Hide resolved

##### Spotlight HOC Parameters
##### Spotlight HOC Configuration

Parameters in the form of an object can be passed as an initial argument to a HOC when creating a
Spotlight control. In these cases, the HOC parameter should remain static and unchanged in the
Configuration in the form of an object can be passed as an initial argument to a HOC when creating a
Spotlight control. In these cases, the HOC configuration should remain static and unchanged in the
life-cycle of the control.

```js
Expand All @@ -246,7 +246,9 @@ const App = kind({

### Spottable

##### Parameters
For more details and full list of `Spottable` api, see [spotlight/Spottable/](../../modules/spotlight/Spottable/).
MikyungKim marked this conversation as resolved.
Show resolved Hide resolved

##### Configuration

`emulateMouse`
+ Type: [boolean]
Expand All @@ -269,14 +271,11 @@ May be added to temporarily make a control not spottable.

A callback function to override default spotlight behavior when exiting the spottable control.

`onSpotlightDisappear`
+ Type: [function]

A callback function to be called when the component is removed while retaining focus.

### Container

##### Parameters
For more details and full list of `Container` api, see [spotlight/SpotlightContainerDecorator](../../modules/spotlight/SpotlightContainerDecorator/).
MikyungKim marked this conversation as resolved.
Show resolved Hide resolved

##### Configuration

`defaultElement`
+ Type: [string|string[]]
Expand All @@ -291,43 +290,7 @@ provided, the first selector that successfully matches a node is used.
+ Default: `''`

If the focus originates from another container, you can define which element in
this container receives focus first.

`preserveId`
+ Type: [boolean]
+ Default: `false`

Whether the container will preserve the id when it unmounts.

#### Properties

`containerId`
+ Type: [string]

Specifies the container id. If the value is `null`, an id will be generated.

`spotlightDisabled`
+ Type: [boolean]
+ Default: `false`

When `true`, controls in the container cannot be navigated.

`spotlightMuted`
+ Type: [boolean]
+ Default: `false`

Whether or not the container is in muted mode. When in muted mode, Spottable controls within the container
can still gain focus, however their `:focus` CSS styles will not be applied, giving them the appearance
of not having focus. Muting a container is generally done to temporarily disable CSS changes and
default `onFocus` and `onBlur` events without removing focus from the container itself - which would
happen if you disabled the container using `spotlightDisabled`.

`spotlightRestrict`
+ Type: [string]
+ Values: [`'none'`, `'self-first'`, or `'self-only'`]
+ Default: `'none'`

Restricts or prioritizes focus to the controls in the current container.
this container receives focus first.
MikyungKim marked this conversation as resolved.
Show resolved Hide resolved

```js
import SpotlightContainerDecorator from '@enact/spotlight/SpotlightContainerDecorator';
Expand Down