DOCX source adapter

1"use client";
2 
3import * as React from "react";
4 
5import type { Source, SourceAnchor } from "@/lib/document-source";
6import type { DocxTarget, DocxViewerHandle } from "@/components/ui/docx-viewer";
7 
8export interface SourceTarget {
9  scrollTo?: (source: Source, options: { behavior: ScrollBehavior }) => void;
10}
11 
12/**
13 * A docx anchor + source payload -> a viewer-ready `DocxTarget`, or null when
14 * the anchor is not a docx anchor. Text spans carry the quoted `content` from
15 * the source; table cells carry their index. The adapter resolves the source
16 * model, while the viewer resolves the rendered DOM.
17 */
18export function docxAnchorToTarget(
19  anchor: SourceAnchor | undefined,
20  source?: Source,
21): DocxTarget | null {
22  if (!anchor) return null;
23  if (anchor.kind === "docx_text_span") {
24    if (
25      !isNonNegativeInteger(anchor.paragraph) ||
26      !isValidOptionalRange(anchor.char_start, anchor.char_end)
27    )
28      return null;
29    const text = source?.content.trim();
30    return text ? { kind: "text", text } : null;
31  }
32  if (anchor.kind === "docx_table_cell") {
33    if (
34      !isNonNegativeInteger(anchor.table) ||
35      !isNonNegativeInteger(anchor.row) ||
36      !isNonNegativeInteger(anchor.column) ||
37      !isValidOptionalRange(anchor.char_start, anchor.char_end)
38    )
39      return null;
40    return {
41      kind: "cell",
42      table: anchor.table,
43      row: anchor.row,
44      column: anchor.column,
45    };
46  }
47  return null;
48}
49 
50function isNonNegativeInteger(value: number) {
51  return Number.isInteger(value) && value >= 0;
52}
53 
54function isValidOptionalRange(start?: number, end?: number) {
55  if (start == null && end == null) return true;
56  if (start == null || end == null) return false;
57  return (
58    Number.isInteger(start) &&
59    Number.isInteger(end) &&
60    start >= 0 &&
61    end >= start
62  );
63}
64 
65/** A stable source target over a `DocxViewer` ref. */
66export function useDocxSourceTarget(
67  viewerRef: React.RefObject<DocxViewerHandle | null>,
68): SourceTarget {
69  return React.useMemo<SourceTarget>(
70    () => ({
71      scrollTo: (source: Source, options) => {
72        const target = docxAnchorToTarget(source.anchor, source);
73        if (target) viewerRef.current?.scrollToTarget(target, options);
74      },
75    }),
76    [viewerRef],
77  );
78}
79 
80/**
81 * The `highlight` prop for `DocxViewer` derived from a source; non-docx
82 * anchors resolve to null.
83 */
84export function sourceToDocxHighlight(
85  source: Source | undefined,
86): DocxTarget | null {
87// … truncated