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

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

@@ -0,0 +1,94 @@
+import { sanitizeDocumentsDisplayLabel } from '../../../lib/displayLabels'
+
+export type DocumentSharePrincipalType = 'user' | 'role'
+export type DocumentSharePermission = 'viewer' | 'commenter' | 'editor'
+
+export type ShareRow = {
+  id: string
+  principalType: DocumentSharePrincipalType
+  principalId: string
+  principalLabel: string
+  principalSecondary: string | null
+  resolved: boolean
+  permission: DocumentSharePermission
+  updatedAt?: string | null
+}
+
+export type SharesResponse = {
+  items?: unknown[]
+  data?: unknown[]
+  shares?: unknown[]
+}
+
+export const SHARE_PERMISSIONS: DocumentSharePermission[] = ['viewer', 'commenter', 'editor']
+export const PRINCIPAL_TYPES: DocumentSharePrincipalType[] = ['user', 'role']
+
+function readRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' ? value as Record<string, unknown> : null
+}
+
+function readString(record: Record<string, unknown>, ...keys: string[]): string | null {
+  for (const key of keys) {
+    const value = record[key]
+    if (typeof value === 'string' && value.trim().length > 0) return value
+  }
+  return null
+}
+
+export function readPrincipalType(value: string | null): DocumentSharePrincipalType {
+  return value === 'role' ? 'role' : 'user'
+}
+
+export function readPermission(value: string | null): DocumentSharePermission {
+  if (value === 'commenter' || value === 'editor') return value
+  return 'viewer'
+}
+
+function normalizeShare(value: unknown, removedPrincipalLabel: string): ShareRow | null {
+  const record = readRecord(value)
+  if (!record) return null
+  const id = readString(record, 'id')
+  const principalId = readString(record, 'principalId', 'principal_id')
+  if (!id || !principalId) return null
+  const principalType = readPrincipalType(readString(record, 'principalType', 'principal_type'))
+  const permission = readPermission(readString(record, 'permission', 'tier'))
+  const resolvedLabel = sanitizeDocumentsDisplayLabel(
+    readString(
+      record,
+      'principalLabel',
+      'principal_label',
+      'principalEmail',
+      'principal_email',
+      'name',
+      'email',
+    ),
+  )
+  const rawSecondary = readString(record, 'principalSecondary', 'principal_secondary')
+  const principalSecondary = sanitizeDocumentsDisplayLabel(rawSecondary)
+  return {
+    id,
+    principalId,
+    principalType,
+    principalLabel: resolvedLabel ?? removedPrincipalLabel,
+    principalSecondary,
+    resolved: resolvedLabel !== null,
+    permission,
+    updatedAt: readString(record, 'updatedAt', 'updated_at'),
+  }
+}
+
+export function readShareItems(
+  payload: SharesResponse | unknown[] | null,
+  removedPrincipalLabel: string,
+): ShareRow[] {
+  const source = Array.isArray(payload)
+    ? payload
+    : (() => {
+        const record = readRecord(payload)
+        if (!record) return []
+        return [record.items, record.data, record.shares].find(Array.isArray) ?? []
+      })()
+  return source
+    .map((row) => normalizeShare(row, removedPrincipalLabel))
+    .filter((row): row is ShareRow => row !== null)
+}

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

@@ -0,0 +1,128 @@
+import { getEntityRegistryEntry, type DocumentEntityType } from '../../../lib/entityRegistry'
+import {
+  firstSafeDocumentsDisplayLabel,
+  sanitizeDocumentsDisplayLabel,
+} from '../../../lib/displayLabels'
+import { readArrayPayload, readBoolean, readRecord, readString } from '../documentUi'
+
+export type TemplateContextSlot = { slot: string; entityType: DocumentEntityType; required?: boolean }
+export type TemplateRow = {
+  id: string
+  name: string
+  description: string | null
+  bodyHtml: string
+  contextSlots: TemplateContextSlot[]
+  isActive: boolean
+  updatedAt: string
+  createdAt: string
+}
+
+export type TemplateSlotSelection = {
+  entityType: DocumentEntityType
+  entityId: string
+  label: string
+  href: string
+  values: Record<string, string | number | null>
+}
+
+export type TemplatePreviewResult = {
+  contentHtml: string
+  unresolvedTokens: string[]
+  templateUpdatedAt: string
+  previewDigest: string
+}
+
+function normalizeSlot(value: unknown): TemplateContextSlot | null {
+  const record = readRecord(value)
+  if (!record) return null
+  const slot = readString(record, 'slot')
+  const entityType = readString(record, 'entityType', 'entity_type')
+  if (!slot || !entityType || !getEntityRegistryEntry(entityType)) return null
+  return { slot, entityType: entityType as DocumentEntityType, required: readBoolean(record, 'required') ?? undefined }
+}
+
+export function normalizeTemplate(value: unknown): TemplateRow | null {
+  const record = readRecord(value)
+  if (!record) return null
+  const id = readString(record, 'id')
+  const name = readString(record, 'name')
+  const updatedAt = readString(record, 'updatedAt', 'updated_at')
+  const createdAt = readString(record, 'createdAt', 'created_at')
+  if (!id || !name || !updatedAt || !createdAt) return null
+  const rawSlots = record.contextSlots ?? record.context_slots
+  return {
+    id,
+    name,
+    updatedAt,
+    createdAt,
+    description: readString(record, 'description'),
+    bodyHtml: readString(record, 'bodyHtml', 'body_html') ?? '',
+    contextSlots: Array.isArray(rawSlots)
+      ? rawSlots.map(normalizeSlot).filter((slot): slot is TemplateContextSlot => slot !== null)
+      : [],
+    isActive: readBoolean(record, 'isActive', 'is_active') ?? true,
+  }
+}
+
+export function normalizeTemplateDetail(value: unknown): TemplateRow | null {
+  const record = readRecord(value)
+  if (!record) return null
+  const bodyHtml = record.bodyHtml ?? record.body_html
+  if (typeof bodyHtml !== 'string') return null
+  const template = normalizeTemplate(record)
+  return template ? { ...template, bodyHtml } : null
+}
+
+export function normalizeTemplates(payload: unknown): TemplateRow[] {
+  return readArrayPayload(payload, 'items', 'data', 'templates')
+    .map(normalizeTemplate)
+    .filter((template): template is TemplateRow => template !== null)
+}
+
+export function normalizeActiveTemplates(payload: unknown): TemplateRow[] {
+  return normalizeTemplates(payload).filter((template) => template.isActive)
+}
+
+export function normalizePreview(payload: unknown): TemplatePreviewResult | null {
+  const record = readRecord(payload)
+  if (!record) return null
+  const contentHtml = readString(record, 'contentHtml', 'content_html') ?? ''
+  const templateUpdatedAt = readString(record, 'templateUpdatedAt', 'template_updated_at')
+  const previewDigest = readString(record, 'previewDigest', 'preview_digest')
+  if (!templateUpdatedAt || !previewDigest) return null
+  return {
+    contentHtml,
+    templateUpdatedAt,
+    previewDigest,
+    unresolvedTokens: Array.isArray(record.unresolvedTokens)
+      ? record.unresolvedTokens.filter((token): token is string => typeof token === 'string')
+      : [],
+  }
+}
+
+export function selectionForPreset(input: {
+  entityType: DocumentEntityType
+  entityId: string
+  label: string
+  fallbackLabel?: string
+  values?: Record<string, string | number | null | undefined>
+}): TemplateSlotSelection | null {
+  const entry = getEntityRegistryEntry(input.entityType)
+  if (!entry) return null
+  const label = firstSafeDocumentsDisplayLabel(input.label, input.fallbackLabel)
+  if (!label) return null
+  const href = entry.resolveHref({ id: input.entityId, label })
+  if (!href) return null
+  const values = Object.fromEntries(entry.tokenFields.flatMap((field) => {
+    const hydrated = input.values?.[field.field]
+    const safeHydrated = typeof hydrated === 'string'
+      ? sanitizeDocumentsDisplayLabel(hydrated)
+      : typeof hydrated === 'number' && Number.isFinite(hydrated) ? hydrated : null
+    if (safeHydrated !== null) {
+      return [[field.field, safeHydrated] as const]
+    }
+    const isPrimary = field.field === 'name' || field.field === 'title' || field.field === 'number'
+    return isPrimary ? [[field.field, label] as const] : []
+  }))
+  return { entityType: input.entityType, entityId: input.entityId, label, href, values }
+}

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

@@ -0,0 +1,43 @@
+"use client"
+
+import * as React from 'react'
+import {
+  getEnabledModuleIds,
+  getInjectionRegistryVersion,
+  subscribeToInjectionRegistryChanges,
+} from '@open-mercato/shared/modules/widgets/injection-loader'
+import type { DocumentEntityRegistryEntry } from '../../../lib/entityRegistry'
+
+export function filterDocumentEntityRegistryByEnabledModules(
+  entries: readonly DocumentEntityRegistryEntry[],
+  enabledModuleIds: ReadonlySet<string> | null,
+): DocumentEntityRegistryEntry[] {
+  if (!enabledModuleIds) return []
+  return entries.filter((entry) => (
+    enabledModuleIds.has(entry.requiredModule)
+    && enabledModuleIds.has(entry.requiredFeatureModule)
+  ))
+}
+
+/**
+ * Client-side peer availability backed by the enabled-module registry that
+ * ClientBootstrap populates. Until bootstrap has registered the canonical
+ * set, peer entity types remain hidden rather than being guessed from stale
+ * ACL grants or the presence of injection widgets.
+ */
+export function useAvailableDocumentEntityRegistry(
+  entries: readonly DocumentEntityRegistryEntry[],
+): { entries: DocumentEntityRegistryEntry[]; isRegistryReady: boolean } {
+  const registryVersion = React.useSyncExternalStore(
+    subscribeToInjectionRegistryChanges,
+    getInjectionRegistryVersion,
+    () => 0,
+  )
+  const enabledModuleIds = getEnabledModuleIds()
+  const availableEntries = React.useMemo(
+    () => filterDocumentEntityRegistryByEnabledModules(entries, enabledModuleIds),
+    // Registry changes replace the canonical Set and bump this version.
+    [enabledModuleIds, entries, registryVersion],
+  )
+  return { entries: availableEntries, isRegistryReady: enabledModuleIds !== null }
+}

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

@@ -0,0 +1,197 @@
+"use client"
+
+import * as React from 'react'
+import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import {
+  DOCUMENT_ENTITY_REGISTRY,
+  readItemsArray,
+  type DocumentEntityType,
+  type DocumentEntityRegistryEntry,
+  type EntityPickerItem,
+} from '../../../lib/entityRegistry'
+import { useAvailableDocumentEntityRegistry } from './useAvailableEntityRegistry'
+
+const PAGE_SIZE = 20
+const DEBOUNCE_MS = 250
+export type EntitySearchItem = EntityPickerItem & { rawItem: Record<string, unknown> }
+
+function filterEntries(typeFilter: DocumentEntityType[] | undefined): DocumentEntityRegistryEntry[] {
+  if (!typeFilter) return DOCUMENT_ENTITY_REGISTRY
+  const allowedTypes = new Set(typeFilter)
+  return DOCUMENT_ENTITY_REGISTRY.filter((entry) => allowedTypes.has(entry.type))
+}
+
+function buildSearchUrl(entry: DocumentEntityRegistryEntry, query: string): string {
+  const params = new URLSearchParams({ search: query, page: '1', pageSize: String(PAGE_SIZE) })
+  return `${entry.searchPath}?${params.toString()}`
+}
+
+function buildResultContext(open: boolean, type: DocumentEntityType | null, query: string): string {
+  return JSON.stringify([open, type, query.trim()])
+}
+
+function isPermanentlyUnavailableStatus(status: number | undefined): boolean {
+  return status === 403 || status === 404
+}
+
+export function useEntitySearch(open: boolean, typeFilter?: DocumentEntityType[], excludeId?: string) {
+  const typeFilterKey = typeFilter?.join('|') ?? ''
+  const requestSequence = React.useRef(0)
+  const activeRequest = React.useRef<AbortController | null>(null)
+  const activeContext = React.useRef('')
+  const resultContext = React.useRef<string | null>(null)
+  const allEntries = React.useMemo(() => filterEntries(typeFilter), [typeFilterKey])
+  const { entries: moduleAvailableEntries, isRegistryReady } = useAvailableDocumentEntityRegistry(allEntries)
+  const [unavailableTypes, setUnavailableTypes] = React.useState<Set<DocumentEntityType>>(() => new Set())
+  const availableEntries = React.useMemo(
+    () => moduleAvailableEntries.filter((entry) => !unavailableTypes.has(entry.type)),
+    [moduleAvailableEntries, unavailableTypes],
+  )
+  const [activeType, setActiveTypeState] = React.useState<DocumentEntityType | null>(
+    moduleAvailableEntries[0]?.type ?? null,
+  )
+  const [searchValue, setSearchValueState] = React.useState('')
+  const [items, setItems] = React.useState<EntitySearchItem[]>([])
+  const [isLoading, setIsLoading] = React.useState(false)
+  const [hasSearched, setHasSearched] = React.useState(false)
+  const [errorContext, setErrorContext] = React.useState<string | null>(null)
+  const [retryToken, setRetryToken] = React.useState(0)
+  const [activeIndex, setActiveIndex] = React.useState(-1)
+  const activeEntry = React.useMemo(
+    () => availableEntries.find((entry) => entry.type === activeType) ?? availableEntries[0] ?? null,
+    [activeType, availableEntries],
+  )
+  const currentContext = buildResultContext(open, activeEntry?.type ?? null, searchValue)
+  activeContext.current = currentContext
+
+  const invalidateResults = React.useCallback(() => {
+    requestSequence.current += 1
+    activeRequest.current?.abort()
+    activeRequest.current = null
+    resultContext.current = null
+    setItems([])
+    setIsLoading(false)
+    setHasSearched(false)
+    setErrorContext(null)
+    setActiveIndex(-1)
+  }, [])
+
+  const setActiveType = React.useCallback((nextType: DocumentEntityType | null) => {
+    // Invalidate before changing the active registry entry. Otherwise a fast
+    // Enter/click can submit a result produced for the previous entity type,
+    // and an already-resolving request can repopulate that stale selection.
+    activeContext.current = buildResultContext(open, nextType, searchValue)
+    invalidateResults()
+    setActiveTypeState(nextType)
+  }, [invalidateResults, open, searchValue])
+
+  const setSearchValue = React.useCallback((nextValue: string) => {
+    activeContext.current = buildResultContext(open, activeEntry?.type ?? null, nextValue)
+    invalidateResults()
+    setSearchValueState(nextValue)
+  }, [activeEntry?.type, invalidateResults, open])
+
+  React.useEffect(() => {
+    invalidateResults()
+    if (!open) return
+    setUnavailableTypes(new Set())
+    setActiveTypeState(moduleAvailableEntries[0]?.type ?? null)
+    setSearchValueState('')
+  }, [invalidateResults, moduleAvailableEntries, open])
+
+  React.useEffect(() => {
+    if (open && activeEntry && activeType !== activeEntry.type) setActiveType(activeEntry.type)
+  }, [activeEntry, activeType, open, setActiveType])
+
+  React.useEffect(() => {
+    if (!open || !activeEntry) return
+    const query = searchValue.trim()
+    if (!query) {
+      invalidateResults()
+      return
+    }
+    const entry = activeEntry
+    const timer = window.setTimeout(() => {
+      const requestId = ++requestSequence.current
+      const requestContext = buildResultContext(true, entry.type, query)
+      const controller = new AbortController()
+      activeRequest.current?.abort()
+      activeRequest.current = controller
+      resultContext.current = null
+      setIsLoading(true)
+      setHasSearched(false)
+      setErrorContext(null)
+      void apiCall<unknown>(
+        buildSearchUrl(entry, query),
+        {
+          headers: { 'x-om-forbidden-redirect': '0', 'x-om-unauthorized-redirect': '0' },
+          signal: controller.signal,
+        },
+        { fallback: { items: [] } },
+      ).then((call) => {
+        if (requestSequence.current !== requestId || activeContext.current !== requestContext) return
+        if (!call.ok) {
+          resultContext.current = null
+          setItems([])
+          if (isPermanentlyUnavailableStatus(call.status)) {
+            setUnavailableTypes((current) => new Set(current).add(entry.type))
+          } else {
+            setErrorContext(requestContext)
+          }
+          return
+        }
+        const next = readItemsArray(call.result).flatMap((rawItem) => {
+          const item = entry.mapItem(rawItem)
+          if (!item || (excludeId && item.id === excludeId)) return []
+          return [{ ...item, rawItem }]
+        })
+        resultContext.current = requestContext
+        setErrorContext(null)
+        setItems(next)
+        setHasSearched(true)
+        setActiveIndex(next.length > 0 ? 0 : -1)
+      }).catch(() => {
+        if (!controller.signal.aborted && requestSequence.current === requestId && activeContext.current === requestContext) {
+          resultContext.current = null
+          setItems([])
+          setErrorContext(requestContext)
+        }
+      }).finally(() => {
+        if (requestSequence.current === requestId) {
+          if (activeRequest.current === controller) activeRequest.current = null
+          setIsLoading(false)
+        }
+      })
+    }, DEBOUNCE_MS)
+    return () => window.clearTimeout(timer)
+  }, [activeEntry, invalidateResults, open, retryToken, searchValue])
+
+  React.useEffect(() => () => { activeRequest.current?.abort() }, [])
+
+  const hasCurrentResult = resultContext.current !== null && resultContext.current === currentContext
+  const isResultCurrent = React.useCallback(
+    () => resultContext.current !== null && resultContext.current === activeContext.current,
+    [],
+  )
+  const retry = React.useCallback(() => {
+    if (!open || !activeEntry || !searchValue.trim()) return
+    requestSequence.current += 1
+    activeRequest.current?.abort()
+    activeRequest.current = null
+    resultContext.current = null
+    setItems([])
+    setIsLoading(false)
+    setHasSearched(false)
+    setErrorContext(null)
+    setActiveIndex(-1)
+    setRetryToken((token) => token + 1)
+  }, [activeEntry, open, searchValue])
+
+  return {
+    allEntries, availableEntries, isRegistryReady, activeEntry, activeType, setActiveType,
+    searchValue, setSearchValue, items: hasCurrentResult ? items : [], isLoading,
+    hasSearched: hasCurrentResult && hasSearched,
+    hasError: errorContext !== null && errorContext === currentContext, retry,
+    activeIndex: hasCurrentResult ? activeIndex : -1, setActiveIndex, isResultCurrent,
+  }
+}

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

@@ -0,0 +1,165 @@
+"use client"
+
+import * as React from 'react'
+import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import {
+  buildPrincipalUrl,
+  mergePrincipalOptions,
+  PRINCIPAL_DEBOUNCE_MS,
+  PRINCIPAL_SEARCH_MIN_LENGTH,
+  readPrincipalPage,
+  type PrincipalListPayload,
+  type PrincipalOption,
+  type PrincipalType,
+} from './principalPickerModel'
+
+const OPTIONAL_HEADERS = { 'x-om-forbidden-redirect': '0', 'x-om-unauthorized-redirect': '0' }
+
+function buildResultContext(documentId: string, principalType: PrincipalType, query: string): string {
+  return JSON.stringify([documentId, principalType, query.trim()])
+}
+
+export function usePrincipalPicker({ documentId, principalType, value, onChange, disabled, fallbackLabel }: {
+  documentId: string
+  principalType: PrincipalType
+  value: string | null
+  onChange: (id: string | null, label: string | null) => void
+  disabled: boolean
+  fallbackLabel: string
+}) {
+  const request = React.useRef(0)
+  const activeRequest = React.useRef<AbortController | null>(null)
+  const activeContext = React.useRef('')
+  const resultContext = React.useRef<string | null>(null)
+  const onChangeRef = React.useRef(onChange)
+  React.useEffect(() => { onChangeRef.current = onChange }, [onChange])
+  const [searchValue, setSearchValue] = React.useState('')
+  const [selectedLabel, setSelectedLabel] = React.useState<string | null>(null)
+  const [items, setItems] = React.useState<PrincipalOption[]>([])
+  const [open, setOpenState] = React.useState(false)
+  const [loading, setLoading] = React.useState(false)
+  const [loadingMore, setLoadingMore] = React.useState(false)
+  const [fetchError, setFetchError] = React.useState(false)
+  const [hasFetched, setHasFetched] = React.useState(false)
+  const [page, setPage] = React.useState(1)
+  const [total, setTotal] = React.useState(0)
+  const [totalPages, setTotalPages] = React.useState(1)
+  const [activeIndex, setActiveIndex] = React.useState(-1)
+  const currentContext = buildResultContext(documentId, principalType, searchValue)
+  activeContext.current = currentContext
+
+  const invalidateResults = React.useCallback(() => {
+    request.current += 1
+    activeRequest.current?.abort()
+    activeRequest.current = null
+    resultContext.current = null
+    setItems([]); setLoading(false); setLoadingMore(false); setHasFetched(false)
+    setPage(1); setTotal(0); setTotalPages(1); setActiveIndex(-1)
+  }, [])
+
+  React.useEffect(() => {
+    if (!disabled) return
+    invalidateResults()
+    setOpenState(false)
+    setFetchError(false)
+  }, [disabled, invalidateResults])
+
+  const reset = React.useCallback((notify: boolean) => {
+    invalidateResults()
+    setSearchValue(''); setSelectedLabel(null); setOpenState(false); setFetchError(false)
+    if (notify) onChangeRef.current(null, null)
+  }, [invalidateResults])
+  React.useEffect(() => { reset(false) }, [documentId, principalType, reset])
+  React.useEffect(() => { if (!value) reset(false) }, [reset, value])
+
+  const enterError = React.useCallback(() => {
+    invalidateResults()
+    setFetchError(true); setOpenState(false)
+  }, [invalidateResults])
+
+  const fetchPage = React.useCallback(async (query: string, nextPage: number, append: boolean) => {
+    const requestId = ++request.current
+    const requestContext = buildResultContext(documentId, principalType, query)
+    const controller = new AbortController()
+    activeRequest.current?.abort()
+    activeRequest.current = controller
+    if (append) setLoadingMore(true)
+    else { resultContext.current = null; setItems([]); setLoading(true); setHasFetched(false); setActiveIndex(-1) }
+    setFetchError(false)
+    try {
+      const call = await apiCall<PrincipalListPayload>(
+        buildPrincipalUrl(documentId, principalType, query, nextPage),
+        { headers: OPTIONAL_HEADERS, signal: controller.signal },
+        { fallback: { items: [], total: 0, totalPages: 1 } },
+      )
+      if (request.current !== requestId || activeContext.current !== requestContext) return
+      if (!call.ok) { enterError(); return }
+      const result = readPrincipalPage(call.result, principalType, nextPage, fallbackLabel)
+      resultContext.current = requestContext
+      setItems((current) => append ? mergePrincipalOptions(current, result.items) : result.items)
+      setPage(nextPage); setTotal(result.total); setTotalPages(result.totalPages)
+      setFetchError(false); setHasFetched(true); setOpenState(true)
+      if (!append) setActiveIndex(result.items.length ? 0 : -1)
+      else if (result.items.length) setActiveIndex((current) => current < 0 ? 0 : current)
+    } catch {
+      if (!controller.signal.aborted && request.current === requestId && activeContext.current === requestContext) enterError()
+    } finally {
+      if (request.current === requestId) {
+        if (activeRequest.current === controller) activeRequest.current = null
+        append ? setLoadingMore(false) : setLoading(false)
+      }
+    }
+  }, [documentId, enterError, fallbackLabel, principalType])
+
+  React.useEffect(() => {
+    if (disabled || fetchError || !open || selectedLabel) return
+    const query = searchValue.trim()
+    if (query.length > 0 && query.length < PRINCIPAL_SEARCH_MIN_LENGTH) return
+    const timer = window.setTimeout(() => { void fetchPage(query, 1, false) }, PRINCIPAL_DEBOUNCE_MS)
+    return () => window.clearTimeout(timer)
+  }, [disabled, fetchError, fetchPage, open, searchValue, selectedLabel])
+
+  const selectOption = React.useCallback((option: PrincipalOption) => {
+    if (disabled || resultContext.current === null || resultContext.current !== activeContext.current) return
+    invalidateResults()
+    setSelectedLabel(option.label); setSearchValue(''); setOpenState(false); setFetchError(false)
+    onChangeRef.current(option.id, option.label)
+  }, [disabled, invalidateResults])
+  const changeSearch = React.useCallback((next: string) => {
+    if (selectedLabel || value) onChangeRef.current(null, null)
+    activeContext.current = buildResultContext(documentId, principalType, next)
+    invalidateResults()
+    setSelectedLabel(null); setSearchValue(next); setFetchError(false); setOpenState(true)
+  }, [documentId, invalidateResults, principalType, selectedLabel, value])
+  const setOpen = React.useCallback((nextOpen: boolean) => {
+    if (disabled && nextOpen) return
+    if (!nextOpen) invalidateResults()
+    setOpenState(nextOpen)
+  }, [disabled, invalidateResults])
+  const loadMore = React.useCallback(() => {
+    if (!disabled && resultContext.current === activeContext.current && !loading && !loadingMore && page < totalPages) {
+      void fetchPage(searchValue.trim(), page + 1, true)
+    }
+  }, [disabled, fetchPage, loading, loadingMore, page, searchValue, totalPages])
+  const retry = React.useCallback(() => { setFetchError(false); setOpenState(false); void fetchPage(searchValue.trim(), 1, false) }, [fetchPage, searchValue])
+  const hasCurrentResult = resultContext.current !== null && resultContext.current === currentContext
+  const visibleItems = hasCurrentResult ? items : []
+  const handleKeyDown = React.useCallback((event: React.KeyboardEvent<HTMLDivElement>) => {
+    if ((event.metaKey || event.ctrlKey) && event.key === 'Enter') return
+    if (event.key === 'Escape' && open) { event.preventDefault(); event.stopPropagation(); setOpen(false); return }
+    if (!open || !visibleItems.length) return
+    if (event.key === 'ArrowDown') { event.preventDefault(); setActiveIndex((index) => Math.min(index + 1, visibleItems.length - 1)); return }
+    if (event.key === 'ArrowUp') { event.preventDefault(); setActiveIndex((index) => Math.max(index - 1, 0)); return }
+    if (event.key === 'Enter' && visibleItems[activeIndex]) { event.preventDefault(); selectOption(visibleItems[activeIndex]) }
+  }, [activeIndex, open, selectOption, setOpen, visibleItems])
+
+  React.useEffect(() => () => { activeRequest.current?.abort() }, [])
+
+  return {
+    searchValue, selectedLabel, items: visibleItems, open, setOpen, loading, loadingMore, fetchError,
+    hasFetched: hasCurrentResult && hasFetched, page, total, totalPages,
+    activeIndex: hasCurrentResult ? activeIndex : -1, setActiveIndex,
+    displayValue: selectedLabel ?? searchValue, changeSearch, clear: () => reset(true),
+    selectOption, loadMore, retry, handleKeyDown,
+  }
+}