<!--
  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 { Canvas, Story } from '@storybook/addon-docs';
import { DocsLink } from '../../docs/utils';
import Row from '.';

# Row

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
        ]
      }
    };
  }
}
```

<Canvas>
  <Story id="navigation-row--row" />
</Canvas>

### 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.

## 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

| name           | type                             | description                                                                                                                         |
| -------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| alwaysScroll   | boolean                          | when true, the row will stop scrolling as it nears the right edge to prevent white space                                            |
| neverScroll    | boolean                          | when true, the row will never scroll, unless alwaysScroll is set to true, and if false, the row will apply normal scrolling logic', |
| scrollIndex    | number                           | index of currently selected item                                                                                                    |
| itemSpacing    | number                           | spacing between items                                                                                                               |
| itemTransition | <DocsLink id="lng.Transition" /> | transition to apply to items on render                                                                                              |

### 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

#### 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.

#### appendItems(items: lng.Component[]): void

Adds items to the end of the child list

#### appendItemsAt(items: lng.Component[], index: number): void

Adds items at a specified index of the child list

#### prependItems(items: lng.Component[]): void

Adds items to the start of the child list

#### removeItemAt(index: number): void

Removes an item (by index) from the row

##### Arguments

| name  | type                                                    | required | default | description             |
| ----- | ------------------------------------------------------- | -------- | ------- | ----------------------- |
| items | <DocsLink id="lng.Component">lng.Component[]</DocsLink> | false    | []      | list of items to append |

#### render(): void

Called when item focus changes. Render is responsible for the scroll behavior
