@open-mercato/documents 0.6.8-develop.7016.1.4ed7b1e49d

package/src/modules/documents/api/templates/route.ts

@@ -0,0 +1,370 @@
+import { NextResponse } from 'next/server'
+import { z } from 'zod'
+import { randomUUID } from 'node:crypto'
+import type { FilterQuery } from '@mikro-orm/core'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { enforceCommandOptimisticLockWithGuards } from '@open-mercato/shared/lib/crud/optimistic-lock-command'
+import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { escapeLikePattern } from '@open-mercato/shared/lib/db/escapeLikePattern'
+import { DocumentTemplate } from '../../data/entities'
+import {
+  documentTemplateContextSlotSchema,
+  documentTemplateCreateSchema,
+  documentTemplateUpdateSchema,
+} from '../../data/validators'
+import { DOCUMENTS_ENTITY_IDS } from '../../lib/constants'
+import { DOCUMENTS_JSON_BODY_LIMITS } from '../../lib/requestBody'
+import type {
+  TemplateCommandResult,
+  TemplateCreateCommandInput,
+  TemplateDeleteCommandInput,
+  TemplateUpdateCommandInput,
+} from '../../commands/templates'
+import {
+  attachDocumentsOperationMetadata,
+  buildDocumentsCommandRuntimeContext,
+  resolveDocumentsCommandBus,
+} from '../_commands'
+import {
+  handleDocumentsRouteError,
+  hasDocumentsFeature,
+  readBody,
+  resolveActorUserId,
+  resolveDocumentsContext,
+  routeErrorSchema,
+  runMutationGuardAfterSuccess,
+  validateMutationGuard,
+  withDocumentsContextErrors,
+} from '../_shared'
+
+const listQuerySchema = z.object({
+  search: z.string().trim().optional(),
+  isActive: z.enum(['true', 'false']).transform((value) => value === 'true').optional(),
+  includeBody: z.enum(['true', 'false']).transform((value) => value === 'true').optional(),
+  page: z.coerce.number().int().min(1).optional(),
+  pageSize: z.coerce.number().int().min(1).max(100).optional(),
+}).refine((query) => (query.page === undefined) === (query.pageSize === undefined), {
+  message: 'page and pageSize must be provided together',
+})
+
+const DEFAULT_TEMPLATE_PAGE = 1
+const DEFAULT_TEMPLATE_PAGE_SIZE = 50
+const TEMPLATE_SUMMARY_FIELDS = [
+  'id',
+  'name',
+  'description',
+  'contextSlots',
+  'isActive',
+  'updatedAt',
+  'createdAt',
+] as const
+
+const templateDeleteSchema = z.object({
+  id: z.string().uuid(),
+})
+
+const templateItemSchema = z.object({
+  id: z.string().uuid(),
+  name: z.string(),
+  description: z.string().nullable(),
+  bodyHtml: z.string(),
+  contextSlots: z.array(documentTemplateContextSlotSchema).nullable(),
+  isActive: z.boolean(),
+  updatedAt: z.string(),
+  createdAt: z.string(),
+})
+
+const templateListResponseSchema = z.object({
+  items: z.array(templateItemSchema.omit({ bodyHtml: true }).extend({ bodyHtml: z.string().optional() })),
+  total: z.number(),
+  capabilities: z.object({ canManageTemplates: z.boolean() }),
+  page: z.number(),
+  pageSize: z.number(),
+  totalPages: z.number(),
+})
+
+const mutationResponseSchema = z.object({
+  id: z.string().uuid(),
+  updatedAt: z.string(),
+})
+
+const deleteResponseSchema = z.object({
+  ok: z.boolean(),
+  id: z.string().uuid(),
+  updatedAt: z.string(),
+})
+
+export const metadata = {
+  GET: { requireAuth: true, requireFeatures: ['documents.view'] },
+  POST: { requireAuth: true, requireFeatures: ['documents.templates.manage'] },
+  PUT: { requireAuth: true, requireFeatures: ['documents.templates.manage'] },
+  DELETE: { requireAuth: true, requireFeatures: ['documents.templates.manage'] },
+}
+
+function serializeTemplate(template: DocumentTemplate, includeBody = true): Record<string, unknown> {
+  return {
+    id: template.id,
+    name: template.name,
+    description: template.description ?? null,
+    ...(includeBody ? { bodyHtml: template.bodyHtml } : {}),
+    contextSlots: template.contextSlots ?? null,
+    isActive: template.isActive,
+    updatedAt: template.updatedAt.toISOString(),
+    createdAt: template.createdAt.toISOString(),
+  }
+}
+
+async function loadScopedTemplate(
+  ctx: Awaited<ReturnType<typeof resolveDocumentsContext>>,
+  id: string,
+): Promise<DocumentTemplate> {
+  const template = await findOneWithDecryption(
+    ctx.em,
+    DocumentTemplate,
+    {
+      id,
+      tenantId: ctx.tenantId,
+      organizationId: ctx.organizationId,
+      deletedAt: null,
+    },
+    undefined,
+    { tenantId: ctx.tenantId, organizationId: ctx.organizationId },
+  )
+  if (!template) throw new CrudHttpError(404, { error: 'documents.templates.notFound' })
+  return template
+}
+
+export async function GET(request: Request): Promise<Response> {
+  try {
+    const ctx = await resolveDocumentsContext(request, ['documents.view'])
+    const url = new URL(request.url)
+    const query = listQuerySchema.parse(Object.fromEntries(url.searchParams.entries()))
+    const page = query.page ?? DEFAULT_TEMPLATE_PAGE
+    const pageSize = query.pageSize ?? DEFAULT_TEMPLATE_PAGE_SIZE
+    // Template bodies are manageable-only. A view-only caller never receives
+    // bodyHtml, even when it asks for it; instantiation/slot flows request
+    // includeBody=false and are unaffected.
+    const canManageTemplates = hasDocumentsFeature(ctx.auth, 'documents.templates.manage')
+    const includeBody = (query.includeBody ?? true) && canManageTemplates
+    const where: FilterQuery<DocumentTemplate> = {
+      tenantId: ctx.tenantId,
+      organizationId: ctx.organizationId,
+      deletedAt: null,
+      ...(query.search ? {
+        $or: [
+          { name: { $ilike: `%${escapeLikePattern(query.search)}%` } },
+          { description: { $ilike: `%${escapeLikePattern(query.search)}%` } },
+        ],
+      } : {}),
+      ...(query.isActive !== undefined ? { isActive: query.isActive } : {}),
+    }
+    const [templates, total] = await Promise.all([
+      findWithDecryption(
+        ctx.em,
+        DocumentTemplate,
+        where,
+        {
+          orderBy: { name: 'ASC', id: 'ASC' },
+          limit: pageSize,
+          offset: (page - 1) * pageSize,
+          ...(includeBody ? {} : { fields: TEMPLATE_SUMMARY_FIELDS }),
+        },
+        { tenantId: ctx.tenantId, organizationId: ctx.organizationId },
+      ),
+      ctx.em.count(DocumentTemplate, where),
+    ])
+    return NextResponse.json({
+      items: templates.map((template) => serializeTemplate(template, includeBody)),
+      total,
+      capabilities: {
+        canManageTemplates,
+      },
+      page,
+      pageSize,
+      totalPages: Math.max(1, Math.ceil(total / pageSize)),
+    })
+  } catch (error) {
+    return handleDocumentsRouteError(error, 'documents.templates.list')
+  }
+}
+
+export async function POST(request: Request): Promise<Response> {
+  try {
+    const ctx = await resolveDocumentsContext(request, ['documents.templates.manage'])
+    const input = documentTemplateCreateSchema.parse(await readBody(
+      request,
+      DOCUMENTS_JSON_BODY_LIMITS.template,
+    ))
+    const guardResult = await validateMutationGuard(ctx, {
+      resourceKind: DOCUMENTS_ENTITY_IDS.documentTemplate,
+      resourceId: 'new',
+      operation: 'create',
+      mutationPayload: input,
+      mutationPayloadSchema: documentTemplateCreateSchema,
+    })
+
+    const commandInput: TemplateCreateCommandInput = {
+      tenantId: ctx.tenantId,
+      organizationId: ctx.organizationId,
+      templateId: randomUUID(),
+      actorUserId: resolveActorUserId(ctx.auth),
+      template: input,
+    }
+    const execution = await resolveDocumentsCommandBus(ctx).execute<TemplateCreateCommandInput, TemplateCommandResult>(
+      'documents.template.create',
+      { input: commandInput, ctx: buildDocumentsCommandRuntimeContext(ctx) },
+    )
+    await runMutationGuardAfterSuccess(ctx, guardResult, {
+      resourceKind: DOCUMENTS_ENTITY_IDS.documentTemplate,
+      resourceId: 'new',
+      operation: 'create',
+    })
+
+    return attachDocumentsOperationMetadata(
+      NextResponse.json({ id: execution.result.id, updatedAt: execution.result.updatedAt }, { status: 201 }),
+      execution.logEntry,
+      { resourceKind: DOCUMENTS_ENTITY_IDS.documentTemplate, resourceId: execution.result.id },
+    )
+  } catch (error) {
+    return handleDocumentsRouteError(error, 'documents.templates.create')
+  }
+}
+
+export async function PUT(request: Request): Promise<Response> {
+  try {
+    const ctx = await resolveDocumentsContext(request, ['documents.templates.manage'])
+    const input = documentTemplateUpdateSchema.parse(await readBody(
+      request,
+      DOCUMENTS_JSON_BODY_LIMITS.template,
+    ))
+    const template = await loadScopedTemplate(ctx, input.id)
+    await enforceCommandOptimisticLockWithGuards(ctx.container, {
+      resourceKind: DOCUMENTS_ENTITY_IDS.documentTemplate,
+      resourceId: template.id,
+      current: template.updatedAt,
+      request,
+    })
+    const guardResult = await validateMutationGuard(ctx, {
+      resourceKind: DOCUMENTS_ENTITY_IDS.documentTemplate,
+      resourceId: template.id,
+      operation: 'update',
+      mutationPayload: input,
+      mutationPayloadSchema: documentTemplateUpdateSchema,
+    })
+
+    const commandInput: TemplateUpdateCommandInput = {
+      tenantId: ctx.tenantId,
+      organizationId: ctx.organizationId,
+      actorUserId: resolveActorUserId(ctx.auth),
+      expectedUpdatedAt: template.updatedAt.toISOString(),
+      template: input,
+    }
+    const execution = await resolveDocumentsCommandBus(ctx).execute<TemplateUpdateCommandInput, TemplateCommandResult>(
+      'documents.template.update',
+      { input: commandInput, ctx: buildDocumentsCommandRuntimeContext(ctx) },
+    )
+    await runMutationGuardAfterSuccess(ctx, guardResult, {
+      resourceKind: DOCUMENTS_ENTITY_IDS.documentTemplate,
+      resourceId: template.id,
+      operation: 'update',
+    })
+
+    return attachDocumentsOperationMetadata(
+      NextResponse.json({ id: execution.result.id, updatedAt: execution.result.updatedAt }),
+      execution.logEntry,
+      { resourceKind: DOCUMENTS_ENTITY_IDS.documentTemplate, resourceId: execution.result.id },
+    )
+  } catch (error) {
+    return handleDocumentsRouteError(error, 'documents.templates.update')
+  }
+}
+
+export async function DELETE(request: Request): Promise<Response> {
+  try {
+    const ctx = await resolveDocumentsContext(request, ['documents.templates.manage'])
+    const input = templateDeleteSchema.parse(await readBody(request))
+    const template = await loadScopedTemplate(ctx, input.id)
+    await enforceCommandOptimisticLockWithGuards(ctx.container, {
+      resourceKind: DOCUMENTS_ENTITY_IDS.documentTemplate,
+      resourceId: template.id,
+      current: template.updatedAt,
+      request,
+    })
+    const guardResult = await validateMutationGuard(ctx, {
+      resourceKind: DOCUMENTS_ENTITY_IDS.documentTemplate,
+      resourceId: template.id,
+      operation: 'delete',
+    })
+
+    const commandInput: TemplateDeleteCommandInput = {
+      tenantId: ctx.tenantId,
+      organizationId: ctx.organizationId,
+      templateId: template.id,
+      actorUserId: resolveActorUserId(ctx.auth),
+      expectedUpdatedAt: template.updatedAt.toISOString(),
+    }
+    const execution = await resolveDocumentsCommandBus(ctx).execute<TemplateDeleteCommandInput, TemplateCommandResult>(
+      'documents.template.delete',
+      { input: commandInput, ctx: buildDocumentsCommandRuntimeContext(ctx) },
+    )
+    await runMutationGuardAfterSuccess(ctx, guardResult, {
+      resourceKind: DOCUMENTS_ENTITY_IDS.documentTemplate,
+      resourceId: template.id,
+      operation: 'delete',
+    })
+
+    return attachDocumentsOperationMetadata(
+      NextResponse.json({ ok: true, id: execution.result.id, updatedAt: execution.result.updatedAt }),
+      execution.logEntry,
+      { resourceKind: DOCUMENTS_ENTITY_IDS.documentTemplate, resourceId: execution.result.id },
+    )
+  } catch (error) {
+    return handleDocumentsRouteError(error, 'documents.templates.delete')
+  }
+}
+
+export const openApi: OpenApiRouteDoc = withDocumentsContextErrors({
+  tag: 'Documents',
+  summary: 'Document templates',
+  methods: {
+    GET: {
+      summary: 'List document templates',
+      query: listQuerySchema,
+      responses: [{ status: 200, description: 'Template list', schema: templateListResponseSchema }],
+      errors: [
+        { status: 401, description: 'Unauthorized', schema: routeErrorSchema },
+        { status: 403, description: 'Forbidden', schema: routeErrorSchema },
+      ],
+    },
+    POST: {
+      summary: 'Create document template',
+      requestBody: { contentType: 'application/json', schema: documentTemplateCreateSchema },
+      responses: [{ status: 201, description: 'Template created', schema: mutationResponseSchema }],
+      errors: [
+        { status: 400, description: 'Validation failed', schema: routeErrorSchema },
+        { status: 413, description: 'Request body exceeds the safe resource bound', schema: routeErrorSchema },
+      ],
+    },
+    PUT: {
+      summary: 'Update document template',
+      requestBody: { contentType: 'application/json', schema: documentTemplateUpdateSchema },
+      responses: [{ status: 200, description: 'Template updated', schema: mutationResponseSchema }],
+      errors: [
+        { status: 409, description: 'Optimistic lock conflict', schema: routeErrorSchema },
+        { status: 413, description: 'Request body exceeds the safe resource bound', schema: routeErrorSchema },
+      ],
+    },
+    DELETE: {
+      summary: 'Delete document template',
+      requestBody: { contentType: 'application/json', schema: templateDeleteSchema },
+      responses: [{ status: 200, description: 'Template deleted', schema: deleteResponseSchema }],
+      errors: [
+        { status: 409, description: 'Optimistic lock conflict', schema: routeErrorSchema },
+        { status: 413, description: 'Request body exceeds the safe resource bound', schema: routeErrorSchema },
+      ],
+    },
+  },
+})
+
+export default { GET, POST, PUT, DELETE }

package/src/modules/documents/backend/documents/DocumentsPageClient.tsx

@@ -0,0 +1,150 @@
+"use client"
+
+import * as React from 'react'
+import dynamic from 'next/dynamic'
+import { Page, PageBody } from '@open-mercato/ui/backend/Page'
+import { ErrorMessage, LoadingMessage } from '@open-mercato/ui/backend/detail'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { Dialog, DialogContent, DialogDescription, DialogHeader, DialogTitle } from '@open-mercato/ui/primitives/dialog'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { ShareDialog } from './components/ShareDialog'
+import { DocumentsTable } from './DocumentsTable'
+import { FolderDialog, type FolderDialogState } from './FolderDialog'
+import { FolderTree } from './FolderTree'
+import { MoveDocumentDialog } from './MoveDocumentDialog'
+import type { DocumentRow } from './documentsListTypes'
+import { useDocumentsList } from './useDocumentsList'
+
+function NewFromTemplateDialogLoading({ error, retry }: { error?: Error | null; retry?: () => void }) {
+  const t = useT()
+  // `next/dynamic` never forwards the caller's `onOpenChange` to a loading
+  // shell, so own the dismissal here. Without it a chunk that fails for good
+  // (a deploy invalidated it) traps the user in a modal Escape cannot close.
+  const [open, setOpen] = React.useState(true)
+  if (!open) return null
+  return (
+    <Dialog open onOpenChange={(next) => { if (!next) setOpen(false) }}>
+      <DialogContent size="xl" dismissible={Boolean(error)}>
+        <DialogHeader>
+          <DialogTitle>{t('documents.templates.instantiate.title')}</DialogTitle>
+          <DialogDescription>{t('documents.templates.instantiate.description')}</DialogDescription>
+        </DialogHeader>
+        {error ? (
+          <ErrorMessage
+            label={t('documents.templates.instantiate.error.load')}
+            action={<Button type="button" size="sm" variant="outline" onClick={retry}>{t('documents.actions.retry')}</Button>}
+          />
+        ) : (
+          <div role="status" aria-live="polite"><LoadingMessage label={t('documents.templates.instantiate.loading')} /></div>
+        )}
+      </DialogContent>
+    </Dialog>
+  )
+}
+
+const NewFromTemplateDialog = dynamic(
+  () => import('./components/NewFromTemplateDialog').then((module) => module.NewFromTemplateDialog),
+  { ssr: false, loading: NewFromTemplateDialogLoading },
+)
+
+export function DocumentsPageClient() {
+  const t = useT()
+  const documents = useDocumentsList()
+  const [shareDocument, setShareDocument] = React.useState<DocumentRow | null>(null)
+  const [templateDialogOpen, setTemplateDialogOpen] = React.useState(false)
+  const [folderDialog, setFolderDialog] = React.useState<FolderDialogState | null>(null)
+  const [moveDocument, setMoveDocument] = React.useState<DocumentRow | null>(null)
+  const selectedFolder = documents.selectedFolderId
+    ? documents.folders.find((folder) => folder.id === documents.selectedFolderId) ?? null
+    : null
+  const destinationWritable = documents.selectedFolderId === null || selectedFolder?.canEdit === true
+  const canCreateDocument = documents.collectionCapabilities.canCreateDocument && destinationWritable
+  const canInstantiateTemplate = documents.collectionCapabilities.canInstantiateTemplate && destinationWritable
+
+  return (
+    <Page>
+      <PageBody>
+        {documents.loadError ? (
+          <ErrorMessage
+            label={documents.loadError}
+            action={<Button type="button" size="sm" variant="outline" onClick={documents.refresh}>{t('documents.actions.retry')}</Button>}
+          />
+        ) : (
+          <div className="grid gap-4 lg:grid-cols-4">
+          <FolderTree
+            folders={documents.folders}
+            selectedFolderId={documents.selectedFolderId}
+            onSelect={(folderId) => { documents.setSelectedFolderId(folderId); documents.setPage(1) }}
+            onCreate={(parentFolderId) => setFolderDialog({ mode: 'create', parentFolderId })}
+            onRename={(folder) => setFolderDialog({ mode: 'rename', folder })}
+            onDelete={(folder) => void documents.deleteFolder(folder)}
+            canCreateFolder={documents.collectionCapabilities.canCreateFolder}
+          />
+          <div className="min-w-0 lg:col-span-3">
+            <DocumentsTable
+              title={selectedFolder?.name ?? t('documents.list.title')}
+              rows={documents.rows}
+              isLoading={documents.isLoading}
+              isCreating={documents.isCreating}
+              search={documents.search}
+              page={documents.page}
+              pageSize={documents.pageSize}
+              total={documents.total}
+              totalPages={documents.totalPages}
+              hasTemplates={documents.hasTemplates}
+              canCreateDocument={canCreateDocument}
+              canInstantiateTemplate={canInstantiateTemplate}
+              canManageTemplates={documents.collectionCapabilities.canManageTemplates}
+              onSearchChange={(search) => { documents.setSearch(search); documents.setPage(1) }}
+              onPageChange={documents.setPage}
+              onPageSizeChange={(pageSize) => { documents.setPageSize(pageSize); documents.setPage(1) }}
+              onRefresh={documents.refresh}
+              onCreate={() => void documents.createDocument()}
+              onNewFromTemplate={() => setTemplateDialogOpen(true)}
+              onShare={setShareDocument}
+              onMove={setMoveDocument}
+              onDelete={(row) => void documents.deleteDocument(row)}
+              archivedFilter={documents.archivedFilter}
+              favoritesOnly={documents.favoritesOnly}
+              onArchivedFilterChange={documents.setArchivedFilter}
+              onFavoritesOnlyChange={documents.setFavoritesOnly}
+              onToggleFavorite={(row) => void documents.toggleFavorite(row)}
+              onDuplicate={(row) => void documents.duplicateDocument(row)}
+              onArchiveToggle={(row) => void documents.archiveToggle(row)}
+            />
+          </div>
+          </div>
+        )}
+        <FolderDialog
+          state={folderDialog}
+          onOpenChange={(open) => { if (!open) setFolderDialog(null) }}
+          onSubmit={(name) => {
+            if (!folderDialog) return false
+            return documents.saveFolder(folderDialog.mode === 'rename'
+              ? { folder: folderDialog.folder, name }
+              : { parentFolderId: folderDialog.parentFolderId, name })
+          }}
+        />
+        {shareDocument ? (
+          <ShareDialog
+            documentId={shareDocument.id}
+            open
+            onOpenChange={(open) => { if (!open) setShareDocument(null) }}
+            canManage={shareDocument.capabilities.canShare}
+          />
+        ) : null}
+        <MoveDocumentDialog
+          document={moveDocument}
+          folders={documents.folders}
+          open={moveDocument !== null}
+          onOpenChange={(open) => { if (!open) setMoveDocument(null) }}
+          onMove={documents.moveDocument}
+        />
+        {canInstantiateTemplate && templateDialogOpen ? <NewFromTemplateDialog open folderId={documents.selectedFolderId} onOpenChange={setTemplateDialogOpen} /> : null}
+        {documents.ConfirmDialogElement}
+      </PageBody>
+    </Page>
+  )
+}
+
+export default DocumentsPageClient

package/src/modules/documents/backend/documents/DocumentsTable.tsx

@@ -0,0 +1,168 @@
+"use client"
+
+import * as React from 'react'
+import Link from 'next/link'
+import { useRouter } from 'next/navigation'
+import { Star } from 'lucide-react'
+import type { LegacyColumnDef as ColumnDef } from '@tanstack/react-table/legacy'
+import { DataTable } from '@open-mercato/ui/backend/DataTable'
+import { RowActions } from '@open-mercato/ui/backend/RowActions'
+import type { RowActionItem } from '@open-mercato/ui/backend/RowActions'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { IconButton } from '@open-mercato/ui/primitives/icon-button'
+import { LinkButton } from '@open-mercato/ui/primitives/link-button'
+import { Badge } from '@open-mercato/ui/primitives/badge'
+import {
+  Select,
+  SelectContent,
+  SelectItem,
+  SelectTrigger,
+  SelectValue,
+} from '@open-mercato/ui/primitives/select'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { DOCUMENTS_ENTITY_IDS } from '../../lib/constants'
+import { formatDateTime } from './documentUi'
+import type { DocumentRow } from './documentsListTypes'
+
+export type DocumentsArchivedFilter = 'exclude' | 'include' | 'only'
+
+type DocumentsTableProps = {
+  title: string
+  rows: DocumentRow[]
+  isLoading: boolean
+  isCreating: boolean
+  search: string
+  page: number
+  pageSize: number
+  total: number
+  totalPages: number
+  hasTemplates: boolean
+  canCreateDocument: boolean
+  canInstantiateTemplate: boolean
+  canManageTemplates: boolean
+  onSearchChange: (search: string) => void
+  onPageChange: (page: number) => void
+  onPageSizeChange: (pageSize: number) => void
+  onRefresh: () => void
+  onCreate: () => void
+  onNewFromTemplate: () => void
+  onShare: (row: DocumentRow) => void
+  onMove: (row: DocumentRow) => void
+  onDelete: (row: DocumentRow) => void
+  archivedFilter: DocumentsArchivedFilter
+  favoritesOnly: boolean
+  onArchivedFilterChange: (value: DocumentsArchivedFilter) => void
+  onFavoritesOnlyChange: (value: boolean) => void
+  onToggleFavorite: (row: DocumentRow) => void
+  onDuplicate: (row: DocumentRow) => void
+  onArchiveToggle: (row: DocumentRow) => void
+}
+
+export function DocumentsTable(props: DocumentsTableProps) {
+  const t = useT()
+  const router = useRouter()
+  const columns = React.useMemo<ColumnDef<DocumentRow>[]>(() => [
+    {
+      id: 'favorite', header: '', meta: { alwaysVisible: true, maxWidth: '48px' },
+      cell: ({ row }) => (
+        <IconButton
+          type="button"
+          variant="ghost"
+          aria-pressed={row.original.isFavorite}
+          aria-label={t(row.original.isFavorite ? 'documents.actions.unfavorite' : 'documents.actions.favorite')}
+          onClick={(event) => {
+            event.stopPropagation()
+            props.onToggleFavorite(row.original)
+          }}
+        >
+          <Star className={row.original.isFavorite ? 'fill-current text-status-warning-icon' : 'text-muted-foreground'} />
+        </IconButton>
+      ),
+    },
+    {
+      accessorKey: 'title', header: t('documents.columns.title'), meta: { alwaysVisible: true, maxWidth: '260px', truncate: true },
+      cell: ({ row }) => (
+        <span className="flex items-center gap-2">
+          <Link href={`/backend/documents/${row.original.id}`} className="font-medium hover:underline">{row.original.title}</Link>
+          {row.original.archivedAt ? <Badge variant="outline">{t('documents.list.archivedBadge')}</Badge> : null}
+        </span>
+      ),
+    },
+    {
+      accessorKey: 'folderName', header: t('documents.columns.folder'), meta: { maxWidth: '180px', truncate: true },
+      cell: ({ row }) => row.original.folderName ?? <span className="text-sm text-muted-foreground">{t('documents.folders.none')}</span>,
+    },
+    { accessorKey: 'ownerLabel', header: t('documents.columns.owner'), meta: { maxWidth: '220px', truncate: true } },
+    { accessorKey: 'sharedWithCount', header: t('documents.columns.sharedWith') },
+    {
+      accessorKey: 'updatedAt', header: t('documents.columns.updatedAt'), meta: { maxWidth: '180px' },
+      cell: ({ row }) => <span className="text-sm">{formatDateTime(row.original.updatedAt, t('documents.list.noValue'))}</span>,
+    },
+  ], [t, props.onToggleFavorite])
+  // A fragment, not a nested flex box: the DataTable header owns the wrapping
+  // row, so on narrow layouts the refresh control and these buttons wrap as
+  // one group instead of a lone refresh icon above a second left-aligned row.
+  const actions = (
+    <>
+      <Button
+        type="button"
+        variant={props.favoritesOnly ? 'secondary' : 'outline'}
+        aria-pressed={props.favoritesOnly}
+        onClick={() => props.onFavoritesOnlyChange(!props.favoritesOnly)}
+      >
+        <Star />{t('documents.list.filters.favorites')}
+      </Button>
+      <Select value={props.archivedFilter} onValueChange={(value) => props.onArchivedFilterChange(value as DocumentsArchivedFilter)}>
+        <SelectTrigger className="w-36" aria-label={t('documents.list.filters.archived.label')}>
+          <SelectValue />
+        </SelectTrigger>
+        <SelectContent>
+          <SelectItem value="exclude">{t('documents.list.filters.archived.active')}</SelectItem>
+          <SelectItem value="include">{t('documents.list.filters.archived.all')}</SelectItem>
+          <SelectItem value="only">{t('documents.list.filters.archived.archivedOnly')}</SelectItem>
+        </SelectContent>
+      </Select>
+      {props.canManageTemplates ? <LinkButton asChild variant="gray"><Link href="/backend/documents/templates">{t('documents.templates.actions.manage')}</Link></LinkButton> : null}
+      {props.hasTemplates && props.canInstantiateTemplate ? <Button type="button" variant="outline" onClick={props.onNewFromTemplate}>{t('documents.templates.instantiate.title')}</Button> : null}
+      {props.canCreateDocument ? <Button type="button" onClick={props.onCreate} disabled={props.isCreating}>{t('documents.actions.create')}</Button> : null}
+    </>
+  )
+  return (
+    <DataTable<DocumentRow>
+      title={props.title}
+      actions={actions}
+      refreshButton={{ label: t('documents.actions.refresh'), onRefresh: props.onRefresh, isRefreshing: props.isLoading }}
+      columns={columns}
+      data={props.rows}
+      isLoading={props.isLoading}
+      searchValue={props.search}
+      onSearchChange={props.onSearchChange}
+      searchPlaceholder={t('documents.list.searchPlaceholder')}
+      emptyState={t('documents.list.empty')}
+      entityId={DOCUMENTS_ENTITY_IDS.document}
+      extensionTableId="documents.documents.list"
+      onRowClick={(row) => router.push(`/backend/documents/${row.id}`)}
+      rowClickActionIds={['open']}
+      stickyActionsColumn
+      pagination={{
+        page: props.page, pageSize: props.pageSize, total: props.total, totalPages: props.totalPages,
+        onPageChange: props.onPageChange, onPageSizeChange: props.onPageSizeChange,
+      }}
+      rowActions={(row) => {
+        const items: RowActionItem[] = [{ id: 'open', label: t('documents.actions.open'), onSelect: () => router.push(`/backend/documents/${row.id}`) }]
+        if (row.capabilities.canShare) items.push({ id: 'share', label: t('documents.actions.share'), onSelect: () => props.onShare(row) })
+        if (row.capabilities.canEdit) items.push({ id: 'move', label: t('documents.folders.actions.moveDocument'), onSelect: () => props.onMove(row) })
+        if (row.capabilities.canDuplicate) items.push({ id: 'duplicate', label: t('documents.actions.duplicate'), onSelect: () => props.onDuplicate(row) })
+        if (row.capabilities.canArchive) {
+          items.push({
+            id: row.archivedAt ? 'unarchive' : 'archive',
+            label: t(row.archivedAt ? 'documents.actions.unarchive' : 'documents.actions.archive'),
+            onSelect: () => props.onArchiveToggle(row),
+          })
+        }
+        if (row.capabilities.canDelete) items.push({ id: 'delete', label: t('documents.actions.delete'), destructive: true, onSelect: () => props.onDelete(row) })
+        return <RowActions items={items} />
+      }}
+    />
+  )
+}