{/* 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 * as TextBoxStories from './TextBox.stories';

<Meta of={TextBoxStories} />

<Title />

General purpose TextBox component

## Source

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

## Usage

Set a content property with your text and specify a property style as a string.
TextBox also accepts inline content arrays and strings which are rendered using the [InlineContent](/docs/components-inlinecontent--test) component.

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

TextBox: {
  type: TextBox,
  content: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit.',
  fixed: true,
  w: 600,
  style: {
    textStyle: 'headline1'
  }
}
```

> **Note on width:**
>
> To assign a width to the `TextBox` component, either a `w` value or `wordWrapWidth` (nested within `textStyle` and the `style` prop) value may be provided.
>
> - If `wordWrapWidth` is defined, then the component will apply that property and the width should reflect the value accordingly.
> - If only a `w` value is provided and no `wordWrapWidth` is defined, the `TextBox` component will automatically apply a `wordWrapWidth` of the defined `w` value to the component.
>   **Important:** the `fixed` property must be set to `true` in this case.
> - If neither `w` or `wordWrapWidth` is defined, the component will automatically set the width to be the width of the component.

### Properties

| name       | type    | required | default   | description                                                                                                                                          |
| ---------- | ------- | -------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| content    | string  | true     | undefined | Text to be displayed in element                                                                                                                      |
| hideOnLoad | boolean | false    | undefined | If `true`, the component will not render as visible following the text texture loading. This allows manually controlling the alpha of the component. |
| fixed      | boolean | false    | false     | If `true`, allows the width of the text to be set with `w`                                                                                           |
| marquee    | boolean | false    | false     | Allows text to be scrollable                                                                                                                         |

TextBox also supports rendering as an InlineContent component. See [InlineContent documentation](/docs/components-inlinecontent--basic) for table of supported properties.

### Style Properties

| name      | type             | description                                                                                                                                                                                                                                             |
| --------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| offsetX   | number           | Used to ensure text is positioned correctly                                                                                                                                                                                                             |
| offsetY   | number           | Used to ensure text is positioned correctly                                                                                                                                                                                                             |
| 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). |

### Methods

#### toggleMarquee(): void

This will restart or stop marquee scrolling to match the marquee flag in case it has changed.
