@aleph-alpha/ui-library 1.8.0 → 1.10.0

package/src/primitives/UiIconButton/UiIconButton.stories.ts

@@ -0,0 +1,446 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+import UiIconButton from './UiIconButton.vue';
+import { UiIcon } from '../UiIcon';
+
+const meta: Meta<typeof UiIconButton> = {
+  title: 'Primitives/UiIconButton',
+  component: UiIconButton,
+  tags: ['autodocs'],
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['default', 'destructive', 'outline', 'secondary', 'ghost', 'link'],
+      description: 'The visual style of the button',
+    },
+    size: {
+      control: 'select',
+      options: ['icon', 'icon-sm', 'icon-lg'],
+      description: 'The size of the icon button',
+    },
+    asChild: {
+      control: 'boolean',
+      description: 'Whether to render as a child (Slot) instead of a wrapper element',
+    },
+    ariaLabel: {
+      control: 'text',
+      description: 'Accessible label (required for icon buttons)',
+    },
+    disabled: {
+      control: 'boolean',
+      description: 'Disables the button',
+    },
+    loading: {
+      control: 'boolean',
+      description: 'Shows a loading state and prevents interaction',
+    },
+  },
+  args: {
+    variant: 'default',
+    size: 'icon',
+    asChild: false,
+    ariaLabel: 'Icon button',
+    disabled: false,
+    loading: false,
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof UiIconButton>;
+
+const defaultTemplateSource = `<script setup lang="ts">
+import { UiIconButton, UiIcon } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <UiIconButton aria-label="Next">
+    <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+  </UiIconButton>
+</template>`;
+
+/**
+ * Default icon button.
+ */
+export const Default: Story = {
+  render: (args) => ({
+    components: { UiIconButton, UiIcon },
+    setup() {
+      return { args };
+    },
+    template: `<UiIconButton :variant="args.variant" :size="args.size" :disabled="args.disabled" :loading="args.loading" :aria-label="args.ariaLabel">
+      <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+    </UiIconButton>`,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: defaultTemplateSource,
+      },
+    },
+  },
+};
+
+const secondaryTemplateSource = `<script setup lang="ts">
+import { UiIconButton, UiIcon } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <UiIconButton variant="secondary" aria-label="Next">
+    <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+  </UiIconButton>
+</template>`;
+
+/**
+ * Secondary icon button variant.
+ */
+export const Secondary: Story = {
+  render: () => ({
+    components: { UiIconButton, UiIcon },
+    template: `<UiIconButton variant="secondary" aria-label="Next">
+      <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+    </UiIconButton>`,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: secondaryTemplateSource,
+      },
+    },
+  },
+};
+
+const destructiveTemplateSource = `<script setup lang="ts">
+import { UiIconButton, UiIcon } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <UiIconButton variant="destructive" aria-label="Delete">
+    <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+  </UiIconButton>
+</template>`;
+
+/**
+ * Destructive icon button variant.
+ */
+export const Destructive: Story = {
+  render: () => ({
+    components: { UiIconButton, UiIcon },
+    template: `<UiIconButton variant="destructive" aria-label="Delete">
+      <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+    </UiIconButton>`,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: destructiveTemplateSource,
+      },
+    },
+  },
+};
+
+const outlineTemplateSource = `<script setup lang="ts">
+import { UiIconButton, UiIcon } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <UiIconButton variant="outline" aria-label="Next">
+    <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+  </UiIconButton>
+</template>`;
+
+/**
+ * Outline icon button variant.
+ */
+export const Outline: Story = {
+  render: () => ({
+    components: { UiIconButton, UiIcon },
+    template: `<UiIconButton variant="outline" aria-label="Next">
+      <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+    </UiIconButton>`,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: outlineTemplateSource,
+      },
+    },
+  },
+};
+
+const ghostTemplateSource = `<script setup lang="ts">
+import { UiIconButton, UiIcon } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <UiIconButton variant="ghost" aria-label="Next">
+    <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+  </UiIconButton>
+</template>`;
+
+/**
+ * Ghost icon button variant.
+ */
+export const Ghost: Story = {
+  render: () => ({
+    components: { UiIconButton, UiIcon },
+    template: `<UiIconButton variant="ghost" aria-label="Next">
+      <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+    </UiIconButton>`,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: ghostTemplateSource,
+      },
+    },
+  },
+};
+
+const linkTemplateSource = `<script setup lang="ts">
+import { UiIconButton, UiIcon } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <UiIconButton variant="link" aria-label="Next">
+    <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+  </UiIconButton>
+</template>`;
+
+/**
+ * Link icon button variant.
+ */
+export const Link: Story = {
+  render: () => ({
+    components: { UiIconButton, UiIcon },
+    template: `<UiIconButton variant="link" aria-label="Next">
+      <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+    </UiIconButton>`,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: linkTemplateSource,
+      },
+    },
+  },
+};
+
+const loadingTemplateSource = `<script setup lang="ts">
+import { UiIconButton, UiIcon } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <UiIconButton :loading="true" aria-label="Loading">
+    <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+  </UiIconButton>
+</template>`;
+
+/**
+ * Loading state shows a spinner.
+ */
+export const Loading: Story = {
+  render: () => ({
+    components: { UiIconButton, UiIcon },
+    template: `<UiIconButton :loading="true" aria-label="Loading">
+      <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+    </UiIconButton>`,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: loadingTemplateSource,
+      },
+    },
+  },
+};
+
+const disabledTemplateSource = `<script setup lang="ts">
+import { UiIconButton, UiIcon } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <UiIconButton :disabled="true" aria-label="Disabled">
+    <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+  </UiIconButton>
+</template>`;
+
+/**
+ * Disabled state.
+ */
+export const Disabled: Story = {
+  render: () => ({
+    components: { UiIconButton, UiIcon },
+    template: `<UiIconButton :disabled="true" aria-label="Disabled">
+      <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+    </UiIconButton>`,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: disabledTemplateSource,
+      },
+    },
+  },
+};
+
+const allVariantsTemplateSource = `<script setup lang="ts">
+import { UiIconButton, UiIcon } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <div class="flex flex-wrap items-center gap-4">
+    <UiIconButton variant="default" aria-label="Default">
+      <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+    </UiIconButton>
+    <UiIconButton variant="secondary" aria-label="Secondary">
+      <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+    </UiIconButton>
+    <UiIconButton variant="destructive" aria-label="Destructive">
+      <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+    </UiIconButton>
+    <UiIconButton variant="outline" aria-label="Outline">
+      <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+    </UiIconButton>
+    <UiIconButton variant="ghost" aria-label="Ghost">
+      <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+    </UiIconButton>
+    <UiIconButton variant="link" aria-label="Link">
+      <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+    </UiIconButton>
+  </div>
+</template>`;
+
+/**
+ * All icon button variants side by side.
+ */
+export const AllVariants: Story = {
+  render: () => ({
+    components: { UiIconButton, UiIcon },
+    template: `<div class="flex flex-wrap items-center gap-4">
+      <UiIconButton variant="default" aria-label="Default">
+        <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+      </UiIconButton>
+      <UiIconButton variant="secondary" aria-label="Secondary">
+        <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+      </UiIconButton>
+      <UiIconButton variant="destructive" aria-label="Destructive">
+        <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+      </UiIconButton>
+      <UiIconButton variant="outline" aria-label="Outline">
+        <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+      </UiIconButton>
+      <UiIconButton variant="ghost" aria-label="Ghost">
+        <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+      </UiIconButton>
+      <UiIconButton variant="link" aria-label="Link">
+        <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+      </UiIconButton>
+    </div>`,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: allVariantsTemplateSource,
+      },
+    },
+  },
+};
+
+const allSizesTemplateSource = `<script setup lang="ts">
+import { UiIconButton, UiIcon } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <div class="flex flex-wrap items-end gap-4">
+    <div class="flex flex-col items-center gap-2">
+      <span class="text-muted-foreground text-xs">icon-sm</span>
+      <UiIconButton size="icon-sm" variant="outline" aria-label="Small Icon">
+        <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+      </UiIconButton>
+    </div>
+    <div class="flex flex-col items-center gap-2">
+      <span class="text-muted-foreground text-xs">icon</span>
+      <UiIconButton size="icon" variant="outline" aria-label="Default Icon">
+        <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+      </UiIconButton>
+    </div>
+    <div class="flex flex-col items-center gap-2">
+      <span class="text-muted-foreground text-xs">icon-lg</span>
+      <UiIconButton size="icon-lg" variant="outline" aria-label="Large Icon">
+        <UiIcon icon="i-material-symbols-chevron-right" class="size-5" />
+      </UiIconButton>
+    </div>
+  </div>
+</template>`;
+
+/**
+ * All icon button sizes.
+ */
+export const AllSizes: Story = {
+  render: () => ({
+    components: { UiIconButton, UiIcon },
+    template: `<div class="flex flex-wrap items-end gap-4">
+      <div class="flex flex-col items-center gap-2">
+        <span class="text-muted-foreground text-xs">icon-sm</span>
+        <UiIconButton size="icon-sm" variant="outline" aria-label="Small Icon">
+          <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+        </UiIconButton>
+      </div>
+      <div class="flex flex-col items-center gap-2">
+        <span class="text-muted-foreground text-xs">icon</span>
+        <UiIconButton size="icon" variant="outline" aria-label="Default Icon">
+          <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+        </UiIconButton>
+      </div>
+      <div class="flex flex-col items-center gap-2">
+        <span class="text-muted-foreground text-xs">icon-lg</span>
+        <UiIconButton size="icon-lg" variant="outline" aria-label="Large Icon">
+          <UiIcon icon="i-material-symbols-chevron-right" class="size-5" />
+        </UiIconButton>
+      </div>
+    </div>`,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: allSizesTemplateSource,
+      },
+    },
+  },
+};
+
+const asChildTemplateSource = `<script setup lang="ts">
+import { UiIconButton, UiIcon } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <UiIconButton :as-child="true" aria-label="Navigate">
+    <a href="#">
+      <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+    </a>
+  </UiIconButton>
+</template>`;
+
+/**
+ * Use `as-child` to render icon button styling on a link or custom element.
+ * Perfect for navigation arrows, external link icons, or router integration.
+ *
+ * **Note:** The `aria-label` is still required for accessibility even when using `as-child`.
+ */
+export const AsChild: Story = {
+  render: () => ({
+    components: { UiIconButton, UiIcon },
+    template: `<UiIconButton :as-child="true" aria-label="Navigate">
+      <a href="#">
+        <UiIcon icon="i-material-symbols-chevron-right" class="size-4" />
+      </a>
+    </UiIconButton>`,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: asChildTemplateSource,
+      },
+    },
+  },
+};

package/src/primitives/UiIconButton/UiIconButton.vue

@@ -0,0 +1,63 @@
+<script setup lang="ts">
+  import { Button as ShadcnButton } from '@/primitives/shadcn/button';
+  import { UiSpinner } from '@/primitives/UiSpinner';
+  import { computed } from 'vue';
+  import type { UiIconButtonProps, UiIconButtonVariant } from './types';
+
+  defineOptions({
+    name: 'UiIconButton',
+  });
+
+  const props = withDefaults(defineProps<UiIconButtonProps>(), {
+    variant: 'default',
+    size: 'icon',
+    asChild: false,
+    type: 'button',
+    disabled: false,
+    loading: false,
+  });
+
+  const variantMap: Record<
+    UiIconButtonVariant,
+    'default' | 'destructive' | 'outline' | 'secondary' | 'ghost' | 'link'
+  > = {
+    default: 'default',
+    destructive: 'destructive',
+    outline: 'outline',
+    secondary: 'secondary',
+    ghost: 'ghost',
+    link: 'link',
+  };
+
+  const sizeMap: Record<'icon' | 'icon-sm' | 'icon-lg', 'icon' | 'icon-sm' | 'icon-lg'> = {
+    icon: 'icon',
+    'icon-sm': 'icon-sm',
+    'icon-lg': 'icon-lg',
+  };
+
+  const isDisabled = computed(() => props.disabled || props.loading);
+
+  function handleClick(e: MouseEvent) {
+    if (isDisabled.value) {
+      e.preventDefault();
+      e.stopPropagation();
+    }
+  }
+</script>
+
+<template>
+  <ShadcnButton
+    :variant="variantMap[props.variant]"
+    :size="sizeMap[props.size]"
+    :aria-label="props.ariaLabel"
+    :as-child="props.asChild"
+    :type="props.type"
+    :disabled="isDisabled"
+    :aria-busy="props.loading ? 'true' : undefined"
+    @click="handleClick"
+  >
+    <!-- Spinner when loading and not using asChild -->
+    <UiSpinner v-if="props.loading && !props.asChild" aria-label="Loading" />
+    <slot v-else />
+  </ShadcnButton>
+</template>

package/src/primitives/UiIconButton/__tests__/UiIconButton.test.ts

@@ -0,0 +1,102 @@
+import { render } from '@testing-library/vue';
+import userEvent from '@testing-library/user-event';
+import { describe, expect, test } from 'vitest';
+import { defineComponent, h, markRaw } from 'vue';
+import UiIconButton from '../UiIconButton.vue';
+
+// Mock icon component for testing slot content
+const MockIcon = markRaw(
+  defineComponent({
+    name: 'MockIcon',
+    template: '<svg data-testid="mock-icon" aria-hidden="true" />',
+  }),
+);
+
+describe('UiIconButton', () => {
+  test('renders with icon, type="button", and required aria-label', () => {
+    const { getByRole, getByTestId } = render(UiIconButton, {
+      props: { ariaLabel: 'Delete item' },
+      slots: { default: () => h(MockIcon) },
+    });
+    const button = getByRole('button');
+    expect(button).toHaveAttribute('type', 'button');
+    expect(button).toHaveAttribute('aria-label', 'Delete item');
+    expect(getByTestId('mock-icon')).toBeInTheDocument();
+  });
+
+  describe('Variants (contract test)', () => {
+    const variants = ['default', 'destructive', 'outline', 'secondary', 'ghost', 'link'] as const;
+
+    test.each(variants)('accepts variant="%s"', (variant) => {
+      const { getByRole } = render(UiIconButton, {
+        props: { ariaLabel: 'Icon', variant },
+        slots: { default: '🔍' },
+      });
+      expect(getByRole('button')).toBeInTheDocument();
+    });
+  });
+
+  describe('Sizes (contract test)', () => {
+    const sizes = ['icon', 'icon-sm', 'icon-lg'] as const;
+
+    test.each(sizes)('accepts size="%s"', (size) => {
+      const { getByRole } = render(UiIconButton, {
+        props: { ariaLabel: 'Icon', size },
+        slots: { default: '🔍' },
+      });
+      expect(getByRole('button')).toBeInTheDocument();
+    });
+  });
+
+  test('emits click event when clicked', async () => {
+    const user = userEvent.setup();
+    const { getByRole, emitted } = render(UiIconButton, {
+      props: { ariaLabel: 'Click me' },
+      slots: { default: '🔍' },
+    });
+
+    await user.click(getByRole('button'));
+
+    expect(emitted('click')).toHaveLength(1);
+  });
+
+  test('is disabled when disabled prop is true', () => {
+    const { getByRole } = render(UiIconButton, {
+      props: { ariaLabel: 'Test', disabled: true },
+      slots: { default: '🔍' },
+    });
+    expect(getByRole('button')).toBeDisabled();
+  });
+
+  describe('Loading State', () => {
+    test('is disabled with aria-busy and shows spinner when loading', () => {
+      const { getByRole, getByLabelText, queryByTestId } = render(UiIconButton, {
+        props: { ariaLabel: 'Test', loading: true },
+        slots: { default: () => h(MockIcon) },
+      });
+      const button = getByRole('button');
+      expect(button).toBeDisabled();
+      expect(button).toHaveAttribute('aria-busy', 'true');
+      expect(getByLabelText('Loading')).toBeInTheDocument();
+      expect(queryByTestId('mock-icon')).not.toBeInTheDocument();
+    });
+
+    test('does not show spinner in asChild mode when loading', () => {
+      const { queryByLabelText } = render(UiIconButton, {
+        props: { ariaLabel: 'Test', loading: true, asChild: true },
+        slots: { default: '🔍' },
+      });
+      expect(queryByLabelText('Loading')).not.toBeInTheDocument();
+    });
+  });
+
+  describe('asChild Mode', () => {
+    test('shows slot content even when loading in asChild mode', () => {
+      const { getByTestId } = render(UiIconButton, {
+        props: { ariaLabel: 'Test', asChild: true, loading: true },
+        slots: { default: () => h(MockIcon) },
+      });
+      expect(getByTestId('mock-icon')).toBeInTheDocument();
+    });
+  });
+});

package/src/primitives/UiIconButton/index.ts

@@ -0,0 +1,2 @@
+export { default as UiIconButton } from './UiIconButton.vue';
+export type { UiIconButtonProps, UiIconButtonVariant, UiIconButtonSize } from './types';

package/src/primitives/UiIconButton/types.ts

@@ -0,0 +1,67 @@
+/**
+ * Visual style variants for UiIconButton.
+ */
+export type UiIconButtonVariant =
+  | 'default'
+  | 'destructive'
+  | 'outline'
+  | 'secondary'
+  | 'ghost'
+  | 'link';
+
+/**
+ * Size variants for UiIconButton.
+ */
+export type UiIconButtonSize = 'icon' | 'icon-sm' | 'icon-lg';
+
+/**
+ * A button that displays only an icon without text. Use for compact
+ * actions like close, edit, delete, or toolbar buttons.
+ *
+ * @category Actions
+ * @useCases close button, edit action, toolbar button, compact action
+ * @keywords iconbutton, icon, button, action, close, edit, delete
+ * @related UiButton, UiIcon
+ */
+export interface UiIconButtonProps {
+  /**
+   * The visual style of the button.
+   * @default 'default'
+   */
+  variant?: UiIconButtonVariant;
+
+  /**
+   * The size of the icon button.
+   * @default 'icon'
+   */
+  size?: UiIconButtonSize;
+
+  /**
+   * Whether to render as a child (Slot) instead of a wrapper element.
+   * Useful for tooltips or wrapping other components.
+   * @default false
+   */
+  asChild?: boolean;
+
+  /**
+   * The native button type.
+   * @default 'button'
+   */
+  type?: 'button' | 'submit' | 'reset';
+
+  /**
+   * Disables the button.
+   */
+  disabled?: boolean;
+
+  /**
+   * Shows a loading state and prevents interaction.
+   */
+  loading?: boolean;
+
+  /**
+   * Accessible label for the button.
+   * **REQUIRED** because the button renders only an icon (no visible text).
+   */
+  ariaLabel: string;
+}