@beyondwork/docx-react-component 1.0.29 → 1.0.30

package/src/core/search/search-text.ts

@@ -0,0 +1,357 @@
+import type {
+  EditorStoryTarget,
+  SearchOptions as PublicSearchOptions,
+  SecondaryStorySurface,
+  SurfaceBlockSnapshot,
+  WorkflowCandidateRange,
+} from "../../api/public-types";
+
+export interface SearchTextOptions extends PublicSearchOptions {
+  caseSensitive?: boolean;
+  regex?: boolean;
+}
+
+export interface SearchResult {
+  from: number;
+  to: number;
+  text: string;
+  index: number;
+}
+
+export interface SurfaceSearchResult extends SearchResult {
+  excerpt: string;
+}
+
+export interface SecondaryStorySearchResult extends SurfaceSearchResult {
+  storyTarget: EditorStoryTarget;
+}
+
+interface ProjectedSurfaceText {
+  text: string;
+  offsetMap: Array<number | null>;
+}
+
+interface SurfaceProjectionBuilder {
+  text: string[];
+  offsetMap: Array<number | null>;
+  nextRuntimeOffset: number;
+}
+
+export function buildSearchPattern(
+  query: string,
+  options: SearchTextOptions = {},
+): RegExp | null {
+  if (!query) {
+    return null;
+  }
+
+  const caseSensitive = options.matchCase ?? options.caseSensitive ?? false;
+  const regex = options.regex ?? false;
+  const wholeWord = options.wholeWord ?? false;
+
+  try {
+    const source = regex
+      ? query
+      : query.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const wrapped = wholeWord ? `\\b${source}\\b` : source;
+    return new RegExp(wrapped, caseSensitive ? "g" : "gi");
+  } catch {
+    return null;
+  }
+}
+
+export function findSearchMatches(
+  text: string,
+  query: string,
+  options: SearchTextOptions = {},
+): SearchResult[] {
+  const pattern = buildSearchPattern(query, options);
+  if (!pattern) return [];
+
+  const results: SearchResult[] = [];
+  let match: RegExpExecArray | null;
+  pattern.lastIndex = 0;
+  while ((match = pattern.exec(text)) !== null) {
+    results.push({
+      from: match.index,
+      to: match.index + match[0].length,
+      text: match[0],
+      index: results.length,
+    });
+
+    if (match[0].length === 0) {
+      pattern.lastIndex += 1;
+    }
+  }
+
+  return results;
+}
+
+export function createSearchExcerpt(
+  text: string,
+  from: number,
+  to: number,
+  radius = 24,
+): string {
+  const safeFrom = Math.max(0, Math.min(from, text.length));
+  const safeTo = Math.max(safeFrom, Math.min(to, text.length));
+  const start = Math.max(0, safeFrom - radius);
+  const end = Math.min(text.length, safeTo + radius);
+  const prefix = start > 0 ? "…" : "";
+  const suffix = end < text.length ? "…" : "";
+  const excerpt = text
+    .slice(start, end)
+    .replace(/[\uFFF9\uFFFA]/gu, "")
+    .replace(/\s{2,}/gu, " ")
+    .trim();
+  return `${prefix}${excerpt}${suffix}`;
+}
+
+export function searchSurfaceBlocks(
+  blocks: readonly SurfaceBlockSnapshot[],
+  query: string,
+  options: SearchTextOptions = {},
+): SurfaceSearchResult[] {
+  const projection = projectSurfaceText(blocks);
+  return findSearchMatches(projection.text, query, options)
+    .map((match) => {
+      const range = resolveProjectedRuntimeRange(
+        projection.offsetMap,
+        match.from,
+        match.to,
+      );
+      if (!range) {
+        return null;
+      }
+
+      return {
+        ...match,
+        from: range.from,
+        to: range.to,
+        excerpt: createSearchExcerpt(projection.text, match.from, match.to),
+      };
+    })
+    .filter((match): match is SurfaceSearchResult => Boolean(match));
+}
+
+export function searchSecondaryStories(
+  stories: readonly SecondaryStorySurface[],
+  query: string,
+  options: SearchTextOptions = {},
+): SecondaryStorySearchResult[] {
+  const results: SecondaryStorySearchResult[] = [];
+
+  for (const story of stories) {
+    for (const match of searchSurfaceBlocks(story.blocks, query, options)) {
+      results.push({
+        storyTarget: story.target,
+        from: match.from,
+        to: match.to,
+        text: match.text,
+        index: results.length,
+        excerpt: match.excerpt,
+      });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Derive workflow candidate ranges from search results.
+ *
+ * Maps search hits into `WorkflowCandidateRange` values suitable for
+ * inclusion in a host-fed `WorkflowOverlay`. The runtime search results
+ * supply runtime-mapped `from`/`to` positions that align with the
+ * canonical document model.
+ */
+export function deriveCandidateRangesFromSearch(
+  results: readonly SurfaceSearchResult[],
+  storyTarget?: EditorStoryTarget,
+  source: WorkflowCandidateRange["source"] = "search",
+): WorkflowCandidateRange[] {
+  return results.map((result, index) => ({
+    candidateId: `search-candidate-${index}`,
+    storyTarget,
+    anchor: {
+      kind: "range" as const,
+      from: result.from,
+      to: result.to,
+      assoc: { start: 1 as const, end: -1 as const },
+    },
+    label: result.excerpt,
+    source,
+  }));
+}
+
+export function projectSurfaceText(
+  blocks: readonly SurfaceBlockSnapshot[],
+): ProjectedSurfaceText {
+  const builder: SurfaceProjectionBuilder = {
+    text: [],
+    offsetMap: [],
+    nextRuntimeOffset: 0,
+  };
+
+  appendSurfaceBlocks(builder, blocks);
+
+  return {
+    text: builder.text.join(""),
+    offsetMap: builder.offsetMap,
+  };
+}
+
+function appendSurfaceBlocks(
+  builder: SurfaceProjectionBuilder,
+  blocks: readonly SurfaceBlockSnapshot[],
+): void {
+  for (const block of blocks) {
+    if (block.kind === "opaque_block") {
+      if (block.fragmentId.startsWith("preview:")) {
+        continue;
+      }
+      appendAtomicSpan(builder, block.from, block.to, "\uFFFA");
+      continue;
+    }
+
+    if (block.kind === "table") {
+      appendRuntimeGap(builder, block.from);
+      for (const [rowIndex, row] of block.rows.entries()) {
+        if (rowIndex > 0) {
+          appendSyntheticSeparator(builder, "\n");
+        }
+        for (const [cellIndex, cell] of row.cells.entries()) {
+          if (cellIndex > 0) {
+            appendSyntheticSeparator(builder, "\t");
+          }
+          appendSurfaceBlocks(builder, cell.content);
+        }
+      }
+      appendRuntimeGap(builder, block.to);
+      continue;
+    }
+
+    if (block.kind === "sdt_block") {
+      appendRuntimeGap(builder, block.from);
+      appendSurfaceBlocks(builder, block.children);
+      appendRuntimeGap(builder, block.to);
+      continue;
+    }
+
+    for (const segment of block.segments) {
+      switch (segment.kind) {
+        case "text":
+          appendTextSpan(builder, segment.text, segment.from);
+          break;
+        case "tab":
+          appendAtomicSpan(builder, segment.from, segment.to, "\t");
+          break;
+        case "hard_break":
+          appendAtomicSpan(builder, segment.from, segment.to, "\n");
+          break;
+        case "image":
+          appendAtomicSpan(builder, segment.from, segment.to, "\uFFFC");
+          break;
+        case "opaque_inline":
+          appendAtomicSpan(builder, segment.from, segment.to, "\uFFF9");
+          break;
+        case "note_ref":
+          appendAtomicSpan(builder, segment.from, segment.to, "\uFFFA");
+          break;
+      }
+    }
+
+    appendRuntimeGap(builder, block.to);
+  }
+}
+
+function appendTextSpan(
+  builder: SurfaceProjectionBuilder,
+  text: string,
+  startOffset: number,
+): void {
+  appendRuntimeGap(builder, startOffset);
+
+  for (let index = 0; index < text.length; index += 1) {
+    builder.text.push(text[index]!);
+    builder.offsetMap.push(startOffset + index);
+  }
+
+  builder.nextRuntimeOffset = Math.max(
+    builder.nextRuntimeOffset,
+    startOffset + text.length,
+  );
+}
+
+function appendAtomicSpan(
+  builder: SurfaceProjectionBuilder,
+  from: number,
+  to: number,
+  char: string,
+): void {
+  appendRuntimeGap(builder, from);
+  const width = Math.max(1, to - from);
+
+  for (let index = 0; index < width; index += 1) {
+    builder.text.push(char);
+    builder.offsetMap.push(from + index);
+  }
+
+  builder.nextRuntimeOffset = Math.max(builder.nextRuntimeOffset, to);
+}
+
+function appendRuntimeGap(
+  builder: SurfaceProjectionBuilder,
+  nextFrom: number,
+): void {
+  for (
+    let offset = builder.nextRuntimeOffset;
+    offset < nextFrom;
+    offset += 1
+  ) {
+    builder.text.push("\n");
+    builder.offsetMap.push(offset);
+  }
+
+  builder.nextRuntimeOffset = Math.max(builder.nextRuntimeOffset, nextFrom);
+}
+
+function appendSyntheticSeparator(
+  builder: SurfaceProjectionBuilder,
+  value: string,
+): void {
+  for (const char of value) {
+    builder.text.push(char);
+    builder.offsetMap.push(null);
+  }
+}
+
+function resolveProjectedRuntimeRange(
+  offsetMap: ReadonlyArray<number | null>,
+  from: number,
+  to: number,
+): { from: number; to: number } | null {
+  let runtimeFrom: number | undefined;
+  for (let index = from; index < to; index += 1) {
+    const offset = offsetMap[index];
+    if (offset !== null && offset !== undefined) {
+      runtimeFrom = offset;
+      break;
+    }
+  }
+
+  let runtimeTo: number | undefined;
+  for (let index = to - 1; index >= from; index -= 1) {
+    const offset = offsetMap[index];
+    if (offset !== null && offset !== undefined) {
+      runtimeTo = offset + 1;
+      break;
+    }
+  }
+
+  if (runtimeFrom === undefined || runtimeTo === undefined) {
+    return null;
+  }
+
+  return { from: runtimeFrom, to: runtimeTo };
+}

package/src/core/selection/README.md

@@ -0,0 +1,3 @@
+# Core Selection
+
+Selections, ranges, position mapping, and anchor remapping helpers belong here.

package/src/core/selection/mapping.ts

@@ -0,0 +1,289 @@
+import type { EditorStoryTarget } from "../../api/public-types";
+
+export type Position = number;
+export type Assoc = -1 | 1;
+
+export interface DocRange {
+  from: Position;
+  to: Position;
+}
+
+export interface BoundaryAssoc {
+  start: Assoc;
+  end: Assoc;
+}
+
+export interface RangeAnchor {
+  kind: "range";
+  range: DocRange;
+  assoc: BoundaryAssoc;
+}
+
+export interface NodeAnchor {
+  kind: "node";
+  at: Position;
+  assoc: Assoc;
+}
+
+export interface DetachedAnchor {
+  kind: "detached";
+  lastKnownRange: DocRange;
+  reason: "deleted" | "invalidatedByStructureChange" | "importAmbiguity";
+}
+
+export type EditorAnchorProjection = RangeAnchor | NodeAnchor | DetachedAnchor;
+
+export interface MappingStep {
+  from: Position;
+  to: Position;
+  insertSize: number;
+}
+
+export interface MappingResult {
+  position: Position;
+  deleted: boolean;
+}
+
+export interface TransactionMapping {
+  steps: MappingStep[];
+  metadata?: {
+    invalidatesStructures?: boolean;
+    affectsComments?: boolean;
+    affectsRevisions?: boolean;
+    affectsOpaqueFragments?: boolean;
+    [key: string]: unknown;
+  };
+}
+
+export const DEFAULT_BOUNDARY_ASSOC: BoundaryAssoc = {
+  start: 1,
+  end: -1,
+};
+
+export function createRangeAnchor(
+  from: Position,
+  to = from,
+  assoc: BoundaryAssoc = DEFAULT_BOUNDARY_ASSOC,
+): RangeAnchor {
+  return {
+    kind: "range",
+    range: normalizeRange({ from, to }),
+    assoc,
+  };
+}
+
+export function createNodeAnchor(at: Position, assoc: Assoc = 1): NodeAnchor {
+  return {
+    kind: "node",
+    at,
+    assoc,
+  };
+}
+
+export function createDetachedAnchor(
+  lastKnownRange: DocRange,
+  reason: DetachedAnchor["reason"],
+): DetachedAnchor {
+  return {
+    kind: "detached",
+    lastKnownRange: normalizeRange(lastKnownRange),
+    reason,
+  };
+}
+
+export function createEmptyMapping(): TransactionMapping {
+  return {
+    steps: [],
+  };
+}
+
+export function normalizeRange(range: DocRange): DocRange {
+  return range.from <= range.to
+    ? { from: range.from, to: range.to }
+    : { from: range.to, to: range.from };
+}
+
+export function getEffectiveRange(anchor: EditorAnchorProjection): DocRange {
+  if (anchor.kind === "range") {
+    return anchor.range;
+  }
+  if (anchor.kind === "node") {
+    return { from: anchor.at, to: anchor.at };
+  }
+  return anchor.lastKnownRange;
+}
+
+export function mapPosition(
+  position: Position,
+  assoc: Assoc,
+  mapping: TransactionMapping,
+): MappingResult {
+  let mappedPosition = position;
+  let deleted = false;
+
+  for (const step of mapping.steps) {
+    const next = mapPositionThroughStep(mappedPosition, assoc, step);
+    mappedPosition = next.position;
+    deleted = deleted || next.deleted;
+  }
+
+  return {
+    position: mappedPosition,
+    deleted,
+  };
+}
+
+export function mapAnchor(
+  anchor: EditorAnchorProjection,
+  mapping: TransactionMapping,
+): EditorAnchorProjection {
+  if (anchor.kind === "detached") {
+    return anchor;
+  }
+
+  if (anchor.kind === "node") {
+    const mapped = mapPosition(anchor.at, anchor.assoc, mapping);
+
+    if (mapped.deleted) {
+      return createDetachedAnchor(
+        { from: anchor.at, to: anchor.at + 1 },
+        mapping.metadata?.invalidatesStructures
+          ? "invalidatedByStructureChange"
+          : "deleted",
+      );
+    }
+
+    return createNodeAnchor(mapped.position, anchor.assoc);
+  }
+
+  const from = mapPosition(anchor.range.from, anchor.assoc.start, mapping);
+  const to = mapPosition(anchor.range.to, anchor.assoc.end, mapping);
+  const mappedRange = normalizeRange({ from: from.position, to: to.position });
+
+  if (from.deleted && to.deleted && mappedRange.from === mappedRange.to) {
+    return createDetachedAnchor(
+      anchor.range,
+      mapping.metadata?.invalidatesStructures
+        ? "invalidatedByStructureChange"
+        : "deleted",
+    );
+  }
+
+  return createRangeAnchor(mappedRange.from, mappedRange.to, anchor.assoc);
+}
+
+export function mapRange(
+  range: DocRange,
+  assoc: BoundaryAssoc,
+  mapping: TransactionMapping,
+): RangeAnchor | DetachedAnchor {
+  const mapped = mapAnchor(createRangeAnchor(range.from, range.to, assoc), mapping);
+  return mapped.kind === "node" ? createRangeAnchor(mapped.at, mapped.at, assoc) : mapped;
+}
+
+export function areAnchorsEqual(
+  left: EditorAnchorProjection,
+  right: EditorAnchorProjection,
+): boolean {
+  if (left.kind !== right.kind) {
+    return false;
+  }
+
+  if (left.kind === "detached" && right.kind === "detached") {
+    return (
+      left.reason === right.reason &&
+      left.lastKnownRange.from === right.lastKnownRange.from &&
+      left.lastKnownRange.to === right.lastKnownRange.to
+    );
+  }
+
+  if (left.kind === "node" && right.kind === "node") {
+    return left.at === right.at && left.assoc === right.assoc;
+  }
+
+  if (left.kind === "range" && right.kind === "range") {
+    return (
+      left.range.from === right.range.from &&
+      left.range.to === right.range.to &&
+      left.assoc.start === right.assoc.start &&
+      left.assoc.end === right.assoc.end
+    );
+  }
+
+  return false;
+}
+
+export function storyTargetsEqual(
+  left: EditorStoryTarget | undefined,
+  right: EditorStoryTarget | undefined,
+): boolean {
+  if (left === right) return true;
+  if (!left || !right) return left === right;
+  if (left.kind !== right.kind) return false;
+  if (left.kind === "main") return true;
+  if (left.kind === "header" && right.kind === "header") {
+    return (
+      left.relationshipId === right.relationshipId &&
+      left.variant === right.variant &&
+      (left.sectionIndex === undefined ||
+      right.sectionIndex === undefined
+        ? true
+        : left.sectionIndex === right.sectionIndex)
+    );
+  }
+  if (left.kind === "footer" && right.kind === "footer") {
+    return (
+      left.relationshipId === right.relationshipId &&
+      left.variant === right.variant &&
+      (left.sectionIndex === undefined ||
+      right.sectionIndex === undefined
+        ? true
+        : left.sectionIndex === right.sectionIndex)
+    );
+  }
+  if (left.kind === "footnote" && right.kind === "footnote") {
+    return left.noteId === right.noteId;
+  }
+  if (left.kind === "endnote" && right.kind === "endnote") {
+    return left.noteId === right.noteId;
+  }
+  return false;
+}
+
+export const MAIN_STORY_TARGET: EditorStoryTarget = { kind: "main" };
+
+function mapPositionThroughStep(
+  position: Position,
+  assoc: Assoc,
+  step: MappingStep,
+): MappingResult {
+  if (position < step.from) {
+    return { position, deleted: false };
+  }
+
+  if (position > step.to) {
+    return {
+      position: position + step.insertSize - (step.to - step.from),
+      deleted: false,
+    };
+  }
+
+  if (position === step.from) {
+    return {
+      position: assoc < 0 ? step.from : step.from + step.insertSize,
+      deleted: false,
+    };
+  }
+
+  if (position === step.to) {
+    return {
+      position: assoc < 0 ? step.from : step.from + step.insertSize,
+      deleted: false,
+    };
+  }
+
+  return {
+    position: assoc < 0 ? step.from : step.from + step.insertSize,
+    deleted: true,
+  };
+}