@aleph-alpha/ui-library 1.11.0 → 1.13.0

package/src/{primitives → components}/UiDropdownMenu/UiDropdownMenuTrigger.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-  import { DropdownMenuTrigger as ShadcnDropdownMenuTrigger } from '@/primitives/shadcn/dropdown-menu';
+  import { DropdownMenuTrigger as ShadcnDropdownMenuTrigger } from '@/components/core/dropdown-menu';
   import type { UiDropdownMenuTriggerProps } from './types';
 
   defineOptions({

package/src/{primitives → components}/UiDropdownMenu/types.ts

@@ -1,7 +1,6 @@
 /**
  * A menu that appears on trigger click with actions and options. Use for
  * context menus, action lists, or any menu triggered by a button.
- *
  * @category Overlays
  * @useCases action menu, context menu, options list, user menu, settings menu
  * @keywords dropdown, menu, actions, options, context, popover, list
@@ -23,6 +22,9 @@ export interface UiDropdownMenuProps {
   modal?: boolean;
 }
 
+/**
+ * Emits for the UiDropdownMenu component.
+ */
 export interface UiDropdownMenuEmits {
   /**
    * Event emitted when the open state changes.
@@ -30,6 +32,10 @@ export interface UiDropdownMenuEmits {
   'update:open': [value: boolean];
 }
 
+/**
+ * Props for the UiDropdownMenuTrigger component.
+ * The element that opens the menu when clicked.
+ */
 export interface UiDropdownMenuTriggerProps {
   /**
    * Accessible label for the trigger button.
@@ -52,6 +58,10 @@ export interface UiDropdownMenuTriggerProps {
   asChild?: boolean;
 }
 
+/**
+ * Props for the UiDropdownMenuContent component.
+ * The floating container for menu items.
+ */
 export interface UiDropdownMenuContentProps {
   /**
    * The preferred side of the trigger to render against when open.
@@ -72,6 +82,9 @@ export interface UiDropdownMenuContentProps {
   align?: 'start' | 'center' | 'end';
 }
 
+/**
+ * Emits for the UiDropdownMenuContent component.
+ */
 export interface UiDropdownMenuContentEmits {
   /**
    * Event emitted when the escape key is pressed.
@@ -80,6 +93,10 @@ export interface UiDropdownMenuContentEmits {
   (e: 'escapeKeyDown', event: KeyboardEvent): void;
 }
 
+/**
+ * Props for the UiDropdownMenuItem component.
+ * A clickable menu item that triggers an action.
+ */
 export interface UiDropdownMenuItemProps {
   /**
    * Visual variant of the menu item.
@@ -106,6 +123,10 @@ export interface UiDropdownMenuItemProps {
   textValue?: string;
 }
 
+/**
+ * Props for the UiDropdownMenuLabel component.
+ * A non-interactive label for grouping menu items.
+ */
 export interface UiDropdownMenuLabelProps {
   /**
    * Whether to add extra left padding (for items under a label).
@@ -114,6 +135,10 @@ export interface UiDropdownMenuLabelProps {
   inset?: boolean;
 }
 
+/**
+ * Props for the UiDropdownMenuCheckboxItem component.
+ * A menu item with a checkbox for toggling options.
+ */
 export interface UiDropdownMenuCheckboxItemProps {
   /**
    * The controlled checked state of the checkbox item.
@@ -133,10 +158,18 @@ export interface UiDropdownMenuCheckboxItemProps {
   textValue?: string;
 }
 
+/**
+ * Emits for the UiDropdownMenuCheckboxItem component.
+ */
 export interface UiDropdownMenuCheckboxItemEmits {
+  /** Emitted when the checked state changes. */
   'update:checked': [value: boolean];
 }
 
+/**
+ * Props for the UiDropdownMenuRadioGroup component.
+ * Container for a group of mutually exclusive radio items.
+ */
 export interface UiDropdownMenuRadioGroupProps {
   /**
    * The value of the selected radio item.
@@ -145,10 +178,18 @@ export interface UiDropdownMenuRadioGroupProps {
   modelValue?: string;
 }
 
+/**
+ * Emits for the UiDropdownMenuRadioGroup component.
+ */
 export interface UiDropdownMenuRadioGroupEmits {
+  /** Emitted when the selected radio item changes. */
   'update:modelValue': [value: string];
 }
 
+/**
+ * Props for the UiDropdownMenuRadioItem component.
+ * A radio option within a radio group.
+ */
 export interface UiDropdownMenuRadioItemProps {
   /**
    * The unique value of the radio item.
@@ -167,6 +208,10 @@ export interface UiDropdownMenuRadioItemProps {
   textValue?: string;
 }
 
+/**
+ * Props for the UiDropdownMenuSub component.
+ * A submenu container for nested menu items.
+ */
 export interface UiDropdownMenuSubProps {
   /**
    * The controlled open state of the submenu.
@@ -179,10 +224,18 @@ export interface UiDropdownMenuSubProps {
   defaultOpen?: boolean;
 }
 
+/**
+ * Emits for the UiDropdownMenuSub component.
+ */
 export interface UiDropdownMenuSubEmits {
+  /** Emitted when the submenu open state changes. */
   'update:open': [value: boolean];
 }
 
+/**
+ * Props for the UiDropdownMenuSubTrigger component.
+ * The element that opens a submenu when hovered or focused.
+ */
 export interface UiDropdownMenuSubTriggerProps {
   /**
    * Whether the sub trigger is disabled.
@@ -202,6 +255,10 @@ export interface UiDropdownMenuSubTriggerProps {
   textValue?: string;
 }
 
+/**
+ * Props for the UiDropdownMenuSubContent component.
+ * The floating container for submenu items.
+ */
 export interface UiDropdownMenuSubContentProps {
   /**
    * The distance in pixels from the trigger.
@@ -210,6 +267,9 @@ export interface UiDropdownMenuSubContentProps {
   sideOffset?: number;
 }
 
+/**
+ * Emits for the UiDropdownMenuSubContent component.
+ */
 export interface UiDropdownMenuSubContentEmits {
   /**
    * Event emitted when the escape key is pressed.

package/src/components/UiEmpty/UiEmpty.stories.ts

@@ -0,0 +1,240 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+import UiEmpty from './UiEmpty.vue';
+import { UiButton } from '../UiButton';
+import { UiIcon } from '../UiIcon';
+
+const SearchIcon = {
+  components: { UiIcon },
+  template: '<UiIcon name="search" :size="48" />',
+};
+
+const meta: Meta<typeof UiEmpty> = {
+  title: 'Components/UiEmpty',
+  component: UiEmpty,
+  argTypes: {
+    title: {
+      control: 'text',
+      description: 'The title text to display',
+    },
+    description: {
+      control: 'text',
+      description: 'The description text to display below the title',
+    },
+    icon: {
+      control: false,
+      description: 'Custom icon component to display',
+    },
+  },
+  args: {
+    title: 'No items found',
+    description: 'There are no items to display at the moment.',
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof UiEmpty>;
+
+const defaultTemplateSource = `<script setup lang="ts">
+import { UiEmpty } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <UiEmpty
+    title="No items found"
+    description="There are no items to display at the moment."
+  />
+</template>`;
+
+/**
+ * Default empty state with title and description.
+ */
+export const Default: Story = {
+  render: (args) => ({
+    components: { UiEmpty },
+    setup() {
+      return { args };
+    },
+    template: `<UiEmpty :title="args.title" :description="args.description" />`,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: defaultTemplateSource,
+      },
+    },
+  },
+};
+
+const titleOnlyTemplateSource = `<script setup lang="ts">
+import { UiEmpty } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <UiEmpty title="No data available" />
+</template>`;
+
+/**
+ * Empty state with title only.
+ */
+export const TitleOnly: Story = {
+  render: () => ({
+    components: { UiEmpty },
+    template: `<UiEmpty title="No data available" />`,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: titleOnlyTemplateSource,
+      },
+    },
+  },
+};
+
+const withCustomIconTemplateSource = `<script setup lang="ts">
+import { UiEmpty, UiIcon } from '@aleph-alpha/ui-library'
+
+const SearchIcon = {
+  components: { UiIcon },
+  template: '<UiIcon name="search" :size="48" />',
+}
+</script>
+
+<template>
+  <UiEmpty
+    :icon="SearchIcon"
+    title="No search results"
+    description="Try adjusting your search terms or filters."
+  />
+</template>`;
+
+/**
+ * Empty state with a custom icon.
+ */
+export const WithCustomIcon: Story = {
+  render: () => ({
+    components: { UiEmpty },
+    setup() {
+      return { SearchIcon };
+    },
+    template: `
+      <UiEmpty
+        :icon="SearchIcon"
+        title="No search results"
+        description="Try adjusting your search terms or filters."
+      />
+    `,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: withCustomIconTemplateSource,
+      },
+    },
+  },
+};
+
+const withActionTemplateSource = `<script setup lang="ts">
+import { UiEmpty, UiButton } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <UiEmpty
+    title="No projects yet"
+    description="Get started by creating your first project."
+  >
+    <UiButton>Create Project</UiButton>
+  </UiEmpty>
+</template>`;
+
+/**
+ * Empty state with an action button in the slot.
+ */
+export const WithAction: Story = {
+  render: () => ({
+    components: { UiEmpty, UiButton },
+    template: `
+      <UiEmpty
+        title="No projects yet"
+        description="Get started by creating your first project."
+      >
+        <UiButton>Create Project</UiButton>
+      </UiEmpty>
+    `,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: withActionTemplateSource,
+      },
+    },
+  },
+};
+
+const withMultipleActionsTemplateSource = `<script setup lang="ts">
+import { UiEmpty, UiButton } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <UiEmpty
+    title="No files uploaded"
+    description="Upload files to get started or import from another source."
+  >
+    <div class="flex gap-2">
+      <UiButton>Upload Files</UiButton>
+      <UiButton variant="outline">Import</UiButton>
+    </div>
+  </UiEmpty>
+</template>`;
+
+/**
+ * Empty state with multiple action buttons.
+ */
+export const WithMultipleActions: Story = {
+  render: () => ({
+    components: { UiEmpty, UiButton },
+    template: `
+      <UiEmpty
+        title="No files uploaded"
+        description="Upload files to get started or import from another source."
+      >
+        <div class="flex gap-2">
+          <UiButton>Upload Files</UiButton>
+          <UiButton variant="outline">Import</UiButton>
+        </div>
+      </UiEmpty>
+    `,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: withMultipleActionsTemplateSource,
+      },
+    },
+  },
+};
+
+const minimalTemplateSource = `<script setup lang="ts">
+import { UiEmpty } from '@aleph-alpha/ui-library'
+</script>
+
+<template>
+  <UiEmpty />
+</template>`;
+
+/**
+ * Minimal empty state with just the default icon.
+ */
+export const Minimal: Story = {
+  render: () => ({
+    components: { UiEmpty },
+    template: `<UiEmpty />`,
+  }),
+  parameters: {
+    docs: {
+      source: {
+        code: minimalTemplateSource,
+      },
+    },
+  },
+};

package/src/components/UiEmpty/UiEmpty.vue

@@ -0,0 +1,35 @@
+<script setup lang="ts">
+  import { UiIcon } from '@/components/UiIcon';
+  import type { UiEmptyProps } from './types';
+
+  defineOptions({
+    name: 'UiEmpty',
+  });
+
+  const props = withDefaults(defineProps<UiEmptyProps>(), {
+    title: undefined,
+    description: undefined,
+    icon: undefined,
+  });
+</script>
+
+<template>
+  <div class="flex flex-col items-center justify-center py-12 text-center">
+    <div class="mb-4 text-muted-foreground" aria-hidden="true">
+      <component :is="props.icon" v-if="props.icon" class="size-12" />
+      <UiIcon v-else name="inbox" :size="48" />
+    </div>
+
+    <h3 v-if="props.title" class="mb-2 text-lg font-semibold text-foreground">
+      {{ props.title }}
+    </h3>
+
+    <p v-if="props.description" class="max-w-sm text-sm text-muted-foreground">
+      {{ props.description }}
+    </p>
+
+    <div v-if="$slots.default" class="mt-6">
+      <slot />
+    </div>
+  </div>
+</template>

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

@@ -0,0 +1,67 @@
+import { render } from '@testing-library/vue';
+import { describe, expect, test } from 'vitest';
+import { MockIcon } from '@/__tests__/test-utils';
+import UiEmpty from '../UiEmpty.vue';
+
+describe('UiEmpty', () => {
+  test('renders with default icon when no icon prop provided', () => {
+    const { container } = render(UiEmpty);
+    // Should render with the default inbox icon (aria-hidden for decorative purposes)
+    const icon = container.querySelector('svg.lucide-inbox');
+    expect(icon).toBeInTheDocument();
+  });
+
+  test('renders title when provided', () => {
+    const { getByText } = render(UiEmpty, {
+      props: { title: 'No items found' },
+    });
+    expect(getByText('No items found')).toBeInTheDocument();
+  });
+
+  test('renders description when provided', () => {
+    const { getByText } = render(UiEmpty, {
+      props: { description: 'There are no items to display.' },
+    });
+    expect(getByText('There are no items to display.')).toBeInTheDocument();
+  });
+
+  test('renders both title and description', () => {
+    const { getByText } = render(UiEmpty, {
+      props: {
+        title: 'Empty State',
+        description: 'Nothing here yet.',
+      },
+    });
+    expect(getByText('Empty State')).toBeInTheDocument();
+    expect(getByText('Nothing here yet.')).toBeInTheDocument();
+  });
+
+  test('renders custom icon when provided', () => {
+    const { getByTestId } = render(UiEmpty, {
+      props: { icon: MockIcon },
+    });
+    expect(getByTestId('mock-icon')).toBeInTheDocument();
+  });
+
+  test('renders slot content', () => {
+    const { getByText } = render(UiEmpty, {
+      props: { title: 'No data' },
+      slots: { default: '<button>Add Item</button>' },
+    });
+    expect(getByText('Add Item')).toBeInTheDocument();
+  });
+
+  test('does not render title element when title is not provided', () => {
+    const { queryByRole } = render(UiEmpty, {
+      props: { description: 'Some description' },
+    });
+    expect(queryByRole('heading', { level: 3 })).not.toBeInTheDocument();
+  });
+
+  test('does not render description element when description is not provided', () => {
+    const { getByText } = render(UiEmpty, {
+      props: { title: 'Some title' },
+    });
+    expect(getByText('Some title')).toBeInTheDocument();
+  });
+});

package/src/components/UiEmpty/index.ts

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

package/src/components/UiEmpty/types.ts

@@ -0,0 +1,26 @@
+import type { Component } from 'vue';
+
+/**
+ * A component to display empty states when there is no content to show.
+ * @category Feedback
+ * @useCases no data available, empty list, empty search results, no items found
+ * @keywords empty, no data, placeholder, blank state, zero state
+ * @related UiSkeleton, UiSpinner
+ */
+export interface UiEmptyProps {
+  /**
+   * The title text to display.
+   */
+  title?: string;
+
+  /**
+   * The description text to display below the title.
+   */
+  description?: string;
+
+  /**
+   * Custom icon component to display.
+   * If not provided, a default empty state icon will be shown.
+   */
+  icon?: Component;
+}

package/src/{primitives → components}/UiField/UiField.stories.ts

@@ -29,11 +29,10 @@ import { ref } from 'vue';
 /**
  * UiField composes label, description, and error messaging into a consistent form-field layout.
  * Use it to keep spacing, typography, and validation feedback consistent across inputs.
- *
  * @slot default - Content of the field (typically UiFieldLabel and UiFieldContent).
  */
 const meta: Meta<typeof UiField> = {
-  title: 'Primitives/UiField',
+  title: 'Components/UiField',
   component: UiField,
   tags: ['autodocs'],
   argTypes: {

package/src/{primitives → components}/UiField/UiField.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-  import { Field as ShadcnField } from '@/primitives/shadcn/field';
+  import { Field as ShadcnField } from '@/components/core/field';
   import type { UiFieldProps } from './types';
 
   defineOptions({

package/src/{primitives → components}/UiField/UiFieldContent.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-  import { FieldContent as ShadcnFieldContent } from '@/primitives/shadcn/field';
+  import { FieldContent as ShadcnFieldContent } from '@/components/core/field';
 
   defineOptions({
     name: 'UiFieldContent',

package/src/{primitives → components}/UiField/UiFieldDescription.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-  import { FieldDescription as ShadcnFieldDescription } from '@/primitives/shadcn/field';
+  import { FieldDescription as ShadcnFieldDescription } from '@/components/core/field';
 
   defineOptions({
     name: 'UiFieldDescription',

package/src/{primitives → components}/UiField/UiFieldError.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-  import { FieldError as ShadcnFieldError } from '@/primitives/shadcn/field';
+  import { FieldError as ShadcnFieldError } from '@/components/core/field';
   import { computed, useSlots } from 'vue';
   import type { UiFieldErrorProps } from './types';
 

package/src/{primitives → components}/UiField/UiFieldGroup.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-  import { FieldGroup as ShadcnFieldGroup } from '@/primitives/shadcn/field';
+  import { FieldGroup as ShadcnFieldGroup } from '@/components/core/field';
 
   defineOptions({
     name: 'UiFieldGroup',

package/src/{primitives → components}/UiField/UiFieldLabel.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-  import { FieldLabel as ShadcnFieldLabel } from '@/primitives/shadcn/field';
+  import { FieldLabel as ShadcnFieldLabel } from '@/components/core/field';
   import type { UiFieldLabelProps } from './types';
 
   defineOptions({

package/src/{primitives → components}/UiField/UiFieldLegend.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-  import { FieldLegend as ShadcnFieldLegend } from '@/primitives/shadcn/field';
+  import { FieldLegend as ShadcnFieldLegend } from '@/components/core/field';
 
   defineOptions({
     name: 'UiFieldLegend',

package/src/{primitives → components}/UiField/UiFieldSeparator.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-  import { FieldSeparator as ShadcnFieldSeparator } from '@/primitives/shadcn/field';
+  import { FieldSeparator as ShadcnFieldSeparator } from '@/components/core/field';
 
   defineOptions({
     name: 'UiFieldSeparator',

package/src/{primitives → components}/UiField/UiFieldSet.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-  import { FieldSet as ShadcnFieldSet } from '@/primitives/shadcn/field';
+  import { FieldSet as ShadcnFieldSet } from '@/components/core/field';
 
   defineOptions({
     name: 'UiFieldSet',

package/src/{primitives → components}/UiField/UiFieldTitle.vue

@@ -1,5 +1,5 @@
 <script setup lang="ts">
-  import { FieldTitle as ShadcnFieldTitle } from '@/primitives/shadcn/field';
+  import { FieldTitle as ShadcnFieldTitle } from '@/components/core/field';
 
   defineOptions({
     name: 'UiFieldTitle',

package/src/{primitives → components}/UiField/index.ts

@@ -8,3 +8,4 @@ export { default as UiFieldLegend } from './UiFieldLegend.vue';
 export { default as UiFieldSeparator } from './UiFieldSeparator.vue';
 export { default as UiFieldSet } from './UiFieldSet.vue';
 export { default as UiFieldTitle } from './UiFieldTitle.vue';
+export type * from './types';

package/src/{primitives → components}/UiField/types.ts

@@ -6,12 +6,17 @@ export type UiFieldOrientation = 'vertical' | 'horizontal' | 'responsive';
 /**
  * Error shape supported by `UiFieldError`.
  */
-export type UiFieldErrorLike = string | { message: string | undefined } | undefined;
+export type UiFieldErrorLike =
+  | string
+  | {
+      /** The error message text. */
+      message: string | undefined;
+    }
+  | undefined;
 
 /**
  * A form field wrapper that groups label, input, description, and error messages.
  * Provides consistent layout and accessibility for form controls.
- *
  * @category Form Inputs
  * @useCases form layout, input wrapper, field grouping, validation display
  * @keywords field, form, label, input, error, validation, wrapper