@aleph-alpha/chat-kit 6.5.0 → 6.7.0

package/src/components/base/CkToolApproval/CkToolApproval.stories.ts

@@ -0,0 +1,661 @@
+import CkToolApproval from './CkToolApproval.vue';
+import {
+  ckToolApprovalStatuses,
+  type CkToolApprovalRequest,
+  type CkToolApprovalStatus,
+} from './types';
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+import { expect, fn, userEvent, within } from 'storybook/test';
+import { defineComponent, h, markRaw, ref, type PropType } from 'vue';
+
+const onAllow = fn();
+const onDeny = fn();
+
+function resetSpies(): void {
+  onAllow.mockClear();
+  onDeny.mockClear();
+}
+
+const REQUEST_ID = 'mcpr_68d3a1f0c2b4';
+const GROUP_NAME = 'Update work items Polarion';
+// Long enough for the browser to drop focus from the disabled button first.
+const BACKEND_DELAY_MS = 300;
+// Upper bound on Tab presses to get past the JSON block's own controls.
+const MAX_TABS_TO_DENY = 10;
+
+const updateWorkItems: CkToolApprovalRequest = {
+  id: REQUEST_ID,
+  connector: 'polarion',
+  connectorLabel: 'Polarion',
+  toolName: 'update_work_items',
+  arguments: {
+    project_id: 'MCPT',
+    items: [
+      {
+        work_item_id: 'MCPT-042',
+        title: 'Brake pedal response under 120 ms',
+        priority: '70.0',
+      },
+      { work_item_id: 'MCPT-043', assignee_ids: ['jdoe', 'asmith'] },
+    ],
+  },
+};
+
+/**
+ * CkToolApproval asks the user to allow or deny a tool call the agent paused
+ * on. While `pending` it shows the call's arguments as JSON with Deny and
+ * Allow; once decided it collapses to a one-line result with a status badge.
+ * The host converts its backend's approval request into `request`, sends the
+ * decision to its backend on `allow` / `deny` (Deny is sent too, so the agent
+ * can carry on), and passes the new `status` in.
+ *
+ * Both buttons lock after the first click so only one answer is sent. If
+ * sending fails and the request stays pending, call the exposed `unlock()` so
+ * the user can try again.
+ */
+const meta: Meta<typeof CkToolApproval> = {
+  title: 'Base/CkToolApproval',
+  component: CkToolApproval,
+  tags: ['autodocs'],
+  argTypes: {
+    status: {
+      control: 'select',
+      options: ckToolApprovalStatuses,
+    },
+    summary: { control: 'text' },
+  },
+  args: {
+    request: updateWorkItems,
+    status: 'pending',
+    onAllow,
+    onDeny,
+  },
+  decorators: [
+    () => ({
+      template:
+        '<div style="max-width: 800px; margin: 0 auto; padding: 24px;"><story /></div>',
+    }),
+  ],
+};
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+const defaultTemplateSource = `<script setup lang="ts">
+import { ref, useTemplateRef } from 'vue';
+import {
+  CkToolApproval,
+  type CkToolApprovalRequest,
+  type CkToolApprovalStatus,
+} from '@aleph-alpha/chat-kit';
+
+// Converted from the backend's approval request by the host.
+const request: CkToolApprovalRequest = {
+  id: 'mcpr_68d3a1f0c2b4',
+  connector: 'polarion',
+  connectorLabel: 'Polarion',
+  toolName: 'update_work_items',
+  arguments: { project_id: 'MCPT', items: [/* … */] },
+};
+
+const status = ref<CkToolApprovalStatus>('pending');
+const approval = useTemplateRef('approval');
+
+async function answer(id: string, approved: boolean) {
+  try {
+    // Your call that answers the approval request on the backend.
+    await sendDecision(id, approved);
+    status.value = approved ? 'allowed' : 'denied';
+  } catch {
+    // Still pending: let the user click again.
+    approval.value?.unlock();
+  }
+}
+</script>
+
+<template>
+  <CkToolApproval
+    ref="approval"
+    :request="request"
+    :status="status"
+    @allow="answer($event, true)"
+    @deny="answer($event, false)"
+  />
+</template>`;
+
+async function expectDecidedRow(
+  canvasElement: HTMLElement,
+  resultLine: string,
+  badge: string,
+): Promise<void> {
+  const group = within(canvasElement).getByRole('group', { name: GROUP_NAME });
+  await expect(group).toHaveAccessibleDescription(resultLine);
+  await expect(within(group).getByText(badge)).toBeInTheDocument();
+  await expect(within(group).queryByRole('button')).not.toBeInTheDocument();
+}
+
+/**
+ * Waiting for the user: the header names the action, derived from `toolName`
+ * when the request has no `toolTitle`, then the arguments as JSON with Deny
+ * and Allow.
+ */
+export const Pending: Story = {
+  parameters: { docs: { source: { code: defaultTemplateSource } } },
+  play: async ({ canvasElement, step }) => {
+    resetSpies();
+    const canvas = within(canvasElement);
+
+    await step(
+      'interaction: Allow emits allow with the request id',
+      async () => {
+        await userEvent.click(canvas.getByRole('button', { name: 'Allow' }));
+        await expect(onAllow).toHaveBeenCalledWith(REQUEST_ID);
+        await expect(onDeny).not.toHaveBeenCalled();
+      },
+    );
+
+    await step(
+      'interaction: both buttons lock after the first click',
+      async () => {
+        await expect(
+          canvas.getByRole('button', { name: 'Allow' }),
+        ).toBeDisabled();
+        await expect(
+          canvas.getByRole('button', { name: 'Deny' }),
+        ).toBeDisabled();
+        await userEvent.click(canvas.getByRole('button', { name: 'Deny' }), {
+          pointerEventsCheck: 0,
+        });
+        await expect(onDeny).not.toHaveBeenCalled();
+      },
+    );
+  },
+};
+
+/** Allowed and run, with an outcome summary from the host. */
+export const Allowed: Story = {
+  args: { status: 'allowed', summary: '2 work items updated' },
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step(
+      'interaction: a decided card has no buttons left to press',
+      async () => {
+        await expect(canvas.queryByRole('button')).not.toBeInTheDocument();
+      },
+    );
+
+    await step(
+      'screen-reader: the outcome is read as text inside the named group',
+      async () => {
+        const group = canvas.getByRole('group', { name: GROUP_NAME });
+        await expect(group).toHaveAccessibleDescription(
+          'Approved by you · 2 work items updated',
+        );
+        await expect(group).toHaveTextContent('Allowed');
+      },
+    );
+  },
+};
+
+/** Denied by the user. Nothing ran. */
+export const Denied: Story = {
+  args: { status: 'denied' },
+  play: async ({ canvasElement, step }) => {
+    await step(
+      'screen-reader: the row is described by its result and has no buttons',
+      () =>
+        expectDecidedRow(
+          canvasElement,
+          'Denied by you · Nothing was updated',
+          'Denied',
+        ),
+    );
+  },
+};
+
+/** Allowed, but the tool errored, so nothing changed. */
+export const Failed: Story = {
+  args: { status: 'failed' },
+  play: async ({ canvasElement, step }) => {
+    await step(
+      'screen-reader: the row is described by its result and has no buttons',
+      () =>
+        expectDecidedRow(
+          canvasElement,
+          'Failed · Nothing was updated',
+          'Failed',
+        ),
+    );
+  },
+};
+
+/** The user sent a new message instead of answering. Nothing ran. */
+export const Skipped: Story = {
+  args: { status: 'skipped' },
+  play: async ({ canvasElement, step }) => {
+    await step(
+      'screen-reader: the row is described by its result and has no buttons',
+      () =>
+        expectDecidedRow(
+          canvasElement,
+          'Skipped · Nothing was updated',
+          'Skipped',
+        ),
+    );
+  },
+};
+
+/**
+ * No `connectorLabel` on the request: the chip is hidden, for chats embedded
+ * in the connector's own app where the target is obvious.
+ */
+export const WithoutConnectorLabel: Story = {
+  args: { request: { ...updateWorkItems, connectorLabel: undefined } },
+  play: async ({ canvasElement, step }) => {
+    await step(
+      'screen-reader: the card is named by its action alone',
+      async () => {
+        await expect(
+          within(canvasElement).getByRole('group', {
+            name: 'Update work items',
+          }),
+        ).toBeInTheDocument();
+      },
+    );
+  },
+};
+
+/**
+ * Another connector, with the tool's own title from its MCP server and a
+ * Lucide icon for the chip. Use the `connector-icon` slot for a brand logo.
+ */
+export const OtherConnector: Story = {
+  args: {
+    request: {
+      id: 'mcpr_9f2e7c1d0a3b',
+      connector: 'gmail',
+      connectorLabel: 'Gmail',
+      connectorIcon: 'mail',
+      toolName: 'send_message',
+      toolTitle: 'Send email',
+      arguments: { to: ['team@example.com'], subject: 'Weekly update' },
+    },
+  },
+  play: async ({ canvasElement, step }) => {
+    resetSpies();
+    const canvas = within(canvasElement);
+
+    await step(
+      "screen-reader: the tool's own title and connector name the card",
+      async () => {
+        await expect(
+          canvas.getByRole('group', { name: 'Send email Gmail' }),
+        ).toBeInTheDocument();
+        await expect(
+          canvasElement.querySelector('.lucide-mail'),
+        ).not.toBeNull();
+      },
+    );
+
+    await step(
+      'interaction: Deny emits deny with this request id',
+      async () => {
+        await userEvent.click(canvas.getByRole('button', { name: 'Deny' }));
+        await expect(onDeny).toHaveBeenCalledWith('mcpr_9f2e7c1d0a3b');
+      },
+    );
+  },
+};
+
+const WorkItemsBody = markRaw(
+  defineComponent({
+    props: {
+      request: {
+        type: Object as PropType<CkToolApprovalRequest>,
+        required: true,
+      },
+    },
+    setup(props) {
+      return () => {
+        const items = props.request.arguments.items;
+        const ids = Array.isArray(items)
+          ? items.map((item: { work_item_id?: unknown }) =>
+              String(item.work_item_id),
+            )
+          : [];
+        return h(
+          'ul',
+          { class: 'list-disc pl-5 text-sm' },
+          ids.map((id) => h('li', `Update ${id}`)),
+        );
+      };
+    },
+  }),
+);
+
+const customBodySource = `<!-- WorkItemsBody.vue: receives the request as its only prop -->
+<script setup lang="ts">
+import { computed } from 'vue';
+import type { CkToolApprovalBodyProps } from '@aleph-alpha/chat-kit';
+
+const props = defineProps<CkToolApprovalBodyProps>();
+
+// Arguments arrive untyped from the model; keep only well-formed items.
+function isWorkItem(value: unknown): value is { work_item_id: string } {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'work_item_id' in value &&
+    typeof value.work_item_id === 'string'
+  );
+}
+
+const workItems = computed(() => {
+  const items = props.request.arguments.items;
+  return Array.isArray(items) ? items.filter(isWorkItem) : [];
+});
+</script>
+
+<template>
+  <ul>
+    <li v-for="item in workItems" :key="item.work_item_id">
+      Update {{ item.work_item_id }}
+    </li>
+  </ul>
+</template>
+
+<!-- Where the card is used -->
+<CkToolApproval
+  :request="request"
+  status="pending"
+  :body-components="{ polarion: { update_work_items: WorkItemsBody } }"
+/>`;
+
+/**
+ * A custom body registered for `polarion` + `update_work_items` replaces the
+ * JSON view. Requests with no entry keep the JSON view.
+ */
+export const CustomBody: Story = {
+  args: {
+    bodyComponents: { polarion: { update_work_items: WorkItemsBody } },
+  },
+  parameters: { docs: { source: { code: customBodySource } } },
+  play: async ({ canvasElement, step }) => {
+    const group = within(canvasElement).getByRole('group', {
+      name: GROUP_NAME,
+    });
+
+    await step(
+      'interaction: the custom body replaces the JSON view',
+      async () => {
+        await expect(within(group).getByText('Update MCPT-042')).toBeVisible();
+        await expect(group).not.toHaveTextContent('"project_id"');
+      },
+    );
+  },
+};
+
+/**
+ * Keyboard users Tab to Deny, then to Allow, and Enter on Allow allows.
+ * Hidden from the sidebar; runs in CI.
+ */
+export const KeyboardNavigation: Story = {
+  name: 'test - Keyboard Navigation',
+  tags: ['!dev', '!autodocs'],
+  parameters: { chromatic: { disableSnapshot: true } },
+  play: async ({ canvasElement, step }) => {
+    resetSpies();
+    const canvas = within(canvasElement);
+    const deny = canvas.getByRole('button', { name: 'Deny' });
+    const allow = canvas.getByRole('button', { name: 'Allow' });
+
+    await step('keyboard: Tab reaches Deny (WCAG 2.1.1 Keyboard)', async () => {
+      // The JSON block's own controls come first; tab past them.
+      for (
+        let i = 0;
+        i < MAX_TABS_TO_DENY && document.activeElement !== deny;
+        i++
+      ) {
+        await userEvent.tab();
+      }
+      await expect(deny).toHaveFocus();
+    });
+
+    await step(
+      'keyboard: Tab moves from Deny to Allow (WCAG 2.4.3 Focus Order)',
+      async () => {
+        await userEvent.tab();
+        await expect(allow).toHaveFocus();
+      },
+    );
+
+    await step('keyboard: Enter on Allow allows', async () => {
+      await userEvent.keyboard('{Enter}');
+      await expect(onAllow).toHaveBeenCalledWith(REQUEST_ID);
+    });
+  },
+};
+
+/**
+ * What assistive tech hears: one named group, two named buttons, and
+ * decorative icons hidden. Also checks that Space on Deny denies. Hidden
+ * from the sidebar; runs in CI.
+ */
+export const ScreenReader: Story = {
+  name: 'test - Screen Reader',
+  tags: ['!dev', '!autodocs'],
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step(
+      'screen-reader: the card is a group named by title and connector (WCAG 1.3.1)',
+      async () => {
+        await expect(
+          canvas.getByRole('group', { name: GROUP_NAME }),
+        ).toBeInTheDocument();
+      },
+    );
+
+    await step(
+      'screen-reader: both actions have accessible names (WCAG 4.1.2)',
+      async () => {
+        await expect(
+          canvas.getByRole('button', { name: 'Deny' }),
+        ).toBeInTheDocument();
+        await expect(
+          canvas.getByRole('button', { name: 'Allow' }),
+        ).toBeInTheDocument();
+      },
+    );
+
+    await step(
+      'screen-reader: the connector icon is hidden from the accessibility tree',
+      async () => {
+        const icon = canvasElement.querySelector('.lucide-app-window');
+        await expect(icon).not.toBeNull();
+        await expect(icon?.closest('[aria-hidden="true"]')).not.toBeNull();
+      },
+    );
+
+    await step('keyboard: Space on Deny denies', async () => {
+      resetSpies();
+      canvas.getByRole('button', { name: 'Deny' }).focus();
+      await userEvent.keyboard(' ');
+      await expect(onDeny).toHaveBeenCalledWith(REQUEST_ID);
+    });
+  },
+};
+
+/**
+ * At 200% zoom the card still fits and both actions stay usable. Hidden from
+ * the sidebar; runs in CI.
+ */
+export const ZoomMagnification: Story = {
+  name: 'test - Zoom Magnification',
+  tags: ['!dev', '!autodocs'],
+  decorators: [
+    () => ({ template: '<div style="zoom: 2; width: 400px;"><story /></div>' }),
+  ],
+  play: async ({ canvasElement, step }) => {
+    resetSpies();
+    const canvas = within(canvasElement);
+    const card = canvas.getByRole('group', { name: GROUP_NAME });
+
+    await step(
+      'zoom: the card does not overflow sideways at 200% (WCAG 1.4.4 Resize Text)',
+      async () => {
+        await expect(card.scrollWidth).toBeLessThanOrEqual(
+          card.clientWidth + 1,
+        );
+      },
+    );
+
+    await step('zoom: Allow stays visible and clickable', async () => {
+      const allow = canvas.getByRole('button', { name: 'Allow' });
+      await expect(allow).toBeVisible();
+      await userEvent.click(allow);
+      await expect(onAllow).toHaveBeenCalledWith(REQUEST_ID);
+    });
+  },
+};
+
+/**
+ * At a 320px phone width the card reflows without sideways scrolling and the
+ * buttons keep a usable touch size. Hidden from the sidebar; runs in CI.
+ */
+export const MobileBreakpoint: Story = {
+  name: 'test - Mobile Breakpoint',
+  tags: ['!dev', '!autodocs'],
+  globals: { viewport: 'mobile' },
+  decorators: [
+    () => ({ template: '<div style="width: 320px;"><story /></div>' }),
+  ],
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+    const card = canvas.getByRole('group', { name: GROUP_NAME });
+
+    await step(
+      'mobile: the card fits a 320px width (WCAG 1.4.10 Reflow)',
+      async () => {
+        const width = card.getBoundingClientRect().width;
+        await expect(width).toBeGreaterThan(0);
+        await expect(width).toBeLessThanOrEqual(320);
+        await expect(card.scrollWidth).toBeLessThanOrEqual(
+          card.clientWidth + 1,
+        );
+      },
+    );
+
+    await step(
+      'mobile: buttons are at least 24px tall (WCAG 2.5.8 Target Size)',
+      async () => {
+        for (const name of ['Deny', 'Allow']) {
+          const height = canvas
+            .getByRole('button', { name })
+            .getBoundingClientRect().height;
+          await expect(height).toBeGreaterThanOrEqual(24);
+        }
+      },
+    );
+  },
+};
+
+/**
+ * The host waits for its backend before passing the new status. Focus must
+ * still land on the result row, although the browser drops it from the
+ * disabled button meanwhile. Hidden from the sidebar; runs in CI.
+ */
+export const FocusAfterSlowDecision: Story = {
+  name: 'test - Focus After Slow Decision',
+  tags: ['!dev', '!autodocs'],
+  render: (args) => ({
+    components: { CkToolApproval },
+    setup() {
+      const status = ref<CkToolApprovalStatus>('pending');
+      function allowLater(): void {
+        setTimeout(() => {
+          status.value = 'allowed';
+        }, BACKEND_DELAY_MS);
+      }
+      return { args, status, allowLater };
+    },
+    template:
+      '<CkToolApproval :request="args.request" :status="status" @allow="allowLater" />',
+  }),
+  play: async ({ canvasElement, step }) => {
+    const canvas = within(canvasElement);
+
+    await step(
+      'keyboard: focus reaches the result row after a slow answer (WCAG 2.4.3 Focus Order)',
+      async () => {
+        canvas.getByRole('button', { name: 'Allow' }).focus();
+        await userEvent.keyboard('{Enter}');
+        const row = await canvas.findByText('Allowed');
+        await expect(
+          row.closest('[role="group"]') as HTMLElement,
+        ).toHaveFocus();
+      },
+    );
+  },
+};
+
+const LONG_CONNECTOR_LABEL = 'Polarion ALM Requirements Engineering Workspace';
+
+/**
+ * A long connector name at a 320px phone width: the chip shrinks and cuts its
+ * text instead of pushing the card wider or into the status badge, and screen
+ * readers still get the full name. Hidden from the sidebar; runs in CI.
+ */
+export const LongConnectorLabel: Story = {
+  name: 'test - Long Connector Label',
+  tags: ['!dev', '!autodocs'],
+  render: () => ({
+    components: { CkToolApproval },
+    setup() {
+      const request = {
+        ...updateWorkItems,
+        connectorLabel: LONG_CONNECTOR_LABEL,
+      };
+      return { request };
+    },
+    template: `
+      <div style="width: 320px; display: flex; flex-direction: column; gap: 16px;">
+        <CkToolApproval :request="request" status="pending" />
+        <CkToolApproval :request="request" status="allowed" summary="2 work items updated" />
+      </div>`,
+  }),
+  play: async ({ canvasElement, step }) => {
+    const groups = within(canvasElement).getAllByRole('group', {
+      name: `Update work items ${LONG_CONNECTOR_LABEL}`,
+    });
+
+    await step(
+      'mobile: neither card grows wider than the screen (WCAG 1.4.10 Reflow)',
+      async () => {
+        await expect(groups).toHaveLength(2);
+        for (const group of groups) {
+          await expect(group.scrollWidth).toBeLessThanOrEqual(
+            group.clientWidth + 1,
+          );
+        }
+      },
+    );
+
+    await step(
+      'mobile: the chip stays clear of the status badge in the result row',
+      async () => {
+        const row = groups[1];
+        const chip = within(row)
+          .getByText(LONG_CONNECTOR_LABEL)
+          .closest('[data-slot="badge"]') as HTMLElement;
+        const status = within(row)
+          .getByText('Allowed')
+          .closest('[data-slot="badge"]') as HTMLElement;
+        await expect(chip.getBoundingClientRect().right).toBeLessThanOrEqual(
+          status.getBoundingClientRect().left,
+        );
+      },
+    );
+  },
+};