@aleph-alpha/ui-library 1.19.0 → 1.20.0

package/docs/public-docs/getting-started-designers.md

@@ -2,16 +2,29 @@
 
 ---
 
-## Figma Access & Library Links
+## Figma design system
 
-Figma components and design files:
+The design system is published as a Figma **library** for the Aleph Alpha organisation. Add it to each design file and build with **library instances** (**components** from **Assets**, and **variables** and **styles** from property pickers) so your work stays connected when the team publishes updates.
 
-- **[AA Design System Components (Figma)](https://www.figma.com/design/SrZQ19QVN1sQkuAMnMC746/AA26--WIP-?node-id=580-9181&t=2HPn1uKWpFKHnrMR-1)** — component library and design system.
+### Adding Components to your Figma file
 
-## Using Design Tokens in Figma
+1. In the left sidebar, click the **Assets** tab next to **Files**. That switches the sidebar from the layer list to Assets.
+2. Click **Browse team libraries**.
+3. In the libraries dialog, select **Your organisation** in the left sidebar.
+4. Select **AA26 (WIP)**, then enable it with **Add to file**.
 
-Coming soon.
+You can then drag **components** from the **Assets** tab into your file.
+
+See Figma documentation for more details on how to manage libraries in [Add or remove a library from a design file](https://help.figma.com/hc/en-us/articles/1500008731201-Add-or-remove-a-library-from-a-design-file).
+
+!!! note "Beta"
+
+    The Figma library is in **beta**. Components will change in look and feel (and sometimes structure) as we iterate with the Design team. Expect updates over time.
+
+### Design tokens
+
+With the library enabled on the file, open the **Style and variables** picker in the **right sidebar** on properties such as fill, stroke, spacing, and typography to apply **variables** and **styles** from the design system.
 
 ## Link to Contribution Model
 
-Coming soon.
+Coming soon.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aleph-alpha/ui-library",
-  "version": "1.19.0",
+  "version": "1.20.0",
   "license": "Apache-2.0",
   "type": "module",
   "main": "dist/system/lib.js",
@@ -71,9 +71,9 @@
     "vitest": "^3.0.0",
     "vue-tsc": "^2.2.12",
     "wait-on": "9.0.3",
+    "@aleph-alpha/eslint-config-frontend": "0.5.0",
     "@aleph-alpha/prettier-config-frontend": "0.4.0",
-    "@aleph-alpha/tsconfig-frontend": "0.5.0",
-    "@aleph-alpha/eslint-config-frontend": "0.5.0"
+    "@aleph-alpha/tsconfig-frontend": "0.5.0"
   },
   "peerDependencies": {
     "@unocss/preset-wind4": ">=66.0.0",

package/src/patterns/UiDataTable/UiDataTable.stories.ts

@@ -229,7 +229,7 @@ const data: Payment[] = [
   { id: '3', amount: 837, status: 'processing', email: 'monserrat44@gmail.com' },
 ];
 
-// Use UiDataTableColumnHeader for sortable columns with dropdown menu
+// Use UiDataTableColumnHeader for sortable columns (click to cycle: unsorted → asc → desc)
 const columns: ColumnDef<Payment>[] = [
   {
     accessorKey: 'status',
@@ -1575,3 +1575,100 @@ export const WithCellFormatting: Story = {
     template: '<UiDataTable v-bind="args" />',
   }),
 };
+
+const withRowClickTemplateSource = `<script setup lang="ts">
+import { ref, h } from 'vue';
+import { UiDataTable, UiDataTableColumnHeader } from '@aleph-alpha/ui-library';
+import type { ColumnDef } from '@tanstack/vue-table';
+
+interface Payment {
+  id: string;
+  amount: number;
+  status: string;
+  email: string;
+}
+
+const data: Payment[] = [
+  { id: '1', amount: 316, status: 'success', email: 'ken99@yahoo.com' },
+  { id: '2', amount: 242, status: 'success', email: 'abe45@gmail.com' },
+  { id: '3', amount: 837, status: 'processing', email: 'monserrat44@gmail.com' },
+];
+
+const columns: ColumnDef<Payment>[] = [
+  {
+    accessorKey: 'status',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Status' }),
+    size: 120,
+  },
+  {
+    accessorKey: 'email',
+    header: ({ column }) => h(UiDataTableColumnHeader, { column, title: 'Email' }),
+    size: 250,
+  },
+  {
+    accessorKey: 'amount',
+    header: ({ column }) => h(UiDataTableColumnHeader, {
+      column,
+      title: 'Amount',
+      class: 'justify-end'
+    }),
+    cell: ({ row }) => {
+      const amount = Number.parseFloat(row.getValue('amount'));
+      return new Intl.NumberFormat('de-DE', {
+        style: 'currency',
+        currency: 'EUR',
+      }).format(amount);
+    },
+    size: 120,
+  },
+];
+
+const clickedRow = ref<Payment | null>(null);
+</script>
+
+<template>
+  <UiDataTable
+    :data="data"
+    :columns="columns"
+    :on-row-click="(row) => (clickedRow = row)"
+  />
+  <div v-if="clickedRow" class="mt-4 rounded border p-3 text-sm">
+    Clicked: {{ clickedRow.email }} - {{ clickedRow.status }}
+  </div>
+</template>`;
+
+export const WithRowClick: Story = {
+  args: {
+    data: payments,
+    columns: sortableColumns,
+  },
+  parameters: {
+    docs: {
+      source: {
+        code: withRowClickTemplateSource,
+      },
+    },
+  },
+  render: (args) => ({
+    components: { UiDataTable },
+    setup() {
+      const clickedRow = ref<Payment | null>(null);
+      return {
+        args,
+        clickedRow,
+        handleRowClick: (row: Payment) => {
+          clickedRow.value = row;
+        },
+      };
+    },
+    template: `
+      <div>
+        <UiDataTable v-bind="args" :on-row-click="handleRowClick" />
+        <div v-if="clickedRow" class="mt-4 rounded border p-3 text-sm">
+          Clicked: <strong>{{ clickedRow.email }}</strong> - {{ clickedRow.status }} - {{ new Intl.NumberFormat('de-DE', { style: 'currency', currency: 'EUR' }).format(clickedRow.amount) }}
+        </div>
+        <div v-else class="text-muted-foreground mt-4 text-sm">Click a row to see its data</div>
+      </div>
+    `,
+  }),
+};

package/src/patterns/UiDataTable/UiDataTable.vue

@@ -22,6 +22,9 @@
   import type { UiDataTableProps } from './types';
   import { DATA_TABLE_LABELS, DEFAULT_COLUMN_SIZE } from './constants';
 
+  const INTERACTIVE_SELECTOR =
+    'button, a, input, textarea, select, [role="button"], [role="link"], [role="menuitem"], [role="checkbox"], [role="switch"], [contenteditable="true"]';
+
   defineOptions({
     name: 'UiDataTable',
   });
@@ -68,6 +71,14 @@
     },
   });
 
+  function handleRowClick(event: MouseEvent | KeyboardEvent, original: TData) {
+    if (!props.onRowClick) return;
+    const target = event.target as HTMLElement;
+    if (target.closest?.(INTERACTIVE_SELECTOR)) return;
+    event.preventDefault();
+    props.onRowClick(original);
+  }
+
   defineExpose({
     table,
   });
@@ -102,6 +113,7 @@
             v-for="row in table.getRowModel().rows"
             :key="row.id"
             :data-state="row.getIsSelected() ? 'selected' : undefined"
+            :class="props.onRowClick ? 'cursor-pointer' : undefined"
           >
             <UiTableCell
               v-for="cell in row.getVisibleCells()"
@@ -111,6 +123,9 @@
                   ? { width: `${cell.column.getSize()}px` }
                   : undefined
               "
+              @click="handleRowClick($event, row.original)"
+              @keydown.enter="handleRowClick($event, row.original)"
+              @keydown.space="handleRowClick($event, row.original)"
             >
               <FlexRender :render="cell.column.columnDef.cell" :props="cell.getContext()" />
             </UiTableCell>

package/src/patterns/UiDataTable/UiDataTableColumnHeader.vue

@@ -1,12 +1,6 @@
 <script setup lang="ts" generic="TData, TValue">
   import { UiButton } from '@/components/UiButton';
   import { UiIcon } from '@/components/UiIcon';
-  import {
-    UiDropdownMenu,
-    UiDropdownMenuContent,
-    UiDropdownMenuItem,
-    UiDropdownMenuTrigger,
-  } from '@/components/UiDropdownMenu';
   import { cn } from '@/lib/utils';
   import { computed } from 'vue';
   import { DATA_TABLE_LABELS } from './constants';
@@ -24,8 +18,6 @@
   const props = defineProps<UiDataTableColumnHeaderProps<TData, TValue>>();
 
   const labels = computed(() => ({
-    sortAscending: props.labels?.sortAscending ?? DATA_TABLE_LABELS.sortAscending,
-    sortDescending: props.labels?.sortDescending ?? DATA_TABLE_LABELS.sortDescending,
     sortedAscending: props.labels?.sortedAscending ?? DATA_TABLE_LABELS.sortedAscending,
     sortedDescending: props.labels?.sortedDescending ?? DATA_TABLE_LABELS.sortedDescending,
     clickToSort: props.labels?.clickToSort ?? DATA_TABLE_LABELS.clickToSort,
@@ -37,57 +29,39 @@
     if (sortState === 'desc') return `${props.title}, ${labels.value.sortedDescending}`;
     return `${props.title}, ${labels.value.clickToSort}`;
   });
+
+  function handleSort() {
+    const current = props.column.getIsSorted();
+    if (current === false) {
+      props.column.toggleSorting(false); // -> asc
+    } else if (current === 'asc') {
+      props.column.toggleSorting(true); // -> desc
+    } else {
+      props.column.clearSorting(); // -> unsorted
+    }
+  }
 </script>
 
 <template>
   <div v-if="column.getCanSort()" :class="cn('flex items-center space-x-2', $attrs.class ?? '')">
-    <UiDropdownMenu>
-      <UiDropdownMenuTrigger as-child>
-        <UiButton
-          variant="ghost"
-          size="sm"
-          class="h-8 data-[state=open]:bg-accent"
-          :aria-label="sortLabel"
-        >
-          <span>{{ title }}</span>
-          <UiIcon
-            v-if="column.getIsSorted() === 'desc'"
-            name="arrow-down"
-            :size="16"
-            class="ml-2"
-            aria-hidden="true"
-          />
-          <UiIcon
-            v-else-if="column.getIsSorted() === 'asc'"
-            name="arrow-up"
-            :size="16"
-            class="ml-2"
-            aria-hidden="true"
-          />
-          <UiIcon v-else name="chevrons-up-down" :size="16" class="ml-2" aria-hidden="true" />
-        </UiButton>
-      </UiDropdownMenuTrigger>
-      <UiDropdownMenuContent align="start">
-        <UiDropdownMenuItem @click="column.toggleSorting(false)">
-          <UiIcon
-            name="arrow-up"
-            :size="14"
-            class="mr-2 text-muted-foreground/70"
-            aria-hidden="true"
-          />
-          {{ labels.sortAscending }}
-        </UiDropdownMenuItem>
-        <UiDropdownMenuItem @click="column.toggleSorting(true)">
-          <UiIcon
-            name="arrow-down"
-            :size="14"
-            class="mr-2 text-muted-foreground/70"
-            aria-hidden="true"
-          />
-          {{ labels.sortDescending }}
-        </UiDropdownMenuItem>
-      </UiDropdownMenuContent>
-    </UiDropdownMenu>
+    <UiButton variant="ghost" size="sm" class="h-8" :aria-label="sortLabel" @click="handleSort">
+      <span>{{ title }}</span>
+      <UiIcon
+        v-if="column.getIsSorted() === 'desc'"
+        name="arrow-down"
+        :size="16"
+        class="ml-2"
+        aria-hidden="true"
+      />
+      <UiIcon
+        v-else-if="column.getIsSorted() === 'asc'"
+        name="arrow-up"
+        :size="16"
+        class="ml-2"
+        aria-hidden="true"
+      />
+      <UiIcon v-else name="chevrons-up-down" :size="16" class="ml-2" aria-hidden="true" />
+    </UiButton>
   </div>
 
   <div v-else :class="$attrs.class">

package/src/patterns/UiDataTable/__tests__/UiDataTable.test.ts

@@ -1,6 +1,6 @@
-import { render, within } from '@testing-library/vue';
+import { fireEvent, render, within } from '@testing-library/vue';
 import userEvent from '@testing-library/user-event';
-import { describe, expect, test } from 'vitest';
+import { describe, expect, test, vi } from 'vitest';
 import { h, ref, nextTick } from 'vue';
 import type { ColumnDef } from '@tanstack/vue-table';
 import UiDataTable from '../UiDataTable.vue';
@@ -137,35 +137,117 @@ describe('UiDataTable', () => {
   });
 
   describe('Sorting', () => {
-    test('sorts data when sortable column header is clicked', async () => {
+    test('sorts ascending on first click', async () => {
       const user = userEvent.setup();
       const { getByRole, getAllByRole } = render(UiDataTable, {
         props: { columns: sortableColumns, data: testData },
       });
 
-      // Click the Name column header button to open dropdown
+      // Click the Name column header button to sort ascending
       await user.click(getByRole('button', { name: /Name/i }));
-      // Click ascending option
-      await user.click(getByRole('menuitem', { name: /Asc/i }));
 
       const cells = getAllByRole('cell');
       // First data row should be Alice (alphabetically first)
       expect(cells[0]).toHaveTextContent('Alice');
     });
 
-    test('sorts descending when desc option is selected', async () => {
+    test('sorts descending on second click', async () => {
       const user = userEvent.setup();
       const { getByRole, getAllByRole } = render(UiDataTable, {
         props: { columns: sortableColumns, data: testData },
       });
 
+      // First click: ascending
+      await user.click(getByRole('button', { name: /Name/i }));
+      // Second click: descending
       await user.click(getByRole('button', { name: /Name/i }));
-      await user.click(getByRole('menuitem', { name: /Desc/i }));
 
       const cells = getAllByRole('cell');
       // First data row should be Charlie (alphabetically last)
       expect(cells[0]).toHaveTextContent('Charlie');
     });
+
+    test('clears sorting on third click', async () => {
+      const user = userEvent.setup();
+      const { getByRole, getAllByRole } = render(UiDataTable, {
+        props: { columns: sortableColumns, data: testData },
+      });
+
+      const initialCells = getAllByRole('cell');
+      const initialFirst = initialCells[0].textContent;
+
+      const headerButton = getByRole('button', { name: /Name/i });
+      // First click: ascending
+      await user.click(headerButton);
+      // Second click: descending
+      await user.click(headerButton);
+      // Third click: clear sorting (back to original order)
+      await user.click(headerButton);
+
+      const finalCells = getAllByRole('cell');
+      expect(finalCells[0]).toHaveTextContent(initialFirst ?? '');
+    });
+  });
+
+  describe('Row Click', () => {
+    test('calls onRowClick with row data when a row is clicked', async () => {
+      const onRowClick = vi.fn();
+      const { getByText } = render(UiDataTable, {
+        props: { columns: basicColumns, data: testData, onRowClick },
+      });
+
+      // Click cell content - handler is on <td>, event bubbles from text
+      await fireEvent.click(getByText('Alice'));
+
+      expect(onRowClick).toHaveBeenCalledWith(testData[0]);
+    });
+
+    test('adds cursor-pointer class when onRowClick is provided', () => {
+      const { container } = render(UiDataTable, {
+        props: { columns: basicColumns, data: testData, onRowClick: () => {} },
+      });
+
+      const dataRows = container.querySelectorAll('tbody tr');
+      expect(dataRows[0]).toHaveClass('cursor-pointer');
+    });
+
+    test('does not add cursor-pointer when onRowClick is not provided', () => {
+      const { container } = render(UiDataTable, {
+        props: { columns: basicColumns, data: testData },
+      });
+
+      const dataRows = container.querySelectorAll('tbody tr');
+      expect(dataRows[0]).not.toHaveClass('cursor-pointer');
+    });
+
+    test('does not fire onRowClick when clicking interactive elements inside a row', async () => {
+      const user = userEvent.setup();
+      const onRowClick = vi.fn();
+      const { getByLabelText } = render({
+        components: { UiDataTable },
+        template: '<UiDataTable :columns="columns" :data="data" :on-row-click="onRowClick" />',
+        setup() {
+          return { columns: selectableColumns, data: testData, onRowClick };
+        },
+      });
+
+      await nextTick();
+
+      // Click the checkbox (interactive element) - should NOT trigger onRowClick
+      await user.click(getByLabelText('Select row Alice'));
+      expect(onRowClick).not.toHaveBeenCalled();
+    });
+
+    test('activates onRowClick via keyboard on cell', async () => {
+      const onRowClick = vi.fn();
+      const { getByText } = render(UiDataTable, {
+        props: { columns: basicColumns, data: testData, onRowClick },
+      });
+
+      await fireEvent.keyDown(getByText('Alice').closest('td')!, { key: 'Enter' });
+
+      expect(onRowClick).toHaveBeenCalledWith(testData[0]);
+    });
   });
 
   describe('Filtering', () => {

package/src/patterns/UiDataTable/__tests__/UiDataTableColumnHeader.test.ts

@@ -1,4 +1,4 @@
-import { render, waitFor } from '@testing-library/vue';
+import { render } from '@testing-library/vue';
 import userEvent from '@testing-library/user-event';
 import { describe, expect, test, vi } from 'vitest';
 import UiDataTableColumnHeader from '../UiDataTableColumnHeader.vue';
@@ -10,6 +10,7 @@ function createMockColumn(options: { canSort?: boolean; isSorted?: false | 'asc'
     getCanSort: vi.fn(() => canSort),
     getIsSorted: vi.fn(() => isSorted),
     toggleSorting: vi.fn(),
+    clearSorting: vi.fn(),
   };
 }
 
@@ -34,13 +35,12 @@ describe('UiDataTableColumnHeader', () => {
       expect(queryByRole('button')).not.toBeInTheDocument();
     });
 
-    test('renders as button with dropdown trigger when column is sortable', () => {
+    test('renders as button when column is sortable', () => {
       const column = createMockColumn({ canSort: true });
       const { getByRole } = render(UiDataTableColumnHeader, {
         props: { column, title: 'Name' },
       });
 
-      // Button should be accessible by role and name
       expect(getByRole('button', { name: /Name/i })).toBeInTheDocument();
     });
 
@@ -55,36 +55,42 @@ describe('UiDataTableColumnHeader', () => {
     });
   });
 
-  describe('Dropdown Menu', () => {
-    test('triggers ascending sort when Asc option is clicked', async () => {
+  describe('Click-to-Sort', () => {
+    test('sorts ascending when unsorted column is clicked', async () => {
       const user = userEvent.setup();
-      const column = createMockColumn();
+      const column = createMockColumn({ isSorted: false });
       const { getByRole } = render(UiDataTableColumnHeader, {
         props: { column, title: 'Name' },
       });
 
       await user.click(getByRole('button'));
-      await waitFor(() => expect(getByRole('menu')).toBeInTheDocument());
-
-      await user.click(getByRole('menuitem', { name: /Asc/i }));
 
       expect(column.toggleSorting).toHaveBeenCalledWith(false);
     });
 
-    test('triggers descending sort when Desc option is clicked', async () => {
+    test('sorts descending when ascending column is clicked', async () => {
       const user = userEvent.setup();
-      const column = createMockColumn();
+      const column = createMockColumn({ isSorted: 'asc' });
       const { getByRole } = render(UiDataTableColumnHeader, {
         props: { column, title: 'Name' },
       });
 
       await user.click(getByRole('button'));
-      await waitFor(() => expect(getByRole('menu')).toBeInTheDocument());
-
-      await user.click(getByRole('menuitem', { name: /Desc/i }));
 
       expect(column.toggleSorting).toHaveBeenCalledWith(true);
     });
+
+    test('clears sorting when descending column is clicked', async () => {
+      const user = userEvent.setup();
+      const column = createMockColumn({ isSorted: 'desc' });
+      const { getByRole } = render(UiDataTableColumnHeader, {
+        props: { column, title: 'Name' },
+      });
+
+      await user.click(getByRole('button'));
+
+      expect(column.clearSorting).toHaveBeenCalled();
+    });
   });
 
   describe('Accessibility', () => {
@@ -115,73 +121,30 @@ describe('UiDataTableColumnHeader', () => {
   });
 
   describe('i18n Support', () => {
-    test('uses default labels when labels prop is not provided', async () => {
-      const user = userEvent.setup();
-      const column = createMockColumn();
-      const { getByRole } = render(UiDataTableColumnHeader, {
-        props: { column, title: 'Name' },
-      });
-
-      await user.click(getByRole('button'));
-
-      await waitFor(() => {
-        expect(getByRole('menuitem', { name: 'Asc' })).toBeInTheDocument();
-        expect(getByRole('menuitem', { name: 'Desc' })).toBeInTheDocument();
-      });
-    });
-
-    test('applies custom labels when provided', async () => {
-      const user = userEvent.setup();
+    test('uses custom aria labels when provided', () => {
       const column = createMockColumn({ isSorted: 'asc' });
       const { getByRole } = render(UiDataTableColumnHeader, {
         props: {
           column,
           title: 'Name',
-          labels: {
-            sortAscending: 'Aufsteigend',
-            sortDescending: 'Absteigend',
-            sortedAscending: 'aufsteigend sortiert',
-          },
+          labels: { sortedAscending: 'aufsteigend sortiert' },
         },
       });
 
-      // Check custom aria-label
       expect(getByRole('button')).toHaveAttribute('aria-label', 'Name, aufsteigend sortiert');
-
-      // Check custom menu labels
-      await user.click(getByRole('button'));
-
-      await waitFor(() => {
-        expect(getByRole('menuitem', { name: 'Aufsteigend' })).toBeInTheDocument();
-        expect(getByRole('menuitem', { name: 'Absteigend' })).toBeInTheDocument();
-      });
     });
 
-    test('merges partial custom labels with defaults', async () => {
-      const user = userEvent.setup();
+    test('uses custom clickToSort label in aria-label', () => {
       const column = createMockColumn({ isSorted: false });
       const { getByRole } = render(UiDataTableColumnHeader, {
         props: {
           column,
-          title: 'Status',
-          labels: {
-            sortAscending: 'Sort A-Z',
-            // Other labels should fall back to defaults
-          },
+          title: 'Email',
+          labels: { clickToSort: 'zum Sortieren klicken' },
         },
       });
 
-      // clickToSort should use default
-      expect(getByRole('button')).toHaveAttribute('aria-label', 'Status, click to sort');
-
-      await user.click(getByRole('button'));
-
-      await waitFor(() => {
-        // Custom label
-        expect(getByRole('menuitem', { name: 'Sort A-Z' })).toBeInTheDocument();
-        // Default label (not overridden)
-        expect(getByRole('menuitem', { name: 'Desc' })).toBeInTheDocument();
-      });
+      expect(getByRole('button')).toHaveAttribute('aria-label', 'Email, zum Sortieren klicken');
     });
 
     test('uses custom sortedDescending label in aria-label', () => {
@@ -190,28 +153,11 @@ describe('UiDataTableColumnHeader', () => {
         props: {
           column,
           title: 'Amount',
-          labels: {
-            sortedDescending: 'absteigend sortiert',
-          },
+          labels: { sortedDescending: 'absteigend sortiert' },
         },
       });
 
       expect(getByRole('button')).toHaveAttribute('aria-label', 'Amount, absteigend sortiert');
     });
-
-    test('uses custom clickToSort label in aria-label', () => {
-      const column = createMockColumn({ isSorted: false });
-      const { getByRole } = render(UiDataTableColumnHeader, {
-        props: {
-          column,
-          title: 'Email',
-          labels: {
-            clickToSort: 'zum Sortieren klicken',
-          },
-        },
-      });
-
-      expect(getByRole('button')).toHaveAttribute('aria-label', 'Email, zum Sortieren klicken');
-    });
   });
 });

package/src/patterns/UiDataTable/types.ts

@@ -36,6 +36,11 @@ export type UiDataTableProps<TData, TValue> = {
    * @example "400px"
    */
   tableMinHeight?: string;
+  /**
+   * Callback when a data row is clicked. Receives the row's original data item.
+   * @example (item) => router.push(`/details/${item.id}`)
+   */
+  onRowClick?: (item: TData) => void;
 };
 
 /**