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

# InlineContent

**Depreciated: [TextBox](/docs/text-textbox--basic) is the recommended component for rendering text and supports all properties of InlineContent**

Renders text, icons, and badges in line together.

## Source

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

## Usage

Pass in a `content` array containing simple strings or objects with badge or icon strings.

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

class Example extends lng.Component {
  static _template() {
    return {
      InlineContent: {
        type: InlineContent,
        content: [
          'example of simple text',
          {
            icon: 'http://myIconUrl.com/goeshere',
            title: 'to add voice out content (essentially alt text)',
            color: '00ff00'
          },
          { newline: true },
          { badge: 'HD' }
        ]
      }
    };
  }
}
```

<Canvas>
  <Story id="text-inlinecontent--basic" />
</Canvas>

## API

### Properties

| name                | type                                                                                          | required | default   | description                                                                                                                                                                                                                                                   |
| ------------------- | --------------------------------------------------------------------------------------------- | -------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| badgeProperties     | object                                                                                        | false    | undefined | styling to update the Badge component                                                                                                                                                                                                                         |
| badgeY              | number                                                                                        | false    | undefined | y value of all badges                                                                                                                                                                                                                                         |
| content             | string \| array                                                                               | false    | undefined | list of data to render inline, see [Content Element Properties](#content-element-properties) below                                                                                                                                                            |
| contentProperties   | object                                                                                        | false    | {}        | object setting flexItem props on all content items                                                                                                                                                                                                            |
| contentWrap         | boolean                                                                                       | false    | false     | determines whether the containing flexbox should wrap the content onto the next line                                                                                                                                                                          |
| justify             | 'flex-start' \| 'flex-end' \| 'center' \| 'space-between' \| 'space-around' \| 'space-evenly' | false    | center    | alignment of first line flexbox content                                                                                                                                                                                                                       |
| customStyleMappings | object                                                                                        | false    | {}        | set of nested objects containing [Lightning Text](https://rdkcentral.github.io/Lightning/docs/textures/text) properties which can be referenced in the [Content Element Properties](#content-element-properties) to apply styling to individual text elements |
| maxLines            | number                                                                                        | false    | undefined | maximum number of lines to render before truncation                                                                                                                                                                                                           |
| maxLinesSuffix      | string                                                                                        | false    | '..'      | suffix appended to last line of content if it will exceed the `maxLines`                                                                                                                                                                                      |

### Style Properties

| name           | type                                                                                          | description                                                                                                                                                                                                                                             |
| -------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| contentSpacing | number                                                                                        | padding between all content items                                                                                                                                                                                                                       |
| iconH          | number                                                                                        | height of each icon                                                                                                                                                                                                                                     |
| iconW          | number                                                                                        | width of each icon                                                                                                                                                                                                                                      |
| justify        | 'flex-start' \| 'flex-end' \| 'center' \| 'space-between' \| 'space-around' \| 'space-evenly' | alignment of first line flexbox content                                                                                                                                                                                                                 |
| marginBottom   | number                                                                                        | space beneath rendered content                                                                                                                                                                                                                          |
| maxLines       | number                                                                                        | Maximum number of lines to display before truncation                                                                                                                                                                                                    |
| textStyle      | string \| object                                                                              | Default style of text to be displayed. Object should come from the current theme or contain any properties that the [Lightning text texture supports](https://lightningjs.io/docs/#/lightning-core-reference/RenderEngine/Textures/Text?id=properties). |
| textY          | number                                                                                        | y value of all text                                                                                                                                                                                                                                     |

### Events

#### $loadedInlineContent(): void

Fires when all contents inside the InlineContent component have finished rendering their textures. This is when you will have all of the correct flex properties of the components as well as `finalH` available to be used.

### Content Element Properties

The `InlineContent` component will recognize the following elements inside its `content` param:

| string\|object                                                                                                             | description                                                                                                                                                                                                                                                                                                |
| -------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `'Text'` <br/><br/> `{ text: 'Text', style: { styleName: styleValue } }` <br/><br/> `{ text: 'Text', style: 'StyleName' }` | any stand alone string will be used a pure text, or an object with the properties of `text` and `style` can be passed to override the default text styles, and `style` can be passed a string which references a predefined entry in the [customStyleMappings](#properties) object passed to the component |
| `{ icon: 'pathToIcon', title: 'IconTitle' }`                                                                               | will render an [Icon](/story/elements-icon--text) with the given source and use the title param as the string to announce                                                                                                                                                                                  |
| `{ badge: 'BadgeName' }`                                                                                                   | will render a [Badge](/story/elements-badge--text)                                                                                                                                                                                                                                                         |
| `{ newline: true }`                                                                                                        | will insert a line break between content if the contentWrap param is true                                                                                                                                                                                                                                  |

#### Content String Markup

Additionally, the `content` param will automatically parse a string into the above elements using the following markup:

| string markup            | parsed element                         |
| ------------------------ | -------------------------------------- |
| `{ICON:title\|url}`      | `{ icon: 'url', title: 'title' }`      |
| `{BADGE:title}`          | `{ badge: 'title' }`                   |
| `{NEWLINE}`              | `{ newline: true }`                    |
| `{TEXT:text\|styleName}` | `{ text: 'text', style: 'styleName' }` |

For example:

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

class Example extends lng.Component {
  static _template() {
    return {
      InlineContent: {
        type: InlineContent,
        contentWrap: true,
        customStyleMappings: {
          red: { textColor: getHexColor('FF6194') }
        },
        content:
          'This is an {ICON:settings|./assets/icons/settings.png} icon and {BADGE:HD} badge with a{NEWLINE} and {TEXT:red text|red}.'
      }
    };
  }
}
```

will yield

```js
[
  'This is an ',
  { icon: './assets/icons/settings.png', title: 'settings' },
  ' icon and ',
  { badge: 'HD' },
  ' badge with a',
  { newline: true },
  ' and ',
  { text: 'red text', style: 'red' },
  '.'
];
```
