@syncfusion/ej2-docx 0.0.0-stage → 35.1.40

package/src/features/hyperlinks/index.d.ts

@@ -0,0 +1,230 @@
+import { WordDocument } from '../document/document';
+import { FeatureInline } from '../document/feature-inline';
+import { FeatureMultiPackagePart } from '../document/feature-multi-package-part';
+import { Paragraph } from '../document/paragraph';
+import { FeatureInlineParagraphItem, ParagraphItem, TextRange } from '../document/text-range';
+import { OpcRelationship, RelationshipId } from '../../core/opc/relationships';
+import { OpcPackage } from '../../core/opc/package';
+import { partName } from '../../core/opc/part-name';
+import { OpenXmlElement } from '../../core/xml/index';
+/**
+ * @private
+ * Transitional hyperlink relationship (ECMA-376-4 §9.2.1). */
+export declare const HYPERLINK_RELATIONSHIP_TYPE = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/hyperlink";
+/**
+ * @private
+ * Strict hyperlink relationship. */
+export declare const STRICT_HYPERLINK_RELATIONSHIP_TYPE = "http://purl.oclc.org/ooxml/officeDocument/relationships/hyperlink";
+/**
+ * Options when appending an external hyperlink via {@link Paragraph.appendHyperlink}.
+ *
+ * @public
+ */
+export interface ExternalHyperlinkOptions {
+    /** Optional screen tip shown when the user hovers the link. */
+    readonly tooltip?: string | undefined;
+    /** Optional bookmark or fragment name within the target resource. */
+    readonly anchor?: string | undefined;
+}
+declare type HyperlinkInlineItem = {
+    readonly type: 'textRange';
+    readonly run: TextRange;
+} | {
+    readonly type: 'opaque';
+    readonly xml: OpenXmlElement;
+};
+interface HyperlinkRelationshipEntry {
+    readonly relationshipId: RelationshipId;
+    readonly target: string;
+    readonly relationshipType: string;
+    pendingRelationship: OpcRelationship | undefined;
+}
+declare class HyperlinkRunOwner {
+    private runs;
+    assertAttachedItem(target: ParagraphItem): void;
+    appendRun(): TextRange;
+    listRuns(): ReadonlyArray<TextRange>;
+    detachRuns(): void;
+    hydrateRuns(runs: TextRange[]): void;
+}
+/**
+ * External or anchor hyperlink (`w:hyperlink`, ECMA-376-1 §17.16.22 `CT_Hyperlink`).
+ *
+ * Nested display content is exposed as {@link Hyperlink.runs}. Non-run children are
+ * preserved opaquely in document order and re-emitted on save.
+ *
+ * The resolved external URL is **not** a parameterless instance property: package
+ * relationships live on the document catalog. Use {@link hyperlinkTarget} with the
+ * owning {@link WordDocument} (MVP “url” / resolved external target).
+ *
+ * @remarks
+ * - `relationshipId` maps `r:id` when present; new external links receive an id at
+ *   materialize/save time.
+ * - `anchor`, `tooltip`, `docLocation`, `tgtFrame`, and `history` map the corresponding
+ *   `w:hyperlink` attributes when present in the package.
+ * - Field-based `HYPERLINK` instructions are out of scope (separate fields module).
+ *
+ * @public
+ */
+export declare class Hyperlink implements FeatureInline {
+    private readonly runOwner;
+    private readonly items;
+    private relationshipIdValue;
+    /**
+     * Optional bookmark or fragment name the link jumps to within the target.
+     *
+     * @public
+     */
+    readonly anchor: string | undefined;
+    /**
+     * Optional screen tip shown when the user hovers the link.
+     *
+     * @public
+     */
+    readonly tooltip: string | undefined;
+    /**
+     * @private
+   * Location in target document (`w:docLocation`); preserved. */
+    readonly docLocation: string | undefined;
+    /**
+     * @private
+   * Target frame (`w:tgtFrame`); preserved. */
+    readonly tgtFrame: string | undefined;
+    /**
+     * @private
+   * Whether the target is added to browser history (`w:history`). */
+    readonly history: boolean | undefined;
+    /**
+     * @private
+     */
+    constructor(runOwner: HyperlinkRunOwner, items: HyperlinkInlineItem[], relationshipId: string | undefined, anchor: string | undefined, tooltip: string | undefined, docLocation: string | undefined, tgtFrame: string | undefined, history: boolean | undefined);
+    /**
+     * @private
+   * External relationship id (`r:id`) when present. */
+    readonly relationshipId: string | undefined;
+    /**
+     * @private
+     */
+    resolveRelationshipId(relationshipId: string): void;
+    /**
+     * Visible text runs inside the hyperlink, in document order.
+     *
+     * @public
+     */
+    readonly runs: ReadonlyArray<TextRange>;
+    /**
+     * @private
+     */
+    releaseContent(): void;
+    /**
+     * @private
+     */
+    toOpenXml(): OpenXmlElement;
+}
+/**
+ * Hyperlink relationships on the Main Document part.
+ *
+ * @private
+ * Catalog of hyperlink relationships; not part of the stable public surface.
+ * @private
+ */
+export declare class HyperlinksCatalog implements FeatureMultiPackagePart {
+    private readonly byRelationshipId;
+    private readonly pendingRemovals;
+    private readonly pendingExternal;
+    private dirty;
+    /**
+     * @private
+     */
+    constructor(byRelationshipId: Map<string, HyperlinkRelationshipEntry>, dirty: boolean);
+    /**
+     * @private
+     */
+    removeEntry(relationshipId: string): void;
+    /**
+     * @private
+     */
+    isDirty(): boolean;
+    /**
+     * @private
+     */
+    applyToPackage(pkg: OpcPackage, mainPartName: ReturnType<typeof partName>): OpcPackage;
+    /**
+     * @private
+     */
+    relationshipIds(): ReadonlyArray<string>;
+    /**
+     * @private
+     */
+    targetForRelationship(relationshipId: string): string | undefined;
+    /**
+     * @private
+   * Register an external hyperlink before relationship allocation. */
+    registerPendingExternal(hyperlink: Hyperlink, target: string, relationshipType?: string): void;
+    /**
+     * @private
+     */
+    pendingTargetFor(hyperlink: Hyperlink): string | undefined;
+    /**
+     * @private
+     */
+    materializePending(document: WordDocument): void;
+    /**
+     * @private
+     */
+    allocateExternalTarget(target: string, usedRelIds: ReadonlySet<string>, relationshipType?: string): string;
+}
+/**
+ * @private
+ * Test hook */
+export declare function resetHyperlinksFeatureForTests(): void;
+/**
+ * @private
+ * Register hyperlink inline and relationship handlers. Idempotent. */
+export declare function registerHyperlinksFeature(): void;
+/**
+ * Hyperlink catalog for a document.
+ *
+ * On a loaded package this is the catalog built from Main Document relationships.
+ * On a newly authored document there are no relationships yet, so this function
+ * attaches an empty catalog on first use and {@link WordDocument.saveSync | saveSync}
+ * materializes pending relationships into the package.
+ *
+ * @throws DocxError `feature/not-registered` when the module was not registered.
+ * @private
+ */
+export declare function hyperlinksFor(document: WordDocument): HyperlinksCatalog;
+/**
+ * Hyperlinks in a paragraph, in document order.
+ *
+ * @private
+ */
+export declare function hyperlinksInParagraph(paragraph: Paragraph): ReadonlyArray<Hyperlink>;
+/**
+ * Resolved external URL (MVP “url”) for a hyperlink, when present.
+ *
+ * Looks up the Main Document hyperlink relationship `Target` for
+ * {@link Hyperlink.relationshipId}, or the pending external target registered for a
+ * newly authored link that has not yet been materialized. Returns `undefined` for
+ * anchor-only internal links with no external relationship.
+ *
+ * Targets are data only — never fetched or executed (see security policy).
+ *
+ * @private
+ */
+export declare function hyperlinkTarget(document: WordDocument, hyperlink: Hyperlink): string | undefined;
+/**
+ * Remove a hyperlink inline from its paragraph and drop its external relationship on save.
+ *
+ * @private
+ */
+export declare function removeHyperlink(document: WordDocument, paragraph: Paragraph, hyperlink: Hyperlink): void;
+/**
+ * Whether paragraph inline content is a modeled hyperlink from this module.
+ *
+ * @private
+ */
+export declare function isHyperlinkInline(inline: ParagraphItem): inline is FeatureInlineParagraphItem & {
+    value: Hyperlink;
+};
+export {};