@svgrid/enterprise 3.0.2 → 3.0.3

package/dist/sheet/index.d.ts

@@ -9,18 +9,39 @@
  */
 export { enableSheet } from '../sheet-enable.js';
 export { createTableRegistry, isValidTableName, resolveTableRange, columnIndexOf, rowCountOf, type TableRegion, type TableRegistry, type TableRange, type TableSpecifier, } from './tables.js';
+export { TABLE_STYLES, DEFAULT_TABLE_STYLE, NO_TABLE_STYLE, findTableStyle, tableStyleColours, tableStyleLabel, type TableStyle, type TableStyleTone, type TableStyleColours, } from './table-styles.js';
 export { goalSeek, goalSeekCell, type GoalSeekOptions, type GoalSeekResult, type GoalSeekSheet, type CellAddress as GoalSeekCellAddress, } from './goal-seek.js';
+export { evaluationSteps, printNode, printValue, type EvaluationStep, } from './evaluate-steps.js';
+export { checkSheet, describeFinding, ERROR_MEANINGS, type ErrorFinding, type ErrorFindingKind, type SheetReader, } from './error-check.js';
+export { imageCall, isDrawableImageSource, type ImageCall } from './cell-images.js';
+export { livePresence, presenceOnSheet, presenceAnchor, presenceColour, presenceInitials, PRESENCE_COLOURS, type SheetPresence, } from './presence.js';
 export { default as SvSheetTabs } from '../SvSheetTabs.svelte';
-export { createWorkbook, isValidSheetName, type Workbook, type SheetData, type WorkbookOptions, } from './workbook.js';
+export { createWorkbook, isValidSheetName, cleanIteration, DEFAULT_ITERATION, type Workbook, type SheetData, type WorkbookOptions, type IterationSettings, } from './workbook.js';
 export { setWorkbook, getWorkbook } from './shortcuts.js';
 export { createSheetDocument, type SheetDocument, type SheetDocumentInit, type SheetState, type SheetStateEntry, type PerSheetState, type SheetChangeReason, } from './document.js';
 export { shiftRect, shiftRects, subtractRect, rectContains, rectsIntersect, remapNotes, lineShift, type NotesMap } from './rects.js';
-export { isLocked, rectsHaveLocked, rectsMixLocked, PROTECTED_MESSAGE } from './protection.js';
-export { commentAt, withComment, listComments, nextComment } from './comments.js';
+export { isLocked, cellLocked, inEditRange, rectsHaveLocked, rectsMixLocked, PROTECTED_MESSAGE, PROTECTION_PERMISSIONS, defaultProtection, copyProtection, newEditRangeId, parseRangeText, rangeText, type ProtectionAllow, type ProtectionPermission, type EditRange, type SheetProtection, } from './protection.js';
+export { commentAt, withComment, withThread, threadAt, threadOf, threadText, notesOf, isThreaded, listComments, nextComment, type CommentEntry, type CommentThread, type CommentValue, type CommentsMap, } from './comments.js';
 export { ruleAt, rulesIn, checkEntry, listChoices, shiftValidation, removeValidation, describeRule, dateValue, validationId, DEFAULT_ALERT_MESSAGE, OPERATOR_LABELS, type ValidationRule, type ValidationAllow, type ValidationOperator, type ValidationContext, type ValidationVerdict, type ValidationSpec, } from './validation.js';
-export { ruleStats, evaluateCf, shiftCf, removeCf, cfIn, describeCf, scaleColor, iconIndex, hasStyle, cfId, CF_PRESET_STYLES, COLOR_SCALES, DATA_BAR_COLOR, type CfRule, type CfRuleBody, type CfStyledRule, type CfBody, type CfPreset, type CfStyle, type CfStats, type CfResult, type CfContext, type CfOperator, type CfTextMatch, type CfIconSet, type CfScaleColors, type CfKind, } from './conditional-formats.js';
+export { ruleStats, evaluateCf, shiftCf, removeCf, cfIn, describeCf, scaleColor, iconIndex, hasStyle, cfId, CF_PRESET_STYLES, COLOR_SCALES, DATA_BAR_COLOR, DATA_BAR_NEGATIVE_COLOR, type CfRule, type CfRuleBody, type CfStyledRule, type CfBody, type CfPreset, type CfStyle, type CfStats, type CfResult, type CfContext, type CfOperator, type CfTextMatch, type CfIconSet, type CfScaleColors, type CfKind, } from './conditional-formats.js';
 export { mergePlan, unmergePlan, mergeDropsValues, mergesIn, mergeAt as sheetMergeAt, isCoveredCell, selectionMerged, toGridMerges, sortBlockedByMerges, reorderMerges, normalRect, type MergeKind, type MergePlan, } from './merges.js';
-export { distinctValues, hiddenRowsFor, passesFilter, isFiltering, withColumnFilter, valuesFilter, shiftAutoFilter, describeFilter, type AutoFilterState, type ColumnFilter, type FilterCondition, type FilterValue, } from './auto-filter.js';
+export { distinctValues, hiddenRowsFor, passesFilter, isFiltering, withColumnFilter, valuesFilter, shiftAutoFilter, describeFilter, datePeriodBounds, distinctFills, isDateColumn, type AutoFilterState, type ColumnFilter, type FilterCondition, type FilterValue, type DatePeriod, type FilterContext, } from './auto-filter.js';
+export { sortOrder, guessHeaderRow, type SortKey, type SortDirection } from './sort.js';
+export { documentToXlsxParts, documentFromXlsxParts, documentToXlsx, documentFromXlsx } from './xlsx-document.js';
+export { csvText, csvRows, guessCsvSeparator, sheetStateFromCsv } from './csv.js';
+export { sheetStateFromOds, documentFromOds, documentToOds, documentToOdsParts, formulaFromOdf, formulaToOdf } from './ods-document.js';
+export { sheetStateFromXls, documentFromXls, documentToXls, isXlsFile } from './xls-document.js';
+export { documentFromFile, readSpreadsheetFile, type OpenedFile } from './open-file.js';
+export { defaultPageSetup, copyPageSetup, marginPresetOf, shiftPageSetup, marginsCss, MARGIN_PRESETS, PAPER_SIZES, type PageSetup, type PageMargins, type PageOrientation, type PaperSize, type MarginPreset, } from './page-setup.js';
+export { sheetPrintHtml, printAreas, type SheetPrintInput, type SheetPrintCell } from './print.js';
+export { sheetCellsFromRows, cellTextOf, type SheetField, type SheetFromRowsOptions } from './from-rows.js';
+export { builtinEngine, type SheetEngine, type SheetEngineHost, type SheetEngineCell, type SheetEngineResult } from './engine.js';
+export { chartSpecOf, chartFromRange, shiftObject, shiftObjects, objectAt, copyObject, objectId, SHEET_CHART_TYPES, type SheetObject, type SheetChartObject, type SheetImageObject, type ObjectAnchor, type SheetChartType, } from './objects.js';
+export { sparklineSeries, sparklineAt, sparklineScale, sparklinesFromRange, clearSparklines, shiftSparkline, shiftSparklines, copySparkline, sparklineId, isColumnLocation, SPARKLINE_TYPES, type SparklineGroup, type SheetSparklineType, } from './sparklines.js';
+export { pivotFields, pivotFieldValues, pivotRecords, filteredRecords, pivotBlock, pivotLayout, pivotDrill, pivotFromRange, pivotWrittenRect, flattenPivotColumns, ALL_VALUES, shiftPivot, shiftPivots, copyPivot, pivotId, SHEET_PIVOT_AGGS, type SheetPivot, type SheetPivotValue, type SheetPivotAgg, type SheetPivotFilter, type PivotLayout, type PivotDrill, } from './pivot-range.js';
+export { createDeltaStream, applySheetDelta, partsOfReasons, type SheetDelta, type SheetDeltaStream, type SheetDeltaOptions, type SheetCellWrite, } from './delta.js';
+export { linkAt, setLink, removeLink, listLinks, shiftLinks, copyLinks, parseLinkTarget, isSafeLinkTarget, linkTitle, type SheetLink, type LinksMap, type LinkTarget, } from './links.js';
+export { default as SvSheetSort } from '../SvSheetSort.svelte';
 export { splitText, textToColumns, guessDelimiter, findDuplicates, removeDuplicates, type SplitOptions, type DuplicateOptions, type DuplicateReport, } from './transforms.js';
 export { insertRows, deleteRows, insertColumns, deleteColumns, axisForSelection, setStructureTarget, getStructureTarget, rewriteFormulas, type StructureTarget, } from './structure.js';
 export { findAll, findNext, replaceOne, replaceAll, replaceInText, cellMatches, setFindTarget, getFindTarget, type FindOptions, type FindHit, type FindTarget, } from './find-replace.js';
@@ -35,19 +56,25 @@ export { RIBBON_ICONS, RIBBON_ICON_NAMES, type RibbonIconName, type IconPath } f
 export { THEME_COLOURS, STANDARD_COLOURS, ALL_COLOURS, tint, type PaletteColour } from './palette.js';
 export { default as SvRibbonIcon } from '../SvRibbonIcon.svelte';
 export { move, selectRegion, selectLine, applyFormat, toggleFormat, preset, autoSum, structural, switchSheet, gridOf, } from './shortcuts.js';
-export { compileNumberFormat, formatWithPattern, FORMAT_PRESETS, type CompiledFormat, type FormatPresetName, } from './number-format.js';
+export { compileNumberFormat, formatWithPattern, FORMAT_PRESETS, FORMAT_CATEGORY_PATTERNS, SPECIAL_FORMATS, formatCategory, accountingPattern, accountingParts, type CompiledFormat, type FormatPresetName, type SpecialFormatName, } from './number-format.js';
 export { createFormatStore, entryToStyle, type SheetFormatStore, type CellFormatEntry, type CellAddressLookup, } from './format-store.js';
 export { createNames, isValidName, type SheetNames, type DefinedName, } from './names.js';
+export { defaultSheetMessages, defaultSheetTextMessages, defaultDialogMessages, ribbonMessageDefaults, resolveSheetMessages, formatMessage, type SheetMessages, type SheetTextMessages, type SheetDialogMessages, type SheetLocalization, } from './messages.js';
 export { suggestFunctions, applySuggestion, signatureAt, partialAt, SIGNATURES, type FunctionSuggestion, } from './autocomplete.js';
 export { setFormatTarget, getFormatTarget, setFormatDialogHandler, type SheetFormatTarget, } from './shortcuts.js';
 export { parseFormula, parse, } from './parse.js';
 export { tokenize, type Token } from './tokenize.js';
-export { evaluate, formatValue, type EvalContext } from './evaluate.js';
+export { evaluate, evaluateSpill, formatValue, type EvalContext } from './evaluate.js';
+export { ARRAY_FUNCTIONS, type ArrayFunction, type Grid as SpillGrid } from './packs/array.js';
 export { FUNCTIONS, withCustomFunctions, type SheetFunction, type FnArgs, } from './functions.js';
-export { translateFormula, fixupReferences, renameSheetReferences, formatFormula, referenceSpans, REFERENCE_COLOURS, type StructuralEdit, type EditScope, type ReferenceSpan, } from './refs.js';
+export { translateFormula, fixupReferences, renameSheetReferences, formatFormula, referenceSpans, repointReferences, REFERENCE_COLOURS, type StructuralEdit, type EditScope, type ReferenceSpan, type CellMove, } from './refs.js';
 export { createDependencyGraph, precedentsOf, cellKey, parseCellKey, type DependencyGraph, type CellKey, } from './deps.js';
 export { parseA1, formatA1, colToLetters, lettersToCol, type CellRef, } from './address.js';
 export { isError, type CellValue, type SheetError, type Node as FormulaNode, } from './ast.js';
 export { SHEET_BINDINGS, handleSheetKey, type SheetBinding, type SheetCommand, } from './shortcuts.js';
 export { edgeOfRegion, currentRegion, isWholeSheet, wholeSheet, isBlankValue, type Direction, type Grid, type Cell, type Rect, } from './navigate.js';
 export { fillDown, fillRight, fillSelection, stampDate, stampNow, copyFromAbove, copyValueFromAbove, guessSumRange, looksNumeric, numericAt, targetRect, setFillTranslator, setSheetValueProbe, getSheetValueProbe, type FillTranslator, type SheetValueProbe, } from './commands.js';
+export { cultureFromLocale, formulaToCulture, formulaFromCulture, parseNumberInCulture, formatNumberInCulture, slashDateParts, isInvariant, INVARIANT_CULTURE, type SheetCulture, } from './culture.js';
+export { emptyOutline, groupLines, ungroupLines, clearOutline, toggleCollapsed, showLevel, hiddenByOutline, detailRange, shiftOutline, autoOutline, outlineLevel, isOutlined, deepestLevel, MAX_OUTLINE_LEVEL, type OutlineState, type OutlineSide, } from './outline.js';
+export { cellTypeAt, isChecked, toggledValue, radioIndex, applyCellType, removeCellTypes, shiftCellTypes, checkboxValues, newCellTypeId, copyCellType, CHECKED, UNCHECKED, type CellTypeRegion, type CellTypeKind, } from './cell-types.js';
+export { projectGridSheet, rowOfRecord, recordOfRow, isRecordRow, columnOfField, copyGridSheet, coerceFieldValue, emptyGridSheet, type SheetKind, type GridSheetSpec, type GridSheetField, } from './sheet-kinds.js';

package/dist/sheet/index.js

@@ -9,18 +9,39 @@
  */
 export { enableSheet } from '../sheet-enable.js';
 export { createTableRegistry, isValidTableName, resolveTableRange, columnIndexOf, rowCountOf, } from './tables.js';
+export { TABLE_STYLES, DEFAULT_TABLE_STYLE, NO_TABLE_STYLE, findTableStyle, tableStyleColours, tableStyleLabel, } from './table-styles.js';
 export { goalSeek, goalSeekCell, } from './goal-seek.js';
+export { evaluationSteps, printNode, printValue, } from './evaluate-steps.js';
+export { checkSheet, describeFinding, ERROR_MEANINGS, } from './error-check.js';
+export { imageCall, isDrawableImageSource } from './cell-images.js';
+export { livePresence, presenceOnSheet, presenceAnchor, presenceColour, presenceInitials, PRESENCE_COLOURS, } from './presence.js';
 export { default as SvSheetTabs } from '../SvSheetTabs.svelte';
-export { createWorkbook, isValidSheetName, } from './workbook.js';
+export { createWorkbook, isValidSheetName, cleanIteration, DEFAULT_ITERATION, } from './workbook.js';
 export { setWorkbook, getWorkbook } from './shortcuts.js';
 export { createSheetDocument, } from './document.js';
 export { shiftRect, shiftRects, subtractRect, rectContains, rectsIntersect, remapNotes, lineShift } from './rects.js';
-export { isLocked, rectsHaveLocked, rectsMixLocked, PROTECTED_MESSAGE } from './protection.js';
-export { commentAt, withComment, listComments, nextComment } from './comments.js';
+export { isLocked, cellLocked, inEditRange, rectsHaveLocked, rectsMixLocked, PROTECTED_MESSAGE, PROTECTION_PERMISSIONS, defaultProtection, copyProtection, newEditRangeId, parseRangeText, rangeText, } from './protection.js';
+export { commentAt, withComment, withThread, threadAt, threadOf, threadText, notesOf, isThreaded, listComments, nextComment, } from './comments.js';
 export { ruleAt, rulesIn, checkEntry, listChoices, shiftValidation, removeValidation, describeRule, dateValue, validationId, DEFAULT_ALERT_MESSAGE, OPERATOR_LABELS, } from './validation.js';
-export { ruleStats, evaluateCf, shiftCf, removeCf, cfIn, describeCf, scaleColor, iconIndex, hasStyle, cfId, CF_PRESET_STYLES, COLOR_SCALES, DATA_BAR_COLOR, } from './conditional-formats.js';
+export { ruleStats, evaluateCf, shiftCf, removeCf, cfIn, describeCf, scaleColor, iconIndex, hasStyle, cfId, CF_PRESET_STYLES, COLOR_SCALES, DATA_BAR_COLOR, DATA_BAR_NEGATIVE_COLOR, } from './conditional-formats.js';
 export { mergePlan, unmergePlan, mergeDropsValues, mergesIn, mergeAt as sheetMergeAt, isCoveredCell, selectionMerged, toGridMerges, sortBlockedByMerges, reorderMerges, normalRect, } from './merges.js';
-export { distinctValues, hiddenRowsFor, passesFilter, isFiltering, withColumnFilter, valuesFilter, shiftAutoFilter, describeFilter, } from './auto-filter.js';
+export { distinctValues, hiddenRowsFor, passesFilter, isFiltering, withColumnFilter, valuesFilter, shiftAutoFilter, describeFilter, datePeriodBounds, distinctFills, isDateColumn, } from './auto-filter.js';
+export { sortOrder, guessHeaderRow } from './sort.js';
+export { documentToXlsxParts, documentFromXlsxParts, documentToXlsx, documentFromXlsx } from './xlsx-document.js';
+export { csvText, csvRows, guessCsvSeparator, sheetStateFromCsv } from './csv.js';
+export { sheetStateFromOds, documentFromOds, documentToOds, documentToOdsParts, formulaFromOdf, formulaToOdf } from './ods-document.js';
+export { sheetStateFromXls, documentFromXls, documentToXls, isXlsFile } from './xls-document.js';
+export { documentFromFile, readSpreadsheetFile } from './open-file.js';
+export { defaultPageSetup, copyPageSetup, marginPresetOf, shiftPageSetup, marginsCss, MARGIN_PRESETS, PAPER_SIZES, } from './page-setup.js';
+export { sheetPrintHtml, printAreas } from './print.js';
+export { sheetCellsFromRows, cellTextOf } from './from-rows.js';
+export { builtinEngine } from './engine.js';
+export { chartSpecOf, chartFromRange, shiftObject, shiftObjects, objectAt, copyObject, objectId, SHEET_CHART_TYPES, } from './objects.js';
+export { sparklineSeries, sparklineAt, sparklineScale, sparklinesFromRange, clearSparklines, shiftSparkline, shiftSparklines, copySparkline, sparklineId, isColumnLocation, SPARKLINE_TYPES, } from './sparklines.js';
+export { pivotFields, pivotFieldValues, pivotRecords, filteredRecords, pivotBlock, pivotLayout, pivotDrill, pivotFromRange, pivotWrittenRect, flattenPivotColumns, ALL_VALUES, shiftPivot, shiftPivots, copyPivot, pivotId, SHEET_PIVOT_AGGS, } from './pivot-range.js';
+export { createDeltaStream, applySheetDelta, partsOfReasons, } from './delta.js';
+export { linkAt, setLink, removeLink, listLinks, shiftLinks, copyLinks, parseLinkTarget, isSafeLinkTarget, linkTitle, } from './links.js';
+export { default as SvSheetSort } from '../SvSheetSort.svelte';
 export { splitText, textToColumns, guessDelimiter, findDuplicates, removeDuplicates, } from './transforms.js';
 export { insertRows, deleteRows, insertColumns, deleteColumns, axisForSelection, setStructureTarget, getStructureTarget, rewriteFormulas, } from './structure.js';
 export { findAll, findNext, replaceOne, replaceAll, replaceInText, cellMatches, setFindTarget, getFindTarget, } from './find-replace.js';
@@ -35,19 +56,25 @@ export { RIBBON_ICONS, RIBBON_ICON_NAMES } from './ribbon-icons.js';
 export { THEME_COLOURS, STANDARD_COLOURS, ALL_COLOURS, tint } from './palette.js';
 export { default as SvRibbonIcon } from '../SvRibbonIcon.svelte';
 export { move, selectRegion, selectLine, applyFormat, toggleFormat, preset, autoSum, structural, switchSheet, gridOf, } from './shortcuts.js';
-export { compileNumberFormat, formatWithPattern, FORMAT_PRESETS, } from './number-format.js';
+export { compileNumberFormat, formatWithPattern, FORMAT_PRESETS, FORMAT_CATEGORY_PATTERNS, SPECIAL_FORMATS, formatCategory, accountingPattern, accountingParts, } from './number-format.js';
 export { createFormatStore, entryToStyle, } from './format-store.js';
 export { createNames, isValidName, } from './names.js';
+export { defaultSheetMessages, defaultSheetTextMessages, defaultDialogMessages, ribbonMessageDefaults, resolveSheetMessages, formatMessage, } from './messages.js';
 export { suggestFunctions, applySuggestion, signatureAt, partialAt, SIGNATURES, } from './autocomplete.js';
 export { setFormatTarget, getFormatTarget, setFormatDialogHandler, } from './shortcuts.js';
 export { parseFormula, parse, } from './parse.js';
 export { tokenize } from './tokenize.js';
-export { evaluate, formatValue } from './evaluate.js';
+export { evaluate, evaluateSpill, formatValue } from './evaluate.js';
+export { ARRAY_FUNCTIONS } from './packs/array.js';
 export { FUNCTIONS, withCustomFunctions, } from './functions.js';
-export { translateFormula, fixupReferences, renameSheetReferences, formatFormula, referenceSpans, REFERENCE_COLOURS, } from './refs.js';
+export { translateFormula, fixupReferences, renameSheetReferences, formatFormula, referenceSpans, repointReferences, REFERENCE_COLOURS, } from './refs.js';
 export { createDependencyGraph, precedentsOf, cellKey, parseCellKey, } from './deps.js';
 export { parseA1, formatA1, colToLetters, lettersToCol, } from './address.js';
 export { isError, } from './ast.js';
 export { SHEET_BINDINGS, handleSheetKey, } from './shortcuts.js';
 export { edgeOfRegion, currentRegion, isWholeSheet, wholeSheet, isBlankValue, } from './navigate.js';
 export { fillDown, fillRight, fillSelection, stampDate, stampNow, copyFromAbove, copyValueFromAbove, guessSumRange, looksNumeric, numericAt, targetRect, setFillTranslator, setSheetValueProbe, getSheetValueProbe, } from './commands.js';
+export { cultureFromLocale, formulaToCulture, formulaFromCulture, parseNumberInCulture, formatNumberInCulture, slashDateParts, isInvariant, INVARIANT_CULTURE, } from './culture.js';
+export { emptyOutline, groupLines, ungroupLines, clearOutline, toggleCollapsed, showLevel, hiddenByOutline, detailRange, shiftOutline, autoOutline, outlineLevel, isOutlined, deepestLevel, MAX_OUTLINE_LEVEL, } from './outline.js';
+export { cellTypeAt, isChecked, toggledValue, radioIndex, applyCellType, removeCellTypes, shiftCellTypes, checkboxValues, newCellTypeId, copyCellType, CHECKED, UNCHECKED, } from './cell-types.js';
+export { projectGridSheet, rowOfRecord, recordOfRow, isRecordRow, columnOfField, copyGridSheet, coerceFieldValue, emptyGridSheet, } from './sheet-kinds.js';

package/dist/sheet/links.d.ts

@@ -0,0 +1,57 @@
+import type { StructuralEdit } from './refs.js';
+export type SheetLink = {
+    /** Where it goes: a URL, or an address on this workbook. */
+    target: string;
+    /** Excel's ScreenTip: what hovering says, when it is not the target. */
+    tip?: string;
+};
+/** `r4` -> `B` -> the link on B5. */
+export type LinksMap = Record<string, Record<string, SheetLink>>;
+/** The link on a cell, or undefined. */
+export declare function linkAt(links: LinksMap, row: number, col: number): SheetLink | undefined;
+/** A copy with the link set on one cell. */
+export declare function setLink(links: LinksMap, row: number, col: number, link: SheetLink): LinksMap;
+/** A copy with the link removed from one cell, and the row dropped if empty. */
+export declare function removeLink(links: LinksMap, row: number, col: number): LinksMap;
+/** Every link, as rows and columns, for a writer or a test. */
+export declare function listLinks(links: LinksMap): Array<{
+    row: number;
+    col: number;
+    link: SheetLink;
+}>;
+/** The links after an insert or delete: they move with their cells. */
+export declare function shiftLinks(links: LinksMap, edit: StructuralEdit): LinksMap;
+/** A deep enough copy to hand out or save. */
+export declare function copyLinks(links: LinksMap): LinksMap;
+/** Whether a target is one this shell will follow out of the page. */
+export declare function isSafeLinkTarget(target: string): boolean;
+export type LinkTarget = {
+    kind: 'external';
+    href: string;
+} | {
+    kind: 'internal';
+    sheet: string | null;
+    row: number;
+    col: number;
+} | {
+    kind: 'name';
+    name: string;
+};
+/**
+ * What a target means. An address wins over a name, so `B4` is a cell and
+ * `Sales` is a defined name; `Sheet1!B4` is the cell on that sheet.
+ */
+export declare function parseLinkTarget(target: string): LinkTarget | null;
+/** What a linked cell's title says: the tip, or where it goes. */
+export declare function linkTitle(link: SheetLink): string;
+/**
+ * The first argument of a top-level `=HYPERLINK(...)`, as it was written,
+ * so the caller can evaluate it and learn where the cell goes.
+ *
+ * Excel makes a cell holding that formula clickable, and the target is
+ * whatever the first argument works out to, which may be an expression
+ * (`"…/issues/" & A2`). Null for anything that is not that call, including
+ * one nested inside another formula, since only the outermost one decides
+ * where the cell goes.
+ */
+export declare function hyperlinkArgument(text: string): string | null;

package/dist/sheet/links.js

@@ -0,0 +1,174 @@
+/**
+ * Hyperlinks: Excel's Insert > Link, and the `HYPERLINK` function.
+ *
+ * A link belongs to a CELL rather than to its text, the way Excel keeps
+ * one: the cell still holds whatever was typed, and the link is kept beside
+ * it so that editing the text does not lose the target and clearing the
+ * cell does. That also means a link survives a format change, a sort of the
+ * text around it and a save, and moves with an insert or a delete.
+ *
+ * Two kinds of target, told apart by how they read rather than by a flag
+ * the user has to set:
+ *
+ *   external   `https://…`, `mailto:…`, anything with a scheme, opened in
+ *              a new tab;
+ *   internal   `Sheet1!B4`, `B4`, or a defined name, which moves the
+ *              selection instead of leaving the page.
+ *
+ * The map is keyed the way the comments map is (`r4` -> `B` -> the link),
+ * so the same `remapNotes` moves both when a row or column is inserted.
+ */
+import { remapNotes } from './rects.js';
+import { colToLetters, lettersToCol, parseA1 } from './address.js';
+import { lineShift } from './rects.js';
+/** The link on a cell, or undefined. */
+export function linkAt(links, row, col) {
+    return links[`r${row}`]?.[colToLetters(col)];
+}
+/** A copy with the link set on one cell. */
+export function setLink(links, row, col, link) {
+    const rowId = `r${row}`;
+    return { ...links, [rowId]: { ...(links[rowId] ?? {}), [colToLetters(col)]: { ...link } } };
+}
+/** A copy with the link removed from one cell, and the row dropped if empty. */
+export function removeLink(links, row, col) {
+    const rowId = `r${row}`;
+    const line = links[rowId];
+    if (!line || !(colToLetters(col) in line))
+        return links;
+    const next = { ...line };
+    delete next[colToLetters(col)];
+    const out = { ...links };
+    if (Object.keys(next).length)
+        out[rowId] = next;
+    else
+        delete out[rowId];
+    return out;
+}
+/** Every link, as rows and columns, for a writer or a test. */
+export function listLinks(links) {
+    const out = [];
+    for (const [rowId, line] of Object.entries(links)) {
+        const row = Number(rowId.slice(1));
+        if (!Number.isInteger(row))
+            continue;
+        for (const [columnId, link] of Object.entries(line)) {
+            const col = lettersToCol(columnId);
+            if (col >= 0)
+                out.push({ row, col, link: { ...link } });
+        }
+    }
+    return out.sort((a, b) => a.row - b.row || a.col - b.col);
+}
+/** The links after an insert or delete: they move with their cells. */
+export function shiftLinks(links, edit) {
+    const rows = edit.kind === 'insertRows' || edit.kind === 'deleteRows';
+    return remapNotes(links, rows ? 'rows' : 'cols', lineShift(edit));
+}
+/** A deep enough copy to hand out or save. */
+export function copyLinks(links) {
+    const out = {};
+    for (const [rowId, line] of Object.entries(links)) {
+        out[rowId] = Object.fromEntries(Object.entries(line).map(([c, link]) => [c, { ...link }]));
+    }
+    return out;
+}
+/** Anything with a scheme, or a bare `www.`, is a link out of the page. */
+const EXTERNAL = /^(?:[a-z][a-z0-9+.-]*:|www\.)/i;
+/**
+ * The schemes a cell's link may carry.
+ *
+ * A link is data: it is typed by a colleague, arrives on a delta stream, or
+ * comes out of a file someone sent. Following `javascript:` from one runs
+ * that text in the page, so the set of schemes that may be followed is
+ * named here rather than assumed, and anything else is not a link at all.
+ */
+const SAFE_SCHEMES = new Set(['http', 'https', 'mailto', 'tel', 'sms', 'ftp', 'ftps']);
+/** Whether a target is one this shell will follow out of the page. */
+export function isSafeLinkTarget(target) {
+    const text = target.trim();
+    const scheme = /^([a-z][a-z0-9+.-]*):/i.exec(text);
+    return scheme ? SAFE_SCHEMES.has(scheme[1].toLowerCase()) : true;
+}
+/**
+ * What a target means. An address wins over a name, so `B4` is a cell and
+ * `Sales` is a defined name; `Sheet1!B4` is the cell on that sheet.
+ */
+export function parseLinkTarget(target) {
+    // Not a string at all: a state built by hand, or one from a version that
+    // spelled a link differently. No link, rather than a thrown TypeError
+    // taking a whole Save As with it.
+    if (typeof target !== 'string')
+        return null;
+    const text = target.trim();
+    if (text === '')
+        return null;
+    // A scheme that is not one of the safe ones is not a link: null rather
+    // than an address, so nothing downstream can follow it or write it into
+    // a file.
+    if (!isSafeLinkTarget(text))
+        return null;
+    if (EXTERNAL.test(text))
+        return { kind: 'external', href: text.toLowerCase().startsWith('www.') ? `https://${text}` : text };
+    // `Sheet1!B4` and `'Two words'!B4`: the sheet is whatever is before the
+    // last `!`, which `parseA1` takes as an argument rather than parsing.
+    const bang = text.lastIndexOf('!');
+    const sheet = bang < 0 ? null : text.slice(0, bang).replace(/^'(.*)'$/, '$1').replace(/''/g, "'");
+    const cell = bang < 0 ? text : text.slice(bang + 1);
+    const ref = parseA1(cell, sheet);
+    if (ref && ref.row !== null)
+        return { kind: 'internal', sheet: ref.sheet, row: ref.row, col: ref.col };
+    return { kind: 'name', name: text };
+}
+/** What a linked cell's title says: the tip, or where it goes. */
+export function linkTitle(link) {
+    return link.tip?.trim() ? link.tip : link.target;
+}
+/**
+ * The first argument of a top-level `=HYPERLINK(...)`, as it was written,
+ * so the caller can evaluate it and learn where the cell goes.
+ *
+ * Excel makes a cell holding that formula clickable, and the target is
+ * whatever the first argument works out to, which may be an expression
+ * (`"…/issues/" & A2`). Null for anything that is not that call, including
+ * one nested inside another formula, since only the outermost one decides
+ * where the cell goes.
+ */
+export function hyperlinkArgument(text) {
+    const m = /^=\s*HYPERLINK\s*\(/i.exec(text.trim());
+    if (!m)
+        return null;
+    const inside = text.trim().slice(m[0].length);
+    let depth = 0;
+    let quoted = false;
+    for (let i = 0; i < inside.length; i += 1) {
+        const ch = inside[i];
+        if (quoted) {
+            // `""` inside a string is an escaped quote, not the end of one.
+            if (ch === '"') {
+                if (inside[i + 1] === '"')
+                    i += 1;
+                else
+                    quoted = false;
+            }
+            continue;
+        }
+        if (ch === '"') {
+            quoted = true;
+            continue;
+        }
+        if (ch === '(') {
+            depth += 1;
+            continue;
+        }
+        if (ch === ')') {
+            if (depth === 0)
+                return inside.slice(0, i).trim() || null;
+            depth -= 1;
+            continue;
+        }
+        if (ch === ',' && depth === 0)
+            return inside.slice(0, i).trim() || null;
+    }
+    return null;
+}