{/* 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 } from '@storybook/blocks';
import * as withLayoutStories from './withLayout.stories';

<Meta of={withLayoutStories} />

# withLayout

Use `withLayout` to autotomatically size an item according to screen dimensions, upCount and/or set explicitly.

## Source

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

## Usage

Let's use an example to see how we can use `withLayout`. Let's say I have a `Tile` component on screen that should be sized according the screen size:

```js
import lng from '@lightningjs/core';
import { withLayout } from '@lightningjs/ui-components';

class Basic extends lng.Component {
  static _template() {
    return {
      Tile: {
        type: withLayout(Tile),
        src: parks,
        itemLayout: {
          ratioX: 16,
          ratioY: 9,
          upCount: 5
        }
      }
    };
  }
}
```

If I want to explicitly set a height but the only other information is the screen dimensions, I can do that by adding these parameters to the itemLayout object.

```js
import lng from '@lightningjs/core';
import { withLayout } from '@lightningjs/ui-components';

class Basic extends lng.Component {
  static _template() {
    return {
      Tile: {
        type: withLayout(Tile),
        src: parks,
        itemLayout: {
          ratioX: 16,
          ratioY: 9,
          h: 180
        }
      }
    };
  }
}
```

If I am unsure of the width, I can autosize by adding a height and upCount properties to the itemLayout object.

```js
import lng from '@lightningjs/core';
import { withLayout } from '@lightningjs/ui-components';

class Basic extends lng.Component {
  static _template() {
    return {
      Tile: {
        type: withLayout(Tile),
        src: parks,
        itemLayout: {
          h: 320,
          upCount: 4
        }
      }
    };
  }
}
```

**NOTE**: A combination of properties is required:

`h and w` (If explicitly set, it may be uncessary to use the withLayout pattern as these properties can be set on the component),
`h and ratioX and ratioY`,
`ratioX and ratioY and upCount`,
`h and upCount`,
`h`, and finally `w`

Auto sizing of the item will happen based on the above priority. So if the `w and h` are passed no other calculations will occur.
If the mixin is unable to calculate the height OR width from the passed parameters. The height will default 9/16 of the width. Inversely the width will default to 16/9 of the height.
If the mixin is unable to calculate height AND width from the passed parameters. No autosize will occur.

### Properties

| name       | type   | required | default | description                                                                  |
| ---------- | ------ | -------- | ------- | ---------------------------------------------------------------------------- |
| itemLayout | object | true     | -       | the auto sizing properties that will override explicitly set h/w for an item |

### itemLayout

| name    | type   | required | default | description                                                                                                                                                              |
| ------- | ------ | -------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| w       | number | false    | 0       | explicitly set the width of an item                                                                                                                                      |
| h       | number | false    | 0       | explicitly set the height of an item                                                                                                                                     |
| ratioX  | number | false    | 0       | units of x resolution relative to the screen height, should be a posititve integer                                                                                       |
| ratioY  | number | false    | 0       | units of y resolution relative to the screen width, should be a posititve integer                                                                                        |
| upCount | number | false    | 0       | the number of items that should be displayed within screen bounds. Additional items will run off-screen or outside of specified row width, should be a posititve integer |
