# Kbd

Keyboard key primitive for shortcuts, inline command hints, and compact keycap groups.

Use Kbd when the UI needs to display the key or shortcut that triggers an action, not to capture keyboard input itself.

## Import

```ts
import { KbdComponent, KbdGroupComponent } from '@edsis/component/kbd';
```

## Composition

The Angular structure mirrors shadcn's `Kbd` and `KbdGroup` composition while keeping the host choice flexible.

```text
kbd[Kbd] or Kbd
KbdGroup or [KbdGroup]
├── kbd[Kbd] or Kbd
└── kbd[Kbd] or Kbd
```

## Basic usage

Prefer a native `<kbd>` host when you want built-in keyboard-input semantics in the DOM.

```html
<p class="inline-flex items-center gap-2 text-sm text-muted-foreground">
  Press <kbd Kbd>Ctrl</kbd> <kbd Kbd>K</kbd> to open search.
</p>
```

## Common patterns

### Key groups

Use `KbdGroup` when several keycaps should read as one shortcut cluster or one family of related commands.

```html
<KbdGroup>
  <kbd Kbd>Ctrl + B</kbd>
  <kbd Kbd>Ctrl + K</kbd>
</KbdGroup>
```

### Button companion

Use Kbd inside the button label when the shortcut is part of the visible affordance.

```html
<button Button type="button" variant="outline">
  Accept
  <kbd Kbd class="translate-x-0.5">⏎</kbd>
</button>
```

### Input group shortcut hint

Pair Kbd with the existing input-group primitives for launcher shortcuts and command-palette patterns.

```html
<InputGroup class="max-w-sm">
  <input InputGroupInput placeholder="Search..." />
  <InputGroupAddon>
    <span aria-hidden="true">⌕</span>
  </InputGroupAddon>
  <InputGroupAddon align="inline-end">
    <KbdGroup>
      <kbd Kbd>⌘</kbd>
      <kbd Kbd>K</kbd>
    </KbdGroup>
  </InputGroupAddon>
</InputGroup>
```

### Tooltip mapping

The local tooltip primitive is a thin string-based wrapper around `matTooltip`, so rich tooltip content with embedded Kbd chips maps to plain tooltip text plus optional visible shortcut chips in adjacent markup.

```html
<button Button type="button" variant="outline" [Tooltip]="'Save changes (S)'">Save</button>
<button Button type="button" variant="outline" [Tooltip]="'Print document (Ctrl + P)'">
  Print
</button>
```

### RTL

Set `dir="rtl"` on an ancestor container when the shortcut rows live in a right-to-left layout.

```html
<div dir="rtl" lang="ar" class="flex flex-col items-center gap-4">
  <KbdGroup>
    <kbd Kbd>⌘</kbd>
    <kbd Kbd>⇧</kbd>
    <kbd Kbd>⌥</kbd>
    <kbd Kbd>⌃</kbd>
  </KbdGroup>

  <KbdGroup>
    <kbd Kbd>Ctrl</kbd>
    <span aria-hidden="true">+</span>
    <kbd Kbd>B</kbd>
  </KbdGroup>
</div>
```

## API reference

| Primitive           | Input   | Type     | Default | Notes                                         |
| ------------------- | ------- | -------- | ------- | --------------------------------------------- |
| `KbdComponent`      | `class` | `string` | `''`    | Extra Tailwind classes merged onto the keycap |
| `KbdGroupComponent` | `class` | `string` | `''`    | Extra Tailwind classes merged onto the group  |

## Styling and theming

`Kbd` uses `border-border`, `bg-background`, `text-foreground`, and the shared `rounded-md` radius token so it stays aligned with buttons, inputs, and tooltip surfaces.

The default typography is mono, compact, and non-selectable to match shadcn's keycap treatment without introducing a separate icon or badge variant system.

## Accessibility

- Prefer `<kbd Kbd>` when you want native keyboard-input semantics in the markup.
- Keep decorative separators such as `+` or `/` `aria-hidden` when the surrounding sentence already communicates the shortcut clearly.
- Kbd is presentational. The actionable control still needs the accessible name, tooltip text, and focus behavior.

## Keyboard interactions

Kbd and KbdGroup do not add keyboard behavior. Buttons, links, inputs, tooltip triggers, and menu items composed with them keep their native keyboard model.

## Angular notes

- There is no React-style `data-icon="inline-end"` API. Use the normal `class` input for spacing or alignment adjustments.
- Import neighboring primitives such as Button, Input Group, or Tooltip separately. The Kbd entrypoint stays intentionally focused.

## Source parity

This Angular slice covers the shadcn Kbd preview, grouped keycaps, button companion usage, input-group shortcut hints, RTL examples, and API/accessibility guidance.

The upstream tooltip example uses rich tooltip content with embedded keycaps. In this repo that maps to the existing string-based tooltip directive, so the shortcut lives in the tooltip message instead of projected tooltip markup.