@arbidocs/blocks 0.4.103 → 0.4.104

package/dist/docx/references/commands.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Insert cross-references, the way Word does.
+ *
+ * Within the document: a hidden `_Ref…` bookmark on the target paragraph and a `REF` field at the
+ * caret — `REF _Ref123 \r \h` for a numbered paragraph (Word's Cross-reference › Numbered item ›
+ * Paragraph number), `REF _Ref123 \h` for a heading's text. The field's cached result is the value
+ * the editor computes, so it updates live when the clauses are renumbered, and Word updates it
+ * with the document's other fields.
+ *
+ * To another document: a hyperlink with the reference text ("SPA, clause 8.2"), aimed at the app
+ * address of that document's passage (so it works from Word too), with a screen tip saying so.
+ */
+import { type DocPoint } from '../definitions/port';
+import { type CrossReferenceTarget } from './numbering';
+import type { ReferencesPort } from './port';
+/** Prefix of Word's hidden cross-reference bookmarks. */
+export declare const REF_BOOKMARK_PREFIX = "_Ref";
+/** A new `_Ref` bookmark name: Word's shape (`_Ref` and nine digits), not yet in the document. */
+export declare function newRefBookmark(taken: ReadonlySet<string>, random?: () => number): string;
+/**
+ * A complex `REF` field with its cached result, every run in the Cross Reference style (Word gives
+ * an updated result the formatting of the field's first run).
+ */
+export declare function refFieldXml(instruction: string, cached: string): string;
+/** The screen tip of a reference to this document: "Cross-reference to clause 2.2". */
+export declare const refTooltip: (value: string, mode: CrossReferenceMode) => string;
+/**
+ * A reference to this document: the `REF` field inside a link to the same bookmark, which carries
+ * the screen tip Word shows on hover ("Cross-reference to clause 2.2").
+ */
+export declare function crossReferenceXml(bookmark: string, mode: CrossReferenceMode, value: string): string;
+export type CrossReferenceMode = 'number' | 'text';
+/** The field instruction for a target: its paragraph number, or its text. */
+export declare const refInstruction: (bookmark: string, mode: CrossReferenceMode) => string;
+/** What the reference reads in the text. */
+export declare const refResult: (target: CrossReferenceTarget, mode: CrossReferenceMode) => string;
+/**
+ * The `_Ref` bookmark a target carries: an existing one at the paragraph, else a new one. For a
+ * paragraph number it is an empty bookmark at the paragraph's start (the number is the
+ * paragraph's); for heading text it wraps the heading's runs (REF shows the bookmarked text).
+ */
+export declare function ensureTargetBookmark(port: ReferencesPort, target: CrossReferenceTarget, mode: CrossReferenceMode): string;
+/**
+ * Mark a cross-reference's target (see {@link ensureTargetBookmark}): what the reference will
+ * address and read. A paragraph number falls back to the heading text when it has none. Done as a
+ * direct edit even while suggesting — the bookmark is hidden, and a heading's text is put back as
+ * it was — so rejecting the reference leaves the target as it was.
+ */
+export declare function markCrossReferenceTarget(port: ReferencesPort, target: CrossReferenceTarget, mode: CrossReferenceMode): {
+    bookmark: string;
+    mode: CrossReferenceMode;
+    value: string;
+};
+/**
+ * Insert the `REF` field of a marked target at `caret`; the caret ends after it. With a port
+ * whose pastes are tracked, the reference is one suggestion.
+ */
+export declare function insertCrossReferenceField(port: ReferencesPort, { bookmark, mode, value }: {
+    bookmark: string;
+    mode: CrossReferenceMode;
+    value: string;
+}, caret: DocPoint): {
+    bookmark: string;
+};
+/** Insert a cross-reference to a target of this document at `caret`; the caret ends after it. */
+export declare function insertCrossReference(port: ReferencesPort, target: CrossReferenceTarget, mode: CrossReferenceMode, caret: DocPoint): {
+    bookmark: string;
+};
+/** The screen tip of a reference to another document: "Cross-reference: SPA, clause 8.2 — opens in ARBI". */
+export declare const documentReferenceTooltip: (text: string, appName?: string) => string;
+/**
+ * Insert a reference to another document's passage: the reference text in the Cross Reference
+ * style, linked to the passage's (absolute) app address, at `caret`.
+ */
+export declare function insertDocumentReference(port: ReferencesPort, reference: {
+    text: string;
+    url: string;
+    appName?: string;
+}, caret: DocPoint): void;
+/** A `REF` field whose cached result no longer says what its target now is. */
+export interface StaleReference {
+    paragraphId: string;
+    offset: number;
+    instruction: string;
+    /** The current value, or null when the target is gone (the reference is broken). */
+    value: string | null;
+    /** The field's cached result (what it last showed). */
+    cached: string;
+    bookmark: string;
+    mode: CrossReferenceMode;
+}
+/** A cross-reference whose target was deleted: its last text, marked in the Broken style. */
+export interface BrokenReference {
+    paragraphId: string;
+    offset: number;
+    text: string;
+}
+/**
+ * The cross-references whose cached result is out of date: a clause renumbered, a heading
+ * reworded. The editor paints a field's live value only while its cached result matches what it
+ * computes, so a stale cache shows the OLD number after the document is reopened (and Word shows
+ * the cached result until its fields are updated).
+ */
+export declare function staleCrossReferences(port: ReferencesPort): StaleReference[];
+/** The broken cross-references marked in the document, in document order. */
+export declare function brokenCrossReferences(port: ReferencesPort): BrokenReference[];
+export interface RefreshResult {
+    /** References rewritten with their current number or text. */
+    refreshed: number;
+    /** References whose target is gone, now (or already) marked broken. */
+    broken: BrokenReference[];
+}
+/**
+ * Bring every cross-reference up to date: a stale one is replaced by the same reference with its
+ * current value (and screen tip); one whose target was deleted becomes its last text in the Cross
+ * Reference Broken style — never Word's "Error! Reference source not found." A field directly
+ * after another field is left alone: a paste there would land inside the previous field.
+ */
+export declare function refreshCrossReferences(port: ReferencesPort): RefreshResult;

package/dist/docx/references/numbering.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Cross-reference targets: the document's numbered paragraphs (clauses, sub-clauses, numbered
+ * captions) and its headings, with the number Word's `REF \r` shows for each.
+ *
+ * The number is what the editor computes for a `REF … \r` field — and it has to be exactly that,
+ * because the engine shows a field's live value only while the field's cached result matches what
+ * it computes (otherwise it keeps the cached text for good). So this mirrors the engine: the
+ * paragraph's own list level, preceded by each higher level whose number its level text does not
+ * already show (`%1.%2` already shows level 1; `(%3)` does not show `2.1`), and one trailing
+ * period dropped (`2.` reads `2`).
+ */
+import type { DocParagraph } from '../definitions/port';
+/** A paragraph's resolved list numbering (the engine's list item). */
+export interface ListItemInfo {
+    numId: string;
+    ilvl: number;
+    markerText: string;
+    numFmt: string;
+}
+/** A list level's definition: its level text (`%1.%2`) and number format. */
+export interface LevelInfo {
+    lvlText: string;
+    numFmt: string;
+}
+export type LevelOf = (numId: string, ilvl: number) => LevelInfo | null;
+/**
+ * The number `REF \r` shows for a paragraph, or null when it is not numbered. `order` is every
+ * paragraph id in document order (for the markers of the levels above it).
+ */
+export declare function paragraphNumber(order: readonly string[], items: ReadonlyMap<string, ListItemInfo>, levelOf: LevelOf, paragraphId: string): string | null;
+/** One place a cross-reference can point at. */
+export interface CrossReferenceTarget {
+    paragraphId: string;
+    /** A numbered paragraph (clause, sub-clause, caption) or an unnumbered heading. */
+    kind: 'numbered' | 'heading';
+    /** What `REF \r` shows (`8.2`), or null for an unnumbered heading. */
+    number: string | null;
+    /** The paragraph's list marker as painted (`8.2`, `(a)`), or empty. */
+    marker: string;
+    /** The paragraph's text (without its marker). */
+    text: string;
+    heading: boolean;
+    /** Its list level (0 for a top-level clause), or 0 for a heading. */
+    level: number;
+}
+/** Every numbered paragraph and every heading, in document order. */
+export declare function listTargets(paragraphs: readonly DocParagraph[], items: ReadonlyMap<string, ListItemInfo>, levelOf: LevelOf): CrossReferenceTarget[];
+/** Targets whose number or text contains the query (case-insensitive). */
+export declare function filterTargets(targets: readonly CrossReferenceTarget[], query: string): CrossReferenceTarget[];

package/dist/docx/references/passages.d.ts

@@ -0,0 +1,32 @@
+/**
+ * References to another document's passages: what a passage is, the reference text a lawyer would
+ * write for it ("SPA, clause 8.2", "Lease, p. 12"), and the passage text shown on hover.
+ */
+/** Where a cross-document reference points: a document's passage (its chunk) and page. */
+export interface DocumentPassageTarget {
+    documentId: string;
+    chunkId: string;
+    page?: number | null;
+}
+/** One passage of a document, as the reference picker lists it. */
+export interface DocumentPassage {
+    chunkId: string;
+    page?: number | null;
+    /** The passage text (Markdown). */
+    text: string;
+}
+/** A document the reference can point into. */
+export interface ReferenceDocument {
+    id: string;
+    title: string;
+}
+/** The document's name as a reference uses it: its own short name if it gives one, no extension. */
+export declare function shortTitle(title: string): string;
+/** The clause number a passage starts with: `8.2` for "8.2 The Seller…", `8` for "## 8. Sale". */
+export declare function passageClause(text: string): string | null;
+/** The reference text for a passage: "SPA, clause 8.2", else "SPA, p. 12", else "SPA". */
+export declare function referenceText(title: string, passage: Pick<DocumentPassage, 'text' | 'page'>): string;
+/** A passage as one line of plain text, for a tooltip or a hover card. */
+export declare function passageExcerpt(text: string, max?: number): string;
+/** Passages containing the query (case-insensitive), in document order. */
+export declare function filterPassages(passages: readonly DocumentPassage[], query: string): DocumentPassage[];

package/dist/docx/references/port.d.ts

@@ -0,0 +1,20 @@
+/**
+ * What the cross-reference commands need beyond the defined-term port: the document's list
+ * numbering as the engine resolves it, and a paragraph's runs as WordprocessingML (to wrap a
+ * heading's text in a bookmark without losing its formatting).
+ */
+import type { DocxEditorInstance } from '@docx-editor.dev/core';
+import type { Revision } from '@arbidocs/coedit/template';
+import { type DefinitionsPort, type OoxmlNodeLike } from '../definitions/port';
+import type { LevelOf, ListItemInfo } from './numbering';
+export interface ReferencesPort extends DefinitionsPort {
+    /** Each numbered paragraph's list item, by paragraph id. */
+    listItems(): ReadonlyMap<string, ListItemInfo>;
+    levelOf: LevelOf;
+    /** The paragraph's runs as WordprocessingML, or null when it holds more than plain runs. */
+    runsXml(paragraphId: string): string | null;
+}
+/** A paragraph's runs as XML (formatting kept), or null for anything but plain runs. */
+export declare function paragraphRunsXml(paragraph: OoxmlNodeLike): string | null;
+/** The port over a live editor; with a `revision`, what it pastes is a tracked insertion by it. */
+export declare function referencesPort(editor: DocxEditorInstance, revision?: Revision | null): ReferencesPort;

package/dist/facts/index.cjs

@@ -1,6 +1,7 @@
 "use client";
 'use strict';
 
+var chunk5FYU7ZIU_cjs = require('../chunk-5FYU7ZIU.cjs');
 var chunk2WLXQGWC_cjs = require('../chunk-2WLXQGWC.cjs');
 var chunkOUW6G4O2_cjs = require('../chunk-OUW6G4O2.cjs');
 var chunkVPPX5XUF_cjs = require('../chunk-VPPX5XUF.cjs');
@@ -8,8 +9,8 @@ var chunkRC25WMVB_cjs = require('../chunk-RC25WMVB.cjs');
 var chunk7RGLTF76_cjs = require('../chunk-7RGLTF76.cjs');
 var chunkV4ISCZJ7_cjs = require('../chunk-V4ISCZJ7.cjs');
 var chunk2EI7NCUA_cjs = require('../chunk-2EI7NCUA.cjs');
-var chunkPPCATBOY_cjs = require('../chunk-PPCATBOY.cjs');
 require('../chunk-C54XEN5T.cjs');
+var chunkPPCATBOY_cjs = require('../chunk-PPCATBOY.cjs');
 var chunkKDG6FER6_cjs = require('../chunk-KDG6FER6.cjs');
 var chunkIXALYQT7_cjs = require('../chunk-IXALYQT7.cjs');
 require('../chunk-FX3K6LNZ.cjs');
@@ -1118,129 +1119,6 @@ function FactDateInput({ value, onChange, idPrefix, labels, testIds }) {
     ] })
   ] }) });
 }
-var DEFAULT_FACT_PASSAGES_LABELS = {
-  loading: "Loading passage\u2026",
-  close: "Close"
-};
-function toPreviewLine(md) {
-  return md.replace(/`{1,3}([^`]*)`{1,3}/g, "$1").replace(/!\[[^\]]*\]\([^)]*\)/g, "").replace(/\[([^\]]*)\]\([^)]*\)/g, "$1").replace(/^[>\s]*#{1,6}\s*/gm, "").replace(/^[>\s]*[-*+]\s+/gm, "").replace(/[*_~]/g, "").replace(/\|/g, " ").replace(/\s+/g, " ").trim();
-}
-var SUP_SUB_RE = /<(sup|sub)>([\s\S]*?)<\/\1>/gi;
-var STRAY_SUP_SUB_RE = /<\/?(?:sup|sub)>/gi;
-var stripStrayTags = (s) => s.replace(STRAY_SUP_SUB_RE, "");
-function renderPreviewInline(line) {
-  const nodes = [];
-  let last = 0;
-  let key = 0;
-  for (const m of line.matchAll(SUP_SUB_RE)) {
-    const start = m.index ?? 0;
-    if (start > last) nodes.push(stripStrayTags(line.slice(last, start)));
-    const inner = stripStrayTags(m[2]);
-    nodes.push(
-      m[1].toLowerCase() === "sup" ? /* @__PURE__ */ jsxRuntime.jsx("sup", { children: inner }, key++) : /* @__PURE__ */ jsxRuntime.jsx("sub", { children: inner }, key++)
-    );
-    last = start + m[0].length;
-  }
-  if (last < line.length) nodes.push(stripStrayTags(line.slice(last)));
-  return nodes;
-}
-function FactPassageItem({
-  index,
-  page,
-  excerpt,
-  isViewing,
-  onSelect,
-  testId,
-  className,
-  labels
-}) {
-  const l = { ...DEFAULT_FACT_PASSAGES_LABELS, ...labels };
-  return /* @__PURE__ */ jsxRuntime.jsxs(
-    "button",
-    {
-      type: "button",
-      onClick: onSelect,
-      "data-testid": chunkMHVNT4J3_cjs.testIdOr(testId, { testId: "fact-source-passage" }),
-      "aria-current": isViewing || void 0,
-      className: ui.cn(
-        "flex w-full items-start gap-2 rounded px-2 py-1.5 text-left text-xs transition-colors pointer-coarse:min-h-11",
-        isViewing ? "bg-ai-soft text-foreground ring-1 ring-ai-accent/40" : "bg-ai-soft/60 text-foreground hover:bg-ai-soft",
-        className
-      ),
-      children: [
-        /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "mt-0.5 shrink-0 rounded bg-muted px-1 py-0.5 font-mono text-xs text-muted-foreground", children: [
-          index + 1,
-          "."
-        ] }),
-        page != null && /* @__PURE__ */ jsxRuntime.jsxs("span", { className: "mt-0.5 shrink-0 rounded-full bg-muted px-1.5 py-0.5 font-mono text-xs text-muted-foreground", children: [
-          "p.",
-          page
-        ] }),
-        /* @__PURE__ */ jsxRuntime.jsx("span", { className: "block min-w-0 flex-1 overflow-hidden text-ellipsis whitespace-nowrap", children: excerpt ? /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
-          "\u201C",
-          renderPreviewInline(toPreviewLine(excerpt)),
-          "\u201D"
-        ] }) : l.loading })
-      ]
-    }
-  );
-}
-function FactSourcesPanel({
-  title,
-  onClose,
-  container,
-  children,
-  labels,
-  testIds
-}) {
-  const l = { ...DEFAULT_FACT_PASSAGES_LABELS, ...labels };
-  return /* @__PURE__ */ jsxRuntime.jsxs(
-    ui.PopoverContent,
-    {
-      align: "start",
-      side: "bottom",
-      sideOffset: 4,
-      collisionPadding: 16,
-      container,
-      collisionBoundary: container ?? void 0,
-      onInteractOutside: (e) => {
-        const target = e.detail.originalEvent.target;
-        if (target?.closest(
-          '[data-testid="parsed-viewer"], [role="dialog"], [data-radix-popper-content-wrapper]'
-        )) {
-          e.preventDefault();
-        }
-      },
-      className: "w-[34rem] max-w-[var(--radix-popover-content-available-width)] p-0 data-[state=closed]:animate-none",
-      "data-testid": chunkMHVNT4J3_cjs.testIdOr(testIds?.popover, { testId: "fact-sources-popover" }),
-      "data-slot": "fact-sources-panel",
-      children: [
-        /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "sticky top-0 z-10 flex items-center justify-between gap-2 border-b border-border bg-popover px-3 py-2", children: [
-          /* @__PURE__ */ jsxRuntime.jsx("span", { className: "text-xs font-semibold text-muted-foreground", children: title }),
-          /* @__PURE__ */ jsxRuntime.jsx(
-            "button",
-            {
-              type: "button",
-              "aria-label": l.close,
-              "data-testid": chunkMHVNT4J3_cjs.testIdOr(testIds?.close, { testId: "fact-sources-close" }),
-              onClick: onClose,
-              className: "-m-1.5 flex shrink-0 items-center justify-center rounded p-1.5 text-muted-foreground transition-colors hover:bg-muted hover:text-foreground pointer-coarse:p-3",
-              children: /* @__PURE__ */ jsxRuntime.jsx(lucideReact.X, { className: "size-3.5" })
-            }
-          )
-        ] }),
-        /* @__PURE__ */ jsxRuntime.jsx(
-          "div",
-          {
-            className: "flex max-h-[min(60vh,var(--radix-popover-content-available-height))] flex-col gap-2 overflow-y-auto p-1.5",
-            "data-testid": chunkMHVNT4J3_cjs.testIdOr(testIds?.list, { testId: "fact-sources-list" }),
-            children
-          }
-        )
-      ]
-    }
-  );
-}
 var DEFAULT_FACT_SOURCE_GROUP_LABELS = {
   remove: "Remove this document",
   wholeDocument: "Whole document \u2014 open it to cite specific passages"
@@ -2252,6 +2130,26 @@ function FactSearchResult({
   ] });
 }
 
+Object.defineProperty(exports, "DEFAULT_FACT_PASSAGES_LABELS", {
+  enumerable: true,
+  get: function () { return chunk5FYU7ZIU_cjs.DEFAULT_FACT_PASSAGES_LABELS; }
+});
+Object.defineProperty(exports, "FactPassageItem", {
+  enumerable: true,
+  get: function () { return chunk5FYU7ZIU_cjs.FactPassageItem; }
+});
+Object.defineProperty(exports, "FactSourcesPanel", {
+  enumerable: true,
+  get: function () { return chunk5FYU7ZIU_cjs.FactSourcesPanel; }
+});
+Object.defineProperty(exports, "renderPreviewInline", {
+  enumerable: true,
+  get: function () { return chunk5FYU7ZIU_cjs.renderPreviewInline; }
+});
+Object.defineProperty(exports, "toPreviewLine", {
+  enumerable: true,
+  get: function () { return chunk5FYU7ZIU_cjs.toPreviewLine; }
+});
 Object.defineProperty(exports, "decodeWhitespaceEntities", {
   enumerable: true,
   get: function () { return chunkRC25WMVB_cjs.decodeWhitespaceEntities; }
@@ -2278,7 +2176,6 @@ exports.DEFAULT_FACT_COLUMN_ORDER = DEFAULT_FACT_COLUMN_ORDER;
 exports.DEFAULT_FACT_COMPOSER_LABELS = DEFAULT_FACT_COMPOSER_LABELS;
 exports.DEFAULT_FACT_DATE_INPUT_LABELS = DEFAULT_FACT_DATE_INPUT_LABELS;
 exports.DEFAULT_FACT_LABELS_CELL_LABELS = DEFAULT_FACT_LABELS_CELL_LABELS;
-exports.DEFAULT_FACT_PASSAGES_LABELS = DEFAULT_FACT_PASSAGES_LABELS;
 exports.DEFAULT_FACT_ROW_ACTIONS_LABELS = DEFAULT_FACT_ROW_ACTIONS_LABELS;
 exports.DEFAULT_FACT_SEARCH_BAR_LABELS = DEFAULT_FACT_SEARCH_BAR_LABELS;
 exports.DEFAULT_FACT_SEARCH_RESULT_LABELS = DEFAULT_FACT_SEARCH_RESULT_LABELS;
@@ -2290,7 +2187,6 @@ exports.FactComposer = FactComposer;
 exports.FactDateInput = FactDateInput;
 exports.FactFieldRow = FactFieldRow;
 exports.FactLabelsCell = FactLabelsCell;
-exports.FactPassageItem = FactPassageItem;
 exports.FactRowActions = FactRowActions;
 exports.FactSearchBar = FactSearchBar;
 exports.FactSearchNoMatches = FactSearchNoMatches;
@@ -2298,7 +2194,6 @@ exports.FactSearchPending = FactSearchPending;
 exports.FactSearchResult = FactSearchResult;
 exports.FactSearchTotals = FactSearchTotals;
 exports.FactSourceGroup = FactSourceGroup;
-exports.FactSourcesPanel = FactSourcesPanel;
 exports.FactSourcesRow = FactSourcesRow;
 exports.FactsBulkBar = FactsBulkBar;
 exports.FactsCalendar = FactsCalendar;
@@ -2315,11 +2210,9 @@ exports.createFactColumns = createFactColumns;
 exports.detectTimezone = detectTimezone;
 exports.factDateFieldsToSpan = factDateFieldsToSpan;
 exports.factDateSpanToFields = factDateSpanToFields;
-exports.renderPreviewInline = renderPreviewInline;
 exports.sourceDocCount = sourceDocCount;
 exports.supportedTimezones = supportedTimezones;
 exports.toFactRow = toFactRow;
 exports.toFactRows = toFactRows;
-exports.toPreviewLine = toPreviewLine;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map