# HotkeyCapture

A component for capturing and displaying keyboard shortcuts or hotkey combinations.

## Usage

Use standalone.
```svelte
<HotkeyCapture {...props} />
```

## Anatomy

The `class` attribute values represent part names. Other attributes represent their corresponding props.

```svelte
<input class="main" {...rest} type="text" readonly />
```

## Props

| Name | Type | Default | Description |
|---|---|---|---|
| `value` | `string` | - | Bindable captured hotkey string |
| `active` | `boolean` | `false` | Bindable state for whether the component accepts input |
| `disabled` | `boolean` | `false` | Disables input and applies the `inactive` variant |
| `oncapture` | `(detail: HotkeyCaptureDetail) => void` | - | Callback fired on each captured combination, receiving modifier flags, trailing key, capture `kind`, and originating event |
| `attach` | `Attachment` | - | Svelte attachment on the input |
| `element` | `HTMLInputElement` | - | Bindable input element |
| `styling` | `SVSClass` | - | Styling override |
| `variant` | `SVSVariant` | `NEUTRAL` | Bindable variant |
Other `HTMLInputAttributes` are passed to `<input>` via rest props; `class` is merged onto the input.

## Styling

To learn more, see [Styling](/docs/styling).

### Variant Management

When the `disabled` prop is true, `inactive` is applied. When input is accepted (the `active` prop is true), `active` is applied; otherwise, `neutral` is applied. If the `variant` prop is specified, the specified value is applied instead of `neutral`.

### Default Class Name

`svs-hotkey-capture`

## Accessibility

### Keyboard Interactions

| Key | Description |
| --- | --- |
| `non-modifier key` | When focused and not disabled, records the key with any held `Ctrl`, `Alt`, `Shift`, and `Meta` modifiers, then fires `oncapture` |
| `Space` | Records as `SPACE` |
| `Control` / `Alt` / `Shift` / `Meta` | Ignored when pressed alone; recorded only as modifiers with another captured key |
Repeated keydown events, IME composition, and unstable keys (`Process`, `Dead`, `Unidentified`) are ignored. Pointer buttons and wheel direction are also captured by the component, but they are reported as pointer or wheel captures rather than keyboard captures.

## Exports

### Types

```ts
interface HotkeyCaptureDetail {
  value: string;
  ctrl: boolean;
  alt: boolean;
  shift: boolean;
  meta: boolean;
  key: string;
  kind: "key" | "pointer" | "wheel";
  event: KeyboardEvent | PointerEvent | WheelEvent;
}
interface HotkeyCaptureProps extends Omit<
  HTMLInputAttributes,
  "type" | "value" | "readonly" | "onkeydown" | "onpointerdown" | "onwheel" | "oncontextmenu"
> {
  value?: string; // bindable
  active?: boolean; // bindable (false)
  disabled?: boolean; // (false)
  oncapture?: (detail: HotkeyCaptureDetail) => void;
  attach?: Attachment<HTMLInputElement>;
  element?: HTMLInputElement; // bindable
  styling?: SVSClass;
  variant?: SVSVariant; // bindable (VARIANT.NEUTRAL)
  // class & other input attributes are passed to the input via ...rest (class is merged onto the input)
}
type HotkeyCaptureReqdProps = never;
type HotkeyCaptureBindProps = "value" | "active" | "variant" | "element";
```

### Others

```ts
// Parses a space-separated hotkey string (e.g. "Ctrl Shift A") into its modifier flags and trailing key.
function parseHotkey(value: string): Omit<HotkeyCaptureDetail, "event" | "kind">;
```

## Examples

The example code uses Tailwind CSS along with `SVSClass`.

### Basic

**Code**

```svelte src=HotkeyCaptureBasic.svelte
<script lang="ts">
  import { HotkeyCapture } from "svseeds";

  const styling = {
    main: "m-2 block w-full max-w-80 h-20 rounded-md border border-dashed text-xl font-medium text-center truncate",
  };
  const myProps = {
    placeholder: "Focus me and key in",
    styling,
  };
</script>

<HotkeyCapture {...myProps} />
```
### With Interactive Variant

**Code**

```svelte src=HotkeyCapturePract.svelte
<script lang="ts">
  import { HotkeyCapture } from "svseeds";

  let { variant = $bindable() } = $props();
  const variantStyle = {
    neutral: "border-gray-400 border-dashed",
    active: "border-teal-500 border-solid",
    inactive: "border-red-500 border-dashed",
    blue: "border-blue-500 border-dashed",
    yellow: "border-yellow-500 border-dashed",
    sky: "border-sky-500 border-dashed",
  };
  const styling = {
    main: {
      base: "m-2 block w-full max-w-80 h-20 rounded-md border-3 border-dashed outline-hidden text-xl font-medium text-center truncate",
      ...variantStyle,
    },
  };
  const myProps = {
    placeholder: "Focus me and key in",
    styling,
  };
</script>

<HotkeyCapture bind:variant {...myProps} />
```