@aleph-alpha/ui-library 1.9.0 → 1.10.0

package/src/primitives/UiPopover/UiPopoverContent.vue

@@ -0,0 +1,27 @@
+<script setup lang="ts">
+  import { PopoverContent as ShadcnPopoverContent } from '@/primitives/shadcn/popover';
+  import type { UiPopoverContentProps, UiPopoverContentEmits } from './types';
+
+  defineOptions({
+    name: 'UiPopoverContent',
+  });
+
+  const props = withDefaults(defineProps<UiPopoverContentProps>(), {
+    side: 'bottom',
+    sideOffset: 4,
+    align: 'center',
+  });
+
+  const emit = defineEmits<UiPopoverContentEmits>();
+</script>
+
+<template>
+  <ShadcnPopoverContent
+    :side="props.side"
+    :side-offset="props.sideOffset"
+    :align="props.align"
+    @escape-key-down="emit('escapeKeyDown', $event)"
+  >
+    <slot />
+  </ShadcnPopoverContent>
+</template>

package/src/primitives/UiPopover/UiPopoverTrigger.vue

@@ -0,0 +1,16 @@
+<script setup lang="ts">
+  import { PopoverTrigger as ShadcnPopoverTrigger } from '@/primitives/shadcn/popover';
+  import type { UiPopoverTriggerProps } from './types';
+
+  defineOptions({
+    name: 'UiPopoverTrigger',
+  });
+
+  defineProps<UiPopoverTriggerProps>();
+</script>
+
+<template>
+  <ShadcnPopoverTrigger :as-child="$props.asChild" :aria-label="$props.ariaLabel">
+    <slot />
+  </ShadcnPopoverTrigger>
+</template>

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

@@ -0,0 +1,87 @@
+import { render } from '@testing-library/vue';
+import { describe, expect, test, vi } from 'vitest';
+import { UiPopover, UiPopoverTrigger, UiPopoverContent } from '../index';
+import { UiButton } from '../../UiButton';
+
+describe('UiPopover', () => {
+  test('emits update:open when trigger is clicked', async () => {
+    const onUpdateOpen = vi.fn();
+    const { getByText } = render({
+      components: { UiPopover, UiPopoverTrigger, UiPopoverContent },
+      setup() {
+        return { onUpdateOpen };
+      },
+      template: `
+        <UiPopover @update:open="onUpdateOpen">
+          <UiPopoverTrigger>Open</UiPopoverTrigger>
+          <UiPopoverContent>Content</UiPopoverContent>
+        </UiPopover>
+      `,
+    });
+
+    await getByText('Open').click();
+
+    expect(onUpdateOpen).toHaveBeenCalledWith(true);
+  });
+
+  test('applies aria-label on trigger', () => {
+    const { getByRole } = render({
+      components: { UiPopover, UiPopoverTrigger, UiPopoverContent },
+      template: `
+        <UiPopover>
+          <UiPopoverTrigger ariaLabel="Open popover">Open</UiPopoverTrigger>
+          <UiPopoverContent>Content</UiPopoverContent>
+        </UiPopover>
+      `,
+    });
+
+    expect(getByRole('button', { name: 'Open popover' })).toBeInTheDocument();
+  });
+
+  test('works with as-child pattern and UiButton', async () => {
+    const onUpdateOpen = vi.fn();
+    const { getByRole } = render({
+      components: { UiPopover, UiPopoverTrigger, UiPopoverContent, UiButton },
+      setup() {
+        return { onUpdateOpen };
+      },
+      template: `
+        <UiPopover @update:open="onUpdateOpen">
+          <UiPopoverTrigger as-child>
+            <UiButton variant="outline">Open Popover</UiButton>
+          </UiPopoverTrigger>
+          <UiPopoverContent>Content</UiPopoverContent>
+        </UiPopover>
+      `,
+    });
+
+    await getByRole('button', { name: 'Open Popover' }).click();
+
+    expect(onUpdateOpen).toHaveBeenCalledWith(true);
+  });
+
+  test('emits escapeKeyDown when Escape is pressed', async () => {
+    const onEscapeKeyDown = vi.fn();
+    const { getByText, getByRole } = render({
+      components: { UiPopover, UiPopoverTrigger, UiPopoverContent },
+      setup() {
+        return { onEscapeKeyDown };
+      },
+      template: `
+        <UiPopover>
+          <UiPopoverTrigger>Open</UiPopoverTrigger>
+          <UiPopoverContent @escape-key-down="onEscapeKeyDown">Content</UiPopoverContent>
+        </UiPopover>
+      `,
+    });
+
+    await getByText('Open').click();
+    expect(getByRole('dialog')).toBeInTheDocument();
+
+    await getByRole('dialog').dispatchEvent(
+      new KeyboardEvent('keydown', { key: 'Escape', bubbles: true }),
+    );
+
+    expect(onEscapeKeyDown).toHaveBeenCalled();
+  });
+});

package/src/primitives/UiPopover/index.ts

@@ -0,0 +1,5 @@
+export { default as UiPopover } from './UiPopover.vue';
+export { default as UiPopoverTrigger } from './UiPopoverTrigger.vue';
+export { default as UiPopoverContent } from './UiPopoverContent.vue';
+
+export * from './types';

package/src/primitives/UiPopover/types.ts

@@ -0,0 +1,86 @@
+export type UiPopoverSide = 'top' | 'right' | 'bottom' | 'left';
+export type UiPopoverAlign = 'start' | 'center' | 'end';
+
+/**
+ * A floating panel that appears relative to a trigger element. Use for
+ * rich content like forms, pickers, or detailed information.
+ *
+ * @category Overlays
+ * @useCases floating panel, picker container, form popup, info panel
+ * @keywords popover, popup, floating, panel, overlay, dropdown
+ * @related UiTooltip, UiDropdownMenu
+ */
+export interface UiPopoverProps {
+  /**
+   * The controlled open state of the popover.
+   * - Omit for uncontrolled mode (component manages state internally)
+   * - Use `v-model:open` for controlled mode
+   * @example
+   * ```vue
+   * <!-- Uncontrolled (component manages state) -->
+   * <UiPopover>...</UiPopover>
+   *
+   * <!-- Controlled (parent manages state) -->
+   * <UiPopover v-model:open="isOpen">...</UiPopover>
+   * ```
+   */
+  open?: boolean;
+
+  /**
+   * The modality of the popover.
+   *
+   * When set to `true`:
+   * - Interaction with outside elements is disabled (outside clicks won't trigger underlying UI)
+   * - Focus is trapped within the popover while open
+   * - Only popover content is visible to screen readers
+   *
+   * Note: The popover is still **dismissed on outside click**. `modal` controls outside interaction,
+   * not whether the popover closes.
+   * @default false
+   */
+  modal?: boolean;
+}
+
+export interface UiPopoverTriggerProps {
+  /**
+   * Accessible label for the trigger button.
+   * **REQUIRED** when trigger contains only icons or images (no visible text).
+   * Applied as `aria-label` attribute.
+   */
+  ariaLabel?: string;
+
+  /**
+   * Render as child element (merges props into slotted element instead of wrapping).
+   * Set to `true` when using custom button components like `UiButton` or `UiIconButton`.
+   * @default false
+   */
+  asChild?: boolean;
+}
+
+export interface UiPopoverContentProps {
+  /**
+   * The preferred side of the trigger to render against when open.
+   * @default 'bottom'
+   */
+  side?: UiPopoverSide;
+
+  /**
+   * The distance in pixels from the trigger.
+   * @default 4
+   */
+  sideOffset?: number;
+
+  /**
+   * The preferred alignment against the trigger.
+   * @default 'center'
+   */
+  align?: UiPopoverAlign;
+}
+
+export interface UiPopoverContentEmits {
+  /**
+   * Event emitted when the escape key is pressed.
+   * Can be used to prevent closing or add custom behavior.
+   */
+  (e: 'escapeKeyDown', event: KeyboardEvent): void;
+}

package/src/primitives/UiProgress/UiProgress.stories.ts

@@ -0,0 +1,92 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+import UiProgress from './UiProgress.vue';
+
+const meta: Meta<typeof UiProgress> = {
+  title: 'Primitives/UiProgress',
+  component: UiProgress,
+  tags: ['autodocs'],
+  argTypes: {
+    modelValue: {
+      control: { type: 'number', min: 0, max: 100 },
+      description: 'The current progress value.',
+    },
+    max: {
+      control: { type: 'number', min: 1 },
+      description: 'The maximum value of the progress bar.',
+    },
+  },
+  args: {
+    modelValue: 33,
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof UiProgress>;
+
+const defaultTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue'
+import { UiProgress } from '@aleph-alpha/ui-library'
+
+const progress = ref(33)
+</script>
+
+<template>
+  <UiProgress v-model="progress" />
+</template>`;
+
+/**
+ * A basic progress bar displaying current progress.
+ */
+export const Default: Story = {
+  render: (args) => ({
+    components: { UiProgress },
+    setup() {
+      return { args };
+    },
+    template: '<UiProgress :model-value="args.modelValue" :max="args.max" class="w-60" />',
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: defaultTemplateSource,
+      },
+    },
+  },
+};
+
+const customMaxTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue'
+import { UiProgress } from '@aleph-alpha/ui-library'
+
+const progress = ref(75)
+const max = 200
+</script>
+
+<template>
+  <UiProgress v-model="progress" :max="max" />
+</template>`;
+
+/**
+ * Progress bar with a custom maximum value. Here, progress is 75 out of 200.
+ */
+export const CustomMax: Story = {
+  render: (args) => ({
+    components: { UiProgress },
+    setup() {
+      return { args };
+    },
+    template: '<UiProgress :model-value="args.modelValue" :max="args.max" class="w-60" />',
+  }),
+  args: {
+    modelValue: 75,
+    max: 200,
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: customMaxTemplateSource,
+      },
+    },
+  },
+};

package/src/primitives/UiProgress/UiProgress.vue

@@ -0,0 +1,25 @@
+<script setup lang="ts">
+  import { computed } from 'vue';
+  import { Progress as ShadcnProgress } from '../shadcn/progress';
+  import { UiProgressProps } from './types';
+
+  defineOptions({
+    name: 'UiProgress',
+  });
+
+  const props = withDefaults(defineProps<UiProgressProps>(), {
+    max: 100,
+  });
+
+  const model = defineModel<number>({
+    default: 0,
+  });
+
+  const currentProgress = computed(() => {
+    return model.value > props.max ? props.max : model.value;
+  });
+</script>
+
+<template>
+  <ShadcnProgress :model-value="currentProgress" :max />
+</template>

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

@@ -0,0 +1,46 @@
+import { render } from '@testing-library/vue';
+import { describe, expect, test } from 'vitest';
+import UiProgress from '../UiProgress.vue';
+
+describe('UiProgress', () => {
+  test('renders progress as 0% done', () => {
+    const { getByRole } = render(UiProgress, {
+      props: {
+        modelValue: 0,
+      },
+    });
+
+    expect(getByRole('progressbar').getAttribute('data-value')).toBe('0');
+  });
+
+  test('renders progress as 50% done', () => {
+    const { getByRole } = render(UiProgress, {
+      props: {
+        modelValue: 50,
+      },
+    });
+
+    expect(getByRole('progressbar').getAttribute('data-value')).toBe('50');
+  });
+
+  test('renders progress as 100% done', () => {
+    const { getByRole } = render(UiProgress, {
+      props: {
+        modelValue: 100,
+      },
+    });
+
+    expect(getByRole('progressbar').getAttribute('data-value')).toBe('100');
+  });
+
+  test('clamps value to max prop', () => {
+    const { getByRole } = render(UiProgress, {
+      props: {
+        modelValue: 100,
+        max: 25,
+      },
+    });
+
+    expect(getByRole('progressbar').getAttribute('data-value')).toBe('25');
+  });
+});

package/src/primitives/UiProgress/index.ts

@@ -0,0 +1,2 @@
+export { default as UiProgress } from './UiProgress.vue';
+export type * from './types.ts';

package/src/primitives/UiProgress/types.ts

@@ -0,0 +1,16 @@
+/**
+ * A progress bar showing completion status. Use for uploads,
+ * downloads, loading states, or any task with measurable progress.
+ *
+ * @category Feedback
+ * @useCases upload progress, download status, loading bar, completion indicator
+ * @keywords progress, bar, loading, percentage, status, completion
+ * @related UiSpinner
+ */
+export type UiProgressProps = {
+  /*
+   * Max value of the Progress
+   * @default: 100
+   */
+  max?: number;
+};