<!--
  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 ControlRow from '.';

# ControlRow

The `ControlRow` component renders a
[TitleRow](/docs/layout-titlerow--basic) component with optional left controls content items, and right controls
which are rendered as row items in that order.

## Source

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

## Usage

`ControlRow` accepts all [properties supported by TitleRow](/docs/layout-titlerow--basic#properties)
as well as optional `leftControls`, `contentItems`, and `rightControls` properties.

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

class Example extends lng.Component {
  static _template() {
    return {
      ControlRow: {
        type: ControlRow,
        leftControls: [
          // list of components to display as left controls
        ],
        contentItems: [
          // list of components to display as content items
        ],
        rightControls: [
          // list of components to display as right controls
        ]
      }
    };
  }
  _getFocused() {
    return this.tag('ControlRow');
  }
}
```

<Canvas>
  <Story id="navigation-controlrow--basic" />
</Canvas>

### lazyLoading

The `ControlRow` component can be configured for lazy loading content items by utilizing the `lazyLoadBuffer` property and `'loadMoreItems'` signal. When a positive number is assigned to `ControlRow.lazyLoadBuffer`, the `ControlRow` will emit a signal, `'loadMoreItems'`. The `lazyLoadBuffer` property defines how many items before the last `contentItems` is the index at which `'loadMoreItems'` will be emitted. The `ControlRow` does not include further side effects to this signal being emitted, but allows parent components to listen for that signal and add further functionality to the component (ex. fetching more content items and appending them to the ControlRow via the `ControlRow.addContentItems` method). If the number of content items in the `ControlRow` is updated (adding or removing content items), the new length of content items will be used to calculate at which index the next `'loadMoreItems'` signal is emitted.

```js
class LazyLoad extends lng.Component {
  static _template() {
    return {
      LazyLoad: {
        type: ControlRow,
        leftControls: [leftControlA, leftControlB],
        contentItems: [contentItemA, contentItemB, contentItemC],
        rightControls: [rightControlA, rightControlB],
        // The loadMoreItems signal will be emitted when the content item 1 before the last content item is focused.
        lazyLoadBuffer: 1,
        // When ControlRow emits the loadMoreItems signal, call this._loadMore().
        signals: {
          loadMoreItems: '_loadMore'
        }
      }
    };
  }

  _loadMore() {
    // fetch more items from an API
    // append those items to the ControlRow via this.tag('ControlRow').addContentItems(itemsToAdd)
  }
}
```

## API

### Properties

**`ControlRow` is a subclass of the [`TitleRow`](/docs/layout-titlerow--basic)**,
so allows setting all properties that are available on `TitleRow`.

| name             | type          | required | default         | description                                                                                   |
| ---------------- | ------------- | -------- | --------------- | --------------------------------------------------------------------------------------------- |
| leftControls     | `Component[]` | false    | []              | Controls displayed at left of row of items.                                                   |
| contentItems     | `Component[]` | false    | []              | Items displayed in row. Array of patch objects.                                               |
| rightControls    | `Component[]` | false    | []              | Controls displayed at right of row of items.                                                  |
| extraItemSpacing | number        | false    | theme.spacer.lg | additional space to be added between controls and content items                               |
| lazyLoadBuffer   | number        | false    | 0               | Number of content items prior to last content items where a "loadMoreItems" signal is emitted |

## Methods

#### loadMoreItems

By default fires a signal, `'loadMoreItems'`, when an item is selected after an index determined by the `lazyLoadBuffer` property

#### addContentItems(items: Component[])

Adds items to the end of the row

#### addContentItemsAt(items: Component[], index: number)

Adds items at a specified index of the row

#### removeContentItemAt(index: number)

Removes an item at the specified index

#### addLeftControls(controls: Component[] || `ComponentPatchObj<ControlSmall>[]`)

Adds controls to the end of the left controls

#### addLeftControlsAt(controls: Component[] || `ComponentPatchObj<ControlSmall>[]`, index: number)

Adds controls at a specified index of the left controls

#### removeLeftControlAt(index: number)

Removes a left control at the specified index

#### addRightControls(controls: Component[] || `ComponentPatchObj<ControlSmall>[]`)

Adds controls to the end of the right controls

#### addRightControlsAt(controls: Component[] || `ComponentPatchObj<ControlSmall>[]`, index: number)

Adds controls at a specified index of the right controls

#### removeRightControlAt(index: number)

Removes a right control at the specified index

## Signals

## loadMoreItems

Emitted when an item is selected after an index determined by the `lazyLoadBuffer` property.
