@aleph-alpha/ui-library 1.11.0 → 1.13.0

package/src/components/UiKbd/UiKbd.stories.ts

@@ -0,0 +1,546 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+import { ref, onMounted, onUnmounted } from 'vue';
+import UiKbd from './UiKbd.vue';
+import UiKbdGroup from './UiKbdGroup.vue';
+import { UiButton } from '../UiButton';
+import { UiTooltipRoot, UiTooltipContent, UiTooltipProvider, UiTooltipTrigger } from '../UiTooltip';
+import {
+  UiDrawer,
+  UiDrawerClose,
+  UiDrawerContent,
+  UiDrawerDescription,
+  UiDrawerFooter,
+  UiDrawerHeader,
+  UiDrawerTitle,
+} from '../UiDrawer';
+
+const meta: Meta<typeof UiKbd> = {
+  title: 'Components/UiKbd',
+  component: UiKbd,
+  tags: ['autodocs'],
+  argTypes: {
+    size: {
+      control: 'select',
+      options: ['sm', 'default', 'lg'],
+      description: 'Size variant for the kbd element',
+    },
+  },
+  args: {
+    size: 'default',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof UiKbd>;
+
+const defaultTemplateSource = `<script setup lang="ts">
+import { UiKbd, UiKbdGroup } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <div class="flex flex-col items-center gap-4">
+    <UiKbdGroup>
+      <UiKbd>⌘</UiKbd>
+      <UiKbd>⇧</UiKbd>
+      <UiKbd>⌥</UiKbd>
+      <UiKbd>⌃</UiKbd>
+    </UiKbdGroup>
+
+    <UiKbdGroup>
+      <UiKbd>Ctrl</UiKbd>
+      <span>+</span>
+      <UiKbd>B</UiKbd>
+    </UiKbdGroup>
+  </div>
+</template>`;
+
+/**
+ * Default keyboard shortcut display with modifier symbols and key combinations.
+ * Use the size control to change the kbd size.
+ */
+export const Default: Story = {
+  render: (args) => ({
+    components: { UiKbd, UiKbdGroup },
+    setup() {
+      return { args };
+    },
+    template: `
+      <div class="flex flex-col items-center gap-4">
+        <UiKbdGroup>
+          <UiKbd v-bind="args">⌘</UiKbd>
+          <UiKbd v-bind="args">⇧</UiKbd>
+          <UiKbd v-bind="args">⌥</UiKbd>
+          <UiKbd v-bind="args">⌃</UiKbd>
+        </UiKbdGroup>
+
+        <UiKbdGroup>
+          <UiKbd v-bind="args">Ctrl</UiKbd>
+          <span>+</span>
+          <UiKbd v-bind="args">B</UiKbd>
+        </UiKbdGroup>
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: defaultTemplateSource,
+      },
+    },
+  },
+};
+
+const interactiveTemplateSource = `<script setup lang="ts">
+import { ref, onMounted, onUnmounted } from 'vue'
+import { UiKbd, UiKbdGroup, UiButton, UiDrawer, UiDrawerContent, UiDrawerHeader, UiDrawerTitle, UiDrawerDescription, UiDrawerFooter, UiDrawerClose } from '@aleph-alpha/ui-library'
+
+const isDrawerOpen = ref(false)
+const showHelp = ref(false)
+
+const handleKeydown = (e: KeyboardEvent) => {
+  if ((e.ctrlKey || e.metaKey) && e.key === '.') {
+    e.preventDefault()
+    isDrawerOpen.value = true
+  }
+  if ((e.ctrlKey || e.metaKey) && e.key === '/') {
+    e.preventDefault()
+    showHelp.value = !showHelp.value
+  }
+  if (e.key === 'Escape') {
+    isDrawerOpen.value = false
+    showHelp.value = false
+  }
+}
+
+onMounted(() => window.addEventListener('keydown', handleKeydown))
+onUnmounted(() => window.removeEventListener('keydown', handleKeydown))
+</script>
+
+<template>
+  <div class="flex flex-col gap-3 rounded-lg border p-4">
+    <div class="flex items-center justify-between gap-8">
+      <span class="text-sm">Open Command Palette</span>
+      <UiKbdGroup>
+        <UiKbd>Ctrl</UiKbd>
+        <span class="text-muted-foreground">+</span>
+        <UiKbd>.</UiKbd>
+      </UiKbdGroup>
+    </div>
+    <div class="flex items-center justify-between gap-8">
+      <span class="text-sm">Toggle Help</span>
+      <UiKbdGroup>
+        <UiKbd>Ctrl</UiKbd>
+        <span class="text-muted-foreground">+</span>
+        <UiKbd>/</UiKbd>
+      </UiKbdGroup>
+    </div>
+  </div>
+
+  <UiDrawer v-model:open="isDrawerOpen">
+    <UiDrawerContent>
+      <UiDrawerHeader>
+        <UiDrawerTitle>Command Palette</UiDrawerTitle>
+        <UiDrawerDescription>
+          Press <UiKbd size="sm">Esc</UiKbd> to close.
+        </UiDrawerDescription>
+      </UiDrawerHeader>
+    </UiDrawerContent>
+  </UiDrawer>
+</template>`;
+
+/**
+ * Interactive keyboard shortcut demo. Press the keyboard shortcuts to trigger actions!
+ * - Press `Ctrl/⌘ + .` to open the command palette drawer
+ * - Press `Ctrl/⌘ + /` to toggle help
+ */
+export const Interactive: Story = {
+  parameters: {
+    docs: {
+      source: {
+        code: interactiveTemplateSource,
+      },
+    },
+  },
+  render: () => ({
+    components: {
+      UiKbd,
+      UiKbdGroup,
+      UiButton,
+      UiDrawer,
+      UiDrawerClose,
+      UiDrawerContent,
+      UiDrawerDescription,
+      UiDrawerFooter,
+      UiDrawerHeader,
+      UiDrawerTitle,
+    },
+    setup() {
+      const isDrawerOpen = ref(false);
+      const showHelp = ref(false);
+      const lastPressed = ref('');
+
+      const handleKeydown = (e: KeyboardEvent) => {
+        if ((e.ctrlKey || e.metaKey) && e.key === '.') {
+          e.preventDefault();
+          isDrawerOpen.value = true;
+          lastPressed.value = 'Ctrl + .';
+        }
+        if ((e.ctrlKey || e.metaKey) && e.key === '/') {
+          e.preventDefault();
+          showHelp.value = !showHelp.value;
+          lastPressed.value = 'Ctrl + /';
+        }
+        if (e.key === 'Escape') {
+          isDrawerOpen.value = false;
+          showHelp.value = false;
+          lastPressed.value = 'Esc';
+        }
+      };
+
+      onMounted(() => {
+        window.addEventListener('keydown', handleKeydown);
+      });
+
+      onUnmounted(() => {
+        window.removeEventListener('keydown', handleKeydown);
+      });
+
+      return { isDrawerOpen, showHelp, lastPressed };
+    },
+    template: `
+      <div class="flex flex-col items-center gap-6 p-4">
+        <div class="text-center space-y-2">
+          <h3 class="text-lg font-semibold">Interactive Keyboard Shortcuts</h3>
+          <p class="text-sm text-muted-foreground">Try pressing these keyboard shortcuts:</p>
+        </div>
+
+        <div class="flex flex-col gap-3 rounded-lg border p-4 bg-muted/30">
+          <div class="flex items-center justify-between gap-8">
+            <span class="text-sm">Open Command Palette</span>
+            <UiKbdGroup>
+              <UiKbd>Ctrl</UiKbd>
+              <span class="text-muted-foreground">+</span>
+              <UiKbd>.</UiKbd>
+            </UiKbdGroup>
+          </div>
+          <div class="flex items-center justify-between gap-8">
+            <span class="text-sm">Toggle Help</span>
+            <UiKbdGroup>
+              <UiKbd>Ctrl</UiKbd>
+              <span class="text-muted-foreground">+</span>
+              <UiKbd>/</UiKbd>
+            </UiKbdGroup>
+          </div>
+          <div class="flex items-center justify-between gap-8">
+            <span class="text-sm">Close / Dismiss</span>
+            <UiKbd>Esc</UiKbd>
+          </div>
+        </div>
+
+        <div v-if="lastPressed" class="text-sm text-muted-foreground">
+          Last pressed: <UiKbd>{{ lastPressed }}</UiKbd>
+        </div>
+
+        <div v-if="showHelp" class="w-full max-w-md rounded-lg border bg-card p-4 shadow-lg">
+          <div class="flex items-center justify-between mb-3">
+            <h4 class="font-medium">Keyboard Shortcuts Help</h4>
+            <UiKbd>Esc</UiKbd>
+          </div>
+          <div class="space-y-2 text-sm text-muted-foreground">
+            <p>Use keyboard shortcuts to navigate quickly through the application.</p>
+            <p>Press <UiKbd>Esc</UiKbd> to close this help panel.</p>
+          </div>
+        </div>
+
+        <UiDrawer v-model:open="isDrawerOpen">
+          <UiDrawerContent>
+            <UiDrawerHeader>
+              <UiDrawerTitle>Command Palette</UiDrawerTitle>
+              <UiDrawerDescription>
+                Quick access to common actions. Press <UiKbd size="sm">Esc</UiKbd> to close.
+              </UiDrawerDescription>
+            </UiDrawerHeader>
+            <div class="p-4 space-y-2">
+              <div class="flex items-center justify-between rounded-md px-3 py-2 hover:bg-hover-default cursor-pointer">
+                <span>New Document</span>
+                <UiKbdGroup>
+                  <UiKbd size="sm">Ctrl</UiKbd>
+                  <UiKbd size="sm">N</UiKbd>
+                </UiKbdGroup>
+              </div>
+              <div class="flex items-center justify-between rounded-md px-3 py-2 hover:bg-hover-default cursor-pointer">
+                <span>Search Files</span>
+                <UiKbdGroup>
+                  <UiKbd size="sm">Ctrl</UiKbd>
+                  <UiKbd size="sm">Shift</UiKbd>
+                  <UiKbd size="sm">F</UiKbd>
+                </UiKbdGroup>
+              </div>
+              <div class="flex items-center justify-between rounded-md px-3 py-2 hover:bg-hover-default cursor-pointer">
+                <span>Go to Line</span>
+                <UiKbdGroup>
+                  <UiKbd size="sm">Ctrl</UiKbd>
+                  <UiKbd size="sm">G</UiKbd>
+                </UiKbdGroup>
+              </div>
+            </div>
+            <UiDrawerFooter>
+              <UiDrawerClose as-child>
+                <UiButton variant="outline">Close</UiButton>
+              </UiDrawerClose>
+            </UiDrawerFooter>
+          </UiDrawerContent>
+        </UiDrawer>
+      </div>
+    `,
+  }),
+};
+
+const groupTemplateSource = `<script setup lang="ts">
+import { UiKbd, UiKbdGroup } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <p class="text-muted-foreground text-sm">
+    Use
+    <UiKbdGroup>
+      <UiKbd>Ctrl</UiKbd>
+      <UiKbd>Shift</UiKbd>
+      <UiKbd>P</UiKbd>
+    </UiKbdGroup>
+    to open the command palette
+  </p>
+</template>`;
+
+/**
+ * Use the `UiKbdGroup` component to group keyboard keys together.
+ */
+export const Group: Story = {
+  render: (args) => ({
+    components: { UiKbd, UiKbdGroup },
+    setup() {
+      return { args };
+    },
+    template: `
+      <div class="flex flex-col items-center gap-4">
+        <p class="text-muted-foreground text-sm">
+          Use
+          <UiKbdGroup>
+            <UiKbd v-bind="args">Ctrl + Shift + P</UiKbd>
+          </UiKbdGroup>
+          to open the command palette
+        </p>
+
+        <div class="mt-8 w-full max-w-md rounded-lg border bg-popover p-4 shadow-lg">
+          <div class="flex items-center gap-2 border-b pb-3">
+            <svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="text-muted-foreground"><circle cx="11" cy="11" r="8"/><path d="m21 21-4.3-4.3"/></svg>
+            <span class="flex-1 text-sm text-muted-foreground">Type a command or search...</span>
+            <UiKbd v-bind="args">Esc</UiKbd>
+          </div>
+          <div class="pt-3 space-y-1">
+            <div class="flex items-center justify-between rounded-md px-2 py-1.5 text-sm hover:bg-hover-default cursor-pointer">
+              <span>Toggle Sidebar</span>
+              <UiKbdGroup>
+                <UiKbd v-bind="args">Ctrl</UiKbd>
+                <UiKbd v-bind="args">\\</UiKbd>
+              </UiKbdGroup>
+            </div>
+            <div class="flex items-center justify-between rounded-md px-2 py-1.5 text-sm hover:bg-hover-default cursor-pointer">
+              <span>Quick Search</span>
+              <UiKbdGroup>
+                <UiKbd v-bind="args">Ctrl</UiKbd>
+                <UiKbd v-bind="args">Shift</UiKbd>
+                <UiKbd v-bind="args">F</UiKbd>
+              </UiKbdGroup>
+            </div>
+            <div class="flex items-center justify-between rounded-md px-2 py-1.5 text-sm hover:bg-hover-default cursor-pointer">
+              <span>Go to Line</span>
+              <UiKbdGroup>
+                <UiKbd v-bind="args">Ctrl</UiKbd>
+                <UiKbd v-bind="args">G</UiKbd>
+              </UiKbdGroup>
+            </div>
+          </div>
+        </div>
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: groupTemplateSource,
+      },
+    },
+  },
+};
+
+const buttonTemplateSource = `<script setup lang="ts">
+import { UiKbd, UiButton } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <div class="flex flex-wrap items-center gap-4">
+    <UiButton variant="outline" size="sm" class="pr-2">
+      Accept <UiKbd>⏎</UiKbd>
+    </UiButton>
+    <UiButton variant="outline" size="sm" class="pr-2">
+      Cancel <UiKbd>Esc</UiKbd>
+    </UiButton>
+  </div>
+</template>`;
+
+/**
+ * Use the `UiKbd` component inside a button.
+ */
+export const Button: Story = {
+  render: (args) => ({
+    components: { UiKbd, UiButton },
+    setup() {
+      return { args };
+    },
+    template: `
+      <div class="flex flex-wrap items-center gap-4">
+        <UiButton variant="outline" size="sm" class="pr-2">
+          Accept <UiKbd v-bind="args">⏎</UiKbd>
+        </UiButton>
+        <UiButton variant="outline" size="sm" class="pr-2">
+          Cancel <UiKbd v-bind="args">Esc</UiKbd>
+        </UiButton>
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: buttonTemplateSource,
+      },
+    },
+  },
+};
+
+const withTooltipTemplateSource = `<script setup lang="ts">
+import { UiKbd, UiKbdGroup, UiButton, UiTooltipRoot, UiTooltipContent, UiTooltipProvider, UiTooltipTrigger } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <UiTooltipProvider>
+    <UiTooltipRoot>
+      <UiTooltipTrigger as-child>
+        <UiButton size="sm" variant="outline">Save</UiButton>
+      </UiTooltipTrigger>
+      <UiTooltipContent>
+        <div class="flex items-center gap-2">
+          Save Changes <UiKbd>S</UiKbd>
+        </div>
+      </UiTooltipContent>
+    </UiTooltipRoot>
+  </UiTooltipProvider>
+</template>`;
+
+/**
+ * Use the `UiKbd` component inside a tooltip.
+ */
+export const WithTooltip: Story = {
+  render: (args) => ({
+    components: {
+      UiKbd,
+      UiKbdGroup,
+      UiButton,
+      UiTooltipRoot,
+      UiTooltipContent,
+      UiTooltipProvider,
+      UiTooltipTrigger,
+    },
+    setup() {
+      return { args };
+    },
+    template: `
+      <div class="flex flex-wrap gap-4">
+        <UiTooltipProvider>
+          <UiTooltipRoot>
+            <UiTooltipTrigger as-child>
+              <UiButton size="sm" variant="outline">Save</UiButton>
+            </UiTooltipTrigger>
+            <UiTooltipContent>
+              <div class="flex items-center gap-2">
+                Save Changes <UiKbd v-bind="args">S</UiKbd>
+              </div>
+            </UiTooltipContent>
+          </UiTooltipRoot>
+        </UiTooltipProvider>
+
+        <UiTooltipProvider>
+          <UiTooltipRoot>
+            <UiTooltipTrigger as-child>
+              <UiButton size="sm" variant="outline">Print</UiButton>
+            </UiTooltipTrigger>
+            <UiTooltipContent>
+              <div class="flex items-center gap-2">
+                Print Document
+                <UiKbdGroup>
+                  <UiKbd v-bind="args">Ctrl</UiKbd>
+                  <UiKbd v-bind="args">P</UiKbd>
+                </UiKbdGroup>
+              </div>
+            </UiTooltipContent>
+          </UiTooltipRoot>
+        </UiTooltipProvider>
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: withTooltipTemplateSource,
+      },
+    },
+  },
+};
+
+const sizesTemplateSource = `<script setup lang="ts">
+import { UiKbd } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <div class="flex items-center gap-4">
+    <UiKbd size="sm">Ctrl</UiKbd>
+    <UiKbd>Ctrl</UiKbd>
+    <UiKbd size="lg">Ctrl</UiKbd>
+  </div>
+</template>`;
+
+/**
+ * Different size variants.
+ */
+export const Sizes: Story = {
+  render: () => ({
+    components: { UiKbd },
+    template: `
+      <div class="flex items-center gap-4">
+        <div class="flex items-center gap-1">
+          <span class="text-xs text-muted-foreground">sm:</span>
+          <UiKbd size="sm">Ctrl</UiKbd>
+          <UiKbd size="sm">S</UiKbd>
+        </div>
+        <div class="flex items-center gap-1">
+          <span class="text-xs text-muted-foreground">default:</span>
+          <UiKbd>Ctrl</UiKbd>
+          <UiKbd>S</UiKbd>
+        </div>
+        <div class="flex items-center gap-1">
+          <span class="text-xs text-muted-foreground">lg:</span>
+          <UiKbd size="lg">Ctrl</UiKbd>
+          <UiKbd size="lg">S</UiKbd>
+        </div>
+      </div>
+    `,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: sizesTemplateSource,
+      },
+    },
+  },
+};

package/src/components/UiKbd/UiKbd.vue

@@ -0,0 +1,57 @@
+<script setup lang="ts">
+  /**
+   * UiKbd renders keyboard key labels in a monospace, pill-shaped container.
+   *
+   * This is a thin wrapper around the shadcn-vue {@link Kbd} primitive that adds
+   * Aleph Alpha design system defaults and size variants.
+   * @component UiKbd
+   * @property {'sm' | 'default' | 'lg'} [size='default'] -
+   * Controls the visual size of the keyboard key. `sm` renders a compact key,
+   * `default` uses the base size, and `lg` renders a larger key.
+   * @slot default
+   * Content to display inside the keyboard key, typically the key label
+   * (for example, ⌘, Enter, or shortcut combinations).
+   * @example Basic usage
+   * ```vue
+   * <template>
+   *   <UiKbd>⌘</UiKbd>
+   * </template>
+   * ```
+   * @example Size variants
+   * ```vue
+   * <template>
+   *   <UiKbd size="sm">Esc</UiKbd>
+   *   <UiKbd>Enter</UiKbd>
+   *   <UiKbd size="lg">Shift</UiKbd>
+   * </template>
+   * ```
+   */
+  import { Kbd as ShadcnKbd } from '@/components/core/kbd';
+  import { computed } from 'vue';
+  import type { UiKbdProps } from './types';
+
+  defineOptions({
+    name: 'UiKbd',
+  });
+
+  const props = withDefaults(defineProps<UiKbdProps>(), {
+    size: 'default',
+  });
+
+  const sizeClasses = computed(() => {
+    switch (props.size) {
+      case 'sm':
+        return 'h-4 px-1 text-[9px]';
+      case 'lg':
+        return 'h-6 px-2 text-xs';
+      default:
+        return '';
+    }
+  });
+</script>
+
+<template>
+  <ShadcnKbd :class="sizeClasses">
+    <slot />
+  </ShadcnKbd>
+</template>

package/src/components/UiKbd/UiKbdGroup.vue

@@ -0,0 +1,13 @@
+<script setup lang="ts">
+  import { KbdGroup as ShadcnKbdGroup } from '@/components/core/kbd';
+
+  defineOptions({
+    name: 'UiKbdGroup',
+  });
+</script>
+
+<template>
+  <ShadcnKbdGroup>
+    <slot />
+  </ShadcnKbdGroup>
+</template>

package/src/components/UiKbd/__tests__/UiKbd.test.ts

@@ -0,0 +1,46 @@
+import { render } from '@testing-library/vue';
+import { describe, expect, test } from 'vitest';
+import UiKbd from '../UiKbd.vue';
+import UiKbdGroup from '../UiKbdGroup.vue';
+
+describe('UiKbd', () => {
+  test('renders kbd element with slot content', () => {
+    const { getByText } = render(UiKbd, {
+      slots: { default: 'Ctrl' },
+    });
+    expect(getByText('Ctrl')).toBeInTheDocument();
+  });
+
+  test('renders as kbd HTML element', () => {
+    const { container } = render(UiKbd, {
+      slots: { default: 'K' },
+    });
+    const kbd = container.querySelector('kbd');
+    expect(kbd).toBeInTheDocument();
+  });
+
+  test('has data-slot attribute', () => {
+    const { container } = render(UiKbd, {
+      slots: { default: 'Enter' },
+    });
+    const kbd = container.querySelector('[data-slot="kbd"]');
+    expect(kbd).toBeInTheDocument();
+  });
+});
+
+describe('UiKbdGroup', () => {
+  test('renders span element with slot content', () => {
+    const { getByText } = render(UiKbdGroup, {
+      slots: { default: 'Content' },
+    });
+    expect(getByText('Content')).toBeInTheDocument();
+  });
+
+  test('has data-slot attribute', () => {
+    const { container } = render(UiKbdGroup, {
+      slots: { default: 'Group' },
+    });
+    const group = container.querySelector('[data-slot="kbd-group"]');
+    expect(group).toBeInTheDocument();
+  });
+});

package/src/components/UiKbd/index.ts

@@ -0,0 +1,3 @@
+export { default as UiKbd } from './UiKbd.vue';
+export { default as UiKbdGroup } from './UiKbdGroup.vue';
+export type { UiKbdProps, UiKbdGroupProps } from './types';

package/src/components/UiKbd/types.ts

@@ -0,0 +1,25 @@
+/**
+ * A keyboard key indicator component. Use to display keyboard shortcuts,
+ * hotkeys, or key combinations in documentation and UI hints.
+ * @category Feedback
+ * @useCases keyboard shortcut, hotkey display, key combination, command hint
+ * @keywords kbd, keyboard, key, shortcut, hotkey, command, keybinding
+ * @related UiKbdGroup, UiTooltip
+ */
+export interface UiKbdProps {
+  /**
+   * The size of the keyboard key indicator.
+   * @default 'default'
+   */
+  size?: 'sm' | 'default' | 'lg';
+}
+
+/**
+ * A container for grouping multiple keyboard keys together. Use to display
+ * key combinations like "Ctrl + C" or "Cmd + Shift + P".
+ * @category Feedback
+ * @useCases key combination, shortcut group, multi-key display
+ * @keywords kbd, keyboard, group, combination, shortcut, keys
+ * @related UiKbd
+ */
+export type UiKbdGroupProps = Record<string, never>;