/**
 * Worksheet hyperlinks (`CT_Hyperlinks` / `CT_Hyperlink`).
 *
 * Citations:
 * - ECMA-376-1 §18.3.1.47 `hyperlink` / §18.3.1.48 `hyperlinks`
 * - transitional sml.xsd `CT_Hyperlink` / `CT_Hyperlinks` / `CT_Worksheet`
 * - officeDocument relationships `…/relationships/hyperlink`
 * - docs/specs/hyperlinks.md; docs/ooxml-mapping/hyperlinks.md; API-RULES R1.5 / R5.1
 *
 * External targets materialize as sheet-part relationships with
 * `TargetMode="External"` on flush (never fetched). Internal targets use
 * `@location` only. Empty collection omits the parent element.
 */
import { CellRange } from '../address/cell-address';
import { OpcRelationship } from '../core/package/relationships';
/**
 * Specifies the kind of destination a hyperlink points to — a web page, a
 * file, a network path, or a location in the same workbook.
 */
export declare type HyperlinkType = 'url' | 'file' | 'unc' | 'workbook';
/**
 * Describes a clickable link attached to a cell, pointing to a web page,
 * file, or another location in the workbook.
 *
 * XlsIO map: `target`↔Address, `displayText`↔TextToDisplay, `tooltip`↔ScreenTip,
 * `type`↔Type, `subAddress`↔SubAddress.
 */
export interface CellHyperlink {
    /**
     * The link's destination: a web address, a file path, or a location in the
     * workbook such as `Sheet1!A1`.
     */
    target: string;
    /**
     * The friendly text shown for the link. When set on a cell, this text also
     * becomes the cell's visible value.
     */
    displayText?: string;
    /** The small text shown when the pointer hovers over the link. */
    tooltip?: string;
    /**
     * The kind of destination the link points to — web page, file, network
     * path, or a place in this workbook. Omit to have it detected from the
     * target.
     */
    type?: HyperlinkType;
    /**
     * An optional specific place inside the target document, such as a
     * bookmark or sheet reference. Combine with an external `target` to
     * deep-link into another file.
     */
    subAddress?: string;
}
/**
 * Represents a clickable hyperlink in a worksheet, letting you set its
 * destination, display text, and tooltip.
 */
export interface Hyperlink {
    /**
     * The cell or range the link is attached to, written as a normalized
     * A1-style address.
     */
    readonly ref: string;
    /**
     * Where the link points — for example a web address like
     * `'https://example.com'`, a file path, or a place inside the workbook
     * such as `'Sheet2!A1'`.
     */
    target: string;
    /**
     * The visible link text. Setting it on a link attached to a single cell
     * also updates that cell's value.
     */
    displayText: string | undefined;
    /** The text shown when hovering over the link. */
    tooltip: string | undefined;
    /**
     * Whether the link points outside the workbook (`'external'`, like a web
     * page or file) or to a place inside it (`'internal'`, like another
     * sheet). See {@link type} for the finer-grained link kind.
     */
    readonly kind: 'external' | 'internal';
    /**
     * What the link points to: a web address (`'url'`), a file (`'file'`), a
     * network path (`'unc'`), or a place in this workbook (`'workbook'`).
     */
    readonly type: HyperlinkType;
    /**
     * A specific location inside the target — for example a cell range on
     * another sheet. Used together with an external `target` when the link
     * must also point to a place inside it.
     */
    subAddress: string | undefined;
}
/**
 * Represents the collection of hyperlinks in a worksheet, letting you add,
 * list, and remove links.
 */
export interface Hyperlinks {
    /** The number of hyperlinks on the worksheet. */
    readonly count: number;
    /**
     * Get all hyperlinks as a list, in the order they appear on the
     * worksheet.
     *
     * @returns the current hyperlinks.
     */
    list(): ReadonlyArray<Hyperlink>;
    /**
     * Get the hyperlink at a zero-based position, in the order the links
     * appear on the worksheet.
     *
     * @param index - The zero-based position of the hyperlink.
     * @returns the hyperlink at `index`.
     * @throws InvalidArgumentError when the index is out of range
     */
    get(index: number): Hyperlink;
    /**
     * Add a hyperlink to the worksheet.
     *
     * @param ref - The cell or range the link is attached to, written as an
     *   A1-style address.
     * @param target - Where the link points - for example a web address,
     *   file path, or a place inside the workbook such as `'Sheet2!A1'`.
     * @param displayText - The visible link text. For a link on a single cell, this
     *   also becomes the cell's value.
     * @param tooltip - The text shown when hovering over the link.
     * @param type - What the link points to: `'url'`, `'file'`, `'unc'`, or
     *   `'workbook'`. Inferred from `target` when omitted.
     * @param subAddress - A specific location inside the target (optional with
     *   external targets).
     * @returns the newly created hyperlink.
     * @throws InvalidArgumentError when required fields are wrong type
     * @throws InvalidHyperlinkError when ref/target invalid
     */
    add(ref: string, target: string, displayText?: string, tooltip?: string, type?: HyperlinkType, subAddress?: string): Hyperlink;
    /**
     * Remove the hyperlink at a zero-based position.
     *
     * @param index - The zero-based position of the hyperlink to remove.
     * @throws InvalidArgumentError when the index is out of range
     */
    removeAt(index: number): void;
    /**
     * Remove a hyperlink previously returned by this collection.
     *
     * @param link - The hyperlink to remove.
     * @throws InvalidArgumentError when the link was not created by this
     *   collection
     */
    remove(link: Hyperlink): void;
    /** Remove every hyperlink from the worksheet. */
    clear(): void;
    /**
     * All hyperlinks whose ref contains the cell, file order.
     * Used by the cell hyperlink property path; not part of the public API.
     * @private
     * @throws InvalidAddressError when address is not a single cell
     */
    findByCell(address: string): ReadonlyArray<Hyperlink>;
}
/**
 * Internal wire entry for one `hyperlink`.
 * @private
 */
export interface HyperlinkEntry {
    ranges: CellRange[];
    /** External URI when kind is external. */
    externalTarget: string | undefined;
    /** Internal location when kind is internal (no leading `#`). */
    location: string | undefined;
    /** Loaded / assigned relationship id; rewritten on flush for externals. */
    relationshipId: string | undefined;
    display: string | undefined;
    tooltip: string | undefined;
    /** Extra attributes excluding modeled ones (XML fragment, no leading space). */
    extraAttrsXml: string;
}
/**
 * Ordered entries for worksheet XML model.
 * @private
 */
export interface HyperlinksModel {
    readonly entries: ReadonlyArray<HyperlinkEntry>;
}
/**
 * Host notifications for hyperlink mutations.
 * @private
 */
export interface HyperlinksHost {
    markDirty(): void;
    /**
     * Apply XlsIO TextToDisplay to a single cell (set visible value).
     * Optional so unit-level stores without a sheet still work.
     */
    applyDisplayText?(address: string, text: string): void;
}
/**
 * Classified target for authoring.
 * @private
 */
export interface ClassifiedHyperlinkTarget {
    readonly kind: 'external' | 'internal';
    readonly type: HyperlinkType;
    readonly externalTarget: string | undefined;
    readonly location: string | undefined;
}
/**
 * Mutable hyperlinks store.
 * @private
 */
export declare class HyperlinksImpl implements Hyperlinks {
    private readonly entries;
    private readonly handles;
    private host;
    constructor(initial?: HyperlinksModel);
    /** @private */
    bindHost(host: HyperlinksHost): void;
    readonly count: number;
    list(): ReadonlyArray<Hyperlink>;
    get(index: number): Hyperlink;
    add(ref: string, target: string, displayText?: string, tooltip?: string, type?: HyperlinkType, subAddress?: string): Hyperlink;
    removeAt(index: number): void;
    remove(link: Hyperlink): void;
    clear(): void;
    /** @private */
    findByCell(address: string): ReadonlyArray<Hyperlink>;
    /**
     * Replace contents from parse (does not mark dirty).
     * @private
     */
    replaceFromParse(model: HyperlinksModel): void;
    /**
     * Snapshot for serialize (before relationship materialization mutates rIds).
     * @private
     */
    toModel(): HyperlinksModel;
    /**
     * Assign sheet-local external relationship ids and return the hyperlink-type
     * relationships to write. Mutates entries in place; caller merges with
     * non-hyperlink sheet rels. R5.1 — materialize only on flush/save.
     *
     * @private
     */
    materializeExternalRelationships(existingSheetRels: ReadonlyArray<OpcRelationship>): {
        readonly entries: ReadonlyArray<HyperlinkEntry>;
        readonly hyperlinkRels: ReadonlyArray<OpcRelationship>;
        readonly retainedRels: ReadonlyArray<OpcRelationship>;
    };
    /**
     * Set or clear the hyperlink for a single cell (cell property path).
     * Removes existing links that contain the cell, then optionally adds one.
     * @private
     */
    setForCell(address: string, value: CellHyperlink | undefined): void;
    /**
     * First hyperlink covering the cell, as {@link CellHyperlink}.
     * @private
     */
    getForCell(address: string): CellHyperlink | undefined;
    /**
     * Hyperlinks whose ref intersects the given range bounds, file order.
     * @private
     */
    findIntersecting(range: CellRange): ReadonlyArray<Hyperlink>;
    /**
     * Remove every hyperlink whose ref intersects the range.
     * @private
     */
    removeIntersecting(range: CellRange): void;
    private applyModel;
    private handleFor;
    private maybeApplyDisplayText;
}
/**
 * Options that refine {@link classifyTarget} (explicit Type / SubAddress).
 */
export interface ClassifyTargetOptions {
    readonly type?: HyperlinkType;
    readonly subAddress?: string;
}
/**
 * Classify authoring target into external URI vs internal location + Type.
 *
 * Rules (docs/specs/hyperlinks.md; XlsIO ExcelHyperLinkType):
 * 1. empty target → error (unless explicit workbook + subAddress only — not used here)
 * 2. explicit `type` overrides inference when provided
 * 3. `#…` / sheet jump / named-range → workbook (`location`)
 * 4. UNC → unc; file: / drive / relative path → file; else scheme URI → url
 *
 * @throws InvalidHyperlinkError | InvalidArgumentError
 */
export declare function classifyTarget(raw: string, options?: ClassifyTargetOptions): ClassifiedHyperlinkTarget;
/**
 * CT_Worksheet local names that appear **before** `hyperlinks` after sheetData.
 *
 * Citation: transitional sml.xsd `CT_Worksheet`
 * (`dataValidations` → `hyperlinks` → `printOptions`).
 */
export declare const HYPERLINKS_PREDECESSORS_AFTER_SHEET_DATA: ReadonlyArray<string>;
/**
 * CT_Worksheet local names that appear **after** `hyperlinks`.
 *
 * Citation: transitional sml.xsd `CT_Worksheet`.
 */
export declare const HYPERLINKS_SUCCESSORS: ReadonlyArray<string>;
/**
 * Index at which to insert serialized `hyperlinks` among after-sheetData siblings.
 */
export declare function findHyperlinksInsertIndex(afterSheetDataLocals: ReadonlyArray<string>): number;
/**
 * Parse `hyperlinks` element XML into a model.
 * Soft-skips individual bad children (keep valid siblings).
 * Resolves `r:id` against sheet relationships when provided.
 *
 * @private
 */
export declare function parseHyperlinksXml(xml: string, sheetRelsById?: ReadonlyMap<string, OpcRelationship>): HyperlinksModel;
/**
 * Serialize model to a `hyperlinks` element, or `undefined` when empty.
 * Caller must materialize `relationshipId` on external entries first.
 *
 * @private
 */
export declare function serializeHyperlinksXml(model: HyperlinksModel): string | undefined;