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

package/src/modules/documents/widgets/injection/related-documents/LinkDocumentDialog.tsx

@@ -0,0 +1,224 @@
+"use client"
+
+import * as React from 'react'
+import { Link2, Search } from 'lucide-react'
+import { apiCall, apiCallOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
+import { flash } from '@open-mercato/ui/backend/FlashMessages'
+import { ErrorMessage, LoadingMessage } from '@open-mercato/ui/backend/detail'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { Dialog, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogTitle } from '@open-mercato/ui/primitives/dialog'
+import { Input } from '@open-mercato/ui/primitives/input'
+import { Label } from '@open-mercato/ui/primitives/label'
+import { useDialogKeyHandler } from '@open-mercato/ui/hooks/useDialogKeyHandler'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { readNumber, readRecord } from '../../../backend/documents/documentUi'
+import { normalizeDocuments, type DocumentRow } from '../../../backend/documents/documentsListTypes'
+import type { RelatedDocumentContext } from './context'
+import { OPTIONAL_HEADERS } from './useRelatedDocuments'
+
+const SEARCH_PAGE_SIZE = 20
+const MAX_SEARCH_PAGES = 5
+
+function buildSearchContext(open: boolean, target: RelatedDocumentContext, query: string): string {
+  return JSON.stringify([open, target.entityType, target.entityId, query.trim()])
+}
+
+async function loadEditableDocuments(
+  search: string,
+  signal: AbortSignal,
+  unknownOwner: string,
+): Promise<{ ok: boolean; rows: DocumentRow[] }> {
+  const editable: DocumentRow[] = []
+  for (let page = 1; page <= MAX_SEARCH_PAGES; page += 1) {
+    const params = new URLSearchParams({ search, page: String(page), pageSize: String(SEARCH_PAGE_SIZE) })
+    const call = await apiCall<unknown>(
+      `/api/documents?${params.toString()}`,
+      { headers: OPTIONAL_HEADERS, signal },
+      { fallback: { items: [] } },
+    )
+    if (!call.ok) return { ok: false, rows: [] }
+    const pageRows = normalizeDocuments(call.result, [], unknownOwner)
+    editable.push(...pageRows.filter((row) => row.capabilities.canEdit))
+    if (editable.length > 0 || pageRows.length === 0) break
+    const totalPages = readNumber(readRecord(call.result) ?? {}, 'totalPages', 'total_pages') ?? page
+    if (page >= totalPages) break
+  }
+  return { ok: true, rows: editable }
+}
+
+export function LinkDocumentDialog({ open, target, onOpenChange, onLinked }: {
+  open: boolean
+  target: RelatedDocumentContext
+  onOpenChange: (open: boolean) => void
+  onLinked: () => void
+}) {
+  const t = useT()
+  const inputId = React.useId()
+  const request = React.useRef(0)
+  const activeRequest = React.useRef<AbortController | null>(null)
+  const activeSearchContext = React.useRef('')
+  const resultSearchContext = React.useRef<string | null>(null)
+  const [query, setQuery] = React.useState('')
+  const [rows, setRows] = React.useState<DocumentRow[]>([])
+  const [loading, setLoading] = React.useState(false)
+  const [errorSearchContext, setErrorSearchContext] = React.useState<string | null>(null)
+  const [retryToken, setRetryToken] = React.useState(0)
+  const [activeRowId, setActiveRowId] = React.useState<string | null>(null)
+  const currentSearchContext = buildSearchContext(open, target, query)
+  activeSearchContext.current = currentSearchContext
+  const mutationContextId = `documents-related-widget:${target.entityType}:${target.entityId}`
+  const { runMutation, retryLastMutation } = useGuardedMutation<{
+    formId: string; resourceKind: string; resourceId: string; retryLastMutation: () => Promise<boolean>
+  }>({ contextId: mutationContextId, blockedMessage: t('ui.forms.flash.saveBlocked') })
+
+  const invalidateSearch = React.useCallback(() => {
+    request.current += 1
+    activeRequest.current?.abort()
+    activeRequest.current = null
+    resultSearchContext.current = null
+    setRows([])
+    setActiveRowId(null)
+    setLoading(false)
+    setErrorSearchContext(null)
+  }, [])
+
+  const changeQuery = React.useCallback((nextQuery: string) => {
+    activeSearchContext.current = buildSearchContext(open, target, nextQuery)
+    invalidateSearch()
+    setQuery(nextQuery)
+  }, [invalidateSearch, open, target.entityId, target.entityType, target.href, target.label])
+
+  const handleOpenChange = React.useCallback((nextOpen: boolean) => {
+    if (!nextOpen) {
+      activeSearchContext.current = buildSearchContext(false, target, '')
+      invalidateSearch()
+      setQuery('')
+    }
+    onOpenChange(nextOpen)
+  }, [invalidateSearch, onOpenChange, target.entityId, target.entityType, target.href, target.label])
+
+  React.useEffect(() => {
+    invalidateSearch()
+    if (!open) { setQuery(''); return }
+    const search = query.trim()
+    if (!search) return
+    const timer = window.setTimeout(() => {
+      const requestId = ++request.current
+      const requestContext = buildSearchContext(true, target, search)
+      const controller = new AbortController()
+      activeRequest.current?.abort()
+      activeRequest.current = controller
+      resultSearchContext.current = null
+      setRows([])
+      setLoading(true)
+      setErrorSearchContext(null)
+      void loadEditableDocuments(search, controller.signal, t('documents.list.unknownOwner'))
+        .then((result) => {
+          if (request.current !== requestId || activeSearchContext.current !== requestContext) return
+          resultSearchContext.current = requestContext
+          if (!result.ok) {
+            setRows([])
+            setActiveRowId(null)
+            setErrorSearchContext(requestContext)
+            return
+          }
+          setRows(result.rows)
+          setActiveRowId(result.rows[0]?.id ?? null)
+        })
+        .catch(() => {
+          if (!controller.signal.aborted && request.current === requestId && activeSearchContext.current === requestContext) {
+            resultSearchContext.current = requestContext
+            setRows([])
+            setActiveRowId(null)
+            setErrorSearchContext(requestContext)
+          }
+        })
+        .finally(() => {
+          if (request.current === requestId) {
+            if (activeRequest.current === controller) activeRequest.current = null
+            setLoading(false)
+          }
+        })
+    }, 250)
+    return () => window.clearTimeout(timer)
+  }, [invalidateSearch, open, query, retryToken, t, target.entityId, target.entityType, target.href, target.label])
+
+  React.useEffect(() => () => { activeRequest.current?.abort() }, [])
+
+  const linkDocument = React.useCallback(async (row: DocumentRow) => {
+    if (resultSearchContext.current === null || resultSearchContext.current !== activeSearchContext.current) return
+    try {
+      await runMutation({
+        operation: () => apiCallOrThrow(
+          `/api/documents/${encodeURIComponent(row.id)}/links`,
+          {
+            method: 'POST', headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ entityType: target.entityType, entityId: target.entityId, label: target.label, href: target.href, source: 'related-panel' }),
+          },
+          { errorMessage: t('documents.relatedDocuments.error.link') },
+        ),
+        context: { formId: mutationContextId, resourceKind: 'documents.document_entity_link', resourceId: row.id, retryLastMutation },
+        mutationPayload: { documentId: row.id, entityType: target.entityType },
+      })
+      flash(t('documents.relatedDocuments.success.link'), 'success')
+      handleOpenChange(false)
+      onLinked()
+    } catch (error) { flash(error instanceof Error ? error.message : t('documents.relatedDocuments.error.link'), 'error') }
+  }, [handleOpenChange, mutationContextId, onLinked, retryLastMutation, runMutation, t, target.entityId, target.entityType, target.href, target.label])
+
+  const hasCurrentResults = resultSearchContext.current !== null && resultSearchContext.current === currentSearchContext
+  const hasCurrentError = errorSearchContext !== null && errorSearchContext === currentSearchContext
+  const visibleRows = hasCurrentResults ? rows : []
+  const retrySearch = React.useCallback(() => {
+    if (!open || !query.trim()) return
+    invalidateSearch()
+    setRetryToken((token) => token + 1)
+  }, [invalidateSearch, open, query])
+  const confirmActiveRow = React.useCallback(() => {
+    const row = visibleRows.find((candidate) => candidate.id === activeRowId) ?? visibleRows[0]
+    if (row) void linkDocument(row)
+  }, [activeRowId, linkDocument, visibleRows])
+  const dialogKeyDown = useDialogKeyHandler({
+    onConfirm: confirmActiveRow,
+    onCancel: () => handleOpenChange(false),
+    disabled: loading || visibleRows.length === 0,
+  })
+  const handleDialogKeyDown = React.useCallback((event: React.KeyboardEvent) => {
+    dialogKeyDown(event)
+    if (event.defaultPrevented || visibleRows.length === 0) return
+    if (event.key !== 'ArrowDown' && event.key !== 'ArrowUp') return
+    event.preventDefault()
+    const currentIndex = visibleRows.findIndex((row) => row.id === activeRowId)
+    const offset = event.key === 'ArrowDown' ? 1 : -1
+    const nextIndex = currentIndex < 0
+      ? 0
+      : (currentIndex + offset + visibleRows.length) % visibleRows.length
+    setActiveRowId(visibleRows[nextIndex]?.id ?? null)
+  }, [activeRowId, dialogKeyDown, visibleRows])
+
+  return (
+    <Dialog open={open} onOpenChange={handleOpenChange}>
+      <DialogContent size="lg" onKeyDown={handleDialogKeyDown}>
+        <DialogHeader><DialogTitle>{t('documents.relatedDocuments.linkDialog.title')}</DialogTitle><DialogDescription>{t('documents.relatedDocuments.linkDialog.description')}</DialogDescription></DialogHeader>
+        <div className="space-y-3">
+          <div className="space-y-2"><Label htmlFor={inputId}>{t('documents.relatedDocuments.linkDialog.searchLabel')}</Label><Input id={inputId} value={query} onChange={(event) => changeQuery(event.target.value)} leftIcon={<Search />} placeholder={t('documents.relatedDocuments.linkDialog.searchPlaceholder')} /></div>
+          {loading ? <LoadingMessage label={t('documents.relatedDocuments.loading')} /> : null}
+          {!loading && hasCurrentError ? (
+            <ErrorMessage
+              label={t('documents.relatedDocuments.linkDialog.error')}
+              action={<Button type="button" size="sm" variant="outline" onClick={retrySearch}>{t('documents.actions.retry')}</Button>}
+            />
+          ) : null}
+          {!loading && !hasCurrentError && query.trim() && hasCurrentResults && visibleRows.length === 0 ? <p className="rounded-md border border-border bg-muted/20 p-3 text-sm text-muted-foreground">{t('documents.relatedDocuments.linkDialog.empty')}</p> : null}
+          {!loading && visibleRows.length > 0 ? <div className="max-h-72 space-y-2 overflow-y-auto">{visibleRows.map((row) => (
+            <Button key={row.id} type="button" variant={activeRowId === row.id ? 'secondary' : 'outline'} aria-current={activeRowId === row.id ? 'true' : undefined} className="h-auto w-full justify-between p-3 text-left" onFocus={() => setActiveRowId(row.id)} onClick={() => { void linkDocument(row) }}>
+              <span className="min-w-0"><span className="block truncate font-medium">{row.title}</span><span className="block truncate text-xs text-muted-foreground">{row.ownerLabel}</span></span><Link2 />
+            </Button>
+          ))}</div> : null}
+        </div>
+        <DialogFooter><Button type="button" variant="outline" onClick={() => handleOpenChange(false)}>{t('documents.actions.cancel')}</Button></DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}

package/src/modules/documents/widgets/injection/related-documents/context.ts

@@ -0,0 +1,101 @@
+import { getEntityRegistryEntry, type DocumentEntityType } from '../../../lib/entityRegistry'
+import { sanitizeDocumentsDisplayLabel } from '../../../lib/displayLabels'
+import type { CollectionCapabilities } from '../../../backend/documents/documentsListTypes'
+
+export type RelatedDocumentContext = {
+  entityType: DocumentEntityType
+  entityId: string
+  label: string | null
+  href: string
+  values: Record<string, string>
+}
+
+function record(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : null
+}
+
+function text(value: Record<string, unknown> | null, ...keys: string[]): string | null {
+  if (!value) return null
+  for (const key of keys) {
+    const candidate = value[key]
+    if (typeof candidate === 'string' && candidate.trim()) return candidate.trim()
+  }
+  return null
+}
+
+function displayText(value: Record<string, unknown> | null, ...keys: string[]): string | null {
+  if (!value) return null
+  for (const key of keys) {
+    const candidate = sanitizeDocumentsDisplayLabel(value[key])
+    if (candidate) return candidate
+  }
+  return null
+}
+
+function nested(value: Record<string, unknown> | null, key: string): Record<string, unknown> | null {
+  return value ? record(value[key]) : null
+}
+
+function contextType(context: Record<string, unknown>): DocumentEntityType | null {
+  const resourceKind = text(context, 'resourceKind', 'resource_kind')
+  if (resourceKind === 'customers.person') return 'customer-person'
+  if (resourceKind === 'customers.company') return 'customer-company'
+  if (resourceKind === 'customers.deal') return 'deal'
+  if (resourceKind === 'catalog.product') return 'product'
+  const kind = text(context, 'kind')
+  if (kind === 'quote') return 'quote'
+  if (kind === 'order') return 'sales-order'
+  return null
+}
+
+function contextItem(type: DocumentEntityType, data: Record<string, unknown> | null): Record<string, unknown> | null {
+  return nested(data, type === 'customer-person' ? 'person' : type === 'customer-company' ? 'company' : type === 'deal' ? 'deal' : 'record') ?? data
+}
+
+function contextLabel(type: DocumentEntityType, item: Record<string, unknown> | null): string | null {
+  if (type === 'customer-person') {
+    const direct = displayText(item, 'displayName', 'display_name', 'name', 'fullName', 'full_name', 'email')
+    if (direct) return direct
+    const parts = [displayText(item, 'firstName', 'first_name'), displayText(item, 'lastName', 'last_name')].filter(Boolean)
+    return sanitizeDocumentsDisplayLabel(parts.length ? parts.join(' ') : null)
+  }
+  if (type === 'customer-company') return displayText(item, 'displayName', 'display_name', 'name', 'legalName', 'legal_name', 'email')
+  if (type === 'deal' || type === 'product') return displayText(item, 'title', 'name')
+  if (type === 'quote') return displayText(item, 'quoteNumber', 'quote_number', 'number', 'title')
+  if (type === 'sales-order') return displayText(item, 'orderNumber', 'order_number', 'number', 'title')
+  return null
+}
+
+export function resolveRelatedDocumentContext(contextValue: unknown, dataValue?: unknown): RelatedDocumentContext | null {
+  const context = record(contextValue)
+  if (!context) return null
+  const type = contextType(context)
+  if (!type) return null
+  const hostRecord = record(context.record)
+  const data = record(dataValue) ?? record(context.data) ?? hostRecord
+  const explicitContextId = text(context, 'resourceId', 'resource_id', 'recordId', 'record_id')
+  const entityId = explicitContextId ?? text(hostRecord, 'id') ?? text(data, 'id')
+  // Some edit hosts keep the id outside their form values, so CrudForm's generic
+  // operation heuristic still reports "create" while version history supplies a
+  // stable resource id. Treat that explicit host identity as authoritative, but
+  // keep genuine create forms (which have no context id) hidden.
+  if (text(context, 'operation') === 'create' && !explicitContextId) return null
+  if (!entityId) return null
+  const entry = getEntityRegistryEntry(type)
+  if (!entry) return null
+  const item = contextItem(type, data)
+  const label = contextLabel(type, item)
+  const href = entry.resolveHref({ id: entityId, label: label ?? '' })
+  const values = Object.fromEntries(entry.tokenFields.flatMap((field) => {
+    const value = item ? field.extract(item) : null
+    return value === null ? [] : [[field.field, value]]
+  }))
+  return href ? { entityType: type, entityId, label, href, values } : null
+}
+
+export function resolveRelatedDocumentActions(capabilities: CollectionCapabilities, disabled: boolean) {
+  return {
+    canLink: !disabled && capabilities.canLinkDocuments,
+    canCreate: !disabled && capabilities.canInstantiateTemplate,
+  }
+}

package/src/modules/documents/widgets/injection/related-documents/useRelatedDocuments.ts

@@ -0,0 +1,112 @@
+"use client"
+
+import * as React from 'react'
+import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import {
+  EMPTY_COLLECTION_CAPABILITIES,
+  normalizeCollectionCapabilities,
+  normalizeDocuments,
+  type CollectionCapabilities,
+  type DocumentRow,
+} from '../../../backend/documents/documentsListTypes'
+import type { RelatedDocumentContext } from './context'
+
+type State = {
+  context: string | null
+  status: 'loading' | 'ready' | 'error' | 'hidden'
+  items: DocumentRow[]
+  capabilities: CollectionCapabilities
+}
+
+const OPTIONAL_HEADERS = {
+  'x-om-forbidden-redirect': '0',
+  'x-om-unauthorized-redirect': '0',
+}
+
+function buildTargetContext(target: RelatedDocumentContext | null): string | null {
+  return target ? JSON.stringify([target.entityType, target.entityId]) : null
+}
+
+function emptyState(context: string | null, status: State['status']): State {
+  return { context, status, items: [], capabilities: EMPTY_COLLECTION_CAPABILITIES }
+}
+
+export function useRelatedDocuments(target: RelatedDocumentContext | null) {
+  const t = useT()
+  const request = React.useRef(0)
+  const activeRequest = React.useRef<AbortController | null>(null)
+  const targetContext = buildTargetContext(target)
+  const activeContext = React.useRef<string | null>(targetContext)
+  activeContext.current = targetContext
+  const [state, setState] = React.useState<State>(() => emptyState(targetContext, target ? 'loading' : 'hidden'))
+  const [reload, setReload] = React.useState(0)
+
+  React.useEffect(() => {
+    activeRequest.current?.abort()
+    activeRequest.current = null
+    if (!target || !targetContext) {
+      request.current += 1
+      setState(emptyState(null, 'hidden'))
+      return
+    }
+    const requestId = ++request.current
+    const requestContext = targetContext
+    const controller = new AbortController()
+    activeRequest.current = controller
+    const params = new URLSearchParams({
+      entityType: target.entityType,
+      entityId: target.entityId,
+      page: '1',
+      pageSize: '10',
+    })
+    setState(emptyState(requestContext, 'loading'))
+    void apiCall<unknown>(
+      `/api/documents?${params.toString()}`,
+      { headers: OPTIONAL_HEADERS, signal: controller.signal },
+      { fallback: { items: [] } },
+    ).then((call) => {
+      if (request.current !== requestId || activeContext.current !== requestContext) return
+      if (call.status === 401 || call.status === 403 || call.status === 404) {
+        setState(emptyState(requestContext, 'hidden'))
+        return
+      }
+      if (!call.ok) { setState(emptyState(requestContext, 'error')); return }
+      setState({
+        context: requestContext,
+        status: 'ready',
+        items: normalizeDocuments(call.result, [], t('documents.list.unknownOwner')),
+        capabilities: normalizeCollectionCapabilities(call.result),
+      })
+    }).catch(() => {
+      if (!controller.signal.aborted && request.current === requestId && activeContext.current === requestContext) {
+        setState(emptyState(requestContext, 'error'))
+      }
+    }).finally(() => {
+      if (activeRequest.current === controller) activeRequest.current = null
+    })
+    return () => {
+      request.current += 1
+      controller.abort()
+      if (activeRequest.current === controller) activeRequest.current = null
+    }
+  }, [reload, t, targetContext])
+
+  React.useEffect(() => () => { activeRequest.current?.abort() }, [])
+
+  const visibleState = state.context === targetContext
+    ? state
+    : emptyState(targetContext, targetContext ? 'loading' : 'hidden')
+
+  const retry = React.useCallback(() => {
+    request.current += 1
+    activeRequest.current?.abort()
+    activeRequest.current = null
+    setState(emptyState(targetContext, targetContext ? 'loading' : 'hidden'))
+    setReload((value) => value + 1)
+  }, [targetContext])
+
+  return { ...visibleState, retry }
+}
+
+export { OPTIONAL_HEADERS }

package/src/modules/documents/widgets/injection/related-documents/widget.client.tsx

@@ -0,0 +1,76 @@
+"use client"
+
+import * as React from 'react'
+import dynamic from 'next/dynamic'
+import Link from 'next/link'
+import { ExternalLink, FilePlus2, Link2 } from 'lucide-react'
+import type { InjectionWidgetComponentProps } from '@open-mercato/shared/modules/widgets/injection'
+import { LoadingMessage, ErrorMessage } from '@open-mercato/ui/backend/detail'
+import { SectionHeader } from '@open-mercato/ui/backend/SectionHeader'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { LinkButton } from '@open-mercato/ui/primitives/link-button'
+import { EmptyState } from '@open-mercato/ui/primitives/empty-state'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { formatDateTime } from '../../../backend/documents/documentUi'
+import { LinkDocumentDialog } from './LinkDocumentDialog'
+import { resolveRelatedDocumentActions, resolveRelatedDocumentContext } from './context'
+import { useRelatedDocuments } from './useRelatedDocuments'
+
+function NewFromTemplateDialogLoading({ error, retry }: { error?: Error | null; retry?: () => void }) {
+  const t = useT()
+  if (error) {
+    return (
+      <ErrorMessage
+        label={t('documents.templates.instantiate.error.load')}
+        action={<Button type="button" size="sm" variant="outline" onClick={retry}>{t('documents.actions.retry')}</Button>}
+      />
+    )
+  }
+  return (
+    <div role="status" aria-live="polite">
+      <LoadingMessage label={t('documents.templates.instantiate.loading')} />
+    </div>
+  )
+}
+
+const NewFromTemplateDialog = dynamic(
+  () => import('../../../backend/documents/components/NewFromTemplateDialog').then((module) => module.NewFromTemplateDialog),
+  { ssr: false, loading: NewFromTemplateDialogLoading },
+)
+
+export default function RelatedDocumentsWidget({ context, data, disabled }: InjectionWidgetComponentProps<Record<string, unknown>, Record<string, unknown>>) {
+  const t = useT()
+  const target = React.useMemo(() => resolveRelatedDocumentContext(context, data), [context, data])
+  const related = useRelatedDocuments(target)
+  const [linkOpen, setLinkOpen] = React.useState(false)
+  const [createOpen, setCreateOpen] = React.useState(false)
+  if (!target || related.status === 'hidden') return null
+  const label = target.label ?? t('documents.relatedDocuments.recordFallback')
+  const actions = resolveRelatedDocumentActions(related.capabilities, Boolean(disabled))
+
+  return (
+    <section className="rounded-lg border border-border bg-card p-4">
+      <SectionHeader
+        title={t('documents.relatedDocuments.title')}
+        count={related.items.length}
+        action={actions.canLink || actions.canCreate ? <>
+          {actions.canLink ? <Button type="button" size="sm" variant="outline" onClick={() => setLinkOpen(true)}><Link2 />{t('documents.relatedDocuments.actions.link')}</Button> : null}
+          {actions.canCreate ? <Button type="button" size="sm" onClick={() => setCreateOpen(true)}><FilePlus2 />{t('documents.relatedDocuments.actions.create')}</Button> : null}
+        </> : undefined}
+      />
+      <div className="mt-4">
+        {related.status === 'loading' ? <LoadingMessage label={t('documents.relatedDocuments.loading')} /> : null}
+        {related.status === 'error' ? <ErrorMessage label={t('documents.relatedDocuments.error.load')} action={<Button type="button" size="sm" variant="outline" onClick={related.retry}>{t('documents.actions.retry')}</Button>} /> : null}
+        {related.status === 'ready' && related.items.length === 0 ? <EmptyState size="sm" variant="subtle" title={t('documents.relatedDocuments.empty')} icon={<Link2 className="size-5" />} /> : null}
+        {related.status === 'ready' && related.items.length > 0 ? <div className="space-y-2">{related.items.map((row) => (
+          <div key={row.id} className="flex flex-wrap items-center justify-between gap-3 rounded-md border border-border p-3">
+            <div className="min-w-0"><Link className="block truncate text-sm font-medium hover:underline focus-visible:underline focus-visible:outline-none" href={`/backend/documents/${row.id}`}>{row.title}</Link><p className="truncate text-xs text-muted-foreground">{t('documents.relatedDocuments.meta', { owner: row.ownerLabel, updated: formatDateTime(row.updatedAt, t('documents.relatedDocuments.unknownDate')) })}</p></div>
+            <LinkButton asChild size="sm" variant="gray"><Link href={`/backend/documents/${row.id}`}><ExternalLink />{t('documents.actions.open')}</Link></LinkButton>
+          </div>
+        ))}</div> : null}
+      </div>
+      {actions.canLink && linkOpen ? <LinkDocumentDialog open target={{ ...target, label }} onOpenChange={setLinkOpen} onLinked={related.retry} /> : null}
+      {actions.canCreate && createOpen ? <NewFromTemplateDialog open onOpenChange={setCreateOpen} presetContext={{ entityType: target.entityType, entityId: target.entityId, label, values: target.values }} /> : null}
+    </section>
+  )
+}

package/src/modules/documents/widgets/injection/related-documents/widget.ts

@@ -0,0 +1,19 @@
+import dynamic from 'next/dynamic'
+import type { InjectionWidgetModule } from '@open-mercato/shared/modules/widgets/injection'
+
+const RelatedDocumentsWidget = dynamic(() => import('./widget.client'))
+
+const widget: InjectionWidgetModule<Record<string, unknown>, Record<string, unknown>> = {
+  metadata: {
+    id: 'documents.injection.related-documents',
+    title: 'Related documents',
+    description: 'Lists and creates documents related to the current record.',
+    features: ['documents.view'],
+    requiredModules: ['documents'],
+    priority: 80,
+    enabled: true,
+  },
+  Widget: RelatedDocumentsWidget,
+}
+
+export default widget

package/src/modules/documents/widgets/injection-table.ts

@@ -0,0 +1,20 @@
+import type { ModuleInjectionTable } from '@open-mercato/shared/modules/widgets/injection'
+
+const relatedDocuments = {
+  widgetId: 'documents.injection.related-documents',
+  kind: 'stack' as const,
+  priority: 80,
+}
+
+export const injectionTable: ModuleInjectionTable = {
+  'detail:customers.person:footer': [relatedDocuments],
+  'customers.person.detail:details': [relatedDocuments],
+  'detail:customers.company:footer': [relatedDocuments],
+  'customers.company.detail:details': [relatedDocuments],
+  'detail:customers.deal:footer': [relatedDocuments],
+  'sales.document.detail.quote:details': [relatedDocuments],
+  'sales.document.detail.order:details': [relatedDocuments],
+  'crud-form:catalog.product': [relatedDocuments],
+}
+
+export default injectionTable

package/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json.schemastore.org/tsconfig",
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "noEmit": true
+  },
+  "include": ["src/**/*", "server/**/*"],
+  "exclude": ["node_modules", "dist", "**/__tests__/**"]
+}

package/watch.mjs

@@ -0,0 +1,6 @@
+import { watch } from '../../scripts/watch.mjs'
+import { dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+watch(__dirname)