feat(documents): AggregatedSection + useAggregatedListing

Two TanStack Query hooks fetch the entity-aggregated payload for files
and workflows; AggregatedSection renders one labelled subsection per
owner-source group with a Show all (N) button wired via the onShowAll
callback. Dumb component — parent owns the row rendering + drill-
through navigation (Task 15 composes this into EntityFolderView).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/components/documents/aggregated-section.tsx

@@ -0,0 +1,112 @@
+'use client';
+
+import { Loader2 } from 'lucide-react';
+
+import type { AggregatedGroup } from '@/hooks/use-aggregated-listing';
+
+interface AggregatedSectionProps<T> {
+  title: string;
+  icon?: React.ReactNode;
+  groups: AggregatedGroup<T>[];
+  renderRow: (item: T, group: AggregatedGroup<T>) => React.ReactNode;
+  emptyMessage?: string;
+  loading?: boolean;
+  onShowAll?: (group: AggregatedGroup<T>) => void;
+}
+
+/**
+ * Renders a Signing or Files section with one labelled subsection per
+ * owner-source group. Each group shows up to 20 rows; a `Show all (N)`
+ * link drills into the source-scoped flat list. Hidden when groups is
+ * empty.
+ */
+export function AggregatedSection<T>({
+  title,
+  icon,
+  groups,
+  renderRow,
+  emptyMessage = 'Nothing here yet.',
+  loading,
+  onShowAll,
+}: AggregatedSectionProps<T>) {
+  const total = groups.reduce((sum, g) => sum + g.total, 0);
+
+  if (loading) {
+    return (
+      <section className="rounded-md border bg-white p-3">
+        <h3 className="flex items-center gap-2 text-sm font-semibold text-foreground">
+          {icon}
+          {title}
+          <Loader2 className="ml-1 h-3.5 w-3.5 animate-spin text-muted-foreground" />
+        </h3>
+      </section>
+    );
+  }
+
+  if (groups.length === 0) {
+    return (
+      <section className="rounded-md border bg-white p-3 text-sm text-muted-foreground">
+        <h3 className="flex items-center gap-2 text-sm font-semibold text-foreground">
+          {icon}
+          {title}
+          <span className="ml-1 text-xs text-muted-foreground tabular-nums">· 0</span>
+        </h3>
+        <p className="mt-2">{emptyMessage}</p>
+      </section>
+    );
+  }
+
+  return (
+    <section className="rounded-md border bg-white">
+      <h3 className="flex items-center gap-2 border-b px-3 py-2 text-sm font-semibold text-foreground">
+        {icon}
+        {title}
+        <span className="ml-1 text-xs text-muted-foreground tabular-nums">· {total}</span>
+      </h3>
+      <div className="divide-y">
+        {groups.map((g) => (
+          <GroupBlock
+            key={`${g.source}-${g.label}`}
+            group={g}
+            renderRow={renderRow}
+            onShowAll={onShowAll}
+          />
+        ))}
+      </div>
+    </section>
+  );
+}
+
+function GroupBlock<T>({
+  group,
+  renderRow,
+  onShowAll,
+}: {
+  group: AggregatedGroup<T>;
+  renderRow: (item: T, group: AggregatedGroup<T>) => React.ReactNode;
+  onShowAll?: (group: AggregatedGroup<T>) => void;
+}) {
+  const items = (group.files ?? group.workflows ?? []) as T[];
+  return (
+    <div className="px-3 py-2">
+      <header className="mb-1 text-[0.7rem] font-medium uppercase tracking-wide text-muted-foreground">
+        {group.label}
+        <span className="ml-1.5 text-muted-foreground/70 tabular-nums">· {group.total}</span>
+      </header>
+      <ul className="space-y-1">
+        {items.map((item) => (
+          <li key={(item as { id: string }).id}>{renderRow(item, group)}</li>
+        ))}
+      </ul>
+      {group.total > items.length ? (
+        <button
+          type="button"
+          className="mt-1 text-xs text-brand hover:underline"
+          onClick={() => onShowAll?.(group)}
+        >
+          Show all ({group.total})
+        </button>
+      ) : null}
+    </div>
+  );
+}

src/hooks/use-aggregated-listing.ts

@@ -0,0 +1,63 @@
+'use client';
+
+import { useQuery } from '@tanstack/react-query';
+
+import { apiFetch } from '@/lib/api/client';
+
+export interface AggregatedFile {
+  id: string;
+  filename: string;
+  mimeType: string | null;
+  createdAt: string;
+  folderId: string | null;
+  clientId: string | null;
+  companyId: string | null;
+  yachtId: string | null;
+}
+
+export interface AggregatedWorkflow {
+  id: string;
+  title: string;
+  status: string;
+  documentType: string;
+  updatedAt: string;
+  createdAt: string;
+}
+
+export interface AggregatedGroup<T> {
+  label: string;
+  source: 'direct' | 'client' | 'company' | 'yacht';
+  files?: T[];
+  workflows?: T[];
+  total: number;
+}
+
+export function useAggregatedFiles(
+  entityType: 'client' | 'company' | 'yacht' | undefined,
+  entityId: string | undefined,
+) {
+  return useQuery<AggregatedGroup<AggregatedFile>[]>({
+    queryKey: ['files', 'aggregated', entityType, entityId],
+    queryFn: () =>
+      apiFetch<{ data: { groups: AggregatedGroup<AggregatedFile>[] } }>(
+        `/api/v1/files?entityType=${entityType}&entityId=${entityId}`,
+      ).then((r) => r.data.groups),
+    enabled: Boolean(entityType && entityId),
+    staleTime: 10_000,
+  });
+}
+
+export function useAggregatedWorkflows(
+  entityType: 'client' | 'company' | 'yacht' | undefined,
+  entityId: string | undefined,
+) {
+  return useQuery<AggregatedGroup<AggregatedWorkflow>[]>({
+    queryKey: ['documents', 'aggregated', entityType, entityId],
+    queryFn: () =>
+      apiFetch<{ data: { groups: AggregatedGroup<AggregatedWorkflow>[] } }>(
+        `/api/v1/documents?entityType=${entityType}&entityId=${entityId}`,
+      ).then((r) => r.data.groups),
+    enabled: Boolean(entityType && entityId),
+    staleTime: 10_000,
+  });
+}