{/* prettier-ignore */}
{/*
Copyright 2023 Comcast Cable Communications Management, LLC

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

SPDX-License-Identifier: Apache-2.0
\*/}

import { Meta, Title } from '@storybook/blocks';
import { DocsLink } from '../../docs/utils';
import * as RowStories from './Row.stories';

<Meta of={RowStories} />

<Title />

Focus management and smooth scrolling for a list of horizontally-oriented items.

## Source

https://github.com/rdkcentral/Lightning-UI-Components/blob/develop/packages/@lightningjs/ui-components/src/components/Row/Row.js

## Usage

`Row` expects a list of `items` which will be laid out side-by-side. By default, the height of `Row`'s Item container is the same as the height of the tallest item, and the width is the width passed in, the width of the wrapping FocusManager if available, or the width of the stage by default. You can change the `w` and `h` attributes to manage `width` and `height`, respectively.

```js
import { Row } from '@lightningjs/ui-components';

class Basic extends lng.Component {
  static _template() {
    return {
      Row: {
        type: Row,
        items: [
          // list of items
        ]
      }
    };
  }
}
```

### Scrolling

By default, `Row` will scroll horizontally to see any items that are not visible within the width of the Row((or just outside of the `Row` width)

The `scrollIndex` property determines the index at which scrolling should begin. By default, that index is 0.
Scroll behavior is determined based on what is passed to the `alwaysScroll`, `lazyScroll`, and `neverScroll` properties.
If multiple of these properties are enabled, the order of precedence from highest to lowest is: `alwaysScroll`, `lazyScroll`, `neverScroll`.

## API

### Properties

| name                 | type                                                    | required | default   | description                                                                                                                                                                          |
| -------------------- | ------------------------------------------------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| items                | <DocsLink id="lng.Component">lng.Component[]</DocsLink> | false    | undefined | components to be listed in the row.                                                                                                                                                  |
| lazyScroll           | boolean                                                 | false    | false     | will only scroll the row if the item is off screen and alwaysScroll and neverScroll are both false                                                                                   |
| selected             | <DocsLink id="lng.Component" />                         | true     | undefined | component that is currently in focus                                                                                                                                                 |
| selectedIndex        | number                                                  | false    | 0         | index of currently selected item                                                                                                                                                     |
| startLazyScrollIndex | number                                                  | false    | undefined | when `lazyScroll` is `true`, index of item in `items`, and items thereafter, at which lazy scrolling should occur at (alwasy scroll functionality will take place before this index) |
| stopLazyScrollIndex  | number                                                  | false    | undefined | when `lazyScroll` is `true`, index of item in `items`, and items preceding, at which lazy scrolling should occur (alwasy scroll functionality will take place after this index)      |

### Style Properties

The Row component shares the same style properties as the ones listed in NavigationManager. For a detailed description, please refer to style properties section in the [NavigationManager component](?path=/docs/components-navigationmanager--docs#style-properties)

### Child Item Properties

The `Row` component will utilize the following properties on each individual element in its `items` array:

| name             | type    | required | default | description                                                      |
| ---------------- | ------- | -------- | ------- | ---------------------------------------------------------------- |
| centerInParent   | boolean | false    | false   | when true, it places the child component in center of the parent |
| extraItemSpacing | number  | false    | 0       | additional space to be added between items                       |

### Methods

The Row component is a subclass of NavigationManager and FocusManager, so inherits all methods from those parent components. These shared methods are already documented in the NavigationManager and FocusManager documentation. For detailed descriptions of these methods, please refer to the methods section in the [NavigationManager](/?path=/docs/components-navigationmanager--row) and [FocusManager](/docs/components-focusmanager--column-with-rows) documentation.

#### onScreenEffect(onScreenItems: lng.Component[]): void

A callback that can be overridden to do something with the items that are currently on screen. This will be called on every new render.
