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

package/src/modules/documents/backend/documents/components/ShareDialogList.tsx

@@ -0,0 +1,117 @@
+"use client"
+
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { ErrorMessage, LoadingMessage } from '@open-mercato/ui/backend/detail'
+import { Alert } from '@open-mercato/ui/primitives/alert'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@open-mercato/ui/primitives/select'
+import {
+  SHARE_PERMISSIONS,
+  readPermission,
+  type DocumentSharePermission,
+  type ShareRow,
+} from './shareDialogModel'
+
+type ShareDialogListProps = {
+  shares: ShareRow[]
+  isLoading: boolean
+  error: string | null
+  canManage: boolean
+  pendingShareIds: ReadonlySet<string>
+  onRetry?: () => void
+  onPermissionChange: (share: ShareRow, permission: DocumentSharePermission) => Promise<void>
+  onRemove: (share: ShareRow) => Promise<void>
+}
+
+export function ShareDialogList({
+  shares,
+  isLoading,
+  error,
+  canManage,
+  pendingShareIds,
+  onRetry,
+  onPermissionChange,
+  onRemove,
+}: ShareDialogListProps) {
+  const t = useT()
+
+  return (
+    <div className="space-y-4">
+      {!canManage ? (
+        <Alert status="information" size="sm">
+          {t('documents.share.dialog.readOnly')}
+        </Alert>
+      ) : null}
+
+      {isLoading ? (
+        <LoadingMessage label={t('documents.share.dialog.loading')} />
+      ) : error ? (
+        <ErrorMessage
+          label={error}
+          action={onRetry ? <Button type="button" size="sm" variant="outline" onClick={onRetry}>{t('documents.actions.retry')}</Button> : undefined}
+        />
+      ) : shares.length === 0 ? (
+        <p className="rounded border border-border bg-muted/20 px-3 py-2 text-sm text-muted-foreground">
+          {t('documents.share.dialog.empty')}
+        </p>
+      ) : (
+        <div className="space-y-2">
+          <p className="text-sm font-medium">{t('documents.share.dialog.current')}</p>
+          <div className="max-h-64 space-y-2 overflow-y-auto pr-1">
+            {shares.map((share) => {
+              const isPending = pendingShareIds.has(share.id)
+              const principalTypeLabel = t(`documents.share.principalTypes.${share.principalType}`)
+              const permissionLabel = t('documents.share.dialog.permission')
+              const removeLabel = t('documents.actions.unshare')
+              return (
+                <div
+                  key={share.id}
+                  className="flex flex-col gap-3 rounded-lg border border-border bg-card p-3 md:flex-row md:items-center"
+                >
+                  <div className="min-w-0 flex-1">
+                    <p className="truncate text-sm font-medium" title={share.principalLabel}>
+                      {share.principalLabel}
+                    </p>
+                    <p className="truncate text-xs text-muted-foreground">
+                      {share.principalSecondary
+                        ? `${principalTypeLabel} — ${share.principalSecondary}`
+                        : principalTypeLabel}
+                    </p>
+                  </div>
+                  <div className="shrink-0 md:w-48">
+                    <Select
+                      value={share.permission}
+                      onValueChange={(value) => void onPermissionChange(share, readPermission(value))}
+                      disabled={!canManage || isPending}
+                    >
+                      <SelectTrigger aria-label={`${permissionLabel}: ${share.principalLabel}`}>
+                        <SelectValue />
+                      </SelectTrigger>
+                      <SelectContent>
+                        {SHARE_PERMISSIONS.map((tier) => (
+                          <SelectItem key={tier} value={tier}>
+                            {t(`documents.permissions.${tier}`)}
+                          </SelectItem>
+                        ))}
+                      </SelectContent>
+                    </Select>
+                  </div>
+                  <Button
+                    type="button"
+                    variant="destructive-outline"
+                    className="shrink-0"
+                    aria-label={`${removeLabel}: ${share.principalLabel}`}
+                    onClick={() => void onRemove(share)}
+                    disabled={!canManage || isPending}
+                  >
+                    {removeLabel}
+                  </Button>
+                </div>
+              )
+            })}
+          </div>
+        </div>
+      )}
+    </div>
+  )
+}

package/src/modules/documents/backend/documents/components/TemplateBodyEditor.tsx

@@ -0,0 +1,96 @@
+"use client"
+
+import * as React from 'react'
+import type { Editor } from '@tiptap/core'
+import { EditorContent, useEditor, useEditorState } from '@tiptap/react'
+import { Bold, Heading1, Heading2, Italic, List, ListOrdered } from 'lucide-react'
+import { IconButton } from '@open-mercato/ui/primitives/icon-button'
+import { Label } from '@open-mercato/ui/primitives/label'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@open-mercato/ui/primitives/select'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { getDocumentEditorExtensions } from '../../../lib/editorConfig'
+
+const EMPTY_TEMPLATE_EDITOR_STATE = {
+  bold: false,
+  italic: false,
+  heading1: false,
+  heading2: false,
+  bulletList: false,
+  orderedList: false,
+}
+
+function EditorButton({ editor, label, active, children, onClick }: {
+  editor: Editor | null
+  label: string
+  active: boolean
+  children: React.ReactNode
+  onClick: (editor: Editor) => void
+}) {
+  return <IconButton type="button" variant={active ? 'outline' : 'ghost'} aria-label={label} aria-pressed={active} title={label} disabled={!editor} onMouseDown={(event) => event.preventDefault()} onClick={() => { if (editor) onClick(editor) }}>{children}</IconButton>
+}
+
+export function TemplateBodyEditor({ bodyHtml, tokenOptions, onChange }: {
+  bodyHtml: string
+  tokenOptions: string[]
+  onChange: (html: string) => void
+}) {
+  const t = useT()
+  const editorLabelId = React.useId()
+  const [token, setToken] = React.useState<string | undefined>()
+  const editor = useEditor({
+    extensions: getDocumentEditorExtensions({
+      entityRefFallbackLabel: t('documents.editor.entityRef.fallbackLabel'),
+    }),
+    content: bodyHtml,
+    editable: true,
+    editorProps: {
+      attributes: {
+        class: 'min-h-80 text-base leading-7 text-foreground focus-visible:outline-none',
+        role: 'textbox',
+        'aria-labelledby': editorLabelId,
+        'aria-multiline': 'true',
+      },
+    },
+    onUpdate: ({ editor: updated }) => onChange(updated.getHTML()),
+  }, [])
+  React.useEffect(() => {
+    if (editor && editor.getHTML() !== bodyHtml) editor.commands.setContent(bodyHtml)
+  }, [bodyHtml, editor])
+  const editorState = useEditorState({
+    editor,
+    selector: ({ editor: current }) => current ? {
+      bold: current.isActive('bold'),
+      italic: current.isActive('italic'),
+      heading1: current.isActive('heading', { level: 1 }),
+      heading2: current.isActive('heading', { level: 2 }),
+      bulletList: current.isActive('bulletList'),
+      orderedList: current.isActive('orderedList'),
+    } : EMPTY_TEMPLATE_EDITOR_STATE,
+  }) ?? EMPTY_TEMPLATE_EDITOR_STATE
+  return (
+    <div className="space-y-3">
+      <Label id={editorLabelId}>{t('documents.templates.fields.body')}</Label>
+      <div className="rounded-md border border-border bg-card">
+        <div className="flex flex-wrap items-center gap-1 border-b border-border p-2">
+          <EditorButton editor={editor} label={t('documents.editor.toolbar.bold')} active={editorState.bold} onClick={(current) => { current.chain().focus().toggleBold().run() }}><Bold /></EditorButton>
+          <EditorButton editor={editor} label={t('documents.editor.toolbar.italic')} active={editorState.italic} onClick={(current) => { current.chain().focus().toggleItalic().run() }}><Italic /></EditorButton>
+          <EditorButton editor={editor} label={t('documents.editor.toolbar.heading1')} active={editorState.heading1} onClick={(current) => { current.chain().focus().toggleHeading({ level: 1 }).run() }}><Heading1 /></EditorButton>
+          <EditorButton editor={editor} label={t('documents.editor.toolbar.heading2')} active={editorState.heading2} onClick={(current) => { current.chain().focus().toggleHeading({ level: 2 }).run() }}><Heading2 /></EditorButton>
+          <EditorButton editor={editor} label={t('documents.editor.toolbar.bulletList')} active={editorState.bulletList} onClick={(current) => { current.chain().focus().toggleBulletList().run() }}><List /></EditorButton>
+          <EditorButton editor={editor} label={t('documents.editor.toolbar.orderedList')} active={editorState.orderedList} onClick={(current) => { current.chain().focus().toggleOrderedList().run() }}><ListOrdered /></EditorButton>
+          <div className="min-w-52">
+            <Select value={token} onValueChange={(value) => {
+              setToken(value)
+              editor?.chain().focus().insertContent(value).run()
+              window.setTimeout(() => setToken(undefined), 0)
+            }}>
+              <SelectTrigger aria-label={t('documents.templates.editor.insertField')}><SelectValue placeholder={t('documents.templates.editor.insertField')} /></SelectTrigger>
+              <SelectContent>{tokenOptions.map((value) => <SelectItem key={value} value={value}>{value}</SelectItem>)}</SelectContent>
+            </Select>
+          </div>
+        </div>
+        <EditorContent editor={editor} className="max-w-none p-4 text-foreground [&_.ProseMirror]:min-h-80 [&_.ProseMirror]:focus-visible:outline-none" />
+      </div>
+    </div>
+  )
+}

package/src/modules/documents/backend/documents/components/TemplateEditorDialog.tsx

@@ -0,0 +1,171 @@
+"use client"
+
+import * as React from 'react'
+import { apiCallOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
+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 { Alert, AlertDescription } from '@open-mercato/ui/primitives/alert'
+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 { Switch } from '@open-mercato/ui/primitives/switch'
+import { Textarea } from '@open-mercato/ui/primitives/textarea'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { DOCUMENTS_ENTITY_IDS } from '../../../lib/constants'
+import { getEntityRegistryEntry } from '../../../lib/entityRegistry'
+import { TemplateBodyEditor } from './TemplateBodyEditor'
+import { TemplateSlotsEditor, TEMPLATE_SLOT_KEY_PATTERN } from './TemplateSlotsEditor'
+import type { TemplateContextSlot, TemplateRow } from './templateUi'
+import { useTemplateDetail } from './useTemplateDetail'
+
+export type DocumentTemplateContextSlot = TemplateContextSlot
+export type DocumentTemplateRow = TemplateRow
+
+type TemplateEditorDialogProps = {
+  open: boolean
+  template: TemplateRow | null
+  onOpenChange: (open: boolean) => void
+  onSaved: () => void
+}
+
+export function TemplateEditorDialog({ open, template, onOpenChange, onSaved }: TemplateEditorDialogProps) {
+  const t = useT()
+  const templateDetail = useTemplateDetail(open, template?.id ?? null)
+  const nameInputId = React.useId()
+  const descriptionInputId = React.useId()
+  const activeInputId = React.useId()
+  const [name, setName] = React.useState('')
+  const [description, setDescription] = React.useState('')
+  const [isActive, setIsActive] = React.useState(true)
+  const [slots, setSlots] = React.useState<TemplateContextSlot[]>([])
+  const [bodyHtml, setBodyHtml] = React.useState('<p></p>')
+  const [isSubmitting, setIsSubmitting] = React.useState(false)
+  const submittingRef = React.useRef(false)
+  const [formError, setFormError] = React.useState<string | null>(null)
+  const mutationContextId = template ? `documents-template-editor:${template.id}` : 'documents-template-editor:new'
+  const { runMutation, retryLastMutation } = useGuardedMutation<{
+    formId: string
+    resourceKind: string
+    resourceId: string
+    retryLastMutation: () => Promise<boolean>
+  }>({ contextId: mutationContextId, blockedMessage: t('ui.forms.flash.saveBlocked') })
+
+  React.useEffect(() => {
+    if (!open) return
+    if (template && !templateDetail.template) {
+      setName('')
+      setDescription('')
+      setIsActive(true)
+      setSlots([])
+      setBodyHtml('<p></p>')
+      setFormError(null)
+      return
+    }
+    const source = templateDetail.template
+    setName(source?.name ?? '')
+    setDescription(source?.description ?? '')
+    setIsActive(source?.isActive ?? true)
+    setSlots(source?.contextSlots ?? [])
+    setBodyHtml(source?.bodyHtml || '<p></p>')
+    setFormError(null)
+  }, [open, template, templateDetail.template])
+
+  const tokenOptions = React.useMemo(() => {
+    const options = ['{{date}}']
+    for (const slot of slots) {
+      const entry = getEntityRegistryEntry(slot.entityType)
+      if (!entry || !TEMPLATE_SLOT_KEY_PATTERN.test(slot.slot)) continue
+      options.push(...entry.tokenFields.map((field) => `{{${slot.slot}.${field.field}}}`), `{{${slot.slot}.chip}}`)
+    }
+    return options
+  }, [slots])
+
+  const save = React.useCallback(async () => {
+    if (submittingRef.current) return
+    const editingTemplate = templateDetail.template
+    if (template && !editingTemplate) return
+    if (!name.trim()) { setFormError(t('documents.templates.validation.nameRequired')); return }
+    if (slots.some((slot) => !TEMPLATE_SLOT_KEY_PATTERN.test(slot.slot))) { setFormError(t('documents.templates.validation.fixSlots')); return }
+    submittingRef.current = true
+    setIsSubmitting(true)
+    setFormError(null)
+    const payload = {
+      name: name.trim(), description: description.trim() || null, bodyHtml,
+      contextSlots: slots.length > 0 ? slots.map((slot) => ({ ...slot, slot: slot.slot.trim(), required: slot.required || undefined })) : null,
+      isActive,
+    }
+    try {
+      await runMutation({
+        operation: () => editingTemplate ? withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(editingTemplate.updatedAt),
+          () => apiCallOrThrow(
+            '/api/documents/templates',
+            { method: 'PUT', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ id: editingTemplate.id, ...payload }) },
+            { errorMessage: t('documents.templates.error.update') },
+          ),
+        ) : apiCallOrThrow(
+          '/api/documents/templates',
+          { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(payload) },
+          { errorMessage: t('documents.templates.error.create') },
+        ),
+        context: { formId: mutationContextId, resourceKind: DOCUMENTS_ENTITY_IDS.documentTemplate, resourceId: editingTemplate?.id ?? 'new', retryLastMutation },
+        mutationPayload: editingTemplate ? { id: editingTemplate.id, ...payload } : payload,
+      })
+      flash(t(editingTemplate ? 'documents.templates.success.update' : 'documents.templates.success.create'), 'success')
+      onSaved()
+      onOpenChange(false)
+    } catch (error) {
+      if (!surfaceRecordConflict(error, t, { onRefresh: onSaved })) {
+        flash(error instanceof Error ? error.message : t(editingTemplate ? 'documents.templates.error.update' : 'documents.templates.error.create'), 'error')
+      }
+    } finally {
+      submittingRef.current = false
+      setIsSubmitting(false)
+    }
+  }, [bodyHtml, description, isActive, mutationContextId, name, onOpenChange, onSaved, retryLastMutation, runMutation, slots, t, template, templateDetail.template])
+
+  return (
+    <Dialog open={open} onOpenChange={onOpenChange}>
+      <DialogContent size="xl" className="overflow-y-auto" onKeyDown={(event) => {
+        if (event.key === 'Escape') onOpenChange(false)
+        if ((event.metaKey || event.ctrlKey) && event.key === 'Enter') { event.preventDefault(); void save() }
+      }}>
+        <DialogHeader>
+          <DialogTitle>{t(template ? 'documents.templates.dialog.editTitle' : 'documents.templates.dialog.createTitle')}</DialogTitle>
+          <DialogDescription>{t('documents.templates.dialog.description')}</DialogDescription>
+        </DialogHeader>
+        {template && templateDetail.isLoading ? <LoadingMessage label={t('documents.templates.instantiate.loading')} /> : null}
+        {template && templateDetail.error ? (
+          <ErrorMessage
+            label={t('documents.templates.error.load')}
+            action={<Button type="button" size="sm" variant="outline" onClick={templateDetail.retry}>{t('documents.actions.retry')}</Button>}
+          />
+        ) : null}
+        {!template || templateDetail.template ? (
+          <>
+            <div className="grid gap-6 xl:grid-cols-3">
+              <div className="space-y-4 xl:col-span-2">
+                <div className="space-y-2"><Label htmlFor={nameInputId}>{t('documents.templates.fields.name')}</Label><Input id={nameInputId} value={name} onChange={(event) => setName(event.target.value)} placeholder={t('documents.templates.fields.namePlaceholder')} aria-invalid={Boolean(formError && !name.trim())} /></div>
+                <div className="space-y-2"><Label htmlFor={descriptionInputId}>{t('documents.templates.fields.description')}</Label><Textarea id={descriptionInputId} value={description} onChange={(event) => setDescription(event.target.value)} placeholder={t('documents.templates.fields.descriptionPlaceholder')} maxLength={2000} showCount /></div>
+                <TemplateBodyEditor bodyHtml={bodyHtml} tokenOptions={tokenOptions} onChange={setBodyHtml} />
+              </div>
+              <div className="space-y-5">
+                <div className="flex items-center justify-between gap-3 rounded-md border border-border bg-card p-3"><Label htmlFor={activeInputId}>{t('documents.templates.fields.active')}</Label><Switch id={activeInputId} checked={isActive} onCheckedChange={setIsActive} aria-label={t('documents.templates.fields.active')} /></div>
+                <TemplateSlotsEditor slots={slots} onChange={setSlots} />
+              </div>
+            </div>
+            {formError ? <Alert status="error"><AlertDescription>{formError}</AlertDescription></Alert> : null}
+          </>
+        ) : null}
+        <DialogFooter>
+          <Button type="button" variant="outline" onClick={() => onOpenChange(false)} disabled={isSubmitting}>{t('documents.actions.cancel')}</Button>
+          <Button type="button" onClick={() => void save()} disabled={isSubmitting || Boolean(template && !templateDetail.template)}>{t('documents.actions.save')}</Button>
+        </DialogFooter>
+      </DialogContent>
+    </Dialog>
+  )
+}

package/src/modules/documents/backend/documents/components/TemplatePreview.tsx

@@ -0,0 +1,43 @@
+"use client"
+
+import * as React from 'react'
+import { EditorContent, useEditor } from '@tiptap/react'
+import { Alert, AlertDescription, AlertTitle } from '@open-mercato/ui/primitives/alert'
+import { LoadingMessage } from '@open-mercato/ui/backend/detail'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { getDocumentEditorExtensions } from '../../../lib/editorConfig'
+import type { TemplatePreviewResult } from './templateUi'
+
+function PreviewSurface({ html, fallbackLabel }: { html: string; fallbackLabel: string }) {
+  const editor = useEditor({
+    extensions: getDocumentEditorExtensions({ entityRefFallbackLabel: fallbackLabel }),
+    content: html,
+    editable: false,
+    editorProps: { attributes: { class: 'min-h-48 text-base leading-7 text-foreground focus-visible:outline-none' } },
+  }, [fallbackLabel])
+  React.useEffect(() => { editor?.commands.setContent(html) }, [editor, html])
+  return <EditorContent editor={editor} className="max-w-none rounded-md border border-border bg-card p-4" />
+}
+
+export function TemplatePreview({ preview, isLoading }: { preview: TemplatePreviewResult | null; isLoading: boolean }) {
+  const t = useT()
+  if (isLoading) return <LoadingMessage label={t('documents.templates.preview.loading')} />
+  if (!preview) {
+    return (
+      <div className="rounded-md border border-dashed border-border p-4 text-sm text-muted-foreground">
+        {t('documents.templates.preview.empty')}
+      </div>
+    )
+  }
+  return (
+    <div className="space-y-3">
+      {preview.unresolvedTokens.length > 0 ? (
+        <Alert status="warning">
+          <AlertTitle>{t('documents.templates.preview.unresolvedTitle')}</AlertTitle>
+          <AlertDescription>{t('documents.templates.preview.unresolvedBody', { tokens: preview.unresolvedTokens.join(', ') })}</AlertDescription>
+        </Alert>
+      ) : null}
+      <PreviewSurface html={preview.contentHtml} fallbackLabel={t('documents.editor.entityRef.fallbackLabel')} />
+    </div>
+  )
+}

package/src/modules/documents/backend/documents/components/TemplateSlotFields.tsx

@@ -0,0 +1,72 @@
+"use client"
+
+import * as React from 'react'
+import { Search, X } from 'lucide-react'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { Label } from '@open-mercato/ui/primitives/label'
+import { Tag } from '@open-mercato/ui/primitives/tag'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { getEntityRegistryEntry } from '../../../lib/entityRegistry'
+import { EntityPicker, type EntityPickerSelection } from './EntityPicker'
+import type { TemplateContextSlot, TemplateSlotSelection } from './templateUi'
+
+type TemplateSlotFieldsProps = {
+  slots: TemplateContextSlot[]
+  selections: Record<string, TemplateSlotSelection | undefined>
+  onSelectionChange: (slot: string, selection: TemplateSlotSelection | undefined) => void
+}
+
+export function TemplateSlotFields({ slots, selections, onSelectionChange }: TemplateSlotFieldsProps) {
+  const t = useT()
+  const [activeSlot, setActiveSlot] = React.useState<TemplateContextSlot | null>(null)
+  const handlePick = React.useCallback((selection: EntityPickerSelection) => {
+    if (!activeSlot) return
+    onSelectionChange(activeSlot.slot, {
+      entityType: selection.type,
+      entityId: selection.id,
+      label: selection.label,
+      href: selection.href,
+      values: selection.values,
+    })
+    setActiveSlot(null)
+  }, [activeSlot, onSelectionChange])
+
+  if (slots.length === 0) {
+    return <p className="rounded-md border border-border bg-muted/20 p-3 text-sm text-muted-foreground">{t('documents.templates.instantiate.noSlots')}</p>
+  }
+  return (
+    <div className="space-y-4">
+      <p className="text-sm font-medium">{t('documents.templates.instantiate.contextTitle')}</p>
+      {slots.map((slot) => {
+        const selection = selections[slot.slot]
+        const entry = getEntityRegistryEntry(slot.entityType)
+        return (
+          <div key={slot.slot} className="space-y-2">
+            <Label>
+              {entry ? t(entry.labelKey) : t('documents.relatedRecords.restricted')}
+              {slot.required ? ` ${t('documents.templates.instantiate.requiredSuffix')}` : ''}
+            </Label>
+            {selection ? (
+              <div className="flex items-center justify-between gap-2 rounded-md border border-border p-3">
+                <div className="min-w-0"><p className="truncate text-sm font-medium">{selection.label}</p><Tag variant="neutral">{entry ? t(entry.labelKey) : t('documents.relatedRecords.restricted')}</Tag></div>
+                <Button type="button" size="sm" variant="ghost" onClick={() => onSelectionChange(slot.slot, undefined)}>
+                  <X />{t('documents.templates.instantiate.clearSelection')}
+                </Button>
+              </div>
+            ) : (
+              <Button type="button" variant="outline" className="w-full justify-start" onClick={() => setActiveSlot(slot)}>
+                <Search />{t('documents.templates.instantiate.searchPlaceholder')}
+              </Button>
+            )}
+          </div>
+        )
+      })}
+      <EntityPicker
+        open={activeSlot !== null}
+        onOpenChange={(open) => { if (!open) setActiveSlot(null) }}
+        onPick={handlePick}
+        typeFilter={activeSlot ? [activeSlot.entityType] : []}
+      />
+    </div>
+  )
+}

package/src/modules/documents/backend/documents/components/TemplateSlotsEditor.tsx

@@ -0,0 +1,72 @@
+"use client"
+
+import { Plus, Trash2 } from 'lucide-react'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { CheckboxField } from '@open-mercato/ui/primitives/checkbox-field'
+import { IconButton } from '@open-mercato/ui/primitives/icon-button'
+import { Input } from '@open-mercato/ui/primitives/input'
+import { Label } from '@open-mercato/ui/primitives/label'
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from '@open-mercato/ui/primitives/select'
+import { useT } from '@open-mercato/shared/lib/i18n/context'
+import {
+  DOCUMENT_ENTITY_REGISTRY,
+  getEntityRegistryEntry,
+  type DocumentEntityType,
+} from '../../../lib/entityRegistry'
+import type { TemplateContextSlot } from './templateUi'
+import { useAvailableDocumentEntityRegistry } from './useAvailableEntityRegistry'
+
+export const TEMPLATE_SLOT_KEY_PATTERN = /^[a-z][a-zA-Z0-9]*$/
+
+function deriveSlotKey(entityType: DocumentEntityType, slots: TemplateContextSlot[], excludeIndex?: number): string {
+  const [first = 'slot', ...rest] = entityType.split('-')
+  const base = [first, ...rest.map((part) => part.slice(0, 1).toUpperCase() + part.slice(1))].join('')
+  const existing = new Set(slots.filter((_, index) => index !== excludeIndex).map((slot) => slot.slot))
+  if (!existing.has(base)) return base
+  let ordinal = 2
+  while (existing.has(`${base}${ordinal}`)) ordinal += 1
+  return `${base}${ordinal}`
+}
+
+export function TemplateSlotsEditor({ slots, onChange }: { slots: TemplateContextSlot[]; onChange: (slots: TemplateContextSlot[]) => void }) {
+  const t = useT()
+  const { entries: availableEntries } = useAvailableDocumentEntityRegistry(DOCUMENT_ENTITY_REGISTRY)
+  const addSlot = () => {
+    const entityType = availableEntries[0]?.type
+    if (!entityType) return
+    onChange([...slots, { slot: deriveSlotKey(entityType, slots), entityType, required: true }])
+  }
+  return (
+    <div className="space-y-3">
+      <div className="flex items-center justify-between gap-3">
+        <Label>{t('documents.templates.slots.title')}</Label>
+        <Button type="button" size="sm" variant="outline" onClick={addSlot} disabled={availableEntries.length === 0}><Plus />{t('documents.templates.slots.add')}</Button>
+      </div>
+      {slots.length === 0 ? <p className="rounded-md border border-border bg-muted/20 p-3 text-sm text-muted-foreground">{t('documents.templates.slots.empty')}</p> : null}
+      {slots.map((slot, index) => {
+        const inputId = `document-template-slot-${index}`
+        const entityTypeInputId = `document-template-slot-entity-type-${index}`
+        const error = !slot.slot ? t('documents.templates.validation.slotRequired') : !TEMPLATE_SLOT_KEY_PATTERN.test(slot.slot) ? t('documents.templates.validation.slotKey') : null
+        const currentEntry = getEntityRegistryEntry(slot.entityType)
+        return (
+          <div key={`${slot.entityType}:${index}`} className="space-y-3 rounded-md border border-border bg-card p-3">
+            <div className="flex items-start gap-2">
+              <div className="min-w-0 flex-1 space-y-2">
+                <Label htmlFor={inputId}>{t('documents.templates.slots.key')}</Label>
+                <Input id={inputId} value={slot.slot} onChange={(event) => onChange(slots.map((item, itemIndex) => itemIndex === index ? { ...item, slot: event.target.value } : item))} aria-invalid={error !== null} />
+                {error ? <p className="text-xs text-status-error-text" role="alert">{error}</p> : null}
+              </div>
+              <IconButton type="button" variant="ghost" aria-label={t('documents.templates.slots.remove')} title={t('documents.templates.slots.remove')} onClick={() => onChange(slots.filter((_, itemIndex) => itemIndex !== index))}><Trash2 /></IconButton>
+            </div>
+            <Label htmlFor={entityTypeInputId}>{t('documents.templates.slots.entityType')}</Label>
+            <Select value={slot.entityType} disabled={availableEntries.length === 0} onValueChange={(value) => onChange(slots.map((item, itemIndex) => itemIndex === index ? { ...item, entityType: value as DocumentEntityType, slot: deriveSlotKey(value as DocumentEntityType, slots, index) } : item))}>
+              <SelectTrigger id={entityTypeInputId}><SelectValue>{currentEntry ? t(currentEntry.labelKey) : t('documents.relatedRecords.restricted')}</SelectValue></SelectTrigger>
+              <SelectContent>{availableEntries.map((entry) => <SelectItem key={entry.type} value={entry.type}>{t(entry.labelKey)}</SelectItem>)}</SelectContent>
+            </Select>
+            <CheckboxField label={t('documents.templates.slots.required')} checked={slot.required === true} onCheckedChange={(checked) => onChange(slots.map((item, itemIndex) => itemIndex === index ? { ...item, required: checked === true } : item))} />
+          </div>
+        )
+      })}
+    </div>
+  )
+}

package/src/modules/documents/backend/documents/components/principalPickerModel.ts

@@ -0,0 +1,86 @@
+import { resolveSearchMinTokenLength } from '@open-mercato/shared/lib/search/config'
+import {
+  firstSafeDocumentsDisplayLabel,
+  sanitizeDocumentsDisplayLabel,
+} from '../../../lib/displayLabels'
+
+export type PrincipalType = 'user' | 'role'
+
+export type PrincipalOption = {
+  id: string
+  label: string
+  primary: string
+  secondary: string | null
+}
+
+export type PrincipalListPayload = { items?: unknown[]; total?: unknown; totalPages?: unknown }
+
+export const PRINCIPAL_PAGE_SIZE = 20
+export const PRINCIPAL_DEBOUNCE_MS = 250
+export const PRINCIPAL_SEARCH_MIN_LENGTH = resolveSearchMinTokenLength()
+
+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>, ...keys: string[]): string | null {
+  for (const key of keys) {
+    const candidate = value[key]
+    if (typeof candidate === 'string' && candidate.trim()) return candidate.trim()
+  }
+  return null
+}
+
+function normalize(value: unknown, fallbackLabel: string): PrincipalOption | null {
+  const item = record(value)
+  if (!item) return null
+  const id = text(item, 'id')
+  if (!id) return null
+  const primary = firstSafeDocumentsDisplayLabel(text(item, 'label'), fallbackLabel)
+  if (!primary) return null
+  const rawSecondary = sanitizeDocumentsDisplayLabel(text(item, 'secondary'))
+  const secondary = rawSecondary && rawSecondary !== primary ? rawSecondary : null
+  return { id, primary, secondary, label: secondary ? `${primary} (${secondary})` : primary }
+}
+
+export function readPrincipalPage(
+  payload: PrincipalListPayload | null,
+  _principalType: PrincipalType,
+  page: number,
+  fallbackLabel: string,
+) {
+  const root = record(payload)
+  const rawItems = Array.isArray(root?.items) ? root.items : []
+  const items = rawItems.slice(0, PRINCIPAL_PAGE_SIZE)
+    .map((item) => normalize(item, fallbackLabel))
+    .filter((item): item is PrincipalOption => item !== null)
+  const rawTotal = root?.total
+  const total = typeof rawTotal === 'number' && Number.isFinite(rawTotal) && rawTotal >= 0 ? rawTotal : items.length
+  const rawPages = root?.totalPages
+  const totalPages = typeof rawPages === 'number' && Number.isFinite(rawPages) && rawPages >= 0
+    ? rawPages
+    : total > 0 ? Math.ceil(total / PRINCIPAL_PAGE_SIZE) : 1
+  return { items, total, totalPages: Math.max(1, totalPages, page) }
+}
+
+export function buildPrincipalUrl(
+  documentId: string,
+  principalType: PrincipalType,
+  query: string,
+  page: number,
+): string {
+  const params = new URLSearchParams({
+    mode: 'share',
+    type: principalType,
+    page: String(page),
+    pageSize: String(PRINCIPAL_PAGE_SIZE),
+  })
+  if (query) params.set('search', query)
+  return `/api/documents/${encodeURIComponent(documentId)}/principals?${params.toString()}`
+}
+
+export function mergePrincipalOptions(current: PrincipalOption[], next: PrincipalOption[]): PrincipalOption[] {
+  const merged = new Map(current.map((item) => [item.id, item]))
+  next.forEach((item) => merged.set(item.id, item))
+  return Array.from(merged.values())
+}