@qoretechnologies/reqraft 0.10.20 → 0.10.26

package/src/components/supportTicket/meta.ts

@@ -0,0 +1,185 @@
+import { TReqoreIntent } from '@qoretechnologies/reqore/dist/constants/theme';
+import { IReqoreIconName } from '@qoretechnologies/reqore/dist/types/icons';
+
+/*
+ * The single source of truth for the Qorus support-ticket presentation
+ * vocabulary — how each status / priority / category / audit-action value
+ * renders (label + Reqore intent + icon), plus the interface-kind icon map and
+ * the small enum helpers. Shared by every Qorus surface that shows a ticket
+ * (the qorus-ide customer view, the admin-portal staff queue, the Qonsole
+ * renderer) so the chips read identically everywhere and can't drift apart.
+ */
+
+export type TTicketStatus = 'new' | 'open' | 'awaiting_customer' | 'resolved' | 'closed';
+export type TTicketPriority = 'low' | 'normal' | 'high' | 'urgent';
+export type TTicketCategory = 'bug' | 'question' | 'billing' | 'feature' | 'other';
+export type TTicketAuditAction = 'replied' | 'noted' | 'status_changed' | 'assigned' | 'updated';
+
+/** A message author. Staff identities are masked from the customer by the backend. */
+export type TTicketMessageAuthor = 'customer' | 'staff' | 'system';
+
+/** Which side "you" sit on — decides self-alignment and audience-specific labels. */
+export type TTicketViewerRole = 'customer' | 'staff';
+
+export interface ITicketEnumMeta {
+  label: string;
+  intent: TReqoreIntent;
+  icon: IReqoreIconName;
+  /** Audience-specific label for the customer view; falls back to `label` (the
+   *  staff / neutral wording). Only a few values differ by audience. */
+  customerLabel?: string;
+}
+
+export const TICKET_STATUS_META: Record<TTicketStatus, ITicketEnumMeta> = {
+  new: { label: 'New', intent: 'info', icon: 'SparklingLine' },
+  open: { label: 'Open', intent: 'pending', icon: 'Chat3Line' },
+  awaiting_customer: {
+    label: 'Awaiting customer',
+    customerLabel: 'Awaiting your reply',
+    intent: 'warning',
+    icon: 'UserReceivedLine',
+  },
+  resolved: { label: 'Resolved', intent: 'success', icon: 'CheckLine' },
+  closed: { label: 'Closed', intent: 'muted', icon: 'CloseCircleLine' },
+};
+
+export const TICKET_PRIORITY_META: Record<TTicketPriority, ITicketEnumMeta> = {
+  low: { label: 'Low', intent: 'muted', icon: 'ArrowDownLine' },
+  normal: { label: 'Normal', intent: 'info', icon: 'SubtractLine' },
+  high: { label: 'High', intent: 'warning', icon: 'ArrowUpLine' },
+  urgent: { label: 'Urgent', intent: 'danger', icon: 'AlarmWarningLine' },
+};
+
+export const TICKET_CATEGORY_META: Record<TTicketCategory, ITicketEnumMeta> = {
+  bug: { label: 'Bug', intent: 'danger', icon: 'BugLine' },
+  question: { label: 'Question', intent: 'info', icon: 'QuestionLine' },
+  billing: { label: 'Billing', intent: 'warning', icon: 'BankCardLine' },
+  feature: { label: 'Feature request', intent: 'success', icon: 'LightbulbLine' },
+  other: { label: 'Other', intent: 'muted', icon: 'MoreLine' },
+};
+
+/** Staff-only audit trail vocabulary (used by the admin-portal staff surface).
+ *  These are exactly the actions the backend writes (qorus-api
+ *  `QorusSaasTicketStore::insertAudit`): a public reply, an internal note, a
+ *  status change, an assignment, or `updated` (a priority/category change). */
+export const TICKET_AUDIT_ACTION_META: Record<TTicketAuditAction, ITicketEnumMeta> = {
+  replied: { label: 'Replied', intent: 'success', icon: 'ReplyLine' },
+  noted: { label: 'Internal note', intent: 'info', icon: 'StickyNoteLine' },
+  status_changed: { label: 'Status changed', intent: 'warning', icon: 'ExchangeLine' },
+  assigned: { label: 'Assigned', intent: 'pending', icon: 'UserFollowLine' },
+  updated: { label: 'Updated', intent: 'muted', icon: 'Edit2Line' },
+};
+
+/** The status label for a given viewer — the customer sees "Awaiting your reply"
+ *  where staff see "Awaiting customer"; all other values are audience-neutral. */
+export const ticketStatusLabel = (
+  status: TTicketStatus,
+  viewerRole?: TTicketViewerRole
+): string => {
+  const meta = TICKET_STATUS_META[status];
+  return viewerRole === 'customer' && meta.customerLabel ? meta.customerLabel : meta.label;
+};
+
+/** A reply may be sent while a ticket is in any state except `closed`. */
+export const REPLYABLE_STATUSES: TTicketStatus[] = [
+  'new',
+  'open',
+  'awaiting_customer',
+  'resolved',
+];
+
+/** Whether a ticket can still be replied to (closed ⇒ no). */
+export const isTicketReplyable = (status: TTicketStatus): boolean => status !== 'closed';
+
+/** A file to upload with a ticket or reply — raw bytes as base64, inline on the
+ *  create/reply payload (the SaaS plane has no separate multipart upload). */
+export interface IAttachmentUpload {
+  filename: string;
+  content_type: string;
+  /** base64-encoded file content */
+  content: string;
+}
+
+/** A reference to a Qorus interface on the subscriber's instance, stored as a
+ *  `{kind, name}` snapshot (the interface itself lives on the instance, not the
+ *  SaaS plane). Attaches to a ticket (at creation) or a message (in a reply). */
+export interface IInterfaceReference {
+  /** interface type: workflow / service / job / fsm / qog / connection / ... */
+  interface_kind: string;
+  /** interface name (may include a version) */
+  interface_name: string;
+  /** server-assigned reference UUID (present on read, absent when submitting) */
+  reference_id?: string;
+  /** For an app-triggered interface (a qog): the triggering app's name. A viewer
+   *  with the app catalogue (the customer's IDE) resolves it to the app's logo the
+   *  same way the qogs list does — see `resolveInterfaceImage` on the tags. */
+  trigger_app?: string;
+  /** A pre-resolved logo/image (data-URI or URL) for the chip, e.g. the trigger
+   *  app's logo. Travels with the reference so a viewer without the app catalogue
+   *  (staff triage, the Qonsole card) still shows it. */
+  logo?: string;
+}
+
+// Built-in per-kind icons for referenced interfaces, kept in step with the
+// qorus-ide interface vocabulary. Used when a consumer doesn't pass its own
+// `resolveInterfaceIcon`, so the staff view and the Qonsole renderer show the
+// same chips as the customer view without each re-declaring the mapping.
+const DEFAULT_INTERFACE_ICONS: Record<string, IReqoreIconName> = {
+  workflow: 'GitBranchLine',
+  service: 'ServerLine',
+  job: 'CalendarLine',
+  fsm: 'DashboardLine',
+  // qog fallback glyph (used only when there's no trigger-app logo to show)
+  qog: 'FlowChart',
+  connection: 'Plug2Line',
+  mapper: 'MindMap',
+  class: 'CodeSLine',
+  'value-map': 'BringToFront',
+  'ai-collection': 'FileMarkedLine',
+  'ai-endpoint': 'RobotLine',
+  'ai-guardrail': 'ShieldLine',
+};
+
+/** Default per-kind icon for a referenced interface, with a generic fallback. */
+export const defaultInterfaceIcon = (kind: string): IReqoreIconName =>
+  DEFAULT_INTERFACE_ICONS[kind] ?? 'CodeBoxLine';
+
+// The reading name for each interface kind. The kind id (`value-map`, `ai-collection`)
+// is a wire value — it's what a host fetches with and what gets stored on the reference
+// — so it must never be what the user reads. These are plural because they name a
+// category the user picks from, not a single interface. `fsm` maps to "Qogs" like every
+// other user-facing surface; the id stays `fsm` wherever a host still uses it.
+const DEFAULT_INTERFACE_KIND_LABELS: Record<string, string> = {
+  workflow: 'Workflows',
+  service: 'Services',
+  job: 'Jobs',
+  fsm: 'Qogs',
+  qog: 'Qogs',
+  connection: 'Connections',
+  mapper: 'Mappers',
+  class: 'Classes',
+  'value-map': 'Value maps',
+  'ai-collection': 'AI collections',
+  'ai-endpoint': 'AI endpoints',
+  'ai-guardrail': 'AI guardrails',
+};
+
+/**
+ * Default reading name for an interface kind — "Value maps" for `value-map`. An
+ * unknown kind is humanised generically (separators to spaces, sentence case, a
+ * plural `s`) so a kind this map hasn't caught up with still reads as a word
+ * rather than an identifier. Consumers with their own vocabulary override the
+ * whole thing via the picker's `resolveKindLabel`.
+ */
+export const defaultInterfaceKindLabel = (kind: string): string => {
+  const known = DEFAULT_INTERFACE_KIND_LABELS[kind];
+
+  if (known) {
+    return known;
+  }
+
+  const words = kind.replace(/[-_]+/g, ' ').trim();
+  const sentenceCase = words.charAt(0).toUpperCase() + words.slice(1);
+
+  return sentenceCase.endsWith('s') ? sentenceCase : `${sentenceCase}s`;
+};

package/src/components/supportTicket/ticketModel.ts

@@ -0,0 +1,131 @@
+import type { IInterfaceReference, TTicketCategory, TTicketMessageAuthor, TTicketPriority, TTicketStatus } from './meta';
+
+/*
+ * The support-ticket wire model, shared by every surface that speaks it.
+ *
+ * These shapes mirror the `SupportTicket` / `SupportMessage` schemas served by
+ * the SaaS plane — `/qorus-saas/support/*` for the customer (qorus-api
+ * `QorusSaasSupportRestClass`) and `/qorus-saas-admin/support/*` for staff
+ * (`QorusSaasAdminRestHandler`). Both planes serve the SAME ticket row; the
+ * staff plane simply projects more of it.
+ *
+ * They live here because they were previously declared twice — once in
+ * qorus-ide's `views/support/types.ts` and once in admin-portal's
+ * `types/supportTickets.ts` — and had already started to drift. The enum
+ * vocabularies (`meta.ts`) were shared from the start; the record shapes that
+ * carry them were not, which is the wrong way round: a field added to the wire
+ * schema had to be remembered in two repos, and nothing failed if it wasn't.
+ *
+ * The split below is deliberate. `ITicket` is what BOTH planes return;
+ * `IStaffTicket` is the extra projection only the admin plane serves.
+ * That keeps "customer must never see the assignee" a property of the type
+ * rather than a convention, while still giving one place to add a field.
+ */
+
+/** Attachment metadata as embedded in a message (no content). */
+export interface ITicketAttachment {
+  attachment_id: string;
+  filename: string;
+  content_type: string;
+  size_bytes: number;
+}
+
+/**
+ * Attachment metadata from the ticket-level list endpoint.
+ *
+ * Richer than the per-message copy: it carries the provenance the embedded
+ * metadata omits — who uploaded the file, when, and which reply it came from
+ * (null for a file attached when the ticket was filed). A staff uploader arrives
+ * already masked by the server, so this never exposes a real staff identity.
+ */
+export interface ITicketAttachmentDetail extends ITicketAttachment {
+  message_id?: string | null;
+  uploaded_by?: string;
+  uploader_type?: 'customer' | 'staff';
+  created?: string;
+}
+
+/** One message in a ticket thread. */
+export interface ITicketMessage {
+  message_id: string;
+  ticket_id: string;
+  author_type: TTicketMessageAuthor;
+  /** author identity; staff identities are masked from the customer */
+  author_id: string;
+  /** message body (markdown) */
+  body: string;
+  /** staff-only internal note — never present in the customer thread */
+  internal: boolean;
+  created: string;
+  /** files attached to this message */
+  attachments?: ITicketAttachment[];
+  /** interfaces referenced in this message, as `{kind, name}` snapshots */
+  referenced_interfaces?: IInterfaceReference[];
+}
+
+/**
+ * One support ticket, in the projection BOTH planes serve.
+ *
+ * Staff-only fields are not optional-here-required-there; they live in
+ * `IStaffTicket` so a customer surface cannot read them by accident.
+ */
+export interface ITicket {
+  /** external ticket UUID, used in URLs */
+  ticket_id: string;
+  /** human-visible ticket number */
+  ticket_number: number;
+  subject: string;
+  /** initial description (markdown) */
+  description: string;
+  status: TTicketStatus;
+  priority: TTicketPriority;
+  category: TTicketCategory;
+  subscription_code: string;
+  /** account name (email) of the filer */
+  created_by: string;
+  /** parent ticket UUID, when this continues a closed ticket */
+  parent_ticket_id?: string;
+  /** first staff-reply timestamp */
+  first_response_at?: string;
+  resolved_at?: string;
+  closed_at?: string;
+  /** most-recent-message timestamp */
+  last_message_at: string;
+  created: string;
+  modified?: string;
+  /** interfaces this ticket references (ticket-level), as `{kind, name}` snapshots */
+  referenced_interfaces?: IInterfaceReference[];
+}
+
+/** The extra projection the admin plane adds on top of {@link ITicket}. */
+export interface IStaffTicket extends ITicket {
+  /** owner scope key (staff view) */
+  scope_key: string;
+  /** organization / account */
+  scope_type: string;
+  account_id: number;
+  groupid?: number;
+  /** the staff assignee */
+  assignee?: string;
+}
+
+/** The offset pagination every support list endpoint returns. */
+export interface ITicketPagedResult {
+  limit: number;
+  offset: number;
+}
+
+/**
+ * A ticket-list response. Generic over the ticket projection so the staff plane
+ * gets `IStaffTicket[]` without redeclaring the envelope; each plane extends this
+ * with the scope fields it actually serves.
+ */
+export interface ITicketListResult<T extends ITicket = ITicket> extends ITicketPagedResult {
+  tickets: T[];
+}
+
+/** A message-list response for one ticket. */
+export interface ITicketMessageListResult extends ITicketPagedResult {
+  ticket_id: string;
+  messages: ITicketMessage[];
+}

package/src/components/ticketReferences/TicketReferences.stories.tsx

@@ -0,0 +1,315 @@
+import { StoryObj } from '@storybook/react-vite';
+import { expect, fn, userEvent, waitFor, within } from 'storybook/test';
+
+import { StoryMeta } from '../../types';
+import { IInterfaceReference } from '../supportTicket/meta';
+import { ITicketReferenceAttachment, TicketReferences } from './TicketReferences';
+
+const NOW = Date.parse('2026-06-30T12:00:00Z');
+const ago = (mins: number) => new Date(NOW - mins * 60_000).toISOString();
+
+// The stories stand in for the authed blob-download endpoint by handing back an
+// inline SVG data-URI per image id, so thumbnails + the lightbox render offline.
+const svgUrl = (label: string, color: string) =>
+  `data:image/svg+xml;utf8,${encodeURIComponent(
+    `<svg xmlns="http://www.w3.org/2000/svg" width="640" height="400">` +
+      `<rect width="640" height="400" fill="${color}"/>` +
+      `<text x="320" y="215" font-size="30" fill="#ffffff" text-anchor="middle" ` +
+      `font-family="sans-serif">${label}</text></svg>`
+  )}`;
+
+const REFERENCES: IInterfaceReference[] = [
+  { interface_kind: 'workflow', interface_name: 'order-sync:1.0', reference_id: 'r1' },
+  { interface_kind: 'workflow', interface_name: 'invoice-sync:2.3', reference_id: 'r2' },
+  { interface_kind: 'service', interface_name: 'datasource-pool:2.3', reference_id: 'r3' },
+  { interface_kind: 'job', interface_name: 'nightly-reconcile', reference_id: 'r4' },
+  { interface_kind: 'connection', interface_name: 'pg-main-ro', reference_id: 'r5' },
+];
+
+// Uploaders come already resolved from the endpoint: customer uploads carry the
+// account, a staff reply's attachment reads "Qorus Support" on the customer plane.
+const ATTACHMENTS: ITicketReferenceAttachment[] = [
+  { attachment_id: 'img-1', filename: 'error-screenshot.png', content_type: 'image/png', size_bytes: 148_221, uploaded_by: 'acme-prod', uploader_type: 'customer', created: ago(180), message_id: 'm1' },
+  { attachment_id: 'img-2', filename: 'pool-metrics.png', content_type: 'image/png', size_bytes: 96_540, uploaded_by: 'Qorus Support', uploader_type: 'staff', created: ago(120), message_id: 'm2' },
+  { attachment_id: 'img-3', filename: 'stack-trace.png', content_type: 'image/png', size_bytes: 210_004, uploaded_by: 'acme-prod', uploader_type: 'customer', created: ago(60), message_id: 'm3' },
+  { attachment_id: 'file-1', filename: 'nightly-trace.log', content_type: 'text/x-log', size_bytes: 219_136, uploaded_by: 'acme-prod', uploader_type: 'customer', created: ago(180), message_id: 'm1' },
+  { attachment_id: 'file-2', filename: 'incident-report.pdf', content_type: 'application/pdf', size_bytes: 512_900, uploaded_by: 'Qorus Support', uploader_type: 'staff', created: ago(90), message_id: 'm2' },
+  { attachment_id: 'file-3', filename: 'pool-config.yaml', content_type: 'application/yaml', size_bytes: 2_048, uploaded_by: 'acme-prod', uploader_type: 'customer', created: ago(90) },
+  { attachment_id: 'file-4', filename: 'diagnostics.zip', content_type: 'application/zip', size_bytes: 3_400_000, uploaded_by: 'acme-prod', uploader_type: 'customer', created: ago(30), message_id: 'm3' },
+];
+
+const IMG_URLS: Record<string, string> = {
+  'img-1': svgUrl('error-screenshot', '#7b3fe4'),
+  'img-2': svgUrl('pool-metrics', '#2872a0'),
+  'img-3': svgUrl('stack-trace', '#b23c3c'),
+};
+const fetchAttachmentUrl = (id: string) => Promise.resolve(IMG_URLS[id] ?? svgUrl(id, '#555555'));
+
+const meta = {
+  component: TicketReferences,
+  title: 'Components/TicketReferences',
+  parameters: { layout: 'padded' },
+  args: {
+    references: REFERENCES,
+    attachments: ATTACHMENTS,
+    viewerRole: 'staff',
+    onDownloadAttachment: fn(),
+    fetchAttachmentUrl,
+  },
+} satisfies StoryMeta<typeof TicketReferences>;
+
+export default meta;
+type Story = StoryObj<typeof meta>;
+
+/** A busy ticket: 5 grouped interface references, 3 screenshots, 4 files, and the
+ *  search / type-filter / sort strip a ticket this full earns. */
+export const Populated: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders a busy ticket with five grouped interface references, three screenshots, and four files — full enough to surface the search box, type-filter, and sort strip.',
+      },
+    },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText('Linked interfaces')).toBeInTheDocument();
+    await expect(canvas.getByText('Screenshots')).toBeInTheDocument();
+    await expect(canvas.getByText('Files')).toBeInTheDocument();
+    // references render as rows carrying their kind as metadata
+    await expect(canvasElement.textContent).toContain('workflow');
+    await expect(canvasElement.textContent).toContain('order-sync:1.0');
+    // a file row with provenance (staff view shows uploaders as stored)
+    await expect(canvas.getByText('incident-report.pdf')).toBeInTheDocument();
+    await expect(canvasElement.textContent).toContain('added by acme-prod');
+    // the control strip: search box + the type-filter and sort dropdowns
+    await expect(
+      canvas.getByPlaceholderText('Search files and references…')
+    ).toBeInTheDocument();
+    await expect(canvas.getByText('All types')).toBeInTheDocument();
+    await expect(canvas.getByText('Newest first')).toBeInTheDocument();
+    // thumbnails resolve to images
+    await waitFor(() =>
+      expect(
+        canvasElement.querySelector('button[title="error-screenshot.png"] img')
+      ).not.toBeNull()
+    );
+  },
+};
+
+/** The control strip in action: search narrows to matches, a no-match query offers
+ *  "Clear filters", and the type filter collapses the view to one family. */
+export const Filtering: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Renders the control strip in action — searching narrows to matching files and references, a no-match query offers 'Clear filters', and the type filter collapses the view to a single family.",
+      },
+    },
+  },
+  play: async ({ canvasElement }) => {
+    const canvas = within(canvasElement);
+    const box = canvas.getByPlaceholderText('Search files and references…');
+
+    // search narrows across both files and screenshots by filename
+    await userEvent.type(box, 'pool');
+    await waitFor(() => {
+      // "pool-*" survive, "error-screenshot"/"nightly-trace" fall away
+      expect(canvas.getByText('pool-config.yaml')).toBeInTheDocument();
+      expect(canvasElement.querySelector('button[title="pool-metrics.png"]')).not.toBeNull();
+      expect(canvasElement.querySelector('button[title="error-screenshot.png"]')).toBeNull();
+      expect(canvas.queryByText('nightly-trace.log')).toBeNull();
+    });
+
+    // a query that matches nothing surfaces the empty state + a clear affordance
+    await userEvent.clear(box);
+    await userEvent.type(box, 'zzz-no-such-file');
+    await waitFor(() =>
+      expect(canvasElement.textContent).toContain('No matching references or files')
+    );
+    await userEvent.click(canvas.getByText('Clear filters'));
+    await waitFor(() => expect(canvas.getByText('Files')).toBeInTheDocument());
+
+    // the type filter collapses to a single family (Screenshots only)
+    await userEvent.click(canvas.getByText('All types'));
+    await userEvent.click(await within(document.body).findByText(/^Screenshots \(3\)$/));
+    await waitFor(() => {
+      expect(canvas.queryByText('Files')).toBeNull();
+      expect(canvas.queryByText('Linked interfaces')).toBeNull();
+      expect(canvasElement.querySelector('button[title="stack-trace.png"]')).not.toBeNull();
+    });
+  },
+};
+
+/** Clicking a loaded screenshot opens the paging lightbox (portalled to body). */
+export const LightboxOpens: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the references view and, when a loaded screenshot is clicked, opens the paging lightbox portalled to the body.',
+      },
+    },
+  },
+  play: async ({ canvasElement }) => {
+    const thumb = await waitFor(() => {
+      const el = canvasElement.querySelector<HTMLButtonElement>(
+        'button[title="error-screenshot.png"]'
+      );
+      if (!el || !el.querySelector('img')) {
+        throw new Error('thumbnail not ready');
+      }
+      return el;
+    });
+    await userEvent.click(thumb);
+    // error-screenshot is the oldest of the three, so under the default
+    // newest-first sort it sits last — the counter reads "3 / 3".
+    await waitFor(() => expect(document.body.textContent).toContain('3 / 3'));
+  },
+};
+
+/** The same ticket from the customer's side: their own uploads read "you", and a
+ *  staff reply's attachment reads "Qorus Support" — never the raw staff identity. */
+export const CustomerView: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Renders the same ticket from the customer's side, where their own uploads read 'added by you' and a staff reply's attachment reads 'Qorus Support' rather than the raw staff identity.",
+      },
+    },
+  },
+  args: { viewerRole: 'customer' },
+  play: async ({ canvasElement }) => {
+    await waitFor(() => expect(canvasElement.textContent).toContain('added by you'));
+    await expect(canvasElement.textContent).toContain('added by Qorus Support');
+  },
+};
+
+/** Without a fetcher, screenshots degrade to download tiles rather than thumbnails. */
+export const NoPreview: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Renders the references view with no fetchAttachmentUrl, so screenshots degrade to download tiles rather than thumbnails.',
+      },
+    },
+  },
+  args: { fetchAttachmentUrl: undefined },
+  play: async ({ canvasElement }) => {
+    // No fetcher ⇒ the tile body falls through to the filename fallback. The caption
+    // always shows the filename, so the discriminating checks are: no thumbnail image,
+    // and no forever-pending "…" in the tile body (the qlip-caught regression).
+    const tile = await waitFor(() => {
+      const el = canvasElement.querySelector<HTMLElement>('button[title="error-screenshot.png"]');
+      if (!el) {
+        throw new Error('screenshot tile not rendered');
+      }
+      return el;
+    });
+    await expect(tile.querySelector('img')).toBeNull();
+    await expect(tile.textContent).not.toContain('…');
+  },
+};
+
+/** Nothing attached or linked. */
+export const Empty: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Renders the empty state with nothing attached or linked, showing 'No references or files yet'.",
+      },
+    },
+  },
+  args: { references: [], attachments: [], messages: [] },
+  play: async ({ canvasElement }) => {
+    await expect(canvasElement.textContent).toContain('No references or files yet');
+  },
+};
+
+/**
+ * With `onShowInChat` wired, a row that came from a reply gains a "three dots" menu
+ * offering to reveal it in the conversation.
+ *
+ * A row filed against the ticket itself carries the same menu, but its reveal is
+ * disabled and labelled "Filed on the ticket" — there's no message to jump to. That
+ * distinction between a reply-borne row and a ticket-level one is the thing to see here.
+ */
+export const ShowInChat: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Renders references with onShowInChat wired — a reply-borne row's menu offers an active 'Show in chat' that calls onShowInChat, while a ticket-level row carries the same menu with its reveal disabled ('Filed on the ticket').",
+      },
+    },
+  },
+  args: {
+    messages: [
+      {
+        message_id: 'm-42',
+        author_type: 'customer',
+        author_id: 'acme-prod',
+        body: 'Same failure on the reconcile job.',
+        created: ago(30),
+        referenced_interfaces: [{ interface_kind: 'job', interface_name: 'nightly-reconcile' }],
+      },
+    ],
+    onShowInChat: fn(),
+  },
+  play: async ({ args, canvasElement }) => {
+    const canvas = within(canvasElement);
+    await expect(canvas.getByText('nightly-reconcile')).toBeInTheDocument();
+
+    const rowFor = (label: string) =>
+      Array.from(canvasElement.querySelectorAll<HTMLElement>('.reqore-entity-row')).find((row) =>
+        row.textContent?.includes(label)
+      );
+
+    // the reply-borne reference offers the menu...
+    const fromReply = rowFor('nightly-reconcile');
+    const menuButton = fromReply?.querySelector<HTMLElement>(
+      '.reqore-entity-row-actions .reqore-button:last-child'
+    );
+    await userEvent.click(menuButton!);
+    const item = await waitFor(() => {
+      const found = Array.from(document.querySelectorAll<HTMLElement>('.reqore-menu-item')).find(
+        (el) => /Show in chat/.test(el.textContent || '')
+      );
+      if (!found) {
+        throw new Error('Show in chat not offered');
+      }
+      return found;
+    });
+    await userEvent.click(item);
+    await expect(args.onShowInChat).toHaveBeenCalledWith('m-42');
+
+    // ...and a ticket-level reference carries the SAME menu, so the rows don't look
+    // half-broken — but the reveal is disabled there, because it was filed on the
+    // ticket and has no message to jump to.
+    const ticketLevel = rowFor('order-sync:1.0');
+    const ticketMenu = ticketLevel?.querySelector<HTMLElement>(
+      '.reqore-entity-row-actions .reqore-button:last-child'
+    );
+    await expect(ticketMenu).toBeTruthy();
+    await userEvent.click(ticketMenu!);
+    const ticketEntry = await waitFor(() => {
+      const entry = Array.from(document.querySelectorAll<HTMLElement>('.reqore-menu-item')).find(
+        (el) => /Show in chat/.test(el.textContent || '')
+      );
+      if (!entry) {
+        throw new Error('the menu should still offer the entry, disabled');
+      }
+      return entry;
+    });
+    // it is genuinely unclickable, not merely styled as such — and the handler stays
+    // on its single call from the reply-borne row above
+    await expect(getComputedStyle(ticketEntry).pointerEvents).toBe('none');
+    await expect(ticketEntry.textContent).toContain('Filed on the ticket');
+    await expect(args.onShowInChat).toHaveBeenCalledTimes(1);
+  },
+};