{/* 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 KeyStories from './Key.stories';

<Meta of={KeyStories} />

<Title />

An extension of the Button component that represents an individual key on a keyboard

## Source

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

## Usage

The Key component takes in a title or icon which can be automatically pushed to the Keyboard component's input field.

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

class Basic extends lng.Component {
  static _template() {
    return {
      Key: {
        type: Key
      }
    };
  }
}
```

### Sizing

There are two options for setting the width of a `Key`: dynamically based of the `baseWidth` and `sizes` style properties, or setting a fixed width manually.

For dynamic sizing, the width of the smallest `Key` is defined as the `baseWidth` style property. Then, by setting the `size` property, the `Key` width will increase by multiples of that `baseWdith` (plus the spacing between `Key` components on a `Keyboard`, defined by the `keySpacing` property).

For fixed sizing, set the `fixed` property to `true` and define the `w` property.

## API

### Properties

| name       | type     | required | default   | description                                                                                                                                                                                                           |
| ---------- | -------- | -------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| fixed      | boolean  | false    | false     | when true, `w` overrides dynamically calculated width                                                                                                                                                                 |
| icon       | string   | false    | null      | url for icon                                                                                                                                                                                                          |
| onEnter    | function | false    | undefined | if defined, will be invoked when enter is pressed while focused on the `Key` component. When defined, the `$onSoftKey` and `$toggleKeyboard` events will not be emitted from the key (see Events section below)       |
| size       | string   | false    | sm        | width of the Key                                                                                                                                                                                                      |
| toggle     | boolean  | false    | undefined | If true, pressing the key will trigger the $toggleKeyboard event. If false, the key will trigger the $onSoftKey event                                                                                                 |
| keySpacing | number   | false    | 0         | The horizontal spacing between each key in a [Keyboard](?path=/docs/components-keyboard--docs). This value is factored into the width of the key so that it aligns with with the borders of other keys in a Keyboard. |

### Style Properties

| name       | type             | description                                                                                                              |
| ---------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------ |
| baseWidth  | number           | The base width of a key. This value will be multiplied based on the `size` property of the key                           |
| iconWidth  | number           | width set to all icons                                                                                                   |
| iconHeight | number           | height set to all icons                                                                                                  |
| minWidth   | number           | used as a fallback width if no width is passed into the component and `fixed` is false                                   |
| paddingX   | number           | space between the button horizontal edge and the content                                                                 |
| sizes      | object           | used to determine the width of key, contains the properties `sm`, `md`, `lg`, `xl`. See Sizing section for more details. |
| textStyle  | string \| object | text style to apply to the title                                                                                         |

### Events

#### `$onSoftKey({ key: string, toggle: boolean })`

Fired when the enter key is pressed while focused on a `Key` component. An event will be emitted
via Lightning's `fireAncestors` with an object of the `Key`'s `title` and `toggle` property values.
If a funciton is passed to the `Key`'s `onEnter` property, that function will be invoked and the
`$onSoftKey` event will not be emitted.

#### `$toggleKeyboard({ key: string, toggle: boolean })`

Fired when the enter key is pressed while focused on a `Key` component with its `toggle` property
set to `true`. If a funciton is passed to the `Key`'s `onEnter` property, that function will be invoked and the
`$toggleKeyboard` event will not be emitted.
