@aleph-alpha/chat-kit 1.9.1 → 1.10.0

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

@@ -0,0 +1,307 @@
+import type { Meta, StoryObj } from '@storybook/vue3-vite';
+import { ref } from 'vue';
+import CkFileItemsList from './CkFileItemsList.vue';
+import type { CkFileEntry } from './types';
+
+const meta: Meta<typeof CkFileItemsList> = {
+  title: 'Base/CkFileItemsList',
+  component: CkFileItemsList,
+  tags: ['autodocs'],
+  parameters: {
+    layout: 'padded',
+    docs: {
+      description: {
+        component:
+          'Compact horizontal row of file attachments. Renders up to `maxInline` `UiFileItem`s side-by-side; once that threshold is exceeded, the full list collapses into a single popover trigger.',
+      },
+    },
+  },
+  argTypes: {
+    maxInline: { control: { type: 'number', min: 1, max: 6, step: 1 } },
+    size: { control: { type: 'inline-radio' }, options: ['default', 'small'] },
+    isRemovable: { control: 'boolean' },
+    disabled: { control: 'boolean' },
+    listLabel: { control: 'text' },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof CkFileItemsList>;
+
+const baseFiles: CkFileEntry[] = [
+  {
+    id: 1,
+    filename: 'project-proposal.pdf',
+    typeLabel: 'PDF',
+    sizeLabel: '1.2 MB',
+  },
+  { id: 2, filename: 'meeting-notes.md', typeLabel: 'MD', sizeLabel: '14 KB' },
+  { id: 3, filename: 'q3-revenue.csv', typeLabel: 'CSV', sizeLabel: '320 KB' },
+];
+
+const overflowFiles: CkFileEntry[] = [
+  ...baseFiles,
+  {
+    id: 4,
+    filename: 'design-spec.docx',
+    typeLabel: 'DOCX',
+    sizeLabel: '880 KB',
+  },
+  { id: 5, filename: 'readme.txt', typeLabel: 'TXT', sizeLabel: '4 KB' },
+];
+
+const inlineTemplateSource = `<script setup lang="ts">
+import { CkFileItemsList, type CkFileEntry } from '@aleph-alpha/chat-kit';
+
+const files: CkFileEntry[] = [
+  { id: 1, filename: 'project-proposal.pdf', typeLabel: 'PDF', sizeLabel: '1.2 MB' },
+  { id: 2, filename: 'meeting-notes.md', typeLabel: 'MD', sizeLabel: '14 KB' },
+  { id: 3, filename: 'q3-revenue.csv', typeLabel: 'CSV', sizeLabel: '320 KB' },
+];
+</script>
+
+<template>
+  <CkFileItemsList :files="files" />
+</template>`;
+
+const collapsedTemplateSource = `<script setup lang="ts">
+import { CkFileItemsList, type CkFileEntry } from '@aleph-alpha/chat-kit';
+
+const files: CkFileEntry[] = [
+  /* … five entries … */
+];
+</script>
+
+<template>
+  <CkFileItemsList :files="files" />
+</template>`;
+
+const removableTemplateSource = `<script setup lang="ts">
+import { ref } from 'vue';
+import { CkFileItemsList, type CkFileEntry } from '@aleph-alpha/chat-kit';
+
+const files = ref<CkFileEntry[]>([
+  { id: 1, filename: 'project-proposal.pdf', typeLabel: 'PDF', sizeLabel: '1.2 MB' },
+  { id: 2, filename: 'meeting-notes.md', typeLabel: 'MD', sizeLabel: '14 KB' },
+  { id: 3, filename: 'q3-revenue.csv', typeLabel: 'CSV', sizeLabel: '320 KB' },
+]);
+
+function handleRemove(id: CkFileEntry['id']) {
+  files.value = files.value.filter((f) => f.id !== id);
+}
+</script>
+
+<template>
+  <CkFileItemsList :files="files" is-removable @remove="handleRemove" />
+</template>`;
+
+/**
+ * Up to `maxInline` (default `3`) files are rendered inline as a horizontal
+ * row of `UiFileItem`s.
+ */
+export const Inline: Story = {
+  render: () => ({
+    components: { CkFileItemsList },
+    setup: () => ({ files: baseFiles }),
+    template: `
+      <div class="bg-background-surface-primary p-4 w-[36rem]">
+        <CkFileItemsList :files="files" />
+      </div>
+    `,
+  }),
+  parameters: { docs: { source: { code: inlineTemplateSource } } },
+};
+
+/**
+ * When the list overflows `maxInline`, the component collapses to a single
+ * popover trigger. Click it to reveal the full vertical list of files.
+ */
+export const Collapsed: Story = {
+  render: () => ({
+    components: { CkFileItemsList },
+    setup: () => ({ files: overflowFiles }),
+    template: `
+      <div class="bg-background-surface-primary p-4 w-[36rem]">
+        <CkFileItemsList :files="files" />
+      </div>
+    `,
+  }),
+  parameters: { docs: { source: { code: collapsedTemplateSource } } },
+};
+
+/**
+ * Each row exposes a remove control when `isRemovable` is `true`. The component
+ * emits `remove` with the corresponding file `id`.
+ */
+export const Removable: Story = {
+  render: () => ({
+    components: { CkFileItemsList },
+    setup() {
+      const files = ref<CkFileEntry[]>([...baseFiles]);
+      function handleRemove(id: CkFileEntry['id']) {
+        files.value = files.value.filter((f) => f.id !== id);
+      }
+      return { files, handleRemove };
+    },
+    template: `
+      <div class="bg-background-surface-primary p-4 w-[36rem]">
+        <CkFileItemsList :files="files" is-removable @remove="handleRemove" />
+      </div>
+    `,
+  }),
+  parameters: { docs: { source: { code: removableTemplateSource } } },
+};
+
+const customItemTemplateSource = `<script setup lang="ts">
+import { CkFileItemsList, type CkFileEntry } from '@aleph-alpha/chat-kit';
+
+const files: CkFileEntry[] = [
+  { id: 1, filename: 'project-proposal.pdf' },
+  { id: 2, filename: 'meeting-notes.md' },
+  { id: 3, filename: 'q3-revenue.csv' },
+];
+</script>
+
+<template>
+  <CkFileItemsList :files="files">
+    <template #item="{ file, remove }">
+      <a :href="\`/files/\${file.id}\`" class="…custom row…">
+        {{ file.filename }}
+      </a>
+    </template>
+  </CkFileItemsList>
+</template>`;
+
+/**
+ * Use the `item` scoped slot to replace the row rendering entirely. The
+ * default renders `UiFileItem`; overriding it lets consumers render any
+ * component (router links, custom chips, project-specific file rows, …)
+ * while still receiving the file data and a pre-bound `remove` handler.
+ */
+export const CustomItem: Story = {
+  render: () => ({
+    components: { CkFileItemsList },
+    setup: () => ({ files: baseFiles }),
+    template: `
+      <div class="bg-background-surface-primary p-4 w-[36rem]">
+        <CkFileItemsList :files="files">
+          <template #item="{ file }">
+            <a
+              :href="'#/files/' + file.id"
+              class="block truncate rounded-lg bg-background-surface-secondary px-3 py-2 body-14-medium text-content-on-surface-primary hover:underline"
+            >
+              {{ file.filename }}
+            </a>
+          </template>
+        </CkFileItemsList>
+      </div>
+    `,
+  }),
+  parameters: { docs: { source: { code: customItemTemplateSource } } },
+};
+
+const clickableTemplateSource = `<script setup lang="ts">
+import { CkFileItemsList, type CkFileEntry } from '@aleph-alpha/chat-kit';
+
+const files: CkFileEntry[] = [
+  /* … */
+];
+
+function openFile(file: CkFileEntry) {
+  // open viewer, navigate, etc.
+  console.log('open', file.id);
+}
+</script>
+
+<template>
+  <CkFileItemsList :files="files" @item-click="openFile" />
+</template>`;
+
+/**
+ * Listen for `item-click` to make rows actionable (open a file viewer,
+ * navigate, etc.). Clicks on the remove button — or on any `<button>` /
+ * `<a>` rendered via the `#item` slot — are excluded so they don't double
+ * fire. The popover auto-closes after a click in the collapsed state.
+ */
+export const Clickable: Story = {
+  render: () => ({
+    components: { CkFileItemsList },
+    setup() {
+      const lastClicked = ref<string>('');
+      function openFile(file: CkFileEntry) {
+        lastClicked.value = String(file.id);
+      }
+      return { files: overflowFiles, openFile, lastClicked };
+    },
+    template: `
+      <div class="bg-background-surface-primary p-4 w-[36rem]">
+        <CkFileItemsList
+          :files="files"
+          list-label="Attached files"
+          @item-click="openFile"
+        />
+        <p class="label-12-regular mt-3 text-content-on-surface-muted">
+          Last clicked id: {{ lastClicked || '—' }}
+        </p>
+      </div>
+    `,
+  }),
+  parameters: { docs: { source: { code: clickableTemplateSource } } },
+};
+
+const disabledTemplateSource = `<script setup lang="ts">
+import { CkFileItemsList, type CkFileEntry } from '@aleph-alpha/chat-kit';
+
+const files: CkFileEntry[] = [
+  /* one entry has its own \`disabled: true\` */
+];
+
+const isStreaming = true;
+</script>
+
+<template>
+  <!-- whole-list disabled while a response is streaming -->
+  <CkFileItemsList :files="files" :disabled="isStreaming" is-removable />
+</template>`;
+
+/**
+ * Set `disabled` on the list (or `disabled: true` on individual `CkFileEntry`)
+ * to make rows `inert` while a response streams or a network request is in
+ * flight. Disabled rows do not emit `remove` or `item-click`, and the
+ * collapsed trigger button itself is `disabled`.
+ */
+export const Disabled: Story = {
+  render: () => ({
+    components: { CkFileItemsList },
+    setup: () => ({
+      files: [
+        ...baseFiles,
+        {
+          id: 4,
+          filename: 'archive.zip',
+          typeLabel: 'ZIP',
+          sizeLabel: '2 MB',
+          disabled: true,
+        },
+      ] as CkFileEntry[],
+    }),
+    template: `
+      <div class="flex flex-col gap-6 bg-background-surface-primary p-4 w-[36rem]">
+        <div>
+          <p class="label-12-medium text-content-on-surface-muted mb-2">
+            Whole list disabled
+          </p>
+          <CkFileItemsList :files="files.slice(0, 3)" disabled is-removable />
+        </div>
+        <div>
+          <p class="label-12-medium text-content-on-surface-muted mb-2">
+            Per-row disabled (the .zip)
+          </p>
+          <CkFileItemsList :files="files" is-removable />
+        </div>
+      </div>
+    `,
+  }),
+  parameters: { docs: { source: { code: disabledTemplateSource } } },
+};

package/src/components/base/CkFileItemsList/CkFileItemsList.vue

@@ -0,0 +1,168 @@
+<script setup lang="ts">
+import {
+  UiFileType,
+  UiIcon,
+  UiPopover,
+  UiPopoverContent,
+  UiPopoverTrigger,
+  type UiFileItemSize,
+} from '@aleph-alpha/ui-library';
+import { computed, ref } from 'vue';
+import CkFileItemRow from './CkFileItemRow.vue';
+import type {
+  CkFileEntry,
+  CkFileItemsListEmits,
+  CkFileItemsListProps,
+} from './types';
+
+defineOptions({
+  name: 'CkFileItemsList',
+});
+
+const props = withDefaults(defineProps<CkFileItemsListProps>(), {
+  maxInline: 3,
+  size: 'small',
+  isRemovable: false,
+  removeLabel: 'Remove file',
+  disabled: false,
+  triggerLabel: undefined,
+  triggerAriaLabel: undefined,
+  listLabel: undefined,
+  popoverClass: undefined,
+});
+
+const emit = defineEmits<CkFileItemsListEmits>();
+
+// Replace the default `UiFileItem` row. `remove()` is pre-bound and
+// `disabled` reflects list-level + per-row disable.
+defineSlots<{
+  item: (props: {
+    file: CkFileEntry;
+    remove: () => void;
+    size: UiFileItemSize;
+    isRemovable: boolean;
+    removeLabel: string;
+    disabled: boolean;
+  }) => unknown;
+}>();
+
+const isCollapsed = computed(() => props.files.length > props.maxInline);
+const isOpen = ref(false);
+
+function isRowDisabled(file: CkFileEntry): boolean {
+  return props.disabled || file.disabled === true;
+}
+
+const defaultTriggerLabel = computed(() => `${props.files.length} files`);
+const resolvedTriggerLabel = computed(
+  () => props.triggerLabel ?? defaultTriggerLabel.value,
+);
+const resolvedTriggerAriaLabel = computed(
+  () =>
+    props.triggerAriaLabel ?? props.triggerLabel ?? defaultTriggerLabel.value,
+);
+
+function handleRemove(file: CkFileEntry) {
+  if (isRowDisabled(file)) return;
+  emit('remove', file.id);
+}
+
+function handleRowClick(file: CkFileEntry, event: MouseEvent) {
+  if (isRowDisabled(file)) return;
+  // Skip clicks originating from any interactive child (remove button,
+  // links/buttons supplied via #item) so they don't double-fire.
+  const target = event.target as HTMLElement | null;
+  if (target?.closest('button, a, [role="button"]')) return;
+  emit('item-click', file, event);
+  if (isOpen.value) isOpen.value = false;
+}
+</script>
+
+<template>
+  <ul
+    v-if="!isCollapsed"
+    data-slot="file-items-list"
+    class="m-0 flex w-full min-w-0 list-none flex-wrap items-center gap-2 p-0"
+    :aria-label="listLabel"
+  >
+    <li
+      v-for="file in files"
+      :key="file.id"
+      class="min-w-0 max-w-full flex-1 basis-0"
+      @click="handleRowClick(file, $event)"
+    >
+      <CkFileItemRow
+        :file="file"
+        :size="size"
+        :is-removable="isRemovable"
+        :remove-label="removeLabel"
+        :disabled="isRowDisabled(file)"
+        @remove="handleRemove(file)"
+      >
+        <template #default="bindings">
+          <slot name="item" v-bind="bindings" />
+        </template>
+      </CkFileItemRow>
+    </li>
+  </ul>
+
+  <UiPopover v-else v-model:open="isOpen">
+    <UiPopoverTrigger as-child>
+      <button
+        type="button"
+        data-slot="file-items-list-trigger"
+        :disabled="disabled"
+        class="relative flex w-full max-w-full min-w-0 items-center gap-3 rounded-xl bg-background-surface-muted-subtle text-left transition-colors hover:bg-background-surface-muted focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-border-focus disabled:cursor-not-allowed disabled:opacity-50 disabled:hover:bg-background-surface-muted-subtle"
+        :class="size === 'small' ? 'p-2' : 'p-3'"
+        :aria-label="resolvedTriggerAriaLabel"
+      >
+        <UiFileType icon="paperclip" tone="default" />
+        <span
+          class="min-w-0 flex-1 truncate text-content-on-surface-primary"
+          :class="size === 'small' ? 'label-12-medium' : 'body-14-medium'"
+        >
+          {{ resolvedTriggerLabel }}
+        </span>
+        <UiIcon
+          name="chevron-down"
+          :size="16"
+          aria-hidden="true"
+          class="shrink-0 text-content-on-surface-muted transition-transform"
+          :class="isOpen && 'rotate-180'"
+        />
+      </button>
+    </UiPopoverTrigger>
+
+    <UiPopoverContent
+      align="start"
+      :side-offset="4"
+      :class="['w-64 p-2', popoverClass]"
+    >
+      <ul
+        data-slot="file-items-list-collapsed"
+        class="m-0 flex list-none flex-col gap-2 p-0"
+        :aria-label="listLabel"
+      >
+        <li
+          v-for="file in files"
+          :key="file.id"
+          class="min-w-0"
+          @click="handleRowClick(file, $event)"
+        >
+          <CkFileItemRow
+            :file="file"
+            :size="size"
+            :is-removable="isRemovable"
+            :remove-label="removeLabel"
+            :disabled="isRowDisabled(file)"
+            @remove="handleRemove(file)"
+          >
+            <template #default="bindings">
+              <slot name="item" v-bind="bindings" />
+            </template>
+          </CkFileItemRow>
+        </li>
+      </ul>
+    </UiPopoverContent>
+  </UiPopover>
+</template>

package/src/components/base/CkFileItemsList/index.ts

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

package/src/components/base/CkFileItemsList/types.ts

@@ -0,0 +1,64 @@
+import type {
+  UiFileItemMediaTone,
+  UiFileItemSize,
+} from '@aleph-alpha/ui-library';
+
+export interface CkFileEntry {
+  /** Stable id used as the `:key` and emitted with `remove`. */
+  id: string | number;
+  /** Full file name. */
+  filename: string;
+  /** Short type label, e.g. `PDF`. */
+  typeLabel?: string;
+  /** Size label, e.g. `1.2 MB`. */
+  sizeLabel?: string;
+  /** Upload progress 0–100; `< 100` shows a progress bar. */
+  progress?: number | null;
+  /** Error message; non-empty enters the error state. */
+  error?: string | null;
+  /** Lucide icon override for the media badge. */
+  mediaIcon?: string;
+  /** Media badge tone override. */
+  mediaTone?: UiFileItemMediaTone;
+  /** Per-row disable. */
+  disabled?: boolean;
+}
+
+/**
+ * Horizontal list of file attachments; collapses to a popover once the
+ * count exceeds `maxInline`.
+ *
+ * @category Inputs
+ * @useCases user message attachments, prompt input previews, chat file row
+ * @keywords files, attachments, file list, popover, chat
+ * @related UiFileItem, UiPopover
+ */
+export interface CkFileItemsListProps {
+  /** Files to render. Order is preserved. */
+  files: CkFileEntry[];
+  /** @default 3 */
+  maxInline?: number;
+  /** @default 'small' */
+  size?: UiFileItemSize;
+  /** Show a remove control on every row. @default false */
+  isRemovable?: boolean;
+  /** Remove control label, forwarded to `UiFileItem`. */
+  removeLabel?: string;
+  /** Disable every row + the collapsed trigger. @default false */
+  disabled?: boolean;
+  /** Visible label on the collapsed trigger. Defaults to `"{n} files"`. */
+  triggerLabel?: string;
+  /** A11y label for the trigger. Falls back to `triggerLabel`, then count. */
+  triggerAriaLabel?: string;
+  /** `aria-label` for the `<ul>` (e.g. `"Attached files"`). */
+  listLabel?: string;
+  /** Extra classes for the popover content (override the default `w-64`). */
+  popoverClass?: string;
+}
+
+export interface CkFileItemsListEmits {
+  /** Remove control activated. Suppressed for disabled rows. */
+  (event: 'remove', id: CkFileEntry['id']): void;
+  /** Row clicked outside any interactive child. Suppressed for disabled rows. */
+  (event: 'item-click', file: CkFileEntry, originalEvent: MouseEvent): void;
+}

package/src/components/base/index.ts

@@ -8,6 +8,12 @@ export type {
   CkFeedbackButtonProps,
   CkFeedbackValue,
 } from './CkFeedbackButton';
+export { CkFileItemsList } from './CkFileItemsList';
+export type {
+  CkFileEntry,
+  CkFileItemsListProps,
+  CkFileItemsListEmits,
+} from './CkFileItemsList';
 export { CkHistoryItem } from './CkHistoryItem';
 export type { CkHistoryItemProps, CkHistoryItemEmits } from './CkHistoryItem';
 export { CkHistoryWrapper } from './CkHistoryWrapper';

package/src/components/index.ts

@@ -4,6 +4,7 @@ export {
   CkConversationLayout,
   CkCopyMessageActionButton,
   CkFeedbackButton,
+  CkFileItemsList,
   CkHistoryItem,
   CkHistoryWrapper,
   CkMarkdownRenderer,
@@ -20,6 +21,9 @@ export type {
   CkConversationLayoutProps,
   CkFeedbackButtonProps,
   CkFeedbackValue,
+  CkFileEntry,
+  CkFileItemsListEmits,
+  CkFileItemsListProps,
   CkHistoryItemEmits,
   CkHistoryItemProps,
   CkHistoryWrapperProps,

package/src/index.ts

@@ -67,6 +67,7 @@ export {
   CkConversationLayout,
   CkCopyMessageActionButton,
   CkFeedbackButton,
+  CkFileItemsList,
   CkHistory,
   CkHistoryItem,
   CkHistoryWrapper,
@@ -86,6 +87,9 @@ export type {
   CkConversationProps,
   CkFeedbackButtonProps,
   CkFeedbackValue,
+  CkFileEntry,
+  CkFileItemsListEmits,
+  CkFileItemsListProps,
   CkHistoryEmits,
   CkHistoryItemEmits,
   CkHistoryItemProps,