feat: add Kbd component

apps/www/src/content/docs/components/command/index.mdx

@@ -97,7 +97,7 @@ Visual divider between groups. The separator is hidden automatically while the u
 
 ### Shortcut
 
-A `<kbd>` element for keyboard hints. Typically passed as `trailingIcon` on `Command.Item`.
+Keyboard hints for an item, typically passed as `trailingIcon` on `Command.Item`. Built on [`Kbd`](/docs/components/kbd): it renders a `Kbd.Group` of `ghost` keys and forwards every prop.
 
 <auto-type-table path="./props.ts" name="CommandShortcutProps" />
 

apps/www/src/content/docs/components/command/props.ts

@@ -132,6 +132,18 @@ export interface CommandSeparatorProps {
 }
 
 export interface CommandShortcutProps {
+  /**
+   * The keys to display. A whitespace-separated string is split into one key
+   * per token, so `"⌘ K"` renders two keys.
+   */
+  children?: React.ReactNode;
+
+  /**
+   * Visual style variant, applied to every key in the shortcut.
+   * @defaultValue "ghost"
+   */
+  variant?: 'solid' | 'ghost';
+
   /** Additional CSS class names. */
   className?: string;
 }

apps/www/src/content/docs/components/kbd/demo.ts

@@ -0,0 +1,121 @@
+'use client';
+
+import type { ComponentPropsType } from '@/components/demo/types';
+import { getPropsString } from '@/lib/utils';
+
+export const getCode = (props: ComponentPropsType) => {
+  const { children, ...rest } = props;
+
+  return `<Kbd${getPropsString(rest)}>${children}</Kbd>`;
+};
+
+export const playground = {
+  type: 'playground',
+  controls: {
+    variant: {
+      type: 'select',
+      options: ['solid', 'ghost'],
+      defaultValue: 'solid'
+    },
+    children: {
+      type: 'text',
+      initialValue: 'Esc'
+    }
+  },
+  getCode
+};
+
+export const singleDemo = {
+  type: 'code',
+  code: `<Flex gap={5} align="center">
+    <Kbd>Esc</Kbd>
+    <Kbd aria-label="Command">⌘</Kbd>
+    <Kbd aria-label="Shift">⇧</Kbd>
+    <Kbd aria-label="Enter">↵</Kbd>
+    <Kbd>Tab</Kbd>
+  </Flex>`
+};
+
+export const variantDemo = {
+  type: 'code',
+  code: `<Flex gap={7} align="center">
+    <Kbd.Group>
+      <Kbd aria-label="Command">⌘</Kbd>
+      <Kbd>K</Kbd>
+    </Kbd.Group>
+    <Kbd.Group variant="ghost">
+      <Kbd aria-label="Command">⌘</Kbd>
+      <Kbd>K</Kbd>
+    </Kbd.Group>
+  </Flex>`
+};
+
+export const groupDemo = {
+  type: 'code',
+  code: `<Flex gap={7} align="center">
+    <Kbd.Group>
+      <Kbd aria-label="Command">⌘</Kbd>
+      <Kbd>K</Kbd>
+    </Kbd.Group>
+    <Kbd.Group>
+      <Kbd aria-label="Command">⌘</Kbd>
+      <Kbd aria-label="Shift">⇧</Kbd>
+      <Kbd>P</Kbd>
+    </Kbd.Group>
+  </Flex>`
+};
+
+export const separatorDemo = {
+  type: 'code',
+  tabs: [
+    {
+      name: 'Plus',
+      code: `<Kbd.Group>
+        <Kbd aria-label="Command">⌘</Kbd>
+        +
+        <Kbd>K</Kbd>
+      </Kbd.Group>`
+    },
+    {
+      name: 'Then',
+      code: `<Kbd.Group>
+        <Kbd>G</Kbd>
+        then
+        <Kbd>P</Kbd>
+      </Kbd.Group>`
+    }
+  ]
+};
+
+export const withTextDemo = {
+  type: 'code',
+  code: `<Text size="small" variant="secondary">
+    Press <Kbd.Group><Kbd aria-label="Command">⌘</Kbd><Kbd>K</Kbd></Kbd.Group> to open the command palette.
+  </Text>`
+};
+
+export const withInputDemo = {
+  type: 'code',
+  code: `<Input
+    placeholder="Search projects"
+    trailingIcon={<Kbd variant="ghost" aria-label="Command K">⌘K</Kbd>}
+  />`
+};
+
+export const withTooltipDemo = {
+  type: 'code',
+  code: `<Tooltip>
+    <Tooltip.Trigger render={<Button variant="outline" />}>
+      Search
+    </Tooltip.Trigger>
+    <Tooltip.Content>
+      <Flex gap={3} align="center">
+        Open search
+        <Kbd.Group variant="ghost">
+          <Kbd aria-label="Command">⌘</Kbd>
+          <Kbd>K</Kbd>
+        </Kbd.Group>
+      </Flex>
+    </Tooltip.Content>
+  </Tooltip>`
+};

apps/www/src/content/docs/components/kbd/index.mdx

@@ -0,0 +1,110 @@
+---
+title: Kbd
+description: A component for displaying keyboard keys and shortcuts.
+source: packages/raystack/components/kbd
+tag: new
+---
+
+import {
+  playground,
+  singleDemo,
+  variantDemo,
+  groupDemo,
+  separatorDemo,
+  withTextDemo,
+  withInputDemo,
+  withTooltipDemo,
+} from "./demo.ts";
+
+<Demo data={playground} />
+
+## Anatomy
+
+Import and assemble the component. A single `Kbd` renders one key; wrap several in `Kbd.Group` to show a sequence.
+
+```tsx
+import { Kbd } from "@raystack/apsara";
+
+<Kbd>Esc</Kbd>
+
+<Kbd.Group>
+  <Kbd>⌘</Kbd>
+  <Kbd>K</Kbd>
+</Kbd.Group>
+```
+
+## API Reference
+
+Both parts render a `<kbd>` element and forward any native attributes (`id`, `title`, `aria-label`, …) to it.
+
+### Root
+
+A single keyboard key. Renders a `<kbd>` element.
+
+<auto-type-table path="./props.ts" name="KbdProps" />
+
+### Group
+
+Groups multiple keyboard keys for key combinations.
+
+<auto-type-table path="./props.ts" name="KbdGroupProps" />
+
+### Slots
+
+Every rendered part carries a stable `data-slot` attribute for [styling and testing](/docs/styling#with-data-slot):
+
+| Slot | Element |
+|------|---------|
+| `kbd` | Each individual key |
+| `kbd-group` | The `Kbd.Group` wrapper |
+
+## Examples
+
+### Single keys
+
+Use `Kbd` on its own for a one-key hint. Keys share a minimum width so a narrow `K` lines up with a wide `⌘`.
+
+<Demo data={singleDemo} />
+
+### Variants
+
+`solid` is the default and suits standalone hints. Use `ghost` on surfaces that already have their own background, such as a menu row, a tooltip, or an input.
+
+<Demo data={variantDemo} />
+
+### Sequences
+
+Wrap keys in `Kbd.Group` to show a chord. Setting `variant` on the group applies it to every key inside.
+
+<Demo data={groupDemo} />
+
+### Separators
+
+`Kbd.Group` renders whatever you put between the keys, so separators are plain text. Use `+` for keys pressed together and a word like `then` for keys pressed in order. Separator text takes the surrounding typography rather than the key styling.
+
+<Demo data={separatorDemo} />
+
+### Inline with text
+
+Keys sit on the text baseline, so they can be dropped straight into a sentence.
+
+<Demo data={withTextDemo} />
+
+### In an input
+
+Surface a focus shortcut in a search field. Use a single `ghost` key here — the input's trailing slot is sized for an icon, so a multi-key `Kbd.Group` will be clipped.
+
+<Demo data={withInputDemo} />
+
+### In a tooltip
+
+A common use is surfacing a shortcut alongside the action it triggers.
+
+<Demo data={withTooltipDemo} />
+
+## Accessibility
+
+- `Kbd` is presentational and renders the semantic `<kbd>` element. It has no ARIA role of its own and is not exposed as a separate accessible object, so it does not change how surrounding content is announced.
+- Symbol-only keys such as `⌘`, `⇧`, or `↵` are not announced usefully on their own — they are read by their Unicode names, if at all. Add an `aria-label` when the symbol is the only cue: `<Kbd aria-label="Command">⌘</Kbd>`.
+- Keys are not focusable and carry no interaction. Keep the shortcut wired to a real handler elsewhere — `Kbd` only displays it.
+- Keys ignore pointer events and text selection, so clicking or dragging across a menu row does not highlight the key labels.

apps/www/src/content/docs/components/kbd/props.ts

@@ -0,0 +1,29 @@
+import type { ReactNode } from 'react';
+
+export interface KbdProps {
+  /** The key to display, e.g. `⌘`, `Esc`, or `Enter`. */
+  children?: ReactNode;
+
+  /**
+   * Visual style variant. Inherited from a parent `Kbd.Group` when set there.
+   * @defaultValue "solid"
+   */
+  variant?: 'solid' | 'ghost';
+
+  /** Additional CSS class names. */
+  className?: string;
+}
+
+export interface KbdGroupProps {
+  /** The keys in the sequence, plus any plain-text separators between them. */
+  children?: ReactNode;
+
+  /**
+   * Visual style variant applied to every key in the group.
+   * @defaultValue "solid"
+   */
+  variant?: 'solid' | 'ghost';
+
+  /** Additional CSS class names. */
+  className?: string;
+}

packages/raystack/components/command/__tests__/command.test.tsx

@@ -2,6 +2,8 @@ import { fireEvent, render, screen, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import * as React from 'react';
 import { describe, expect, it, vi } from 'vitest';
+import { Kbd } from '../../kbd';
+import kbdStyles from '../../kbd/kbd.module.css';
 import { Command } from '../command';
 import styles from '../command.module.css';
 
@@ -315,4 +317,57 @@ describe('Command', () => {
       });
     });
   });
+
+  describe('Command.Shortcut', () => {
+    it('splits a string of keys into individual keys', () => {
+      render(<Command.Shortcut>⌘ K</Command.Shortcut>);
+      expect(screen.getByText('⌘')).toBeInTheDocument();
+      expect(screen.getByText('K')).toBeInTheDocument();
+    });
+
+    it('renders each key through Kbd', () => {
+      render(<Command.Shortcut>⌘ K</Command.Shortcut>);
+      const key = screen.getByText('⌘');
+      expect(key.tagName).toBe('KBD');
+      expect(key).toHaveClass(kbdStyles['kbd']);
+    });
+
+    it('defaults its keys to the ghost variant', () => {
+      render(<Command.Shortcut>⌘ K</Command.Shortcut>);
+      expect(screen.getByText('⌘')).toHaveClass(kbdStyles['kbd-ghost']);
+    });
+
+    it('allows the variant to be overridden', () => {
+      render(<Command.Shortcut variant='solid'>⌘ K</Command.Shortcut>);
+      expect(screen.getByText('⌘')).toHaveClass(kbdStyles['kbd-solid']);
+    });
+
+    it('forwards props and merges className onto the group', () => {
+      const { container } = render(
+        <Command.Shortcut className='custom' aria-label='Command K'>
+          ⌘ K
+        </Command.Shortcut>
+      );
+      const group = container.querySelector('[data-slot="command-shortcut"]');
+      expect(group).toHaveClass('custom');
+      expect(group).toHaveClass(styles.shortcut);
+      expect(group).toHaveAttribute('aria-label', 'Command K');
+    });
+
+    it('forwards ref', () => {
+      const ref = React.createRef<HTMLElement>();
+      render(<Command.Shortcut ref={ref}>⌘ K</Command.Shortcut>);
+      expect(ref.current?.tagName).toBe('KBD');
+    });
+
+    it('does not double-wrap element children in a second key', () => {
+      const { container } = render(
+        <Command.Shortcut>
+          <Kbd>⌘</Kbd>
+        </Command.Shortcut>
+      );
+      const keys = container.querySelectorAll(`.${kbdStyles['kbd']}`);
+      expect(keys).toHaveLength(1);
+    });
+  });
 });